Gets a network structure

Description

This function is simply a wrapper around the plotting method for mlVAR objects, that extracts the network structure rather than plotting them.

Usage

getNet(x, ...)

Arguments

Author(s)

Sacha Epskamp <mail@sachaepskamp.com>

Import output from Mplus

Description

This function imports the output from an Mplus model that has been generated by mlVAR. It can be used to make manual changes to the input file.

Usage

importMplus(outfile)

Arguments

Author(s)

Sacha Epskamp <mail@sachaepskamp.com>

Multi-Level Gaussian Graphical Model Estimation

Description

Estimates within-cluster and between-cluster partial correlation networks from cross-sectional multilevel data (e.g., individuals nested in classrooms, patients nested in clinics) using a single-step nodewise regression approach. Unlike mlVAR, which uses a two-step procedure (temporal model first, then contemporaneous), mlGGM fits all effects in a single multilevel model per variable. This makes it suitable for cross-sectional data where no temporal ordering exists.

For each variable y_i, a single mixed-effects model is fitted with within-cluster centered predictors and cluster-mean predictors. Two undirected networks (GGMs) are extracted: one capturing partial correlations at the within-cluster level (individual deviations from cluster means) and one at the between-cluster level (cluster means).

NOTE: This function is currently experimental and may change in future versions.

Usage

mlGGM(data, vars, idvar = "id",
      estimator = c("lmer"),
      randomeffects = c("default", "correlated", "orthogonal", "fixed"),
      scale = TRUE, na.rm = TRUE, verbose = TRUE,
      full_detrend = FALSE)

## S3 method for class 'mlGGM'
print(x, ...)
## S3 method for class 'mlGGM'
summary(object, show = c("fit", "within", "between"),
        round = 3, ...)
## S3 method for class 'mlGGM'
plot(x, type = c("within", "between"),
     partial = TRUE, SD = FALSE, subject, order,
     nonsig = c("default", "show", "hide", "dashed"),
     rule = c("or", "and"), alpha = 0.05,
     layout = "spring", verbose = TRUE, ...)

Arguments

Details

mlGGM estimates multi-level Gaussian graphical models by fitting one mixed-effects regression model per variable. For each variable y_i, the model is:

y_i = \beta_0 + \sum_{j \neq i} \gamma^{(w)}_{ij} (y_j - \bar{y}_j) + \sum_{j \neq i} \gamma^{(b)}_{ij} \bar{y}_j + u_{0} + \sum_{j \neq i} u_j (y_j - \bar{y}_j) + \varepsilon

where (y_j - \bar{y}_j) are within-cluster centered predictors and \bar{y}_j are cluster-mean predictors. The random effects u_0, u_j are placed on the intercept and within-cluster predictors only (not on between-cluster means).

Two GGMs are extracted using the relationship between nodewise regression coefficients and the precision matrix:

Within-cluster network: The precision matrix is computed as K_w = D_w (I - \Gamma_w), where D_w = \mathrm{diag}(1/\sigma^2_i) contains the inverse residual variances and \Gamma_w contains the fixed effects of the within-cluster centered predictors. The matrix is symmetrized and forced to be positive definite. Partial correlations are derived from the precision matrix.

Between-cluster network: The precision matrix is computed as K_b = D_b (I - \Gamma_b), where D_b = \mathrm{diag}(1/\mu^2_{SD,i}) contains the inverse squared random intercept standard deviations and \Gamma_b contains the fixed effects of the cluster-mean predictors.

Cluster-specific networks: When randomeffects is "correlated" or "orthogonal", cluster-specific within-cluster networks are also computed by adding the estimated random effects to the fixed effects for each cluster. These can be accessed via the subject argument in the plot method.

Network matrices can be extracted using getNet with type = "within" or type = "between". The rule argument controls the significance thresholding rule.

Value

An object of class "mlGGM" containing:

Author(s)

Sacha Epskamp

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.

Epskamp, S., Rhemtulla, M. T., & Borsboom, D. (2017). Generalized network psychometrics: Combining network and latent variable models. Psychometrika, 82(4), 904-927.

See Also

mlVAR for multilevel VAR estimation with temporal data, getNet for extracting network matrices.

Examples

## Not run: 
# Generate simulated multilevel data with known GGM structure:
library(bootnet)

nNode <- 4
nCluster <- 30
clusterSize <- 50

# True within-cluster and between-cluster networks:
set.seed(1)
net_within <- genGGM(nNode, propPositive = 0.8)
net_between <- genGGM(nNode, p = 1, propPositive = 0.5)

# Generate within-cluster deviations:
within_data <- ggmGenerator()(nCluster * clusterSize, net_within)
within_data <- as.data.frame(within_data)
vars <- names(within_data)
within_data$cluster <- rep(1:nCluster, each = clusterSize)

# Generate between-cluster means:
between_data <- ggmGenerator()(nCluster, net_between)
between_data <- as.data.frame(between_data)
between_data$cluster <- 1:nCluster

# Combine: observed = within deviation + cluster mean
merged <- dplyr::left_join(within_data, between_data, by = "cluster",
                           suffix = c("_w", "_b"))
data <- merged[, grep("_w$", names(merged))] +
        merged[, grep("_b$", names(merged))]
names(data) <- vars
data$cluster <- merged$cluster

# Fit the multi-level GGM:
fit <- mlGGM(data, vars = vars, idvar = "cluster")

# Inspect results:
summary(fit)

# Plot within-cluster and between-cluster networks:
plot(fit, type = "within")
plot(fit, type = "between")

# Extract network matrices (with AND rule for better specificity):
within_net <- getNet(fit, "within", rule = "and")
between_net <- getNet(fit, "between", rule = "and")

## End(Not run)

Multilevel VAR Estimation for Multiple Time Series

Description

The function mlVAR computes estimates of the multivariate vector autoregression model. This model returns three stuctures: temporal effects (e.g., lag-1 regression weights), contemporaneous relationships (correlations or partial correlations) and between-subject effects (correlations and partial correlations). See details.

The predict method computes fitted values and residuals from the temporal model (step 1). It returns predictions aligned to the original input data, with NA for rows that cannot be predicted (e.g., the first observation per person-day lost to lagging, or rows with missing data). When newdata is supplied, predictions are computed for the new data using the fitted model(s). For estimator = "lmer", new subjects are predicted using fixed effects only (allow.new.levels = TRUE); for estimator = "lm", prediction is only possible for subjects seen during training.

The residuals method is a convenience wrapper around predict that returns only the residuals.

The resimulate method generates simulated data from a fitted mlVAR model using person-specific estimated parameters (fixed + random effects). For each person, a VAR time series is simulated using their estimated temporal effects (Beta), contemporaneous precision matrix (Theta), and person-specific means (mu). The output has the same dimensions and missingness pattern as the original input data, making it suitable for posterior predictive checks and model diagnostics.

Usage

mlVAR(data, vars, idvar, lags = 1, dayvar, beepvar,
                 estimator = c("default", "lmer", "lm","Mplus"),
                 contemporaneous = c("default", "correlated",
                 "orthogonal", "fixed", "unique"), temporal =
                 c("default", "correlated", "orthogonal", "fixed",
                 "unique"), nCores = 1, verbose = TRUE, compareToLags,
                 scale = TRUE, scaleWithin = FALSE, AR = FALSE,
                 MplusSave = TRUE, MplusName = "mlVAR", iterations = "(2000)",
                 chains = nCores, signs, orthogonal,
                 trueMeans, na.rm = TRUE,
                 full_detrend = FALSE
  )

## S3 method for class 'mlVAR'
predict(object, newdata, scale_back = TRUE,
        include_ids = TRUE, ...)

## S3 method for class 'mlVAR'
residuals(object, scale_back = TRUE,
        include_ids = TRUE, ...)

resimulate(object, ...)

## S3 method for class 'mlVAR'
resimulate(object, scale_back = TRUE,
        include_ids = TRUE, nTime = NULL,
        keep_missing = TRUE,
        variance = c("model", "empirical"), ...)

Arguments

Details

This function estimates the multi-level VAR model to obtain temporal, contemporaneous and between-subject effects using nodewise estimation. Temporal and between-subject effects are obtained directly from the models and contemporaneous effects are estimated post-hoc by correlating the residuals. See arxiv.org/abs/1609.04156 for details.

Setting estimator = "Mplus" will generate a Mplus model, run the analysis and read the results into R. Mplus 8 is required for this estimation. It is recommended to set contemporaneous = "fixed", though not required. For the estimation of contemporaneous random effects, the signs of contemporaneous *correlations * (not partial correlations) need be set (or estimated) via the signs argument.

Value

mlVAR returns an mlVAR object.

predict.mlVAR returns a data frame of predicted (fitted) values with the same number of rows as the original input data (or newdata). Rows that could not be predicted (e.g., first observation per person-day lost to lagging, or rows with missing data) contain NA. If include_ids = TRUE, the idvar, dayvar, and beepvar columns are prepended.

residuals.mlVAR returns a data frame of residuals with the same structure as predict.mlVAR.

resimulate.mlVAR returns a data frame of simulated values. By default (when nTime = NULL), it has the same number of rows as the original input data, with NAs in the same positions as the original data (unless keep_missing = FALSE). If include_ids = TRUE, the idvar, dayvar, and beepvar columns are prepended. When nTime is specified, the output has nIDs * nTime rows with the idvar column and variable columns only. Person-specific stationary means are computed from the model parameters, and innovation covariances are derived from the estimated contemporaneous precision matrices.

Author(s)

Sacha Epskamp (mail@sachaepskamp.com)

References

Bringmann, L. F., Vissers, N., Wichers, M., Geschwind, N., Kuppens, P., Peeters, F., ... & Tuerlinckx, F. (2013). A network approach to psychopathology: New insights into clinical longitudinal data. PloS one, 8(4), e60188.

Hamaker, E. L., & Grasman, R. P. (2014). To center or not to center? Investigating inertia with a multilevel autoregressive model. Frontiers in psychology, 5.

Epskamp, S., Waldorp, L. J., Mottus, R., & Borsboom, D. (2017). Discovering Psychological Dynamics: The Gaussian Graphical Model in Cross-sectional and Time-series Data. arxiv.org/abs/1609.04156.

See Also

mlVARcompare, summary.mlVAR, plot.mlVAR, mlGGM

Examples

## Not run: 
### Small example ###
# Simulate data:
Model <- mlVARsim(nPerson = 50, nNode = 3, nTime = 50, lag=1)

# Estimate using correlated random effects:
fit1 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, temporal = "correlated")

# Print some pointers:
print(fit1)

# Summary of all parameter estimates:
summary(fit1)

# Compare temporal relationships:
layout(t(1:2))
plot(Model, "temporal", title = "True temporal relationships", layout = "circle")
plot(fit1, "temporal", title = "Estimated temporal relationships", layout = "circle")

# Compare contemporaneous partial correlations:
layout(t(1:2))
plot(Model, "contemporaneous", title = "True contemporaneous relationships", 
    layout = "circle")
plot(fit1, "contemporaneous", title = "Estimated contemporaneous relationships", 
    layout = "circle")

# Compare between-subjects partial correlations:
layout(t(1:2))
plot(Model, "between", title = "True between-subjects relationships", layout = "circle")
plot(fit1, "between", title = "Estimated between-subjects relationships",
    layout = "circle")

# Predictions and residuals (same number of rows as input data):
pred <- predict(fit1)
res <- residuals(fit1)
dim(pred)
dim(res)

# Resimulate data from the fitted model (posterior predictive check):
sim <- resimulate(fit1)
dim(sim)  # same dimensions as original data

# Resimulate with custom time series length (e.g., longer series):
sim_long <- resimulate(fit1, nTime = 500)
dim(sim_long)  # nIDs * 500 rows

# Resimulate without applying original missingness pattern:
sim_complete <- resimulate(fit1, keep_missing = FALSE)
sum(is.na(sim_complete))  # only structural NAs (day/beep boundaries)

# Resimulate with empirical innovation variances (model partial correlations,
# scaled by person-specific empirical residual SDs):
sim_emp <- resimulate(fit1, variance = "empirical")
dim(sim_emp)

# Run same model with non-correlated temporal relationships and fixed-effect model:
fit2 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "orthogonal")
fit3 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "fixed")

# Compare models:
mlVARcompare(fit1,fit2,fit3)

# Inspect true parameter correlation matrix:
Model$model$Omega$cor$mean
# Even though correlations are high, orthogonal model works well often!


### Large example ###
Model <- mlVARsim(nPerson = 100, nNode = 10, nTime = 100,lag=1)

# Correlated random effects no longer practical. Use orthogonal or fixed:
fit4 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "orthogonal")
fit5 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "fixed")

# Compare models:
mlVARcompare(fit4, fit5)

# Compare temporal relationships:
layout(t(1:2))
plot(Model, "temporal", title = "True temporal relationships", layout = "circle")
plot(fit4, "temporal", title = "Estimated temporal relationships", layout = "circle")

# Compare contemporaneous partial correlations:
layout(t(1:2))
plot(Model, "contemporaneous", title = "True contemporaneous relationships", 
    layout = "circle")
plot(fit4, "contemporaneous", title = "Estimated contemporaneous relationships", 
    layout = "circle")

# Compare between-subjects partial correlations:
layout(t(1:2))
plot(Model, "between", title = "True between-subjects relationships", layout = "circle")
plot(fit4, "between", title = "Estimated between-subjects relationships", 
    layout = "circle")

## End(Not run)

Fixed and random effects

Description

These functions return a table of the fixed and random effects.

FUNCTIONS ARE DEPRECATED AND WILL BE REMOVED SOON.

Usage

fixedEffects(object, digits = 5)
randomEffects(object, digits = 5)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com), Marie K. Deserno (m.k.deserno@uva.nl) and Laura F. Bringmann (laura.bringmann@ppw.kuleuven.be)

Multilevel VAR Estimation for Multiple Time Series

Description

The function mlVAR0 computes estimates of the multivariate vector autoregression model as introduced by Bringmann et al. (2013) which can be extended through treatment effects, covariates and pre- and post assessment effects.

FUNCTION IS DEPRECATED AND WILL BE REMOVED SOON.

Usage

mlVAR0(data, vars, idvar, lags = 1, dayvar, beepvar,
                 periodvar, treatmentvar, covariates, timevar,
                 maxTimeDiff, control = list(optimizer = "bobyqa"),
                 verbose = TRUE, orthogonal, estimator = c("lmer",
                 "lmmlasso"), method = c("default", "stepwise",
                 "movingWindow"), laginteractions = c("none", "mains",
                 "interactions"), critFun = BIC, lambda = 0,
                 center = c("inSubject","general","none"))

Arguments

Details

mlVAR0 has been built to extract individual network dynamics by estimating a multilevel vector autoregression model that models the time dynamics of selected variables both within an individual and on group level. For example, in a lag-1-model each variable at time point t is regressed to a lagged version of itself at time point t-1 and all other variables at time point t-1. In psychological research, for example, this analysis can be used to relate the dynamics of symptoms on one day (as assessed by experience sampling methods) to the dynamics of these symptoms on the consecutive day.

Value

mlVAR0 returns a 'mlVAR0' object containing

Author(s)

Sacha Epskamp (mail@sachaepskamp.com), Marie K. Deserno (m.k.deserno@uva.nl) and Laura F. Bringmann (laura.bringmann@ppw.kuleuven.be)

References

Bringmann, L. F., Vissers, N., Wichers, M., Geschwind, N., Kuppens, P., Peeters, F., ... & Tuerlinckx, F. (2013). A network approach to psychopathology: New insights into clinical longitudinal data. PloS one, 8(4), e60188.

See Also

fixedEffects, fixedEffects

Examples

## Not run: 
### Small network ###
nVar <- 3
nPerson <- 25
nTime <- 25

# Simulate model and data:
Model <- mlVARsim0(nPerson,nVar,nTime,sparsity = 0.5)

# Run mlVAR0:
Res <- mlVAR0(Model)

# Compare true fixed model with significant edges of estimated fixed model:
layout(t(1:2))
plot(Model,"fixed", title = "True model",layout="circle", edge.labels = TRUE)
plot(Res,"fixed", title = "Estimated model", layout = "circle", onlySig = TRUE, 
        alpha = 0.05, edge.labels = TRUE)

# Compare true and estimated individual differences in parameters:
layout(t(1:2))
plot(Model,"fixed", title = "True model",layout="circle", edge.color = "blue", 
        edge.labels = TRUE)
plot(Res,"fixed", title = "Estimated model", layout = "circle", edge.color = "blue", 
        edge.labels = TRUE)

# Compare networks of subject 1:
layout(t(1:2))
plot(Model,"subject",subject = 1, title = "True model",layout="circle", 
        edge.labels = TRUE)
plot(Res,"subject",subject = 1,title = "Estimated model", layout = "circle", 
        edge.labels = TRUE)



### Large network ###
nVar <- 10
nPerson <- 50
nTime <- 50

# Simulate model and data:
Model <- mlVARsim0(nPerson,nVar,nTime, sparsity = 0.5)

# Run orthogonal mlVAR:
Res <- mlVAR0(Model, orthogonal = TRUE)

# Compare true fixed model with significant edges of estimated fixed model:
layout(t(1:2))
plot(Model,"fixed", title = "True model",layout="circle")
plot(Res,"fixed", title = "Estimated model", layout = "circle", onlySig = TRUE, 
        alpha = 0.05)

# Compare true and estimated individual differences in parameters:
layout(t(1:2))
plot(Model,"fixed", title = "True model",layout="circle", edge.color = "blue")
plot(Res,"fixed", title = "Estimated model", layout = "circle", edge.color = "blue")

# Compare networks of subject 1:
layout(t(1:2))
plot(Model,"subject",subject = 1, title = "True model",layout="circle")
plot(Res,"subject",subject = 1,title = "Estimated model", layout = "circle")

## End(Not run)

print and summary functions for mlVAR0 objects

Description

Create a short summary of an object created by mlVAR0.

FUNCTION IS DEPRECATED AND WILL BE REMOVED SOON.

Usage

  ## S3 method for class 'mlVAR0'
print(x, ...)
  ## S3 method for class 'mlVAR0'
summary(object, ...)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com), Marie K. Deserno (m.k.deserno@uva.nl) and Laura F. Bringmann (laura.bringmann@ppw.kuleuven.be)

Compare mlVAR model fit

Description

This function compares the fit of several mlVAR models. Since an mlVAR model is a combination of univariate models this function will compare the fits for each univariate model.

Usage

mlVARcompare(...)

Arguments

Details

Important to note is that the number of observations must be equal to make models comparable. If the lags are different and compareToLags was not used in mlVAR this function will stop with an informative error message.

Author(s)

Sacha Epskamp (mail@sachaepskamp.com)

Examples

## Not run: 
### Small example ###
# Simulate data:
Model <- mlVARsim(nPerson = 50, nNode = 3, nTime = 50, lag=1)

# Estimate using different methods:
fit1 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "correlated")
fit2 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "orthogonal")
fit3 <- mlVAR(Model$Data, vars = Model$vars, idvar = Model$idvar, lags = 1, 
    temporal = "fixed")

# Compare models:
mlVARcompare(fit1,fit2,fit3)

## End(Not run)

Simulator function given an mlVAR object

Description

Simulates data based on an mlVAR object, estimates the mlVAR network model based on the simulated data and compares the estimated network to the mlVAR object network.

Usage

mlVARsample(object, nTime = c(25,50,100,200), nSample = 100, pMissing = 0, 
  nReps = 100, nCores = 1, ...)

## S3 method for class 'mlVARsample'
summary(object, ...)

Arguments

Details

This function simulates data based on the mlVAR object. The individual networks (random effects) are used to simulate data using the graphicalVARsim function from the graphicalVAR package (Epskamp, 2020). The individual data is combined into one dataset. This dataset is used to estimate the mlVAR network.

For every condition, the function returns four values per network comparison measure (correlation, sensitivity, specificity, bias, and precision): one for the fixed temporal effects, one for the fixed contemporaneous effects, the mean comparison value of the random temporal effects, and the mean comparison value of the random contemporaneous effects.

Author(s)

Sacha Epskamp <mail@sachaepskamp.com>

References

Sacha Epskamp (2020). graphicalVAR: Graphical VAR for Experience Sampling Data. R package version 0.2.3. https://CRAN.R-project.org/package=graphicalVAR

See Also

mlVARsim, mlVAR

Examples

## Not run: 
### Small example ###
# Simulate data:
Model <- mlVARsim(nPerson = 100, nNode = 3, nTime = 50, lag=1)

# Estimate using correlated random effects:
fit <- mlVAR(Model$Data, vars = Model$vars, 
             idvar = Model$idvar, lags = 1, 
             temporal = "correlated")

# Sample from fitted model: 
samples <- mlVARsample(fit, nTime = 50, nSample = 50, pMissing = 0.1,
                       nReps = 5, nCores = 1)

# Summarize results:
summary(samples)

## End(Not run) 

Simulates an mlVAR model and data

Description

Simulates an mlVAR model and data with a random variance-covariance matrix for the random effects.

Usage

mlVARsim(nPerson = 10, nNode = 5, nTime = 100, lag = 1, thetaVar = rep(1,nNode),
DF_theta = nNode * 2, mu_SD = c(1, 1), init_beta_SD = c(0.1, 1), fixedMuSD = 1, 
shrink_fixed = 0.9, shrink_deviation = 0.9, beta_sparsity = 0.5, pcor_sparsity = 0.5)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com)

Plot Method for mlVAR

Description

The function plot.mlVAR plots estimated model coefficients as networks using qgraph. These can be three networks: temporal, contemporaneous and between-subjects effects, of which the latter two can be plotted as a correlation or a partial correlation network.

Usage

  ## S3 method for class 'mlVAR'
plot(x, type = c("temporal", "contemporaneous", "between"),
                 lag = 1, partial = TRUE, SD = FALSE, subject, order,
                 nonsig = c("default", "show", "hide", "dashed"), rule
                 = c("or", "and"), alpha = 0.05, onlySig = FALSE,
                 layout = "spring", verbose = TRUE, ...)
  ## S3 method for class 'mlVARsim'
plot(x, ...)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com)

Plot Method for mlVAR0

Description

The function plot.mlVAR0 plots estimated model coefficients as a network using qgraph.

FUNCTION IS DEPRECATED AND WILL BE REMOVED SOON.

Usage

  ## S3 method for class 'mlVAR0'
plot(x, type = c("fixed", "SD", "subject"), lag = 1,
                 subject, order, onlySig = FALSE, alpha, ...)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com), Marie K. Deserno (m.k.deserno@uva.nl) and Laura F. Bringmann (laura.bringmann@ppw.kuleuven.be)

Simulate data from VAR model

Description

Simulates a timeseries using VAR parameters

Usage

simulateVAR(pars,  means = 0, lags = 1, Nt = 100, init, residuals = 0.1,
                 burnin)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com), Marie K. Deserno (m.k.deserno@uva.nl) and Laura F. Bringmann (laura.bringmann@ppw.kuleuven.be)

Summary of mlVAR results

Description

Prints tables with fit indices and parameter estimates.

Usage

## S3 method for class 'mlVAR'
summary(object, show = c("fit", "temporal", "contemporaneous", "between"), 
      round = 3, ...)
## S3 method for class 'mlVAR'
print(x, ...)

Arguments

Author(s)

Sacha Epskamp (mail@sachaepskamp.com), Marie K. Deserno (m.k.deserno@uva.nl) and Laura F. Bringmann (laura.bringmann@ppw.kuleuven.be)