CoSMoS (version 2.2.0)

generateTS: Generate time series

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.

Usage

generateTS(
  n,
  margdist,
  margarg,
  p = NULL,
  p0 = 0,
  TSn = 1,
  distbounds = c(-Inf, Inf),
  acsvalue = NULL
)

Value

An object of class 'cosmosts': a list of TSn numeric vectors, each of length n, with per-series attributes recording the fitted model parameters.

Arguments

n

Positive integer. Length of the generated time series.

margdist

target marginal distribution

margarg

list of marginal distribution arguments

p

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

p0

probability zero

TSn

number of time series to generate

distbounds

numeric vector of length 2; distribution bounds (default c(-Inf, Inf))

acsvalue

Numeric vector. Target autocorrelation structure starting from lag 0 (i.e. acsvalue[1] = 1).

Details

A step-by-step guide:

• First define the target marginal (margdist), that is, the probability distribution of the generated data. For example set margdist = 'ggamma' for the Generalised Gamma distribution, margdist = 'burrXII' for Burr type XII etc. For a full list of supported distributions see the help vignette. In general, the package supports all built-in distribution functions of R and of other packages.

• Define the parameters (margarg) of the selected distribution. For example the Generalised Gamma has one scale and two shape parameters, e.g. margarg = list(scale = 2, shape1 = 0.9, shape2 = 0.8). See the help vignette for details on each distribution's parameters.

• If you wish your time series to be intermittent (e.g. precipitation), define the probability zero. For example p0 = 0.9 produces 90\

• Define your linear autocorrelations.

  • Supply specific lag autocorrelations starting from lag 0 up to a desired lag, e.g. 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.

  • Alternatively, use a parametric autocorrelation structure (see section 3.2 in Papalexiou (2018)). Supported structures: weibull, paretoII, fgn and burrXII. See also acs.

• Define the AR model order p. For example if you aim to preserve the first 10 lag autocorrelations then set p = 10. Set p = NULL and the model will choose p to preserve the whole autocorrelation structure.

• Set the time series length, e.g. n = 1000, and the number of time series to generate, e.g. TSn = 10.

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, tools:::Rd_expr_doi("10.1016/j.advwatres.2018.02.013")

See Also

regenerateTS, ARp, actpnts

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)

# }