% 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,
  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}{Character string specifying the marginal distribution.
One of \code{"normal"} (default) or \code{"exponential"}.}

\item{skew_direction}{Integer vector of length 2 indicating skew direction
for exponential margins. Required when \code{margins = "exponential"}.}

\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 half-normal on innovation SDs.}

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

\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.}

\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 exponential-margin
multilevel fits. 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{
This model currently supports normal and exponential margins.

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.
}
