% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate-multilevel.R
\name{simulate_dcvar_multilevel}
\alias{simulate_dcvar_multilevel}
\title{Simulate data from a multilevel copula VAR(1) model}
\usage{
simulate_dcvar_multilevel(
  N = 40,
  n_time = 100,
  phi_bar = c(0.3, 0.1, 0.1, 0.3),
  tau_phi = c(0.1, 0.05, 0.05, 0.1),
  sigma = c(1, 1),
  rho = 0.3,
  margins = "normal",
  skew_direction = NULL,
  skew_params = NULL,
  phi_trajectory = NULL,
  sigma_trajectory = NULL,
  tv_sigma_k = NULL,
  burnin = 30,
  center = TRUE,
  seed = NULL
)
}
\arguments{
\item{N}{Number of units.}

\item{n_time}{Number of time points per unit.}

\item{phi_bar}{Population mean for VAR coefficients (length-4 vector:
phi11, phi12, phi21, phi22).}

\item{tau_phi}{Population SD for each VAR coefficient (length-4 vector).}

\item{sigma}{Innovation scale vector (length 2). Values are on each
family's natural residual scale: innovation SD for normal/skew-normal,
\code{sigma_exp} for exponential, and \code{sigma_gam} for gamma.}

\item{rho}{Global copula correlation.}

\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 \code{1}/\code{-1} vector. Required whenever any
dimension uses an \code{"exponential"} or \code{"gamma"} margin.}

\item{skew_params}{Named list of margin-specific parameters: \code{alpha}
(length-2 skew-normal shape) and/or \code{shape} (scalar gamma shape).}

\item{phi_trajectory}{Optional population-level time-varying VAR coefficient
path. Unit-specific coefficients follow this shared drift around their
sampled baselines.}

\item{sigma_trajectory}{Optional shared time-varying innovation scale path.
The supplied value is each family's natural scale (innovation SD for
normal, residual SD for skew-normal, \code{sigma_exp} / \code{sigma_gam} for
exponential / gamma).}

\item{tv_sigma_k}{Soft-barrier sharpness for time-varying exponential/gamma
scales.}

\item{burnin}{Number of burn-in observations to discard (default: 30).}

\item{center}{Logical; person-mean center the data (default: \code{TRUE}).}

\item{seed}{Random seed for reproducibility.}
}
\value{
A named list with:
\itemize{
\item \code{data}: panel data frame with columns \code{id}, \code{time}, \code{y1}, \code{y2}
\item \code{true_params}: list of true parameter values, including \code{phi_bar},
\code{tau_phi}, \code{sigma}, \code{rho}, \code{margins}, \code{skew_direction}, \code{skew_params},
the per-unit VAR coefficients \code{Phi_mat} (an \verb{N x 4} matrix) and
\code{Phi_list} (a length-\code{N} list of \verb{2 x 2} matrices), \code{Phi_population}
(the shared population VAR path: \code{phi_bar} when constant, or an
\verb{(n_time - 1) x 4} matrix when \code{phi_trajectory} is supplied), and
\code{Phi_unit_paths} (a length-\code{N} list of per-unit effective coefficient
paths, each \verb{(n_time - 1) x 4})
\item \code{person_means}: N x 2 matrix of person means (before centering)
}
}
\description{
Generates panel data with unit-specific VAR coefficients drawn from
a population distribution and a global copula correlation. The simulator
matches the fitted multilevel model support by leaving unit-level VAR
matrices unconstrained; nonstationary draws are possible.
}
