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.
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")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)| Model | Function | Dependence Structure | Status |
|---|---|---|---|
| DC-VAR | dcvar() |
Continuous random-walk on Fisher-z scale | Core |
| HMM Copula | dcvar_hmm() |
Discrete regime-switching with K states | Core |
| Constant Copula | dcvar_constant() |
Time-invariant Gaussian or Clayton baseline | Core |
| Multilevel | dcvar_multilevel() |
Random VAR coefficients for panel data | Experimental |
| SEM | dcvar_sem() |
Fixed measurement model for latent processes | Experimental |
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.
If you use dcvar in your work, cite it with:
citation("dcvar")