fit_graphical_var: Graphical VAR Estimation

In idiographic: Person-Specific (Idiographic) and Heterogeneous Complex Networks

Graphical VAR Estimation

Description

Estimate a graphical vector autoregressive (GVAR) model from time series or panel data. Jointly estimates a sparse temporal network (L1-penalized VAR coefficients) and a sparse contemporaneous network (graphical lasso on residuals) using EBIC model selection over a lambda grid.

Usage

fit_graphical_var(
  data,
  vars,
  id = NULL,
  day = NULL,
  beep = NULL,
  lags = 1L,
  n_lambda = 50L,
  gamma = 0.5,
  scale = TRUE,
  center_within = TRUE,
  lambda_min_ratio = 0.05,
  lambda_min_kappa = NULL,
  lambda_min_beta = NULL,
  penalize_diagonal = TRUE,
  lambda_beta = NULL,
  lambda_kappa = NULL,
  regularize_mat_beta = NULL,
  regularize_mat_kappa = NULL,
  maxit_in = 100L,
  maxit_out = 100L,
  delete_missings = TRUE,
  likelihood = c("unpenalized", "penalized"),
  ebic_tol = 1e-04,
  mimic = "current",
  verbose = FALSE,
  min_obs = NULL,
  subject = NULL
)

Arguments

data	A data.frame or matrix with columns for variables, and optionally id, day, beep columns for panel/ESM data. A prepared list containing numeric matrices data_c (current responses) and data_l (lagged design, with or without an intercept column) is also accepted.
vars	Character vector of variable names. May be omitted for prepared input when data_c has column names.
id	Character. Name of the person-ID column. If NULL, assumes single subject.
day	Character. Name of the day/session column. Default: NULL.
beep	Character. Name of the beep/measurement column. Default: NULL.
lags	Positive integer vector of explicit lags to include. Default: 1.
n_lambda	Integer scalar, or a two-value vector giving the number of beta and kappa penalties. The latter can be named, for example c(beta = 30, kappa = 20), or unnamed in beta/kappa order. Default: 50.
gamma	Numeric. EBIC hyperparameter (0 = BIC, higher = sparser). Default: 0.5.
scale	Logical. Whether to standardize variables. Default: TRUE.
center_within	Logical. Whether to centre within person when more than one id is present (removes between-person variance). Default: TRUE.
lambda_min_ratio	Numeric scalar, or a two-value beta/kappa vector. Ratio of min/max lambda unless overridden per-dimension. Default: 0.05.
lambda_min_kappa, lambda_min_beta	Numeric or NULL. Per-dimension min/max lambda ratios (matching graphicalVAR's lambda_min_kappa / lambda_min_beta). When NULL, fall back to lambda_min_ratio.
penalize_diagonal	Logical. Penalize the autoregressive diagonal in beta. Default: TRUE (matches graphicalVAR).
lambda_beta	Numeric scalar (or vector), or NULL. When supplied, the temporal penalty is pinned to this value instead of being EBIC-selected over a grid – matching graphicalVAR's lambda_beta argument (e.g. lambda_beta = 0.1). Default NULL (EBIC grid).
lambda_kappa	Numeric scalar (or vector), or NULL. As lambda_beta but for the contemporaneous (kappa) penalty.
regularize_mat_beta	Optional numeric/logical matrix (p x p or p x (p+1)) of per-element beta penalty multipliers (matches graphicalVAR's regularize_mat_beta). NULL uses penalize_diagonal.
regularize_mat_kappa	Optional p x p numeric/logical matrix of per-element kappa penalty multipliers (matches graphicalVAR's regularize_mat_kappa). NULL penalizes all off-diagonals.
maxit_in, maxit_out	Integer. Max inner (beta) / outer (beta-kappa) iterations. Defaults 100 (matches maxit.in / maxit.out).
delete_missings	Logical. Drop rows with missing current/lagged values. Default TRUE (matches deleteMissings).
likelihood	Either "unpenalized" (default; refit precision for the EBIC, matching graphicalVAR) or "penalized" (use the regularized kappa directly).
ebic_tol	Numeric. Tolerance for the EBIC tie-break. Default 1e-4.
mimic	Character. Only "current" is supported. Legacy modes error explicitly because idiographic does not claim equivalence to them.
verbose	Logical. Emit progress messages. Default FALSE.
min_obs	Integer or NULL. Keep only subjects with at least this many observations (counts taken from data). Default NULL.
subject	Optional vector naming the exact subject(s) to analyse. Default NULL (all subjects).

Details

This is a clean-room reimplementation of the Rothman/Epskamp two-step estimator that is numerically equivalent to graphicalVAR::graphicalVAR(): identical data preparation (global scaling, optional within-person centring, intercept column, lag-1 construction within id/day blocks), identical lambda grids (generate_lambdas), the coupled MRCE beta-update / glasso kappa-update loop, the unpenalized-likelihood EBIC, and the same tie-broken model selection. The committed end-to-end regression tests use tolerance 1e-6, covering both well-conditioned and numerically difficult fits. That equivalence claim is limited to mimic = "current" and lags = 1; multiple lags are an idiographic extension and are labelled as such in the returned equivalence metadata.

Value

A list of class gvar_result containing:

beta

Temporal coefficient matrix, outcome x (intercept + predictors), in graphicalVAR's convention.

temporal

The first requested p x p temporal layer as [outcome, predictor]; unchanged for the default lag 1 fit.

temporal_layers

Named p x p coefficient matrices for every lag.

kappa

Precision matrix (p x p, symmetric).

PCC

Partial contemporaneous correlations -cov2cor(kappa), diagonal zeroed.

PDC

Partial directed correlations.

contemporaneous

Alias for PCC.

labels

Variable names.

n_obs

Number of valid lag-pair observations.

lambda_beta, lambda_kappa

Selected penalties.

gamma, EBIC

EBIC gamma used and the selected EBIC.

References

Epskamp, S., Waldorp, L. J., Mottus, R., & Borsboom, D. (2018). The Gaussian Graphical Model in Cross-Sectional and Time-Series Data. Multivariate Behavioral Research, 53(4), 453-480.

Rothman, A. J., Levina, E., & Zhu, J. (2010). Sparse multivariate regression with covariance estimation. JCGS, 19(4), 947-962.

Examples

set.seed(1)
d <- data.frame(A = rnorm(60), B = rnorm(60))
fit <- fit_graphical_var(d, vars = c("A", "B"), n_lambda = 3,
                         scale = FALSE)
fit$temporal
fit$contemporaneous

idiographic documentation built on Aug. 4, 2026, 1:07 a.m.