% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fitVAR.r
\name{fitVAR}
\alias{fitVAR}
\title{VAR model parameters to simulate correlated parent Gaussian random vectors and fields}
\usage{
fitVAR(
  spacepoints,
  p,
  margdist,
  margarg,
  p0,
  distbounds = c(-Inf, Inf),
  stcsid,
  stcsarg,
  scalefactor = 1,
  anisotropyid = "affine",
  anisotropyarg = list(phi1 = 1, phi2 = 1, phi12 = 0, theta = 0),
  advectionid = "uniform",
  advectionarg = list(u = 0, v = 0),
  dsid = "gauss",
  dsarg = NULL
)
}
\arguments{
\item{spacepoints}{it can be a numeric integer, which is interpreted as the side length m of the square field (m x m), or a matrix (d x 2) of coordinates (e.g. longitude and latitude) of d spatial locations (e.g. d gauge stations)}

\item{p}{order of VAR(p) model}

\item{margdist}{target marginal distribution of the field}

\item{margarg}{list of marginal distribution arguments. Please consult the documentation of the selected marginal distribution indicated in the argument \code{margdist} for the list of required parameters}

\item{p0}{probability zero}

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

\item{stcsid}{spatiotemporal correlation structure ID}

\item{stcsarg}{list of spatiotemporal correlation structure arguments. Please consult the documentation of the selected spatiotemporal correlation structure indicated in the argument \code{stcsid} for the list of required parameters}

\item{scalefactor}{factor specifying the distance between the centers of two pixels (default set to 1)}

\item{anisotropyid}{spatial anisotropy ID (\code{affine} by default, \code{swirl} or \code{wave})}

\item{anisotropyarg}{list of arguments characterizing the spatial anisotropy according to the syntax of the function \code{\link{anisotropyT}}. Isotropic fields by default}

\item{advectionid}{advection field ID (\code{uniform} by default, \code{rotation}, \code{spiral}, \code{spiralCE}, \code{radial}, or \code{hyperbolic})}

\item{advectionarg}{list of arguments characterizing the advection field according to the syntax of \code{advectionF}. No advection by default}

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

\item{dsarg}{argument characterizing the dependence structure: \code{NULL} for \code{gauss} by default, number of degrees of freedom for \code{student} or parameter \code{m} in \code{(-Inf, Inf)} for \code{bardossy} (see Note section for more details)}
}
\description{
Compute VAR model parameters to simulate parent Gaussian random vectors with specified spatiotemporal correlation structure using the method described by Biller and Nelson (2003).
}
\details{
The fitting algorithm has \eqn{O(m*m)^3} complexity for a \eqn{(m*m)} field
or equivalently \eqn{O(d^3)} complexity for a \eqn{d}-dimensional vector.
Very large values of \eqn{(m*m)} (or \eqn{d}) and high order AR correlation
structures can be unpractical on standard machines.

Here, we give indicative CPU times for some settings, referring to a
Windows 10 Pro x64 laptop with Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz,
4-core, 8 logical processors, and 32GB RAM. \cr:
CPU time:\cr
d = 100 or m = 10, p = 1: ~  0.4s \cr
d = 900 or m = 30, p = 1: ~  6.0s \cr
d = 900 or m = 30, p = 5: ~ 47.0s \cr
d = 2500 or m = 50, p = 1: ~100.0s
}
\note{
While all the advection types can be applied to isotropic random fields,
anisotropic random fields require more care. We suggest combining \code{affine}
anysotropy with \code{uniform} advection, and \code{swirl} anisotropy
with \code{rotation} or \code{spiral} advection with the same rotation center..\cr
Concerning the Bardossy model, the increase of the parameter \code{m}
leads to a more and more symmetrical copula, and if \code{m} tends to \code{Inf},
then the copula converges to the Gaussian copula. The \code{bardossy} model is
characterized by lower tail dependence weaker than the upper tail dependence, while the
flipped Bárdossy dependence structure, denoted as  \code{bardossyF}, has lower tail
dependence stronger than the upper tail dependence.
See Bárdossy (2006) for more details about the properties and
parametrization of the multivariate Bardossy distribution
}
\examples{
## for multivariate simulation
coord <- cbind(runif(4)*30, runif(4)*30)

fit <- fitVAR(
  spacepoints = coord,
  p = 1,
  margdist ='burrXII',
  margarg = list(scale = 3,
                 shape1 = .9,
                 shape2 = .2),
  p0 = 0.8,
  stcsid = "clayton",
  stcsarg = list(scfid = "weibull",
                 tcfid = "weibull",
                 copulaarg = 2,
                 scfarg = list(scale = 20,
                               shape = 0.7),
                 tcfarg = list(scale = 1.1,
                               shape = 0.8))
)

dim(fit$alpha)
dim(fit$res.cov)

fit$m
fit$margarg
fit$margdist

## for random fields simulation
fit <- fitVAR(
  spacepoints = 10,
  p = 1,
  margdist ='burrXII',
  margarg = list(scale = 3, shape1 = .9, shape2 = .2),
  p0 = 0.8,
  stcsid = "clayton",
  stcsarg = list(scfid = "weibull", tcfid = "weibull",
                 copulaarg = 2,
                 scfarg = list(scale = 20, shape = 0.7),
                 tcfarg = list(scale = 1.1, shape = 0.8))
)

dim(fit$alpha)
dim(fit$res.cov)

fit$m
fit$margarg
fit$margdist

}
\references{
Bárdossy, A. (2006), Copula-based geostatistical models for groundwater
quality parameters, Water Resour. Res., 42, W11416, \doi{10.1029/2005WR004754}

Biller, B., Nelson, B.L. (2003). Modeling and generating multivariate
time-series input processes using a vector autoregressive technique.
ACM Trans. Model. Comput. Simul. 13(3), 211-237, \doi{10.1145/937332.937333}

Papalexiou, S.M. (2018). Unified theory for stochastic modelling of
hydroclimatic processes: Preserving marginal distributions, correlation structures,
and intermittency. Advances in Water Resources, 115, 234-252,
\doi{10.1016/j.advwatres.2018.02.013}

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}

Papalexiou, S.M., Serinaldi, F., Porcu, E. (2021). Advancing
Space-Time Simulation of Random Fields: From Storms to Cyclones and Beyond.
Water Resources Research, 57, e2020WR029466, \doi{10.1029/2020WR029466}
}
