---
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`

When you have interactions between observed variables, it is generally recommended to use `method = "pind"`. Interaction effects with observed variables are not supported by the `LMS` and `QML` approaches. In some 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, but this is generally not recommended.

```{r}
# Using "pind" as the method (see Chapter 3)
est2 <- modsem('y1 ~ x1 + z1 + x1:z1', data = oneInt, method = "pind")
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:observer'`). As with interactions between observed variables, it is generally recommended to use `method = "pind"` for estimating the effect between latent and observed variables.

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

est3 <- modsem(m3, oneInt, method = "pind")
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)
```

**Note**: Other approaches also work but may be quite slow depending on the number of interaction effects, particularly for the `LMS` and constrained approaches.