README.Rmd

---
output: github_document
always_allow_html: true
---

<!-- README.md is generated from README.Rmd. Please edit that file 
use devtools::build_readme() to update README.md-->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  warning = FALSE, message = FALSE,
  out.width = "100%"
)
```

# rmedsem <a href="https://ihrke.github.io/rmedsem/"><img src="man/figures/logo.png" align="right" height="139" /></a>

<!-- badges: start -->
<!-- badges: end   -->


The goal of rmedsem is to conduct a mediation analysis based on a structural equation model (SEM), including observed and/or latent variables as well as combination of observed and latent variables. The package supports: 

- covariance-based SEM estimated with the [lavaan](https://lavaan.ugent.be/) package
- PLS-SEM estimated using [cSEM](https://m-e-rademaker.github.io/cSEM/)
- Bayesian SEM estimated using [blavaan](https://ecmerkle.github.io/blavaan/index.html)


Currently, only continuous independent and mediator variables are
supported. See [this article](articles/mediation_technical.html) for technical details on
the estimation procedure used.

See the examples in the section below and refer to the `rmedsem()` documentation.
Examples covering the different estimation methods (CB-SEM, PLS-SEM, Bayesian SEM) are
detailed in [this article](articles/estimation_methods.html).


## Installation

You can install the development version of rmedsem from
[GitHub](https://github.com/) with:

```r
# install.packages("devtools")
devtools::install_github("ihrke/rmedsem")
```

## Getting started

We start with a simple example using the `hsbdemo` dataset included in `rmedsem`.
In this model, we include only observed variables and have a simple case in which
mathematical skills `math` directly affect performance in science-related areas `science`
and where part of this association is mediated thrugh their abiliy to `read`.

```{r, echo=F, warning=F, message=FALSE}
library(DiagrammeR)
grViz("
digraph {
  rankdir=LR;
    math -> read;
    read -> science;
    math -> science;
}")
```

```{r, eval=F,echo=F, warning=F, message=FALSE}
mod.txt <- "
  read ~ math
  science ~ read + math
"
library(lavaan)
mod <- lavaan::sem(mod.txt, data=rmedsem::hsbdemo)
semPlot::semPaths(mod)
```

We can express this model in `lavaan` syntax as follows:

```{r}
mod.txt <- "
  read ~ math
  science ~ read + math
"

```

Once specified, we can use `lavaan` to fit the model using CB-SEM:

```{r, message=F}
library(lavaan)
mod <- lavaan::sem(mod.txt, data=rmedsem::hsbdemo)
```

We can inspect the estimated coefficients using `lavaan`s methods (`summary()` etc). To run the mediation analysis, we use `rmedsem()` and specify the independent variable (`indep="math"`), the mediator (`med="red"`) and the dependent variable (`dep="science"`). The output is captured in an output object `out` which implements a printing function (`print.rmedsem()`) to show a summary
of the results:

```{r}
library(rmedsem)
out <- rmedsem(mod, indep="math", med="read", dep="science")
print(out)
```

The result reports the estimated indirect effect using the Sobel, Delta and Monte-Carlo methods (see [technical details](articles/mediation_technical.html)) and also explains the Baron-Kenny procedure in detail.

We can switch to an alternative method by Zhao, Lynch & Chen (2010) using the `approach="zlc"` option (here we also switched to standardized coefficients using `standardized=T`): 
```{r}
rmedsem(mod, indep="math", med="read", dep="science",
        standardized=T, approach = "zlc")
```

We can also apply `rmedsem()` to more complex SEM's that contain both latent and
observed variables:

```{r, warning=F}
model03 <- "
   Attractive =~ face + sexy
   Appearance =~ body + appear + attract
   Muscle =~ muscle + strength + endur
   Weight =~ lweight + calories + cweight
   Appearance ~ Attractive + age
   Muscle ~ Appearance + Attractive + age
   Weight ~ Appearance + Attractive + age
"
mod <- sem(model03, data=rmedsem::workout)
```

```{r, echo=F}
semPlot::semPaths(mod)
```
Here, we have latent variables `Appearance`, `Attractiveness`, `Muscle` and `Weight` that measure the motivation of people going to a gym to workout.

This model features several complex mediation pathways. We can use `rmedsem()` to investigate
those one by one. We start by considering the pathway `Attractive` -> `Appearance` -> `Muscle` (the more attractive the person perceives her/himself, the more this will indirectly influence her/him to want to work out more to build up muscles):

```{r}
rmedsem(mod, indep="Attractive", med="Appearance", dep="Muscle",
        approach = c("bk","zlc"))
```

Similarly, we could investigate the pathway `Attractive` -> `Appearance` -> `Weight` (the more attractive the person perceives her/himself, the more this will indirectly influence her/him to want to work out more to lose weight):

```{r}
rmedsem(mod, indep="Attractive", med="Appearance", dep="Weight",
        approach = "zlc")
```

Note that these models involve latent variables. It is also possible to use a combination of latent and observed variables and to use [different packages/estimation techniques](articles/estimation_methods.html) to fit the models.