CoSMoS (version 2.2.0)

analyzeTS: Analyse, report, and simulate seasonal time series

Description

analyzeTS automatically performs seasonal analysis, fits distributions and correlation structures. reportTS visualises the fitted distributions and correlation structures, or returns a table of fitted parameters and descriptive statistics. simulateTS takes the result of analyzeTS and generates synthetic realisations.

Usage

analyzeTS(
  TS,
  season = "month",
  dist = "ggamma",
  acsID = "weibull",
  norm = "N1",
  n.points = 30,
  lag.max = 30,
  constrain = FALSE,
  opts = NULL
)
reportTS(aTS, method = "dist")
simulateTS(aTS, from = NULL, to = NULL)

Value

• analyzeTS: a list with elements data, dfits, afits, and attributes season, dist, acsID, date

• reportTS: a ggplot object ("dist" or "acs" method) or a data.frame ("stat" method)

• simulateTS: a data.table with columns date and value

Arguments

TS

data frame or data table with columns date and value

season

character; name of a date-component function (e.g. "month", "week")

dist

character; name of the distribution to fit (e.g. "norm", "ggamma")

acsID

character; ACS identifier passed to fitACS

norm

character; norm identifier — one of "N1", "N2", "N3", "N4"

n.points

integer; number of ECDF points used in the norm computation

lag.max

integer; maximum lag for the empirical ACF

constrain

logical; if TRUE, constrains shape2 parameters to (0, 0.48) to enforce finite upper tails

opts

list of nloptr minimisation options

aTS

an analyzeTS result object

method

character; report type — "dist" for distribution fits, "acs" for ACS fits, "stat" for descriptive statistics table

from

POSIXct; start of simulation period (defaults to start of observed series)

to

POSIXct; end of simulation period (defaults to end of observed series)

Details

In practice, we typically want to simulate a natural process from observed data. analyzeTS fits a marginal distribution and autocorrelation structure for each season; reportTS lets you inspect the fit; simulateTS generates synthetic time series with the same seasonal statistical properties.

Recommended distributions by variable type:

• precipitation / streamflow: ggamma, burrXII, burrIII

• relative humidity: beta

• temperature: norm

See Also

fitDist, fitACS, generateTS

Examples

library(CoSMoS)

## Load data included in the package
data("precip")
# \donttest{
## Fit seasonal ACSs and distributions to the data
a <- analyzeTS(precip)

reportTS(a, "dist")  ## seasonal distribution fits
reportTS(a, "acs")   ## seasonal ACS fits
reportTS(a, "stat")  ## descriptive statistics

## Simulate a time series of the same length
sim <- simulateTS(a)

precip[, id := "observed"]
sim[, id := "simulated"]
dta <- rbind(precip, sim)

ggplot(dta) +
  geom_line(aes(x = date, y = value)) +
  facet_wrap(~id, ncol = 1) +
  theme_classic()

## Simulate a time series of different length
sim <- simulateTS(a,
                  from = as.POSIXct("1978-12-01 00:00:00"),
                  to   = as.POSIXct("2008-12-01 00:00:00"))
# }
# \dontshow{
precip <- precip[between(date,
  as.POSIXct("1990-1-01", format("%Y-%m-%d"), tz = "America/Regina"),
  as.POSIXct("1990-1-5",  format("%Y-%m-%d"), tz = "America/Regina"))]
a <- analyzeTS(precip, opts = list("algorithm" = "NLOPT_LN_NELDERMEAD",
                                   "maxeval" = 10))
# }