% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/seasonal.R
\name{analyzeTS}
\alias{analyzeTS}
\alias{reportTS}
\alias{simulateTS}
\title{Analyse, report, and simulate seasonal time series}
\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)
}
\arguments{
\item{TS}{data frame or data table with columns \code{date} and \code{value}}

\item{season}{character; name of a date-component function
(e.g. \code{"month"}, \code{"week"})}

\item{dist}{character; name of the distribution to fit (e.g. \code{"norm"},
\code{"ggamma"})}

\item{acsID}{character; ACS identifier passed to \code{\link{fitACS}}}

\item{norm}{character; norm identifier — one of \code{"N1"}, \code{"N2"},
\code{"N3"}, \code{"N4"}}

\item{n.points}{integer; number of ECDF points used in the norm computation}

\item{lag.max}{integer; maximum lag for the empirical ACF}

\item{constrain}{logical; if \code{TRUE}, constrains \code{shape2} parameters
to \code{(0, 0.48)} to enforce finite upper tails}

\item{opts}{list of \code{nloptr} minimisation options}

\item{aTS}{an \code{analyzeTS} result object}

\item{method}{character; report type — \code{"dist"} for distribution fits,
\code{"acs"} for ACS fits, \code{"stat"} for descriptive statistics table}

\item{from}{POSIXct; start of simulation period (defaults to start of
observed series)}

\item{to}{POSIXct; end of simulation period (defaults to end of observed
series)}
}
\value{
\itemize{
\item \code{analyzeTS}: a list with elements \code{data}, \code{dfits},
\code{afits}, and attributes \code{season}, \code{dist}, \code{acsID},
\code{date}
\item \code{reportTS}: a \code{ggplot} object (\code{"dist"} or \code{"acs"}
method) or a \code{data.frame} (\code{"stat"} method)
\item \code{simulateTS}: a \code{data.table} with columns \code{date} and
\code{value}
}
}
\description{
\code{analyzeTS} automatically performs seasonal analysis, fits distributions
and correlation structures. \code{reportTS} visualises the fitted
distributions and correlation structures, or returns a table of fitted
parameters and descriptive statistics. \code{simulateTS} takes the result of
\code{analyzeTS} and generates synthetic realisations.
}
\details{
In practice, we typically want to simulate a natural process from observed
data. \code{analyzeTS} fits a marginal distribution and autocorrelation
structure for each season; \code{reportTS} lets you inspect the fit;
\code{simulateTS} generates synthetic time series with the same seasonal
statistical properties.

Recommended distributions by variable type:
\itemize{
\item \emph{precipitation / streamflow}: \code{ggamma}, \code{burrXII}, \code{burrIII}
\item \emph{relative humidity}: \code{beta}
\item \emph{temperature}: \code{norm}
}
}
\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))
}

}
\seealso{
\code{\link{fitDist}}, \code{\link{fitACS}}, \code{\link{generateTS}}
}
