% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generate-ts.R
\name{generateTS}
\alias{generateTS}
\title{Generate time series}
\usage{
generateTS(
  n,
  margdist,
  margarg,
  p = NULL,
  p0 = 0,
  TSn = 1,
  distbounds = c(-Inf, Inf),
  acsvalue = NULL
)
}
\arguments{
\item{n}{Positive integer. Length of the generated time series.}

\item{margdist}{target marginal distribution}

\item{margarg}{list of marginal distribution arguments}

\item{p}{Positive integer or \code{NULL}. AR model order. When
\code{NULL} (default), the order is chosen automatically as the number of
lags where the transformed ACS exceeds 0.01, capped at 1000.}

\item{p0}{probability zero}

\item{TSn}{number of time series to generate}

\item{distbounds}{numeric vector of length 2; distribution bounds (default
\code{c(-Inf, Inf)})}

\item{acsvalue}{Numeric vector. Target autocorrelation structure starting
from lag 0 (i.e. \code{acsvalue[1] = 1}).}
}
\value{
An object of class \code{'cosmosts'}: a list of \code{TSn} numeric
vectors, each of length \code{n}, with per-series attributes recording the
fitted model parameters.
}
\description{
Generates time series with given properties. Provide (1) the target marginal
distribution and its parameters, (2) the target autocorrelation structure or
individual autocorrelation values up to a desired lag, and (3) the probability
zero if you wish to simulate an intermittent process.
}
\details{
A step-by-step guide:
\itemize{
\item First define the target marginal (\code{margdist}), that is, the probability
distribution of the generated data. For example set \code{margdist = 'ggamma'}
for the Generalised Gamma distribution, \code{margdist = 'burrXII'} for Burr
type XII etc. For a full list of supported distributions see the help
\href{https://CRAN.R-project.org/package=CoSMoS/vignettes/vignette.html}{vignette}.
In general, the package supports all built-in distribution functions of R and
of other packages.
\item Define the parameters (\code{margarg}) of the selected distribution.
For example the Generalised Gamma has one scale and two shape parameters,
e.g. \code{margarg = list(scale = 2, shape1 = 0.9, shape2 = 0.8)}.
See the help vignette for details on each distribution's parameters.
\item If you wish your time series to be intermittent (e.g. precipitation), define
the probability zero. For example \code{p0 = 0.9} produces 90\\% zero values.
\item Define your linear autocorrelations.
\itemize{
\item Supply specific lag autocorrelations starting from lag 0 up to a desired
lag, e.g. \code{acsvalue = c(1, 0.9, 0.8, 0.7)}; this preserves lag-1,
lag-2 and lag-3 autocorrelations equal to 0.9, 0.8 and 0.7.
\item Alternatively, use a parametric autocorrelation structure (see section 3.2
in Papalexiou (2018)). Supported structures: \code{weibull}, \code{paretoII},
\code{fgn} and \code{burrXII}. See also \code{\link[CoSMoS]{acs}}.
}
\item Define the AR model order \code{p}. For example if you aim to preserve the
first 10 lag autocorrelations then set \code{p = 10}. Set \code{p = NULL} and
the model will choose \code{p} to preserve the whole autocorrelation structure.
\item Set the time series length, e.g. \code{n = 1000}, and the number of time
series to generate, e.g. \code{TSn = 10}.
}
}
\examples{

library(CoSMoS)

## Case 1:
## Generate 3 time series of length 1000 following the Generalised Gamma
## distribution with scale = 1, shape1 = 0.8, shape2 = 0.8 and ParetoII
## autocorrelation structure with scale = 1 and shape = 0.75.
x <- generateTS(margdist = "ggamma",
                margarg = list(scale = 1,
                               shape1 = .8,
                               shape2 = .8),
                acsvalue = acs(id = "paretoII",
                               t = 0:30,
                               scale = 1,
                               shape = .75),
                n = 1000,
                p = 30,
                TSn = 3)

## see the results
plot(x)

\donttest{

## Case 2:
## Same as Case 1 but intermittent with probability zero equal to 90\%.
y <- generateTS(margdist = "ggamma",
                margarg = list(scale = 1,
                               shape1 = .8,
                               shape2 = .8),
                acsvalue = acs(id = "paretoII",
                               t = 0:30,
                               scale = 1,
                               shape = .75),
                p0 = .9,
                n = 1000,
                p = 30,
                TSn = 3)

## see the results
plot(y)

## Case 3:
## Generate a time series of length 1000 following the Beta distribution
## (e.g. relative humidity in [0, 1]) with shape1 = 0.6, shape2 = 0.8
## and ParetoII autocorrelation structure.
z <- generateTS(margdist = "beta",
                margarg = list(shape1 = .6,
                               shape2 = .8),
                distbounds = c(0, 1),
                acsvalue = acs(id = "paretoII",
                               t = 0:30,
                               scale = 1,
                               shape = .75),
                n = 1000,
                p = 20)

## see the results
plot(z)

## Case 4:
## Same as Case 3 but providing specific autocorrelation values for the
## first three lags (lag 1 to 3 equal to 0.9, 0.8, 0.7).
z <- generateTS(margdist = "beta",
                margarg = list(shape1 = .6,
                               shape2 = .8),
                distbounds = c(0, 1),
                acsvalue = c(1, .9, .8, .7),
                n = 1000,
                p = NULL)

## see the results
plot(z)

}

}
\references{
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}
}
\seealso{
\code{\link{regenerateTS}}, \code{\link{ARp}}, \code{\link{actpnts}}
}
