% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit-hmm.R
\name{dcvar_hmm}
\alias{dcvar_hmm}
\title{Fit the HMM copula model}
\usage{
dcvar_hmm(
  data,
  vars,
  K = 2,
  time_var = "time",
  standardize = TRUE,
  margins = "normal",
  skew_direction = NULL,
  switch = "rho",
  allow_gaps = FALSE,
  prior_mu_sd = 2,
  prior_phi_sd = 0.5,
  prior_sigma_eps_rate = 1,
  prior_kappa = 10,
  prior_alpha_off = 1,
  prior_z_rho_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{K}{Number of hidden states (default: 2).}

\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, a length-2 character vector giving a per-variable
(mixed) margin, e.g. \code{c("normal", "exponential")}, or -- for a state-specific
family -- a length-\code{K} list of such specifications, one per hidden state,
e.g. \code{list(c("normal", "normal"), c("exponential", "gamma"))}. Each entry is
one of \code{"normal"} (default), \code{"exponential"}, \code{"skew_normal"}, or \code{"gamma"}.
A per-state list is consumed in increasing-\code{rho} order.}

\item{skew_direction}{Skew direction for asymmetric margins: each element \code{1}
(right-skewed) or \code{-1} (left-skewed). A length-2 vector (recycled across
states) or, for per-state margins, a length-\code{K} list of length-2 vectors.
Required whenever any (state, dimension) uses an \code{"exponential"} or
\code{"gamma"} margin; only those entries consult it.}

\item{switch}{Which parameters become state-specific. \code{"rho"} (default) keeps
only the copula correlation switching (the classic HMM). A character vector
drawn from \code{c("rho", "mu", "phi", "ar", "cross", "sigma")} (with \code{"ar"} /
\code{"cross"} / coefficient names like \code{"phi11"} selecting a subset of the VAR
coefficients), or \code{TRUE} for everything. \code{rho} must be included whenever any
other component switches (it is the label-switching anchor).}

\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_kappa}{Sticky Dirichlet self-transition concentration (default: 10).}

\item{prior_alpha_off}{Sticky Dirichlet off-diagonal concentration (default: 1).}

\item{prior_z_rho_sd}{Prior SD for state-specific z_rho (default: 1.0).}

\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_hmm_fit} object.
}
\description{
Fits a Hidden Markov Model copula VAR(1) with K discrete states and
state-specific correlations. Uses ordered z_rho constraint to prevent
label switching and a sticky Dirichlet prior to encourage state persistence.
}
\section{State-specific parameters and per-state margins}{

By default only the copula correlation switches by state. The \code{switch}
argument turns a full Markov-switching VAR on: the intercepts, the VAR
coefficients, and the residual scales can each be made state-specific. The
marginal \strong{family} can also switch by state by passing a length-\code{K}
\code{margins} list. Because the states are identified by an ordered correlation
(\code{z_rho}), \code{rho} is the mandatory anchor and a per-state \code{margins} list is
consumed in increasing-correlation order (\code{margins[[1]]} is the lowest-rho
state). Richly-parameterized configurations on a single short bivariate series
are weakly identified; fit a ladder (\code{switch = "rho"} ->
\code{switch = c("rho", "ar")} -> full) and widen \code{prior_phi_sd}. See
\code{\link[=hmm_state_params]{hmm_state_params()}} for the per-state parameter view.
}

\examples{
\donttest{
sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_step(12),
  seed = 1
)
fit <- dcvar_hmm(
  sim$Y_df,
  vars = c("y1", "y2"),
  K = 2,
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
print(fit)
hmm_states(fit)
}
}
\seealso{
\code{\link[=dcvar]{dcvar()}} for the smooth time-varying model,
\code{\link[=dcvar_constant]{dcvar_constant()}} for the time-invariant baseline,
\code{\link[=hmm_states]{hmm_states()}} for state extraction, \code{\link[=plot_hmm_states]{plot_hmm_states()}} for visualisation,
\code{\link[=dcvar_compare]{dcvar_compare()}} for LOO-CV model comparison.
}
