% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit-dcvar.R
\name{dcvar}
\alias{dcvar}
\title{Fit the DC-VAR model}
\usage{
dcvar(
  data,
  vars,
  time_var = "time",
  standardize = TRUE,
  margins = "normal",
  skew_direction = NULL,
  allow_gaps = FALSE,
  prior_mu_sd = 2,
  prior_phi_sd = 0.5,
  prior_sigma_eps_rate = 1,
  prior_sigma_omega_rate = 0.1,
  prior_rho_init_sd = 1,
  chains = 4,
  iter_warmup = 2000,
  iter_sampling = 4000,
  adapt_delta = 0.99,
  max_treedepth = 12,
  seed = NULL,
  cores = NULL,
  refresh = 500,
  init = NULL,
  stan_file = NULL,
  backend = getOption("dcvar.backend", "auto"),
  ...
)
}
\arguments{
\item{data}{A data frame with time series observations.}

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

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

\item{standardize}{Logical; whether to z-score variables (default: \code{TRUE}).}

\item{margins}{Character string specifying the marginal distribution.
One of \code{"normal"} (default), \code{"exponential"}, \code{"skew_normal"}, or \code{"gamma"}.}

\item{skew_direction}{Integer vector of length D indicating skew direction
for asymmetric margins. Each element must be \code{1} (right-skewed) or \code{-1}
(left-skewed). Required for \code{"exponential"} and \code{"gamma"} margins.}

\item{allow_gaps}{Logical; if \code{FALSE} (default), interior missing values
cause an error because they break VAR(1) time series adjacency. Set to
\code{TRUE} to allow fitting with a warning instead.}

\item{prior_mu_sd}{Prior SD for intercepts: \code{mu ~ normal(0, prior_mu_sd)}.}

\item{prior_phi_sd}{Prior SD for VAR coefficients: \code{Phi ~ normal(0, prior_phi_sd)}.}

\item{prior_sigma_eps_rate}{Prior mean for innovation SDs (see
\code{\link[=prepare_dcvar_data]{prepare_dcvar_data()}}).}

\item{prior_sigma_omega_rate}{Prior mean for rho process SD (see
\code{\link[=prepare_dcvar_data]{prepare_dcvar_data()}}).}

\item{prior_rho_init_sd}{Prior SD for initial rho on Fisher-z scale.}

\item{chains}{Number of MCMC chains (default: 4).}

\item{iter_warmup}{Warmup iterations per chain (default: 2000).}

\item{iter_sampling}{Sampling iterations per chain (default: 4000).}

\item{adapt_delta}{Target acceptance rate (default: 0.99). The DC-VAR model
uses a lower default than \code{dcvar_constant()} (0.999) because the
non-centered parameterisation already handles posterior geometry well.}

\item{max_treedepth}{Maximum tree depth (default: 12).}

\item{seed}{Random seed.}

\item{cores}{Number of parallel chains. \code{NULL} uses all available cores.}

\item{refresh}{How often to print progress (default: 500). Set to 0 for
silent operation.}

\item{init}{Custom init function or \code{NULL} for smart defaults.}

\item{stan_file}{Path to a custom Stan file, or \code{NULL} to use the bundled
model.}

\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_fit} object.
}
\description{
Fits a Dynamic Copula VAR(1) model with time-varying correlation following
a random walk on the Fisher-z scale. Uses non-centered parameterisation
for efficient HMC sampling.
}
\examples{
\donttest{
sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_decreasing(12),
  seed = 1
)
fit <- dcvar(
  sim$Y_df,
  vars = c("y1", "y2"),
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
print(fit)
summary(fit)
plot(fit)
}
}
\seealso{
\code{\link[=dcvar_constant]{dcvar_constant()}} for the time-invariant baseline,
\code{\link[=dcvar_hmm]{dcvar_hmm()}} for the regime-switching model,
\code{\link[=dcvar_compare]{dcvar_compare()}} for LOO-CV model comparison,
\code{\link[=rho_trajectory]{rho_trajectory()}} and \code{\link[=plot_rho]{plot_rho()}} for inspecting results.
}
