---
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 basically introduces a new feature to the lavaan-syntax -- the semicolon operator (":").
The semicolon operator works the same way as in the lm()-function. In order to specify an interaction effect between two variables, you join them by Var1:Var2,
Models can either be estimated using the 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, whilst the lms and qml approaches are estimated via modsem itself.

## A Simple Example
Here we can see 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, 
but the method can be changed using the method argument. 

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

## Interactions Between two Observed Variables

modsem does not only allow you to estimate interactions between latent variables, but also interactions between observed variables. Here 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().

**Regression**

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

**Using modsem()** In general, when you have interactions between observed variables it is recommended that you use method = "pind".
Interaction effects with observed variables is not supported by the LMS- and QML-approach. 
In certain circumstances, you can define a latent variabale with a single indicator to estimate the interaction effect between two observed variables, 
in the LMS and QML approach, but it is generally not recommended.

```{r}
# Here we use "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, you just join a latent and an observed variable by a colon, e.g., 'latent:observer'. As with interactions between observed variables, it is generally recommended that you use method = "pind" for estimating the effect between observed x latent

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

In essence, quadratic effects are just 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, "qml")
summary(est4)
```

## More Complicated Examples 

Here we can see a more complicated example using the model for the theory of planned behaviour.

```{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 apporach
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 included two quadratic- and one interaction effect,
using the included dataset `jordan`.
The dataset is 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: The other approaches work as well, but might be quite slow depending on the number of interaction effects (particularly for the LMS- and constrained approach).