---
title: "stim-vignette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{stim-vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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

```{r installation, eval = FALSE}
devtools::install_github("https://github.com/AnnaWysocki/stim")
```

## Example 

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

```{r data}
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

```{r modelspec1}
model <- 'Y ~ X' # outcome ~ predictor
```

More complex models can be specified as well.

```{r modelspec2}
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. 

```{r modelspec3}
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. 


```{r modelspec4}
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.

```{r modelspec5}
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. 

```{r stability1}
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). 


```{r stability2}
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 

```{r stim1}
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 

```{r}
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. 
```{r output 1}
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. 

```{r output 2 }
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. 

```{r output 3}
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. 

```{r output 4}
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. 

```{r output 5}
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`
```{r output 6}
lavaanSummary(modelFit)

```

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

```{r output 6.2}
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. 
```{r output 7}
modelFit$NoWarnings # Means no warnings for both models

```

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

```{r output 8}
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

```{r output 9}
modelFit$SIMSyntax 

```

#### modelImpliedEquations 

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

```{r output 10}
modelFit$modelImpliedEquations 

```



