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

```{r, include = FALSE}
EVAL_DEFAULT <- FALSE
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = EVAL_DEFAULT
)
```

```{r setup}
library(modsem)
```

# The Basic Syntax

`modsem` introduces a new feature to the `lavaan` syntax—the semicolon operator (`:`). The semicolon operator works the same way as in the `lm()` function. To specify an interaction effect between two variables, you join them by `Var1:Var2`. 

Models can be estimated using one of the product indicator approaches (`"ca"`, `"rca"`, `"dblcent"`, `"pind"`) or by using the latent moderated structural equations approach (`"lms"`) or the quasi maximum likelihood approach (`"qml"`). The product indicator approaches are estimated via `lavaan`, while the `lms` and `qml` approaches are estimated via `modsem` itself.

## A Simple Example

Here is a simple example of how to specify an interaction effect between two latent variables in `lavaan`.

```{r}
m1 <- '
  # Outer Model
  X =~ x1 + x2 + x3
  Y =~ y1 + y2 + y3
  Z =~ z1 + z2 + z3
  
  # Inner Model
  Y ~ X + Z + X:Z 
'

est1 <- modsem(m1, oneInt)
summary(est1)
```

By default, the model is estimated using the `"dblcent"` method. If you want to use another method, you can change it using the `method` argument.

```{r}
est1 <- modsem(m1, oneInt, method = "lms")
summary(est1)
```

## Interactions Between Two Observed Variables

`modsem` allows you to estimate interactions between not only latent variables but also observed variables. Below, we first run a regression with only observed variables, where there is an interaction between `x1` and `z2`, and then run an equivalent model using `modsem()`.

### Using a Regression

```{r}
reg1 <- lm(y1 ~ x1*z1, oneInt)
summary(reg1)
```

### Using `modsem`

`modsem` can also be used to to estimate interaction effects between observed variables.
Interaction effects with observed variables are not supported by the `LMS` and `QML` approaches. 
In most cases, you can define a latent variable with a single indicator to estimate the interaction 
effect between two observed variables in the `LMS` and `QML` approaches.

```{r}
est2 <- modsem('y1 ~ x1 + z1 + x1:z1', data = oneInt, method = "dblcent")
summary(est2)
```

## Interactions Between Latent and Observed Variables

`modsem` also allows you to estimate interaction effects between latent and observed variables. 
To do so, simply join a latent and an observed variable with a colon (e.g., `'latent:observed'`). 
In most of the product indicator approaches the residuals of product indicators with common variables (e.g., `x1z1` and `x1z2`)
are allowed to covary freely. This is problematic when there is an interaction term between an observed variable
(or a latent variable with a single indicator) and a latent variables (with multiple indicators), since
all of the product indicators share a common element. 

In the example below, all the generated product indicators
(`x1z1`, `x2z1` and `x3z1`) share `z1`. If all the indicator residuals of
a latent variabel are allowed to covary freely, the model
will (in general) be unidenfified. The simplest way to fix this issue, is to constrain the residual covariances
to be zero, by using the `res.cov.method` argument.

```{r}
m3 <- '
  # Outer Model
  X =~ x1 + x2 + x3
  Y =~ y1 + y2 + y3
  
  # Inner Model
  Y ~ X + z1 + X:z1 
'

est3 <- modsem(m3, oneInt, method = "dblcent", res.cov.method = "none")
summary(est3)
```

## Quadratic Effects

Quadratic effects are essentially a special case of interaction effects. Thus, `modsem` can also be used to estimate quadratic effects.

```{r}
m4 <- '
# Outer Model
X =~ x1 + x2 + x3
Y =~ y1 + y2 + y3
Z =~ z1 + z2 + z3

# Inner Model
Y ~ X + Z + Z:X + X:X
'

est4 <- modsem(m4, oneInt, method = "qml")
summary(est4)
```

## More Complicated Examples

Here is a more complex example using the theory of planned behavior (TPB) model.

```{r}
tpb <- ' 
# Outer Model (Based on Hagger et al., 2007)
  ATT =~ att1 + att2 + att3 + att4 + att5
  SN =~ sn1 + sn2
  PBC =~ pbc1 + pbc2 + pbc3
  INT =~ int1 + int2 + int3
  BEH =~ b1 + b2

# Inner Model (Based on Steinmetz et al., 2011)
  INT ~ ATT + SN + PBC
  BEH ~ INT + PBC + INT:PBC  
'

# The double-centering approach
est_tpb <- modsem(tpb, TPB)

# Using the LMS approach
est_tpb_lms <- modsem(tpb, TPB, method = "lms")
summary(est_tpb_lms)
```

Here is an example that includes two quadratic effects and one interaction effect, using the `jordan` dataset. The dataset is a subset of the PISA 2006 dataset.

```{r}
m2 <- '
ENJ =~ enjoy1 + enjoy2 + enjoy3 + enjoy4 + enjoy5
CAREER =~ career1 + career2 + career3 + career4
SC =~ academic1 + academic2 + academic3 + academic4 + academic5 + academic6
CAREER ~ ENJ + SC + ENJ:ENJ + SC:SC + ENJ:SC
'

est_jordan <- modsem(m2, data = jordan)
est_jordan_qml <- modsem(m2, data = jordan, method = "qml")
summary(est_jordan_qml)
```