% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit-multilevel.R
\name{dcvar_multilevel}
\alias{dcvar_multilevel}
\title{Fit an experimental multilevel copula VAR(1) model}
\usage{
dcvar_multilevel(
  data,
  vars,
  id_var = "id",
  time_var = "time",
  center = TRUE,
  margins = "normal",
  skew_direction = NULL,
  prior_phi_bar_sd = 0.5,
  prior_tau_phi_scale = 0.2,
  prior_sigma_sd = 1,
  prior_rho_sd = 0.5,
  tv_phi = FALSE,
  tv_sigma = FALSE,
  prior_tau_phi_rate = 0.025,
  prior_tau_sigma_rate = 0.05,
  tv_sigma_k = 8,
  chains = 4,
  iter_warmup = 2000,
  iter_sampling = 4000,
  adapt_delta = 0.9,
  max_treedepth = 14,
  seed = NULL,
  cores = NULL,
  refresh = 500,
  init = NULL,
  stan_file = NULL,
  backend = getOption("dcvar.backend", "auto"),
  ...
)
}
\arguments{
\item{data}{A data frame in long (panel) format with columns for unit ID,
time, and two outcome variables.}

\item{vars}{Character vector of two variable names to model.}

\item{id_var}{Name of the unit/person ID column (default: \code{"id"}).}

\item{time_var}{Name of the time column (default: \code{"time"}).}

\item{center}{Logical; whether to person-mean center the data
(default: \code{TRUE}). The bundled multilevel Stan model requires
\code{center = TRUE}; set \code{center = FALSE} only with a custom
\code{stan_file} that includes intercept terms.}

\item{margins}{Marginal distribution specification. A single string applies
the same family to both variables. A length-2 character vector gives a
per-variable (mixed) margin (for example \code{c("normal", "gamma")}). Normal,
exponential, skew-normal, and gamma margins are supported; homogeneous
skew-normal/gamma and per-variable specs route through the generic
mixed-margin Stan model under the Gaussian copula.}

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

\item{prior_phi_bar_sd}{Prior SD for population-mean VAR coefficients.}

\item{prior_tau_phi_scale}{Prior scale for half-t(3) on tau_phi.}

\item{prior_sigma_sd}{Prior SD for the innovation scales. For normal
margins this is the SD of a half-normal prior on \code{sigma}; for
exponential/gamma margins it is the SD of the lognormal prior on the
marginal scale.}

\item{prior_rho_sd}{Prior SD for normal on rho.}

\item{tv_phi}{Selects which population VAR(1) coefficients carry a shared
time-varying drift around the unit-specific baselines. Either a logical
scalar or a character selector as in \code{\link[=dcvar]{dcvar()}}.}

\item{tv_sigma}{Logical; if \code{TRUE}, residual scales evolve as shared
log-scale random walks across time.}

\item{prior_tau_phi_rate}{Prior mean for the time-drift Phi random-walk
innovation SDs.}

\item{prior_tau_sigma_rate}{Prior mean for log-scale random-walk innovation
SDs.}

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

\item{chains}{Number of MCMC chains.}

\item{iter_warmup}{Warmup iterations per chain.}

\item{iter_sampling}{Sampling iterations per chain.}

\item{adapt_delta}{Target acceptance rate.}

\item{max_treedepth}{Maximum tree depth.}

\item{seed}{Random seed. When supplied, it seeds both the Stan sampler and
the default per-chain initial values, so repeated fits are reproducible.}

\item{cores}{Number of parallel chains.}

\item{refresh}{How often to print progress.}

\item{init}{Custom init function or \code{NULL}.}

\item{stan_file}{Custom Stan file path or \code{NULL}.}

\item{backend}{Character: \code{"auto"} (default, uses rstan), \code{"rstan"}, or
\code{"cmdstanr"}. Can also be set globally via
\code{options(dcvar.backend = "cmdstanr")}.}

\item{...}{Additional backend-specific sampling arguments.}
}
\value{
A \code{dcvar_multilevel_fit} object.
}
\description{
Fits a hierarchical copula VAR(1) model with unit-specific VAR coefficients
(random effects) and a global copula correlation. Uses non-centered
parameterization for the random Phi coefficients.
}
\details{
\strong{Experimental extension.} This multilevel variant supports
\code{fitted()} and \code{predict()}. PSIS-LOO is available for all multilevel
fits; the stored \code{log_lik} values are conditional one-step-ahead
densities given the unit-level random effects. PIT diagnostics are not yet implemented.

\code{adapt_delta} defaults to 0.90 and \code{max_treedepth} to 14 because the
hierarchical structure with random effects benefits from deeper trees but
does not require aggressive step-size adaptation.
}
\note{
The bundled multilevel Stan program is defined for person-mean
centered data and omits intercept terms. With the bundled model,
\code{center = FALSE} is therefore not supported.
}
\seealso{
\code{\link[=random_effects]{random_effects()}} for extracting unit-specific coefficients,
\code{\link[=simulate_dcvar_multilevel]{simulate_dcvar_multilevel()}} for data generation.
}
