Dynamic Copula VAR Models for Time-Varying Dependence.

dcvar: Dynamic Copula VAR Models for Time-Varying Dependence

dcvar is an R package for fitting Bayesian copula VAR(1) models to bivariate time series. Most bundled models use Gaussian copulas; the constant-copula baseline also supports a Clayton copula with normal margins. The core scope is single-level dynamic, regime-switching, and constant-copula specifications, all estimated through Stan. The package also ships experimental multilevel and SEM extensions.

Installation

dcvar uses rstan as its default backend.

Install dcvar from CRAN:

install.packages("dcvar")

For the development version:

install.packages("remotes")
remotes::install_github("benlug/dcvar")

Optionally, you can use cmdstanr as an alternative backend:

install.packages(
  "cmdstanr",
  repos = c("https://stan-dev.r-universe.dev", getOption("repos"))
)
cmdstanr::install_cmdstan()

CI includes a dedicated Ubuntu release lane that runs the backend = "cmdstanr" regression tests when both cmdstanr and CmdStan are available.

For skew-normal margins, install sn:

install.packages("sn")

Example

The example below simulates a bivariate time series with decreasing dependence, fits the baseline DC-VAR model, and compares it to HMM and constant-copula alternatives.

library(dcvar)

# simulate data with decreasing coupling
sim <- simulate_dcvar(
  n_time = 150,
  rho_trajectory = rho_decreasing(150, rho_start = 0.7, rho_end = 0.3)
)

# fit the DC-VAR model
fit <- dcvar(sim$Y_df, vars = c("y1", "y2"))

# inspect results
summary(fit)
plot_rho(fit, true_rho = sim$true_params$rho)

# compare models via LOO-CV
fit_hmm <- dcvar_hmm(sim$Y_df, vars = c("y1", "y2"), K = 2)
fit_con <- dcvar_constant(sim$Y_df, vars = c("y1", "y2"))
dcvar_compare(dcvar = fit, hmm = fit_hmm, constant = fit_con)

Supported Models

Most models use Gaussian copulas. The core three time-series models (dcvar(), dcvar_hmm(), and dcvar_constant(copula = "gaussian")) support four marginal distributions: normal, exponential, skew-normal, and gamma. dcvar_constant(copula = "clayton") supports a Clayton-copula baseline with normal margins. The multilevel and SEM variants support normal and exponential margins.

If you are reading the accompanying manuscript, note that dcvar now includes the constant Clayton-copula baseline, the exponential-margin multilevel model, and naive SEM score models used in the simulation studies.

fitted() and predict() are implemented for the public fit classes. The multilevel methods return unit-specific trajectories and intervals; the SEM methods support both latent-state (type = "link") and indicator-scale (type = "response") summaries. pit_values() and pit_test() currently support the single-level models only. loo() supports single-level fits, covariate fits, exponential-margin multilevel fits, and naive SEM score fits. plot_ppc() is available for normal and exponential margins; gamma and skew-normal fits do not yet have replicated residuals on the observed margin scale.

pit_values() and pit_test() are approximate residual diagnostics based on posterior means. They are useful as heuristic checks, not exact posterior predictive calibration tests.

Documentation

• Getting started vignette: vignettes/getting-started.Rmd
• Model comparison vignette: vignettes/model-comparison.Rmd
• Simulation tools vignette: vignettes/simulation-tools.Rmd
• Full Quarto walkthrough: vignettes/dcvar-walkthrough.qmd
• Source code and issue tracker: https://github.com/benlug/dcvar

Citation

If you use dcvar in your work, cite it with:

citation("dcvar")

Getting Help

• Report bugs or request features at https://github.com/benlug/dcvar/issues
• For usage questions, include a minimal reproducible example when possible.