Visual Diagnostic Checks for Vector Autoregressive Models.
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:
| Column | Content |
|---|---|
| Empirical & Predicted | Time series of observed vs. predicted values, annotated with R² and RMSE |
| Residuals | Residuals over time, annotated with AR(1) coefficient and 95% CI |
| Residuals vs. Predicted | Scatter of residuals against predictions |
| Simulated | Time series simulated from the fitted model |
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 Modelshttps://doi.org/10.31234/osf.io/k6uz4_v3