% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ts_sim.R
\name{ts_sim}
\alias{ts_sim}
\title{Time series simulation with changepoint effects}
\usage{
ts_sim(
  Ts,
  beta,
  XMat,
  sigma,
  phi = NULL,
  theta = NULL,
  d = 0,
  Delta = NULL,
  CpLoc = NULL,
  seed = NULL
)
}
\arguments{
\item{Ts}{A integer indicating simulated time series length (sample size).}

\item{beta}{A parameter vector contains other mean function parameters without changepoint parameters.}

\item{XMat}{The covairates for time series mean function without changepoint indicators.}

\item{sigma}{The standard deviation for time series residuals \eqn{\epsilon_{t}}.}

\item{phi}{A vector for the autoregressive (AR) parameters for AR part.}

\item{theta}{A vector for the moving average (MA) parameters for MA part.}

\item{d}{A nonnegative integer for the order of differencing in the ARIMA model. Default is 0, which reduces to an ARMA model.}

\item{Delta}{The parameter vector contains the changepoint parameters for time series mean function.}

\item{CpLoc}{A vector contains the changepoint locations range from \eqn{1\leq\tau\leq T_{s}}.}

\item{seed}{The random seed for simulation reproducibility.}
}
\value{
The simulated time series with attributes:
\itemize{
  \item \code{DesignX}: The covariates including changepoint indicators.
  \item \code{mu}: The mean vector for the simulated time series.
  \item \code{theta}: The true parameter vector including changepoint effects.
  \item \code{CpEff}: The true changepoint magnitudes.
  \item \code{CpLoc}: The true changepoint locations.
  \item \code{arEff}: The AR coefficients.
  \item \code{maEff}: The MA coefficients.
  \item \code{diffEff}: The differencing order.
  \item \code{seed}: The random seed used for simulation.
}
}
\description{
This is a function to simulate time series with changepoint effects. See
details below.
}
\details{
The simulated time series \eqn{Z_t, t = 1, \ldots, T_s} is generated from
\deqn{Z_t = \mu_t + e_t.}

The error process \eqn{e_t} can be:
\itemize{
  \item IID Gaussian noise when \code{phi = NULL}, \code{theta = NULL},
    and \code{d = 0}.
  \item An ARMA(p,q) process when \code{d = 0} and at least one of
    \code{phi} or \code{theta} is specified.
  \item An ARIMA(p,d,q) process when \code{d > 0}.
}

The mean structure \eqn{\mu_t} is specified through \code{XMat} and
\code{beta}, and changepoint effects can be introduced as
\deqn{\mu_t = X_t^\top \beta + \Delta_1 I(t \ge \tau_1) + \cdots +
\Delta_m I(t \ge \tau_m),}
where \eqn{1 \le \tau_1 < \cdots < \tau_m \le T_s} are changepoint
locations and \eqn{\Delta_1, \ldots, \Delta_m} are changepoint magnitudes.
}
\examples{
##### M1: Time series observations are IID
Ts <- 1000
betaT <- c(0.5)
XMatT <- matrix(1, nrow = Ts, ncol = 1)
colnames(XMatT) <- "intercept"
sigmaT <- 1
DeltaT <- c(2, -2)
Cpprop <- c(1 / 4, 3 / 4)
CpLocT <- floor(Ts * Cpprop)

myts <- ts_sim(
  Ts = Ts, beta = betaT, XMat = XMatT, sigma = sigmaT,
  Delta = DeltaT, CpLoc = CpLocT, seed = 1234
)

##### M2: ARMA(2,1) model with constant mean
Ts <- 1000
betaT <- c(0.5)
XMatT <- matrix(1, nrow = Ts, ncol = 1)
colnames(XMatT) <- "intercept"
sigmaT <- 1
phiT <- c(0.5, -0.5)
thetaT <- c(0.8)
DeltaT <- c(2, -2)
CpLocT <- floor(Ts * c(1 / 4, 3 / 4))

myts <- ts_sim(
  Ts = Ts, beta = betaT, XMat = XMatT, sigma = sigmaT,
  phi = phiT, theta = thetaT, d = 0,
  Delta = DeltaT, CpLoc = CpLocT, seed = 1234
)

##### M3: ARIMA(1,1,1) model with changepoint effects
Ts <- 1000
betaT <- c(0.5)
XMatT <- matrix(1, nrow = Ts, ncol = 1)
colnames(XMatT) <- "intercept"
sigmaT <- 1
phiT <- c(0.5)
thetaT <- c(-0.3)
DeltaT <- c(2, -2)
CpLocT <- floor(Ts * c(1 / 4, 3 / 4))

myts <- ts_sim(
  Ts = Ts, beta = betaT, XMat = XMatT, sigma = sigmaT,
  phi = phiT, theta = thetaT, d = 1,
  Delta = DeltaT, CpLoc = CpLocT, seed = 1234
)
}
