meta_var1: Meta-analytic VAR(1) model

Description

Single-stage meta-analytic vector autoregressive model (VAR(1)) for time-series data collected across multiple studies. Pools temporal (lag-1) and contemporaneous network structures across studies using a random-effects framework. The meta_gvar wrapper sets contemporaneous = "ggm" for graphical VAR estimation, and meta_var() is the primary short name of meta_var1() (identical function).

Usage

meta_var1(data, covs, nobs,
          vars, studyvar, idvar, dayvar, beepvar,
          contemporaneous = c("cov", "chol", "prec", "ggm", "cor"),
          beta = "full",
          omega_zeta = "full", delta_zeta = "full",
          kappa_zeta = "full", sigma_zeta = "full",
          lowertri_zeta = "full",
          rho_zeta = "full", SD_zeta = "full",
          randomEffects = c("chol", "cov", "prec", "ggm", "cor"),
          sigma_randomEffects = "full",
          kappa_randomEffects = "full",
          omega_randomEffects = "full",
          lowertri_randomEffects = "full",
          delta_randomEffects = "full",
          rho_randomEffects = "full",
          SD_randomEffects = "full",
          Vmats,
          Vmethod = c("individual", "pooled"),
          Vestimation = c("averaged", "per_study"),
          baseline_saturated = TRUE, optimizer,
          estimator = c("FIML", "ML"),
          sampleStats, verbose = FALSE,
          bootstrap = FALSE, boot_sub, boot_resample)
meta_var(...)
meta_gvar(...)

Value

An object of the class psychonetrics (psychonetrics-class)

Arguments

data: A data frame containing time-series data for multiple studies. Use together with studyvar to identify studies.
covs: A list of pre-computed Toeplitz covariance matrices (one per study). Each matrix should have dimension 2p x 2p where p is the number of variables, with the first p rows/columns being lagged variables and the second p being current variables. Alternative to data.
nobs: A vector with the number of observations per study. Required when covs is supplied.
vars: Character vector of observed variable names. If missing, inferred from data.
studyvar: A string indicating the column name in data that identifies the study. Required when data is supplied. If not supplied but idvar is, idvar is used as studyvar with a warning.
idvar: Optional string indicating the subject ID column within each study. When both studyvar and idvar are supplied, data is first split by studyvar, then idvar is used within each study to collate time series (as in var1).
dayvar: Optional string indicating the day variable (passed to tsData per study).
beepvar: Optional string indicating the beep variable within day (passed to tsData per study).
contemporaneous: Parameterization of the contemporaneous (residual innovation) covariance structure. One of "cov", "chol", "prec", "ggm", or "cor".
beta: Temporal lag-1 regression matrix specification. Defaults to "full" (all elements free, including diagonal autoregressive effects).
omega_zeta: Contemporaneous partial correlation matrix specification (used when contemporaneous = "ggm").
delta_zeta: Contemporaneous scaling matrix specification (used when contemporaneous = "ggm").
kappa_zeta: Contemporaneous precision matrix specification (used when contemporaneous = "prec").
sigma_zeta: Contemporaneous covariance matrix specification (used when contemporaneous = "cov").
lowertri_zeta: Contemporaneous Cholesky factor specification (used when contemporaneous = "chol").
randomEffects: Parameterization of the random effects covariance structure.
sigma_randomEffects: Random effects covariance matrix specification (used when randomEffects = "cov").
kappa_randomEffects: Random effects precision matrix specification (used when randomEffects = "prec").
omega_randomEffects: Random effects partial correlation matrix specification (used when randomEffects = "ggm").
lowertri_randomEffects: Random effects Cholesky factor specification (used when randomEffects = "chol").
delta_randomEffects: Random effects scaling matrix specification (used when randomEffects = "ggm").
rho_randomEffects: Random effects correlation matrix specification (used when randomEffects = "cor").
SD_randomEffects: Random effects standard deviation matrix specification (used when randomEffects = "cor").
Vmats: Optional list with 'V' matrices (sampling error variance approximations).
Vmethod: Which method should be used to approximate the sampling error variance? "individual" or "pooled".
Vestimation: How should the sampling error estimates be evaluated? "averaged" or "per_study".
baseline_saturated: Logical indicating if baseline and saturated models should be included.
optimizer: The optimizer to be used. Defaults to "nlminb".
estimator: The estimator to be used. "ML" or "FIML" (default).
sampleStats: Optional sample statistics object.
verbose: Logical, should progress be printed?
bootstrap: Should the data be bootstrapped?
boot_sub: Proportion of cases to subsample for bootstrap.
boot_resample: Logical, should bootstrap be with replacement?
rho_zeta: Only used when contemporaneous = "cor". Contemporaneous (innovation) correlation matrix specification ("full", "zero", or a pattern matrix).
SD_zeta: Only used when contemporaneous = "cor". Diagonal matrix of contemporaneous (innovation) standard deviations ("full", "diag", or a pattern matrix).
...: Arguments sent to meta_var1.

Author

Sacha Epskamp <mail@sachaepskamp.com>

Details

This function implements a single-stage meta-analytic VAR(1) model. For p observed variables, each study's time-series data is transformed into a Toeplitz covariance structure from which two blocks are extracted:

Sigma_0: the p x p stationary covariance (symmetric, p(p+1)/2 unique elements)
Sigma_1: the p x p lag-1 cross-covariance (non-symmetric, p^2 elements)

The VAR(1) structural model implies: $$\textrm{vec}(\Sigma_0) = (I - \beta \otimes \beta)^{-1} \textrm{vec}(\Sigma_\zeta)$$ $$\Sigma_1 = \beta \Sigma_0$$

The meta-level mean is $\mu = [\textrm{vech}(\Sigma_0), \textrm{vec}(\Sigma_1)]$ and heterogeneity is modeled as $\Sigma = \Sigma^{(\textrm{ran})} + V$.

Note: the exogenous (lagged) covariance block from the full Toeplitz matrix is not modeled, as it is a nuisance parameter at the meta-analytic level.

Sample size convention. When raw data is supplied, the per-study sample size used in the sampling-error approximation (the 'V' matrices) is the number of rows of the lag-augmented data set, including rows in which the lagged block is missing (e.g., the first measurement of each day or subject). The covariances themselves are computed using pairwise-complete observations. For studies consisting of many short segments (e.g., few beeps per day), this convention slightly overstates the effective number of (current, lagged) pairs for the lagged-covariance elements, and hence slightly understates their sampling variance. When this is a concern, the 'V' matrices can be supplied manually via Vmats.

Model size limits. The number of meta-level outcomes is p(p+1)/2 + p^2, which grows quickly with the number of variables: the default full random-effects structure has on the order of p^4 parameters, and internal matrices grow with the fourth power of the number of outcomes. Models with more than 11 variables (215 outcomes) exceed internal limits and are refused with an informative error; models close to that limit are very slow and memory-hungry, and require many studies to be estimable (a warning is given when the number of studies is smaller than the number of outcomes). For large numbers of variables, or when the "studies" are in fact subjects of a single intensive longitudinal study, consider the multi-level VAR model ml_var1 / ml_gvar1 instead.

Fit indices. The saturated meta-analytic model (fully free $\Sigma_0$, $\Sigma_1$ and random effects) has zero degrees of freedom, in which case chi-square based fit indices are not informative and are left blank.

Examples

Run this code

if (FALSE) {
library("dplyr")
set.seed(42)

# Simulate stationary VAR(1) time-series data for several subjects/studies
# directly in base R (no extra packages needed):
nNode  <- 3
nTime  <- 50
nStudy <- 20

# Fixed lag-1 (temporal) coefficient matrix:
beta <- matrix(c( 0.4,  0.1,  0.0,
                  0.0,  0.4,  0.1,
                  0.1,  0.0,  0.4), nNode, nNode, byrow = TRUE)

# Innovation (contemporaneous) covariance:
Sigma <- diag(nNode)

varNames <- paste0("V", 1:nNode)

simVAR1 <- function(id, nTime, beta, Sigma){
  p <- nrow(beta)
  L <- chol(Sigma)
  Y <- matrix(0, nTime, p)
  for (t in 2:nTime){
    Y[t, ] <- beta %*% Y[t - 1, ] + as.vector(t(L) %*% rnorm(p))
  }
  out <- as.data.frame(Y)
  names(out) <- paste0("V", 1:p)
  out$study <- id
  out
}

Data <- do.call(rbind, lapply(seq_len(nStudy), simVAR1,
                              nTime = nTime, beta = beta, Sigma = Sigma))

# Fit meta-analytic VAR(1):
mod <- meta_var1(Data,
                 vars = varNames,
                 studyvar = "study",
                 estimator = "ML")
mod <- mod %>% runmodel

# Inspect results:
print(mod)
getmatrix(mod, "beta")

# Fit meta-analytic GVAR (with GGM contemporaneous):
mod_gvar <- meta_gvar(Data,
                      vars = varNames,
                      studyvar = "study",
                      estimator = "ML")
mod_gvar <- mod_gvar %>% runmodel
getmatrix(mod_gvar, "omega_zeta")
}

Run the code above in your browser using DataLab