% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit-covariate.R
\name{dcvar_covariate}
\alias{dcvar_covariate}
\title{Fit the covariate DC-VAR model}
\usage{
dcvar_covariate(
  data,
  vars,
  covariates,
  time_var = "time",
  standardize = TRUE,
  standardize_covariates = FALSE,
  drift = TRUE,
  zero_init_eta = TRUE,
  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,
  prior_beta_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{covariates}{Character vector of covariate column names.}

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

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

\item{standardize_covariates}{Logical; whether to z-score covariates
(default: \code{FALSE}).}

\item{drift}{Logical; if \code{TRUE} (default), include residual random-walk drift
after the covariate effect. If \code{FALSE}, fit the no-drift sensitivity model.}

\item{zero_init_eta}{Logical; if \code{TRUE} (default), fixes \code{eta[1] = 0} in the
residual-drift model.}

\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 the dependence intercept \code{beta_0} on
the Fisher-z scale (the covariate model has no separate initial-rho
parameter; \code{beta_0} plays that role).}

\item{prior_beta_sd}{Prior SD for covariate effects.}

\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. 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. \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_covariate_fit} object.
}
\description{
Fits a Gaussian Dynamic Copula VAR(1) model in which contemporaneous
innovation dependence varies on the Fisher-z scale as a function of observed
covariates. With \code{drift = TRUE}, the model adds residual random-walk drift:
\verb{zeta_i = beta_0 + x_\{i+1\}' beta + eta_i}. With \code{drift = FALSE}, the
dependence trajectory is explained entirely by the covariates.
}
\examples{
\donttest{
sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_step(12),
  seed = 1
)
sim$Y_df$phase <- as.numeric(sim$Y_df$time > 6)
fit <- dcvar_covariate(
  sim$Y_df,
  vars = c("y1", "y2"),
  covariates = "phase",
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
covariate_effects(fit)

fit_nodrift <- dcvar_covariate(
  sim$Y_df,
  vars = c("y1", "y2"),
  covariates = "phase",
  drift = FALSE,
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
rho_trajectory(fit_nodrift)
}
}
\seealso{
\code{\link[=prepare_dcvar_covariate_data]{prepare_dcvar_covariate_data()}}, \code{\link[=covariate_effects]{covariate_effects()}},
\code{\link[=rho_trajectory]{rho_trajectory()}}, and \code{\link[=dcvar]{dcvar()}} for the covariate-free random-walk model.
}
