% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data-preparation.R
\name{prepare_dcvar_data}
\alias{prepare_dcvar_data}
\title{Prepare data for the DC-VAR model}
\usage{
prepare_dcvar_data(
  data,
  vars,
  time_var = "time",
  standardize = TRUE,
  margins = "normal",
  skew_direction = NULL,
  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,
  tv_phi = FALSE,
  tv_sigma = FALSE,
  prior_tau_phi_rate = 0.025,
  prior_tau_sigma_rate = 0.05,
  tv_sigma_k = 8,
  allow_gaps = FALSE
)
}
\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}{Marginal distribution specification. Either a single string
applied to both variables, or a length-2 character vector giving a
per-variable (mixed) margin (for example \code{c("normal", "exponential")}).
Each entry is one of \code{"normal"} (default), \code{"exponential"},
\code{"skew_normal"}, or \code{"gamma"}. When the two entries differ the returned
data carries an integer \code{family} array for the generic mixed-margins Stan
model; identical entries are equivalent to the scalar form and reuse the
specialised single-family model.}

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

\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:
\code{sigma_eps ~ exponential(1/prior_sigma_eps_rate)}. Default \code{1} gives
\code{exponential(1)} with prior mean 1.}

\item{prior_sigma_omega_rate}{Prior mean for rho process SD:
\code{sigma_omega ~ exponential(1/prior_sigma_omega_rate)}. Default \code{0.1} gives
\code{exponential(10)} with prior mean 0.1.}

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

\item{tv_phi}{Selects which VAR(1) coefficients evolve as random walks
around the constant baseline \code{Phi}. Either a logical (\code{TRUE} = all four,
\code{FALSE} = none, the default) or a character selector: \code{"ar"} (the
autoregressive effects phi11, phi22), \code{"cross"} (the cross-lagged effects
phi12, phi21), or specific names from
\code{c("phi11", "phi12", "phi21", "phi22")}.}

\item{tv_sigma}{Logical; if \code{TRUE}, the residual scales evolve as log-scale
random walks around their constant baselines (default: \code{FALSE}). Applies
to all margin families; exponential and gamma dimensions use a
soft-barrier construction (see \code{\link[=dcvar]{dcvar()}}).}

\item{prior_tau_phi_rate}{Prior mean for the four Phi random-walk
innovation SDs: \code{tau_phi ~ exponential(1/prior_tau_phi_rate)}. Only used
when \code{tv_phi = TRUE}. The default \code{0.025} allows a total drift SD of
about 0.3 over 150 time points while shrinking toward constant
coefficients.}

\item{prior_tau_sigma_rate}{Prior mean for the per-dimension log-scale
random-walk innovation SDs:
\code{tau_sigma ~ exponential(1/prior_tau_sigma_rate)}. Only used when
\code{tv_sigma = TRUE}. The default \code{0.05} allows scale factors of roughly
0.5--2 over 150 time points.}

\item{tv_sigma_k}{Soft-barrier sharpness for time-varying exponential/gamma
scales (default \code{8}); see \code{\link[=dcvar]{dcvar()}}.}

\item{allow_gaps}{Logical; if \code{FALSE} (default), interior missing values
cause an error. If \code{TRUE}, they produce a warning and are removed.}
}
\value{
A named list suitable as Stan data input.
}
\description{
Transforms a data frame into a list suitable for the DC-VAR Stan model.
Handles sorting, missing values, and optional standardization.
}
\section{Prior naming conventions}{

Parameters ending in \verb{_sd} specify normal prior standard deviations
(location parameters). Parameters ending in \verb{_rate} specify exponential
prior means (scale parameters), where the exponential rate is
\verb{1/prior_*_rate}. The constant and HMM models use \code{prior_z_rho_sd}
(normal prior on the Fisher-z scale), while the DC-VAR model uses
\code{prior_sigma_omega_rate} (exponential prior on the random-walk SD)
because the two quantities have fundamentally different roles.
}

