stim-vignette

In stim: Incorporating Stability Information into Cross-Sectional Estimates

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

The stim package fits the Stability Informed Model which incorporates variable stability--how a variable correlates with future versions of itself--into cross-sectional estimates. Assuming the process is stationary, the model is specified correctly, and the stability values are correct, the Stability Informed Model can estimate parameters that are unbiased for cross-lagged (longitudinal) effects even when only cross-sectional data are available.

For more information on the Stability Informed Model see https://psyarxiv.com/vg5as

This tutorial outlines how to estimate a Stability Informed Model using the stim package within an SEM framework.

Installation

You can install the development version of stim from GitHub with

devtools::install_github("https://github.com/AnnaWysocki/stim")

Example

Let's create some data to use in our example.

library(stim)

S <-  matrix(c(1, .3, .3,
              .3,  1, .3,
              .3, .3,  1), 
             nrow = 3, ncol = 3,
             dimnames = list(c("X", "Y", "Z"), 
                             c("X", "Y", "Z")))

stim Function Overview

Estimate a single or a set of Stability Informed Models using the stim() function.

stim() has five arguments

• data : A data frame with the measured variables. Not needed if S is provided.
• S: A covariance matrix for the measured variables. Not needed if data is provided.
• n: Number of observations in data set. Not needed if data is provided.
• model: An object with the cross-sectional model specified in lavaan syntax.
• stability: an object with the stability information for each variable in the model

More details on the model and stability arguments can be found below.

The model Argument

Input an object with the cross-sectional model specified in lavaan syntax. \n The model syntax should be specified as a cross-sectional path model in lavaan (See https://lavaan.ugent.be/tutorial/tutorial.pdf for information on lavaan syntax).

This input determines what parameters/effects are estimated. Note, the Stability Informed model can estimate a maximum of $$ \frac{p (p-1)}{2} $$ parameters (where p is the number of measured variables). These parameters can be, for example, cross-lagged effects or residual covariances.

To estimate the effect of X on Y, I could create the following object

model <- 'Y ~ X' # outcome ~ predictor

More complex models can be specified as well.

model2 <- 'Y ~ X
           Z ~ X + Y'

The default is to constrain all residual covariances to 0. But this constraint can be relaxed by specifying a residual covariance in the model syntax.

model2 <- 'Y ~ X
           Z ~ X + Y

           X ~~ Y' # Allows X and Y to have covarying residuals

The above model object specifies 4 estimated parameters, but, with 3 measured variables, the Stability Informed Model can only estimate 3 parameters. The remaining effects can either be fixed to 0 or fixed to a non-zero value.

model2 <- 'Y ~ .6 * X  # fix effect of X on Y to .6
           Z ~ X + Y

           X ~~  Y' 

Labels can be specified for the estimated parameters.

model2 <- 'Y ~ .6 * X 
           Z ~ Effect1 * X + Y # label the estimated effect of X on Z

           X ~~ Y'

If no label is specified for a cross-lagged parameter, the default label is 'CL' and a subscript with the predictor name and the outcome name.

Residual covariances are labeled 'RCov' and a subscript with the names of the two variable whose residuals are covarying.

Inputs for the stability Argument

Input a object with the stability information for each variable in the model.

To fit model2, the stability input should have a stability value for X, Y, and Z.

stability <- c(X = .5, Y = .1, Z = .1)

The stability values need to be named, and the names must match the variable names in the data or S input.

Multiple stability values can be specified for each variable. This results in multiple Stability Informed Models being estimated (one for each stability condition).

stability <- data.frame(X = c(.5, .55), Y = c(.1, .15), Z = c(.1, .2))

rownames(stability) <- c("Model 1", "Model 2")

stability

If this is the stability input, two models will be estimated. One model where the stability values for X, Y, and Z are .5, .1, and .1, respectively, and one where the stability values for X, Y, and Z are .55, .15, and .2, respectively.

Estimate the Stability Informed Model

modelFit <- stim(S = S, n = 1000, model = model2, stability = stability) 

Some information about the model(s) is automatically printed out when the stim() function is run. The summary() function can be used to print out more information

summary(modelFit)

Eploring the stim Output Object

modelFit is a stim object that contains a list of objects with information for the Stability Informed Model

• n: Sample size
• p: Number of measured variables used in the Stability Informed Model
• q: Number of estimated parameters
• df: Degrees of freedom
• stability : A table of the stability conditions
• CLEffectTable : A table with information on which cross-lagged effects are estimated
• CLMatrices: A list of matrices (1 for each Stability Informed Model that was estimated) with the estimated cross-lagged effects and their associated standard errors and p-values.
• RCovMatrices: A list of matrices (1 for each Stability Informed Model that was estimated) with the estimated residual covariances and their associated standard errors and p-values.
• ARVector: A list of vectors (1 for each Stability Informed Model that was estimated) with the values for the auto-regressive effects.
• lavaanObjects : A list of lavaan objects (1 for each Stability Informed Model that was estimated)
• NoWarnings : A vector with information on whether there were any errors or warnings for each of the estimated models
• CSModelSyntax : The user-specified model syntax (input for model argument)
• SIMSyntax : The syntax for the Stability Informed Model--model syntax for the lavaan function
• modelImpliedEquations : Model implied equations for the latent covariances and auto-regressive effects

stability

A table of the stability conditions. Each row contains the stability information for one Stability Informed Model.

modelFit$stability 

CLEffectTable

A table with information on the cross-lagged paths. It has the predictor and outcome names, cross-lagged effect labels, and whether the cross-lagged path is estimated or constrained.

modelFit$CLEffectTable 

CLMatrices

A list of matrices with the estimated cross-lagged effects and standard errors and p-values for each of the estimated cross-lagged effects. Each matrix corresponds to one of the estimated Stability Informed Models.

modelFit$CLMatrices 

RCovMatrices

A list of matrices with the estimated residual covariances and their standard errors and p-values. Each matrix corresponds to one of the estimated Stability Informed Models.

modelFit$RCovMatrices 

ARVector

A list of vectors (1 for each Stability Informed Model that was estimated) with the values for the auto-regressive effects.

A list of vectors with the values for each auto-regressive effect. Each vector corresponds to one of the estimated Stability Informed Models.

modelFit$ARVector

lavaanObjects

A list of lavaan objects (1 for each Stability Informed Model)

To output the lavaan object easily, you can use the lavaanSummary() function

lavaanSummary(modelFit)

You can also print a subset of the lavaan objects by using the subset argument.

lavaanSummary(modelFit, subset = 1)

NoWarnings

A vector with logical information on whether there were any errors or warnings for each of the estimated models.

FALSE means no warnings TRUE means warnings.

modelFit$NoWarnings # Means no warnings for both models

CSModelSyntax

The user-specified model syntax (input for model argument)

modelFit$CSModelSyntax 

SIMSyntax

The syntax for the Stability Informed Model--model syntax for the lavaan function. This contains the syntax to specify the structural part of the Stability Informed Model as well as the parameter constraints for the auto-regressive paths and the latent correlations

modelFit$SIMSyntax 

modelImpliedEquations

Model implied equations for the latent covariances and auto-regressive paths

modelFit$modelImpliedEquations 

stim documentation built on Jan. 23, 2023, 5:33 p.m.