% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generate-fields.R
\name{generateMTSFast}
\alias{generateMTSFast}
\title{Faster simulation of multiple time series with approximately separable
spatiotemporal correlation structure}
\usage{
generateMTSFast(
  n,
  spacepoints,
  margdist,
  margarg,
  p0,
  distbounds = c(-Inf, Inf),
  stcsarg,
  scalefactor = 1,
  anisotropyid = "affine",
  anisotropyarg = list(phi1 = 1, phi2 = 1, phi12 = 0, theta = 0),
  dsid = "gauss",
  dsarg = NULL
)
}
\arguments{
\item{n}{number of time steps to simulate}

\item{spacepoints}{matrix (d x 2) of coordinates (e.g. longitude and
latitude) for d spatial locations (e.g. gauge stations)}

\item{margdist}{target marginal distribution}

\item{margarg}{list of marginal distribution arguments; consult the
documentation of the selected distribution for the required parameters}

\item{p0}{probability zero}

\item{distbounds}{distribution bounds (default \code{c(-Inf, Inf)})}

\item{stcsarg}{list of spatiotemporal correlation structure arguments;
consult the documentation of the selected structure for required parameters}

\item{scalefactor}{factor specifying the distance between pixel centres
(default 1)}

\item{anisotropyid}{spatial anisotropy ID (\code{"affine"} by default;
\code{"swirl"} or \code{"wave"} also available)}

\item{anisotropyarg}{list of arguments for \code{\link{anisotropyT}};
isotropic fields by default}

\item{dsid}{dependence structure ID (\code{"gauss"} by default;
\code{"student"}, \code{"bardossy"}, or \code{"bardossyF"})}

\item{dsarg}{argument for the dependence structure: \code{NULL} for
\code{"gauss"}, degrees of freedom for \code{"student"}, or parameter
\code{m} in \eqn{(-\infty, \infty)} for \code{"bardossy"}}
}
\value{
A matrix of class \code{c("matrix", "cosmosts")} with attribute
\code{STmodel} containing the fitted model components.
}
\description{
For more details see section 6 in Serinaldi and Kilsby (2018) and section 2.4
in Papalexiou and Serinaldi (2020).
}
\details{
\code{\link{generateMTSFast}} provides faster multivariate simulation than
\code{\link{generateMTS}} by exploiting circulant-embedding fast Fourier
transformation. This approach is feasible only for approximately separable
target spatiotemporal correlation functions.
\code{\link{generateMTSFast}} combines fitting and simulation in a single call.
Indicative CPU times (Windows 10 Pro x64, Intel Core i7-6700HQ, 32 GB RAM): \cr
d = 2500, n = 1000: ~58s \cr
d = 2500, n = 10000: ~160s \cr
d = 10000, n = 1000: ~2955s (~50 min) \cr
where \eqn{d} denotes the number of spatial locations.
}
\examples{
coord <- cbind(runif(4) * 30, runif(4) * 30)

sim <- generateMTSFast(
    n = 50,
    spacepoints = coord,
    p0 = 0.7,
    margdist = "paretoII",
    margarg = list(scale = 1,
                   shape = .3),
    stcsarg = list(scfid = "weibull",
                   tcfid = "weibull",
                   scfarg = list(scale = 20,
                                 shape = 0.7),
                   tcfarg = list(scale = 1.1,
                                 shape = 0.8))
)

}
\references{
Serinaldi, F., Kilsby, C.G. (2018). Unsurprising Surprises:
The Frequency of Record-breaking and Overthreshold Hydrological Extremes Under
Spatial and Temporal Dependence. Water Resources Research, 54(9), 6460-6487,
\doi{10.1029/2018WR023055}

Papalexiou, S.M., Serinaldi, F. (2020). Random Fields Simplified:
Preserving Marginal Distributions, Correlations, and Intermittency,
With Applications From Rainfall to Humidity. Water Resources Research, 56(2),
e2019WR026331, \doi{10.1029/2019WR026331}
}
\seealso{
\code{\link{generateMTS}}, \code{\link{generateRFFast}},
\code{\link{fitVAR}}
}
