Package 'dcvar'

Description

Aggregate metrics across simulation replications

Usage

aggregate_metrics(metrics_list)

Arguments

Value

A named list with:

• rho: data frame of aggregated rho metrics (mean, SD, quantiles) for every field in the per-replication rho metric list

• n_reps: number of replications

Description

Returns the full parameter summary as a tidy data frame with correct 2.5%/97.5% quantiles.

Usage

## S3 method for class 'dcvar_model_fit'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame with columns variable, mean, sd, q2.5, q97.5, rhat, ess_bulk, ess_tail.

Description

Compute scalar parameter recovery metrics

Usage

compute_param_metrics(true_value, est_mean, est_lower, est_upper)

Arguments

Value

A named list with bias, relative_bias, covered, interval_width.

Description

Evaluates how well the estimated rho trajectory recovers the true values.

Usage

compute_rho_metrics(rho_true, rho_est, rho_lower, rho_upper)

Arguments

Value

A named list with:

• bias: mean bias

• relative_bias: mean relative bias (%)

• coverage: proportion of intervals containing true value

• interval_width: mean interval width

• correlation: Pearson correlation between true and estimated

• bias_start, bias_end: bias at first/last time point

• coverage_start, coverage_end: coverage at endpoints

Description

Returns posterior summaries for the Fisher-z intercept and covariate effects. The residual random-walk innovation scale sigma_omega is reported separately by var_params() for drift = TRUE fits.

Usage

covariate_effects(object, ...)

## Default S3 method:
covariate_effects(object, ...)

## S3 method for class 'dcvar_covariate_fit'
covariate_effects(object, probs = c(0.025, 0.5, 0.975), ...)

Arguments

Value

A data frame with one row per effect and columns term, variable, mean, sd, and one column per requested quantile.

Description

Fits a Dynamic Copula VAR(1) model with time-varying correlation following a random walk on the Fisher-z scale. Uses non-centered parameterisation for efficient HMC sampling.

Usage

dcvar(
  data,
  vars,
  time_var = "time",
  standardize = TRUE,
  margins = "normal",
  skew_direction = NULL,
  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,
  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

Value

A dcvar_fit object.

See Also

dcvar_constant() for the time-invariant baseline, dcvar_hmm() for the regime-switching model, dcvar_compare() for LOO-CV model comparison, rho_trajectory() and plot_rho() for inspecting results.

Examples

sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_decreasing(12),
  seed = 1
)
fit <- dcvar(
  sim$Y_df,
  vars = c("y1", "y2"),
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
print(fit)
summary(fit)
plot(fit)

Description

Convenience wrapper around loo::loo_compare() that accepts named dcvar model fits.

Usage

dcvar_compare(...)

Arguments

Value

A loo_compare matrix.

See Also

loo::loo_compare() for details on the comparison method, dcvar(), dcvar_hmm(), dcvar_constant() for fitting models.

Examples

sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_decreasing(12),
  seed = 1
)
fit_dcvar <- dcvar(
  sim$Y_df,
  vars = c("y1", "y2"),
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
fit_constant <- dcvar_constant(
  sim$Y_df,
  vars = c("y1", "y2"),
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
dcvar_compare(dcvar = fit_dcvar, constant = fit_constant)

Description

Fits a copula VAR(1) model with a single time-invariant correlation parameter. This serves as a baseline for comparison with the DC-VAR and HMM copula models.

Usage

dcvar_constant(
  data,
  vars,
  time_var = "time",
  standardize = TRUE,
  margins = "normal",
  copula = "gaussian",
  skew_direction = NULL,
  allow_gaps = FALSE,
  prior_mu_sd = 2,
  prior_phi_sd = 0.5,
  prior_sigma_eps_rate = 1,
  prior_z_rho_sd = 1,
  chains = 4,
  iter_warmup = 2000,
  iter_sampling = 4000,
  adapt_delta = 0.999,
  max_treedepth = 12,
  seed = NULL,
  cores = NULL,
  refresh = 500,
  init = NULL,
  stan_file = NULL,
  backend = getOption("dcvar.backend", "auto"),
  ...
)

Arguments

Details

adapt_delta defaults to 0.999 because the constant-rho model has a simpler correlation structure that benefits from tighter step-size adaptation without significant computational cost, reducing occasional divergences near the rho boundary.

Value

A dcvar_constant_fit object.

See Also

dcvar() for the time-varying model, dcvar_hmm() for the regime-switching model, dcvar_compare() for LOO-CV model comparison.

Examples

sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_constant(12, rho = 0.5),
  seed = 1
)
fit <- dcvar_constant(
  sim$Y_df,
  vars = c("y1", "y2"),
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
print(fit)

Description

S3 methods for dcvar_constant_fit objects

Usage

## S3 method for class 'dcvar_constant_fit'
print(x, ...)

## S3 method for class 'dcvar_constant_fit'
summary(object, probs = c(0.025, 0.5, 0.975), ...)

## S3 method for class 'dcvar_constant_fit'
coef(object, ...)

## S3 method for class 'dcvar_constant_fit'
plot(x, type = c("rho", "phi", "diagnostics", "ppc", "pit"), ...)

Arguments

Value

Invisibly returns x.

A dcvar_constant_summary object (a list).

A named list of posterior means: mu, Phi, margin-specific scale/shape parameters (e.g. sigma_eps for normal margins), and either rho (Gaussian copula) or theta (Clayton copula).

A ggplot object.

Functions

• print(dcvar_constant_fit): Print a concise overview of the constant copula fit.

• summary(dcvar_constant_fit): Produce a detailed summary including constant rho, VAR parameters, and diagnostics.

• coef(dcvar_constant_fit): Extract posterior means of model coefficients.

• plot(dcvar_constant_fit): Dispatch to a plot type: "rho", "phi", "diagnostics", "ppc", or "pit".

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 drift = TRUE, the model adds residual random-walk drift: ⁠zeta_i = beta_0 + x_{i+1}' beta + eta_i⁠. With drift = FALSE, the dependence trajectory is explained entirely by the covariates.

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

Value

A dcvar_covariate_fit object.

See Also

prepare_dcvar_covariate_data(), covariate_effects(), rho_trajectory(), and dcvar() for the covariate-free random-walk model.

Examples

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)

Description

S3 methods for covariate DC-VAR fits

Usage

## S3 method for class 'dcvar_covariate_fit'
print(x, ...)

## S3 method for class 'dcvar_covariate_fit'
summary(object, probs = c(0.025, 0.5, 0.975), ...)

## S3 method for class 'dcvar_covariate_fit'
coef(object, ...)

## S3 method for class 'dcvar_covariate_fit'
plot(x, type = c("rho", "phi", "diagnostics", "ppc", "pit"), ...)

Arguments

Value

Invisibly returns x.

A dcvar_covariate_summary object (a list).

A named list with elements mu, Phi, sigma_eps, beta_0, beta, and, when drift = TRUE, sigma_omega.

A ggplot object.

Functions

• print(dcvar_covariate_fit): Print a concise overview of the covariate DC-VAR fit.

• summary(dcvar_covariate_fit): Produce a detailed summary including rho trajectory, VAR parameters, covariate effects, and diagnostics.

• coef(dcvar_covariate_fit): Extract posterior means of model coefficients.

• plot(dcvar_covariate_fit): Dispatch to a plot type: "rho", "phi", "diagnostics", "ppc", or "pit".

Description

Returns a summary of sampling diagnostics including divergences, tree depth warnings, Rhat, and effective sample size. The convergence headline is computed from sampled parameters only and excludes generated quantities and deterministic transformed outputs.

Usage

dcvar_diagnostics(object, ...)

## Default S3 method:
dcvar_diagnostics(object, ...)

## S3 method for class 'dcvar_model_fit'
dcvar_diagnostics(object, ...)

Arguments

Value

A named list with:

• n_divergent: total number of divergent transitions

• n_max_treedepth: transitions hitting max tree depth

• max_rhat: worst (highest) Rhat across sampled parameters

• min_ess_bulk: smallest bulk ESS among sampled parameters

• min_ess_tail: smallest tail ESS among sampled parameters

• mean_accept_prob: mean acceptance probability

Description

S3 methods for dcvar_fit objects

Usage

## S3 method for class 'dcvar_fit'
print(x, ...)

## S3 method for class 'dcvar_fit'
summary(object, probs = c(0.025, 0.5, 0.975), ...)

## S3 method for class 'dcvar_fit'
coef(object, ...)

## S3 method for class 'dcvar_fit'
plot(x, type = c("rho", "phi", "diagnostics", "ppc", "pit"), ...)

Arguments

Value

Invisibly returns x.

A dcvar_summary object (a list).

A named list of posterior means: mu, Phi, margin-specific scale/shape parameters (e.g. sigma_eps for normal margins), and sigma_omega.

A ggplot object.

Functions

• print(dcvar_fit): Print a concise overview of the DC-VAR fit.

• summary(dcvar_fit): Produce a detailed summary including rho trajectory, VAR parameters, and diagnostics.

• coef(dcvar_fit): Extract posterior means of model coefficients.

• plot(dcvar_fit): Dispatch to a plot type: "rho", "phi", "diagnostics", "ppc", or "pit".

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.

Usage

dcvar_hmm(
  data,
  vars,
  K = 2,
  time_var = "time",
  standardize = TRUE,
  margins = "normal",
  skew_direction = NULL,
  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

Value

A dcvar_hmm_fit object.

See Also

dcvar() for the smooth time-varying model, dcvar_constant() for the time-invariant baseline, hmm_states() for state extraction, plot_hmm_states() for visualisation, dcvar_compare() for LOO-CV model comparison.

Examples

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)

Description

S3 methods for dcvar_hmm_fit objects

Usage

## S3 method for class 'dcvar_hmm_fit'
print(x, ...)

## S3 method for class 'dcvar_hmm_fit'
summary(object, probs = c(0.025, 0.5, 0.975), ...)

## S3 method for class 'dcvar_hmm_fit'
coef(object, ...)

## S3 method for class 'dcvar_hmm_fit'
plot(
  x,
  type = c("rho", "states", "transition", "phi", "diagnostics", "ppc", "pit"),
  ...
)

Arguments

Value

Invisibly returns x.

A dcvar_hmm_summary object (a list).

A named list of posterior means: mu, Phi, margin-specific scale/shape parameters (e.g. sigma_eps for normal margins), z_rho, and rho_state.

A ggplot object.

Functions

• print(dcvar_hmm_fit): Print a concise overview of the HMM fit.

• summary(dcvar_hmm_fit): Produce a detailed summary including state information, VAR parameters, and diagnostics.

• coef(dcvar_hmm_fit): Extract posterior means of model coefficients including state-specific rho values.

• plot(dcvar_hmm_fit): Dispatch to a plot type: "rho", "states", "transition", "phi", "diagnostics", "ppc", or "pit".

Description

Fits a hierarchical copula VAR(1) model with unit-specific VAR coefficients (random effects) and a global copula correlation. Uses non-centered parameterization for the random Phi coefficients.

Usage

dcvar_multilevel(
  data,
  vars,
  id_var = "id",
  time_var = "time",
  center = TRUE,
  margins = "normal",
  skew_direction = NULL,
  prior_phi_bar_sd = 0.5,
  prior_tau_phi_scale = 0.2,
  prior_sigma_sd = 1,
  prior_rho_sd = 0.5,
  chains = 4,
  iter_warmup = 2000,
  iter_sampling = 4000,
  adapt_delta = 0.9,
  max_treedepth = 14,
  seed = NULL,
  cores = NULL,
  refresh = 500,
  init = NULL,
  stan_file = NULL,
  backend = getOption("dcvar.backend", "auto"),
  ...
)

Arguments

Details

Experimental extension. This multilevel variant supports fitted() and predict(). PSIS-LOO is available for exponential-margin multilevel fits. PIT diagnostics are not yet implemented.

adapt_delta defaults to 0.90 and max_treedepth to 14 because the hierarchical structure with random effects benefits from deeper trees but does not require aggressive step-size adaptation.

Value

A dcvar_multilevel_fit object.

Note

Single-family fits support only normal and exponential margins; use a per-variable margins vector (for example c("normal", "gamma")) to access skew_normal and gamma margins via the mixed-margin model.

The bundled multilevel Stan program is defined for person-mean centered data and omits intercept terms. With the bundled model, center = FALSE is therefore not supported.

See Also

random_effects() for extracting unit-specific coefficients, simulate_dcvar_multilevel() for data generation.

Description

S3 methods for dcvar_multilevel_fit objects

Usage

## S3 method for class 'dcvar_multilevel_fit'
print(x, ...)

## S3 method for class 'dcvar_multilevel_fit'
summary(object, ...)

## S3 method for class 'dcvar_multilevel_fit'
coef(object, ...)

## S3 method for class 'dcvar_multilevel_fit'
plot(x, type = c("random_effects", "diagnostics"), ...)

Arguments

Details

Unlike single-level models (where coef() returns ⁠$Phi⁠), the multilevel model returns hierarchical parameters:

phi_bar

Population-mean VAR coefficients (analogous to Phi in single-level models, vectorised as phi11, phi12, phi21, phi22).

tau_phi

Between-unit SD of VAR coefficients.

scale parameters

sigma (innovation SDs) for normal margins, sigma_exp for exponential margins, or per-family scale/shape parameters (e.g. sigma_eps, sigma_gam, shape_gam) for per-variable (mixed) margins.

rho

Copula correlation (constant across units).

Use random_effects() to obtain unit-specific VAR coefficients.

Value

Invisibly returns x.

A dcvar_multilevel_summary object (a list).

A named list of posterior means.

A ggplot object.

Functions

• print(dcvar_multilevel_fit): Print a concise overview.

• summary(dcvar_multilevel_fit): Produce a detailed summary.

• coef(dcvar_multilevel_fit): Extract posterior means of population-level coefficients.

• plot(dcvar_multilevel_fit): Dispatch to a plot type.

Description

Fits a copula VAR(1) model with a fixed measurement model (factor loadings and measurement error SD are not estimated). Latent innovations are treated as parameters, making this model computationally intensive for large T.

Usage

dcvar_sem(
  data,
  indicators,
  J = NULL,
  lambda = NULL,
  sigma_e = NULL,
  margins = "normal",
  skew_direction = NULL,
  time_var = "time",
  method = c("indicator", "naive"),
  prior_mu_sd = 0.25,
  prior_phi_sd = 0.5,
  prior_sigma_sd = 0.5,
  prior_rho_sd = 0.75,
  chains = 4,
  iter_warmup = 2000,
  iter_sampling = 4000,
  adapt_delta = 0.95,
  max_treedepth = 13,
  seed = NULL,
  cores = NULL,
  refresh = 500,
  init = NULL,
  stan_file = NULL,
  backend = getOption("dcvar.backend", "auto"),
  ...
)

Arguments

Details

Experimental extension. This SEM variant supports fitted() and predict(). PSIS-LOO is available for naive score fits. PIT diagnostics are not yet implemented.

Boundary constraints. The SEM model constrains each VAR coefficient (Phi) to the interval $[-0.99, 0.99]$, unlike other dcvar models where Phi is unconstrained. Very strong autoregressive or cross-lag dynamics near $\pm 1$ cannot be captured by this variant.

The copula correlation $\rho$ is constrained to $(-0.97, 0.97)$ via rho = 0.97 * tanh(rho_raw) to avoid boundary singularity in the Gaussian copula density. Extremely high correlations near $\pm 1$ are truncated.

Margins. Single-family SEM fits support normal and exponential latent innovation margins. Exponential margins use the same shifted-exponential parameterization as the single-level models and therefore require skew_direction. A per-variable (mixed) margins vector additionally supports "skew_normal" and "gamma" per dimension, routing to a generic mixed-margins Stan model.

Post-estimation. fitted() and predict() are available for both the latent-state scale (type = "link") and the observed-indicator scale (type = "response"). Use latent_states() when you specifically need the full posterior summaries of the latent trajectories.

Value

A dcvar_sem_fit object.

Note

Single-family SEM fits are limited to normal and exponential latent margins. Skew-normal and gamma margins are available within dcvar_sem itself via a per-variable (mixed) margins vector (for example c("normal", "gamma")); only a homogeneous skew-normal or gamma latent margin requires another model family such as dcvar(), dcvar_constant(), or dcvar_hmm().

See Also

latent_states() for extracting estimated latent states, simulate_dcvar_sem() for data generation.

Description

S3 methods for dcvar_sem_fit objects

Usage

## S3 method for class 'dcvar_sem_fit'
print(x, ...)

## S3 method for class 'dcvar_sem_fit'
summary(object, ...)

## S3 method for class 'dcvar_sem_fit'
coef(object, ...)

## S3 method for class 'dcvar_sem_fit'
plot(x, type = c("latent_states", "rho", "diagnostics"), ...)

Arguments

Value

Invisibly returns x.

A dcvar_sem_summary object (a list).

A named list of posterior means.

A ggplot object.

Functions

• print(dcvar_sem_fit): Print a concise overview.

• summary(dcvar_sem_fit): Produce a detailed summary.

• coef(dcvar_sem_fit): Extract posterior means of latent VAR coefficients.

• plot(dcvar_sem_fit): Dispatch to a plot type.

Description

Returns the file path to a Stan model file included with the package.

Usage

dcvar_stan_path(
  model = c("dcvar", "dcvar_covariate", "dcvar_covariate_nodrift", "hmm", "constant",
    "multilevel", "sem", "sem_naive"),
  margins = "normal",
  copula = "gaussian"
)

Arguments

Value

File path to the Stan model file.

Examples

dcvar_stan_path("dcvar")
dcvar_stan_path("constant", margins = "exponential")

Description

Returns posterior summaries for Kendall's tau, using the fitted copula family to transform the model-specific dependence parameter. For Gaussian copulas, tau = 2 / pi * asin(rho). For Clayton copulas, tau = theta / (theta + 2).

Usage

dependence_summary(object, ...)

## Default S3 method:
dependence_summary(object, ...)

## S3 method for class 'dcvar_fit'
dependence_summary(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_covariate_fit'
dependence_summary(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_hmm_fit'
dependence_summary(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_constant_fit'
dependence_summary(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_multilevel_fit'
dependence_summary(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_sem_fit'
dependence_summary(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

Arguments

Value

A data frame with columns time, mean, sd, and one column per requested quantile.

Description

Extract posterior draws from a fitted model.

Usage

draws(object, ...)

## Default S3 method:
draws(object, ...)

## S3 method for class 'dcvar_model_fit'
draws(object, variable = NULL, format = "draws_array", ...)

Arguments

Value

A posterior draws object.

Description

Returns the one-step-ahead fitted values (posterior mean of y_hat) from the VAR(1) component. For single-level fits (constant, dynamic, HMM, covariate) this is the mean-centered form y_hat[t] = mu + Phi * (y[t-1] - mu).

Usage

## S3 method for class 'dcvar_model_fit'
fitted(object, type = c("link", "response"), ...)

## S3 method for class 'dcvar_multilevel_fit'
fitted(object, type = c("link", "response"), ...)

## S3 method for class 'dcvar_sem_fit'
fitted(object, type = c("link", "response"), ...)

Arguments

Details

If the model was fit with standardize = TRUE (the default), fitted values are on the standardized (z-scored) scale by default. Use type = "response" to back-transform to the original data scale.

fitted() and predict() are implemented for the public fit classes. For multilevel fits, the methods return unit-specific trajectories; because the data are already person-mean-centered, the link-scale fitted values apply the unit's VAR matrix to the previous observation with no mu term (y_hat[t] = Phi_unit %*% y[t-1]), and the person mean is re-added only for type = "response". For SEM fits, type = "link" returns latent-state summaries and type = "response" returns observed indicator-scale summaries.

Value

A data frame of posterior-mean fitted values. Single-level fits return columns time plus one column per modeled variable. Multilevel fits additionally include unit. SEM fits return either latent-state columns (type = "link") or observed-indicator columns (type = "response").

Description

Returns state posteriors, Viterbi path, state-specific rho values, and the transition matrix from an HMM copula fit.

Usage

hmm_states(object, ...)

## Default S3 method:
hmm_states(object, ...)

## S3 method for class 'dcvar_hmm_fit'
hmm_states(object, ...)

Arguments

Value

A named list with:

• gamma: T_eff x K matrix of posterior state probabilities

• viterbi: integer vector of MAP state sequence

• rho_state: list with mean, lower, upper for each state

• A: K x K posterior mean transition matrix

• rho_hmm: posterior-averaged rho trajectory

Description

Generates a human-readable interpretation of the estimated rho trajectory, describing the overall trend, magnitude of change, and key features.

Usage

interpret_rho_trajectory(
  object,
  threshold = 0.1,
  strength_breaks = .default_strength_breaks,
  magnitude_breaks = .default_magnitude_breaks,
  fluctuation_threshold = 0.3,
  ...
)

Arguments

Value

A character string with the interpretation (invisibly). The interpretation is also printed to the console.

Examples

sim <- simulate_dcvar(
  n_time = 12,
  rho_trajectory = rho_decreasing(12),
  seed = 1
)
fit <- dcvar(
  sim$Y_df,
  vars = c("y1", "y2"),
  chains = 1,
  iter_warmup = 10,
  iter_sampling = 10,
  refresh = 0,
  seed = 1
)
interpret_rho_trajectory(fit)

Description

Returns posterior summaries for the estimated latent states at each time point.

Usage

latent_states(object, ...)

## Default S3 method:
latent_states(object, ...)

## S3 method for class 'dcvar_sem_fit'
latent_states(object, probs = c(0.025, 0.5, 0.975), ...)

Arguments

Value

A data frame with columns time, variable, mean, sd, and quantile columns.

Description

Compute LOO-CV for a fitted model

Usage

## S3 method for class 'dcvar_fit'
loo(x, ...)

## S3 method for class 'dcvar_covariate_fit'
loo(x, ...)

## S3 method for class 'dcvar_hmm_fit'
loo(x, ...)

## S3 method for class 'dcvar_constant_fit'
loo(x, ...)

## S3 method for class 'dcvar_multilevel_fit'
loo(x, ...)

## S3 method for class 'dcvar_sem_fit'
loo(x, ...)

Arguments

Details

PSIS-LOO is available for Gaussian and Clayton single-level fits, covariate fits, exponential-margin multilevel fits, and naive SEM score fits. Indicator SEM fits and normal-margin multilevel fits are not supported because their stored log_lik quantities are not comparable pointwise predictive densities.

Value

A loo object from the loo package.

Description

Runs a Kolmogorov-Smirnov test per variable to assess whether PIT values are approximately uniform. This is a heuristic check on the plug-in PIT values returned by pit_values(), not an exact posterior predictive test.

Usage

pit_test(object, ...)

## Default S3 method:
pit_test(object, ...)

## S3 method for class 'dcvar_model_fit'
pit_test(object, ...)

Arguments

Details

This applies a Kolmogorov-Smirnov test to the approximate PIT values returned by pit_values(). The result is a heuristic check and does not account for serial dependence or full posterior uncertainty. PIT tests are currently implemented for single-level fits only.

Value

A data frame with columns variable, ks_statistic, p_value, n.

Description

Computes approximate Probability Integral Transform values using posterior mean residuals and posterior mean margin parameters. Large departures from uniformity can indicate model misfit, but these are not exact posterior predictive PIT values.

Usage

pit_values(object, ...)

## Default S3 method:
pit_values(object, ...)

## S3 method for class 'dcvar_model_fit'
pit_values(object, ...)

Arguments

Details

PIT values are computed from posterior mean residuals and posterior mean margin parameters. Treat them as a fast plug-in diagnostic rather than an exact posterior predictive transform that integrates over full posterior uncertainty. PIT diagnostics are currently implemented for the three core single-level fit classes only.

Value

A data frame with columns time, variable, pit.

Description

Creates a combined panel with trace plots, Rhat, and ESS diagnostics.

Usage

plot_diagnostics(object, ...)

Arguments

Value

A combined ggplot object (via patchwork).

Description

Plot HMM state posteriors

Usage

plot_hmm_states(object, show_viterbi = TRUE, ...)

Arguments

Value

A ggplot object.

Description

Plot estimated latent states with credible intervals

Usage

plot_latent_states(object, true_states = NULL, ...)

Arguments

Value

A ggplot object.

Description

Plot VAR(1) coefficient matrix as a heatmap

Usage

plot_phi(object, var_names = NULL, ...)

Arguments

Value

A ggplot object.

Description

Creates faceted histograms of the approximate PIT values returned by pit_values(). Under good model fit, these histograms should be roughly uniform, but they remain plug-in diagnostics rather than exact posterior predictive checks.

Usage

plot_pit(object, bins = 20, ...)

Arguments

Details

PIT histograms visualize the approximate plug-in PIT values returned by pit_values(). They are currently implemented for the three core single-level fit classes only.

Value

A ggplot object.

Description

Posterior predictive check for residual correlations

Usage

plot_ppc(object, n_sample = 100, ...)

Arguments

Details

Posterior predictive checks are currently available for normal and exponential margins. Gamma and skew-normal fits store copula-level replicated z-scores in eps_rep, so their replicated draws are not on the same residual scale as eps.

Value

A ggplot object.

Description

Displays unit-specific VAR coefficients with credible intervals.

Usage

plot_random_effects(object, ...)

Arguments

Value

A ggplot object.

Description

Plot the rho trajectory with credible intervals

Usage

plot_rho(
  object,
  show_ci = TRUE,
  ci_level = 0.95,
  inner_level = 0.8,
  true_rho = NULL,
  title = NULL,
  ...
)

Arguments

Value

A ggplot object.

Description

Visualises several named trajectory scenarios side by side for comparison.

Usage

plot_trajectories(
  n_time,
  scenarios = c("constant", "decreasing", "increasing", "random_walk", "single_middle",
    "large_change", "double_relapse"),
  ...
)

Arguments

Value

A ggplot object.

Examples

plot_trajectories(100)
plot_trajectories(100, scenarios = c("decreasing", "single_middle"))

Description

Returns point predictions and marginal prediction intervals by combining the VAR(1) fitted values with the estimated innovation SDs. Intervals are computed per-variable using a normal approximation and do not account for the copula dependence structure between variables.

Usage

## S3 method for class 'dcvar_model_fit'
predict(object, type = c("link", "response"), ci_level = 0.95, ...)

## S3 method for class 'dcvar_multilevel_fit'
predict(object, type = c("link", "response"), ci_level = 0.95, ...)

## S3 method for class 'dcvar_sem_fit'
predict(object, type = c("link", "response"), ci_level = 0.95, ...)

Arguments

Details

predict() is implemented for the public fit classes. For multilevel fits, the methods return unit-specific trajectories. For SEM fits, type = "link" returns latent states and type = "response" returns observed indicator predictions.

Value

A data frame of marginal prediction intervals at the specified level. Single-level and SEM fits return columns time, variable, mean, lower, upper. Multilevel fits additionally include unit.

Description

Transforms a data frame into a list suitable for the constant copula Stan model.

Usage

prepare_constant_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_z_rho_sd = 1,
  allow_gaps = FALSE
)

Arguments

Value

A named list suitable as Stan data input.

Description

Transforms a data frame into a list suitable for the Gaussian covariate DC-VAR Stan models. Outcome rows are sorted by time_var; rows with missing outcomes are removed with the same adjacency rules used by prepare_dcvar_data(), and covariates are filtered in the same order so X[t + 1, ] aligns with the outcome occasion of transition Y[t, ] -> Y[t + 1, ].

Usage

prepare_dcvar_covariate_data(
  data,
  vars,
  covariates,
  time_var = "time",
  standardize = TRUE,
  standardize_covariates = FALSE,
  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,
  zero_init_eta = TRUE
)

Arguments

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.

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,
  allow_gaps = FALSE
)

Arguments

Value

A named list suitable as Stan data input.

Prior naming conventions

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

Description

Transforms a data frame into a list suitable for the HMM copula Stan model. Includes HMM-specific prior hyperparameters.

Usage

prepare_hmm_data(
  data,
  vars,
  K = 2,
  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_kappa = 10,
  prior_alpha_off = 1,
  prior_z_rho_sd = 1,
  allow_gaps = FALSE
)

Arguments

Value

A named list suitable as Stan data input.

Description

Prepare data for the multilevel copula VAR model

Usage

prepare_multilevel_data(
  data,
  vars,
  id_var = "id",
  time_var = "time",
  center = TRUE,
  prior_phi_bar_sd = 0.5,
  prior_tau_phi_scale = 0.2,
  prior_sigma_sd = 1,
  prior_rho_sd = 0.5,
  margins = "normal",
  skew_direction = NULL
)

Arguments

Value

A named list suitable as Stan data input.

Description

Transforms a data frame of indicator variables into a list suitable for the SEM copula Stan model. The measurement model parameters (lambda, sigma_e) are fixed and passed through to Stan.

Usage

prepare_sem_data(
  data,
  indicators,
  J = NULL,
  lambda = NULL,
  sigma_e = NULL,
  margins = "normal",
  skew_direction = NULL,
  time_var = "time",
  prior_mu_sd = 0.25,
  prior_phi_sd = 0.5,
  prior_sigma_sd = 0.5,
  prior_rho_sd = 0.75,
  method = c("indicator", "naive")
)

Arguments

Value

A named list suitable as Stan data input.

Description

Print a dcvar_constant_summary object

Usage

## S3 method for class 'dcvar_constant_summary'
print(x, ...)

Arguments

Value

Invisibly returns x.

Description

Print a dcvar_covariate_summary object

Usage

## S3 method for class 'dcvar_covariate_summary'
print(x, ...)

Arguments

Value

Invisibly returns x.

Description

Print a dcvar_hmm_summary object

Usage

## S3 method for class 'dcvar_hmm_summary'
print(x, ...)

Arguments

Value

Invisibly returns x.

Description

Print a dcvar_multilevel_summary object

Usage

## S3 method for class 'dcvar_multilevel_summary'
print(x, ...)

Arguments

Value

Invisibly returns x.

Description

Print a dcvar_sem_summary object

Usage

## S3 method for class 'dcvar_sem_summary'
print(x, ...)

Arguments

Value

Invisibly returns x.

Description

Print a dcvar_summary object

Usage

## S3 method for class 'dcvar_summary'
print(x, ...)

Arguments

Value

Invisibly returns x.

Description

Returns posterior summaries for unit-specific VAR coefficients.

Usage

random_effects(object, ...)

## Default S3 method:
random_effects(object, ...)

## S3 method for class 'dcvar_multilevel_fit'
random_effects(object, ...)

Arguments

Value

A data frame with columns unit, parameter, mean, sd, q2.5, q97.5.

Description

Generate a constant rho trajectory

Usage

rho_constant(n_time, rho = 0.5)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_constant(100, rho = 0.5)

Description

Mimics a therapy effect where coupling decreases from high to low.

Usage

rho_decreasing(
  n_time,
  rho_start = 0.7,
  rho_end = 0.3,
  midpoint = NULL,
  steepness = 0.05
)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_decreasing(100)

Description

Three-phase trajectory: level A -> level B -> level C.

Usage

rho_double_step(
  n_time,
  rho_levels = c(0.7, 0.3, 0.7),
  breakpoints = c(1/3, 2/3),
  transition_width = 0
)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_double_step(100, rho_levels = c(0.7, 0.3, 0.7))

Description

Mimics deterioration where coupling increases from low to high.

Usage

rho_increasing(
  n_time,
  rho_start = 0.3,
  rho_end = 0.7,
  midpoint = NULL,
  steepness = 0.05
)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_increasing(100)

Description

Stochastic trajectory matching the DC-VAR data-generating process.

Usage

rho_random_walk(n_time, z_init = 0.5, sigma_omega = 0.05, seed = NULL)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_random_walk(100, seed = 42)

Description

Convenience function to retrieve a standard scenario by name.

Usage

rho_scenario(scenario, n_time, ...)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_scenario("decreasing", n_time = 100)
rho_scenario("double_relapse", n_time = 150)

Description

Abrupt change from one rho level to another at a specified time.

Usage

rho_step(
  n_time,
  rho_before = 0.7,
  rho_after = 0.3,
  breakpoint = 0.5,
  transition_width = 0
)

Arguments

Value

Numeric vector of length n_time - 1.

Examples

rho_step(100, rho_before = 0.7, rho_after = 0.3)

Description

Returns a data frame with the posterior mean, SD, and quantiles of the time-varying correlation at each time point.

Usage

rho_trajectory(object, ...)

## Default S3 method:
rho_trajectory(object, ...)

## S3 method for class 'dcvar_fit'
rho_trajectory(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_covariate_fit'
rho_trajectory(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_hmm_fit'
rho_trajectory(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_constant_fit'
rho_trajectory(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_multilevel_fit'
rho_trajectory(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

## S3 method for class 'dcvar_sem_fit'
rho_trajectory(object, probs = c(0.025, 0.1, 0.5, 0.9, 0.975), ...)

Arguments

Value

A data frame with columns time, mean, sd, and one column per quantile (e.g., q2.5, q10, q50, q90, q97.5). For dcvar_constant_fit objects, the constant rho is expanded to all n_time - 1 time points for consistency with the time-varying models.

See Also

plot_rho() to visualise the trajectory, interpret_rho_trajectory() for a text-based summary, var_params() for VAR parameter extraction.

Description

Convenience wrapper that combines rho_step() or rho_double_step() with simulate_dcvar() for quick breakpoint simulation studies.

Usage

simulate_breakpoint_data(
  n_time,
  type = c("single", "double"),
  rho_before = 0.7,
  rho_after = 0.3,
  rho_levels = c(0.7, 0.3, 0.7),
  breakpoint = 0.5,
  breakpoints = c(1/3, 2/3),
  transition_width = 0,
  mu = c(0, 0),
  Phi = matrix(c(0.3, 0.1, 0.1, 0.3), 2, 2),
  sigma_eps = c(1, 1),
  seed = NULL
)

Arguments

Value

A named list as returned by simulate_dcvar(). Its true_params additionally records the breakpoint specification: type, plus breakpoint (single) or breakpoints (double), as proportions of n_time - 1.

Examples

sim <- simulate_breakpoint_data(n_time = 100, type = "single", seed = 42)
plot(sim$true_params$rho, type = "l")

Description

Generates bivariate time series data with correlated innovations driven by a specified rho trajectory.

Usage

simulate_dcvar(
  n_time,
  rho_trajectory,
  mu = c(0, 0),
  Phi = matrix(c(0.3, 0.1, 0.1, 0.3), 2, 2),
  sigma_eps = c(1, 1),
  margins = "normal",
  skew_direction = NULL,
  skew_params = NULL,
  seed = NULL
)

Arguments

Value

A named list with:

• Y: ⁠n_time x 2⁠ observation matrix

• Y_df: data frame with columns time, y1, y2 (ready for dcvar())

• true_params: list of true parameter values

Examples

sim <- simulate_dcvar(n_time = 100, rho_trajectory = rho_decreasing(100))
head(sim$Y_df)
plot(sim$true_params$rho, type = "l")

Description

Generates panel data with unit-specific VAR coefficients drawn from a population distribution and a global copula correlation. The simulator matches the fitted multilevel model support by leaving unit-level VAR matrices unconstrained; nonstationary draws are possible.

Usage

simulate_dcvar_multilevel(
  N = 40,
  n_time = 100,
  phi_bar = c(0.3, 0.1, 0.1, 0.3),
  tau_phi = c(0.1, 0.05, 0.05, 0.1),
  sigma = c(1, 1),
  rho = 0.3,
  margins = "normal",
  skew_direction = NULL,
  skew_params = NULL,
  burnin = 30,
  center = TRUE,
  seed = NULL
)

Arguments

Value

A named list with:

• data: panel data frame with columns id, time, y1, y2

• true_params: list of true parameter values, including phi_bar, tau_phi, sigma, rho, margins, skew_direction, skew_params, and the per-unit VAR coefficients Phi_mat (an ⁠N x 4⁠ matrix) and Phi_list (a length-N list of ⁠2 x 2⁠ matrices)

• person_means: N x 2 matrix of person means (before centering)

Description

Generates indicator-level time series data from a latent VAR(1) process with Gaussian copula dependence and a fixed measurement model.

Usage

simulate_dcvar_sem(
  n_time = 200,
  J = 3,
  lambda = rep(sqrt(0.8), 3),
  sigma_e = sqrt(0.2),
  Phi = matrix(c(0.5, 0.15, 0.15, 0.3), 2, 2),
  mu = c(0, 0),
  margins = "normal",
  sigma = c(1, 1),
  sigma_exp = c(1, 1),
  skew_direction = NULL,
  skew_params = NULL,
  rho = 0.3,
  burnin = 0,
  seed = NULL
)

Arguments

Value

A named list with:

• data: data frame with columns time, y1_1, ..., y1_J, y2_1, ..., y2_J

• true_params: list of true parameter values

• latent_states: ⁠n_time x 2⁠ matrix of true latent states

• innovations: ⁠n_time x 2⁠ matrix of true innovations

Description

Returns posterior summaries for the VAR parameters: intercepts (mu), coefficients (Phi), innovation SDs (sigma_eps), and sigma_omega (DC-VAR only).

Usage

var_params(object, ...)

## Default S3 method:
var_params(object, ...)

## S3 method for class 'dcvar_model_fit'
var_params(object, ...)

## S3 method for class 'dcvar_multilevel_fit'
var_params(object, ...)

## S3 method for class 'dcvar_sem_fit'
var_params(object, ...)

Arguments

Details

For multilevel models, returns population-level parameters phi_bar (mean VAR coefficients), tau_phi (between-unit SDs), sigma (innovation SDs), and rho (copula correlation). These correspond to Phi, sigma_eps, and rho in single-level models.

Value

A named list of data frames with columns variable, mean, sd, q2.5, q97.5.