Visual Diagnostic Checks for Vector Autoregressive Models

Provides model-agnostic visual diagnostics for vector autoregressive (VAR) models. Given empirical data, model predictions, residuals, and optionally simulated data, the package assembles a multi-panel diagnostic grid: empirical vs. predicted time series, residual inspection, residuals vs. predictions scatter, and posterior predictive style checks via simulated trajectories. Output is a 'patchwork' object composed of 'ggplot2' plots, allowing further customisation via standard 'ggplot2' theme calls. Follows the approach described in Haslbeck et al. (2026) .

VARcheck

VARcheck produces diagnostic grids for vector autoregressive (VAR) models. Given your model's empirical data, predictions, and residuals, it assembles a multi-panel figure that makes the quality of the fit visible.

The package is model-agnostic: it works with any VAR implementation (mlVAR, vars, DSEM, custom code) as long as you can supply a matrix of empirical values, a matrix of predictions, and a matrix of residuals.

The package website includes a getting started guide with a full walkthrough, and an example analyses vignette that reproduces the simulated misfit examples from Haslbeck et al. (2026).

Installation

Install the released version from CRAN:

install.packages("VARcheck")

Or install the development version from GitHub:

# install.packages("devtools")
devtools::install_github("bsiepe/VARcheck")

Usage

Wrap your data in a var_data object, then call plot_var_check(). We provide a longer instruction in the package vignette, but the basic workflow looks like this:

library(VARcheck)

vd <- new_var_data(
  empirical  = emp,     # T × p matrix of observed values
  predicted  = pred,    # T × p matrix of model predictions
  residuals  = res,     # T × p matrix of residuals
  simulated  = sim,     # T × p matrix of posterior-predictive simulations (optional)
  var_names  = c("Mood", "Energy", "Fatigue", "Anxiety")
)

plot_var_check(vd)

Each row of the output corresponds to one variable and contains four column groups:

Marginal histograms with a Gaussian overlay appear next to each time-series panel.

Options

Select variables or panels

# Show only two variables
plot_var_check(vd, vars = c("Mood", "Energy"))

# Drop the simulated column
plot_var_check(vd, panels = c("data", "residuals", "scatter"))

Multiple subjects

Pass a list of matrices (one per subject) to new_var_data(). Use the subject argument to select which one to plot.

vd_multi <- new_var_data(
  empirical = list(emp_s1, emp_s2, emp_s3),
  predicted = list(pred_s1, pred_s2, pred_s3),
  residuals = list(res_s1, res_s2, res_s3)
)

plot_var_check(vd_multi, subject = 2)

Colours and theme

# Change line colours (partial override merges with defaults)
plot_var_check(vd, colors = list(predicted = "steelblue"))

# Override any theme element
plot_var_check(vd, theme = ggplot2::theme(text = ggplot2::element_text(size = 9)))

The default theme is theme_varcheck(), which is a minimal ggplot2 theme you can use on its own.

Reference

Please cite the following paper when using this package:

Haslbeck, J. M. B., Jongerling, J., Siepe, B. S., Epskamp, S., & Waldorp, L. (2026). Model Checking for Vector Autoregressive Models https://doi.org/10.31234/osf.io/k6uz4_v3