| Type: | Package |
| Title: | Visual Diagnostic Checks for Vector Autoregressive Models |
| Version: | 0.1.0 |
| Description: | 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) <doi:10.31234/osf.io/k6uz4_v3>. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| URL: | https://github.com/bsiepe/VARcheck, https://bsiepe.github.io/VARcheck/ |
| BugReports: | https://github.com/bsiepe/VARcheck/issues |
| Imports: | ggplot2 (≥ 3.4.0), patchwork, stats, utils |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | no |
| Packaged: | 2026-05-15 13:55:16 UTC; Bjoern |
| Author: | Björn S. Siepe 
[aut, cre, cph],
Jonas M. B. Haslbeck
[aut] |
| Maintainer: | Björn S. Siepe <bjoernsiepe+software@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-05-19 10:00:07 UTC |
Create a VAR data object
Description
Constructs a 'var_data' object used as input to [plot_var_check()]. Each component is either a single 'T x p' numeric matrix (single subject) or a list of 'T_i x p' matrices (multiple subjects). Single matrices are coerced to a length-1 list automatically.
Usage
new_var_data(
empirical,
predicted,
residuals,
simulated = NULL,
var_names = NULL
)
## S3 method for class 'var_data'
print(x, ...)
Arguments
empirical |
Numeric matrix or list of matrices. Observed values. |
predicted |
Numeric matrix or list of matrices. Model predictions. |
residuals |
Numeric matrix or list of matrices. Residuals ('empirical - predicted'). |
simulated |
Optional numeric matrix or list of matrices. Data simulated from the fitted model. Required only when plotting the '"simulated"' panel. |
var_names |
Optional character vector of length 'p' with variable names used as plot labels. Defaults to '"V1"', '"V2"', etc. |
x |
A 'var_data' object. |
... |
Not used; present for S3 method compatibility. |
Value
An object of class 'var_data'.
Examples
set.seed(1)
emp <- matrix(rnorm(200), nrow = 100, ncol = 2)
pred <- emp + matrix(rnorm(200, sd = 0.3), 100, 2)
res <- emp - pred
sim <- matrix(rnorm(200), 100, 2)
vd <- new_var_data(emp, pred, res, sim, var_names = c("Mood", "Energy"))
Plot VAR model diagnostics
Description
Creates a multi-panel diagnostic grid for a fitted VAR model. Each row corresponds to one variable; columns show (a) empirical data vs. predictions, (b) residuals over time, (c) residuals vs. predictions scatter, and (d) data simulated from the estimated model. Each time-series panel is accompanied by a marginal histogram with a Gaussian overlay.
Usage
plot_var_check(
data,
subject = 1,
vars = NULL,
panels = c("data", "residuals", "scatter", "simulated"),
colors = list(),
theme = NULL,
ylim_data = NULL,
ylim_res = NULL
)
Arguments
data |
A 'var_data' object created with [new_var_data()]. |
subject |
Integer. Index of the subject to plot. Defaults to '1'. |
vars |
Character or integer vector selecting variables to include. Defaults to all variables. |
panels |
Character vector controlling which columns are shown. Any subset of 'c("data", "residuals", "scatter", "simulated")', in that order. Defaults to all four. |
colors |
Named list controlling line colours. Recognised elements: 'empirical' (default '"black"') and 'predicted' (default '"darkorange2"'). Partial lists are merged with the defaults. |
theme |
A 'ggplot2::theme()' object added on top of [theme_varcheck()]. Use this to override individual theme elements. |
ylim_data |
Numeric vector of length 2. Shared y-limits for the data-scale panels (empirical/predicted/simulated). Auto-computed from the data if 'NULL'. |
ylim_res |
Numeric vector of length 2. Shared y-limits for the residual panels. Auto-computed from the residuals if 'NULL'. |
Value
A 'patchwork' object.
Examples
set.seed(1)
emp <- matrix(rnorm(300), nrow = 100, ncol = 3)
pred <- emp + matrix(rnorm(300, sd = 0.3), 100, 3)
res <- emp - pred
sim <- matrix(rnorm(300), 100, 3)
vd <- new_var_data(emp, pred, res, sim, var_names = c("X1", "X2", "X3"))
plot_var_check(vd)
Default VARcheck ggplot2 theme
Description
A minimal theme used as the default style for all VARcheck plots. Pass a 'ggplot2::theme()' object to the 'theme' argument of [plot_var_check()] to override individual elements on top of this base.
Usage
theme_varcheck()
Value
A 'ggplot2' theme object.
Examples
theme_varcheck()