% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate.R
\name{simulate_dcvar}
\alias{simulate_dcvar}
\title{Simulate data from a copula VAR(1) model}
\usage{
simulate_dcvar(
  n_time,
  rho_trajectory,
  mu = c(0, 0),
  Phi = matrix(c(0.3, 0.1, 0.1, 0.3), 2, 2),
  sigma_eps = c(1, 1),
  margins = "normal",
  skew_direction = NULL,
  skew_params = NULL,
  phi_trajectory = NULL,
  sigma_trajectory = NULL,
  tv_sigma_k = NULL,
  seed = NULL
)
}
\arguments{
\item{n_time}{Number of time points.}

\item{rho_trajectory}{Numeric vector of length \code{n_time - 1} specifying the
correlation at each time step. Use \code{\link[=rho_constant]{rho_constant()}}, \code{\link[=rho_decreasing]{rho_decreasing()}},
etc.}

\item{mu}{Intercept vector of length 2 (default: \code{c(0, 0)}).}

\item{Phi}{VAR(1) coefficient matrix, 2x2 (default:
\code{matrix(c(0.3, 0.1, 0.1, 0.3), 2, 2)}).}

\item{sigma_eps}{Innovation standard deviations, length 2 (default:
\code{c(1, 1)}). Used for normal margins.}

\item{margins}{Marginal family. Either a single string applied to both
variables, or a length-2 character vector for per-variable (mixed) margins,
e.g. \code{c("normal", "exponential")}. Each entry is one of \code{"normal"}
(default), \code{"exponential"}, \code{"skew_normal"}, or \code{"gamma"}.}

\item{skew_direction}{Length-2 integer vector of +1/-1. Required whenever any
dimension uses an \code{"exponential"} or \code{"gamma"} margin; only those
dimensions consult it.}

\item{skew_params}{Named list of margin-specific parameters. \code{alpha}
(length-2 vector of skew-normal shape params) is used by skew-normal
dimensions; \code{shape} (scalar gamma shape parameter) is used by gamma
dimensions. Both may be supplied together for mixed margins.}

\item{phi_trajectory}{Optional time-varying VAR coefficient paths for data
matching \code{dcvar(tv_phi = TRUE)}: an \verb{(n_time - 1) x 4} matrix with
columns in row-major order (phi11, phi12, phi21, phi22), a list of 4
length-\code{(n_time - 1)} vectors (the \verb{rho_*} trajectory generators can be
reused per coefficient), or a constant \verb{2 x 2} matrix. Mutually exclusive
with \code{Phi}. \code{NULL} (default) keeps the constant \code{Phi}.}

\item{sigma_trajectory}{Optional time-varying residual scale paths for data
matching \code{dcvar(tv_sigma = TRUE)}: an \verb{(n_time - 1) x 2} positive matrix,
a list of 2 length-\code{(n_time - 1)} vectors, or a constant length-2 vector.
The scale is each family's natural scale (innovation SD for normal,
residual SD for skew-normal, \code{sigma_exp} / \code{sigma_gam} for
exponential / gamma). A non-constant path on an exponential or gamma
dimension requires \code{tv_sigma_k} (soft-barrier generative model). Mutually
exclusive with \code{sigma_eps}. \code{NULL} (default) keeps constant scales.}

\item{tv_sigma_k}{Soft-barrier sharpness for time-varying exponential/gamma
scales. Supply the same value as the intended \code{dcvar(tv_sigma = TRUE, tv_sigma_k = ...)} fit so the simulated data matches that likelihood.
\code{NULL} (default) uses the exact affine shifted margin and requires
constant exp/gamma scales.}

\item{seed}{Random seed for reproducibility.}
}
\value{
A named list with:
\itemize{
\item \code{Y}: \verb{n_time x 2} observation matrix
\item \code{Y_df}: data frame with columns \code{time}, \code{y1}, \code{y2} (ready for
\code{\link[=dcvar]{dcvar()}})
\item \code{true_params}: list of true parameter values. These are on the raw
data scale; the fitting functions standardize by default, so round-trip
comparisons of \code{mu}, \code{Phi}, and \code{sigma_eps} require fitting with
\code{standardize = FALSE} (the \code{rho} trajectory is scale-invariant).
Without \code{sigma_trajectory}, exponential and gamma dimensions are
simulated with unit-SD standardized innovations, so their implied true
scale (\code{sigma_exp}/\code{sigma_gam}) is 1. With trajectories supplied,
\code{Phi} is the \verb{(n_time - 1) x 4} coefficient path and \code{sigma} the
\verb{(n_time - 1) x 2} scale path.
}
}
\description{
Generates bivariate time series data with correlated innovations
driven by a specified rho trajectory.
}
\examples{
sim <- simulate_dcvar(n_time = 100, rho_trajectory = rho_decreasing(100))
head(sim$Y_df)
plot(sim$true_params$rho, type = "l")
}
