---
title: "Conducting a moderated mediation analysis"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Conducting a moderated mediation analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: "`r system.file('references.bib', package='JSmediation')`"
csl: "`r system.file('apa.csl', package='JSmediation')`"
---

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

## Overview

This vignette reports a moderated mediation analysis. This will help getting familiar with the several helpers *JSmediation* offers to conduct moderated mediation analysis.

Simple mediation refers to the pattern of statistical relationships in which the effect of a variable on another goes through a third variable. Sometimes, this indirect relationship is conditional to a fourth variable---a moderator. In such a case, we talk about **moderated mediation**. The *JSmediation* package offers a collection of tools to conduct and report a moderated mediation analysis [@muller_when_2005].

## Conducting a Moderated Mediation Analysis

The [Introduction to JSmediation](jsmediation.html) vignette uses a data set collected by Ho et al. [-@ho_youre_2017] to illustrate simple mediation. This data set contains the result of an experiment in which Ho et al. focus on hypodescent among Black Americans. To illustrate how *JSmediation* can be used to conduct a moderated mediation analysis, we will expand on this example.

```{r setup, message=FALSE}
library(JSmediation)
```

Hypodescent refers to a rule observed in multiracial categorization. Research shows that majority group social perceivers (i.e., White Americans) typically associate Black-White multiracials with their lower status group rather than with their higher group (i.e., with Black Americans rather than with White Americans). This phenomenon is called the hypodescent rule and it was retrieved in the Black Americans population by Ho et al. [-@ho_youre_2017]. The hypothesis is that such categorization occurs because of a sentiment of linked fate between Black Americans and Black-White multiracials.

This observation was supported by data showing that Black Americans felt a stronger sentiment of linked fate between them and Black-White multiracials when they read about an article discussing how Black-White multiracials were likely to suffer from discrimination (compared to an article discussing how they were not). The higher sentiment of linked fate was associated with a higher use of the hypodescent rule in multiracial categorization. In other words, the effect of a discrimination condition on hypodescent rule was mediated by the feeling of linked fate.

In the current vignette, we will investigate whether this indirect effect is moderated by social dominance orientation (SDO). Indeed, SDO correlates with preferences for intergroup equality---higher levels indicates resistance to intergroup equality and support for maintaining status quo, lower levels indicates support for intergroup equality and reducing hierarchy [@ho_youre_2017]. Ho et al. [-@ho_youre_2017] assumed that the indirect effect will be stronger for Black Americans showing lower levels of SDO. They should feel a higher sentiment of linked fate when presented information related to the high discrimination of Black-White multiracials.

```{r}
data(ho_et_al)
```

While this vignette was written to illustrate features from the *JSmediation* package, we will use functions from other packages (e.g., *dplyr*), but make it explicit when we do so. In other words, rather than calling `library(dplyr)` to attache the *dplyr* package and then calling its function (e.g., `mutate`), we will use `dplyr::mutate`, `mutate` will suffice.

### Data Preparation

The data set collected by Ho et al. [-@ho_youre_2017] contains the information necessary for the test of our hypothesis of moderated mediation. It contains a `condition` column indicating whether participants were read about the high or low discrimination of Black-White multiracials and a `hypodescent` column. The data set also contains a `linkedfate` column indicating the feeling of linked fate participants felt in the experimental situation. The simple mediation analysis in the [Introduction to JSmediation](jsmediation.html) vignette shows that participants in high discrimination conditions tend to feel a higher level of linked fate which results in higher hypodescent. We will now investigate whether this indirect effect is more likely to be observed among participants who show higher levels of SDO (thanks to the `sdo` column).

```{r}
head(ho_et_al)
```

Before we run the moderated mediation analysis, we must tweak the data set a little bit. Muller et al. [-@muller_when_2005] recommend centering the continuous predictors and contrast-coding the categorical ones. *JSmediation* offers helpers like `build_contrast` or `standardize_variable` to do so.

```{r}
ho_et_al <-
  ho_et_al %>%
  standardize_variable(c(sdo, linkedfate), suffix = "c") %>%
  dplyr::mutate(condition_c = build_contrast(condition,
                                             "Low discrimination",
                                             "High discrimination")
  )

head(ho_et_al)
```

The first function we used, `standardize_variable`, allows us to center and reduce (to standardize) a set of variables (here: `sdo` and `linkedfate`). The `suffix` argument of this function is used to name the standardized variables. Here, because we set `suffix = "c"`, the new variables are named `sdo_c` and `linkedfate_c`. When the suffix argument is blank, original variables are overwritten. Because *JSmediation* was designed to fit within the tidyverse, `standardize_variable` is especially useful in a *dplyr* [chain](https://dplyr.tidyverse.org/articles/dplyr.html#combining-functions-with-%20%22Combining%20functions%20with%20%60%%3E%%60%22).

Here, we also used a second function from *JSmediation*: `build_contrast`. This function takes a character vector as a first argument and, then, returns a contrast-coded variables. It is designed for variables with two conditions, which is the case of `condition`. Because we want to include the transformed variable in `ho_et_al`, we can use the `dplyr::mutate` function which [creates (or modify) variables](https://dplyr.tidyverse.org/reference/mutate.html "Create, modify, and delete columns"). With this method, we contrast-coded the `condition` variable.

```{r}
ho_et_al %>% 
  dplyr::select(dplyr::starts_with("condition"))
```

### Fitting the moderated mediation model

We will now run our moderated mediation analysis. Remember, we are testing whether participants in high discrimination condition show higher level of hypodescent because of a higher perception of linked fate, and whether this indirect effect is higher among people with high level of SDO. In other words, we are testing whether SDO moderates the mediation of the effect on condition on hypodescent through linked fate perception. To test this moderated mediation, we will use the `mdt_moderated` function.

#### Moderated mediation formalization

Muller et al. [-@muller_when_2005] provide an accessible introduction on how to conduct a moderated mediation analysis using the joint-significance methods. In a nutshell, one will fit several linear models to the data set, and, depending on the significance of some coefficients, one will be able to assess moderated mediation.

To better understand the process of testing a moderated mediation, we can glance at the equation describing the moderation of the indirect effect of X on Y. Such moderation can be described as follows:

$$
c \times Mod = c' \times Mod + (a \times Mod) \times b + a \times (b \times Mod)
$$

with $c \times Mod$ the total moderation of the indirect effect, $c' \times Mod$ the moderation of the direct effect, $(a \times Mod) \times b$, the moderation of the indirect effect passing by the moderation of $a$, and $a \times (b \times Mod)$, the moderation of the indirect effect passing by the moderation of $b$ (see Models section; Muller et al., 2005).

Either both $a \times Mod$ and $b$ or both $a$ and $b \times Mod$ need to be simultaneously significant for the moderation of the indirect effect to be claimed (Muller et al., 2005).

#### Running the Analysis with `mdt_moderated`

`mdt_moderated` works like every `mdt_*` function. It will be fit the necessary linear models (see the Models section in the help page of `mdt_moderated`) and returns the relevant coefficient in a nicely formatted output.

To use the function, we will have to describe the role of the variable in the `ho_et_al` data set.

```{r}
moderated_mediation_fit <- 
  mdt_moderated(data = ho_et_al,
                IV   = condition_c,
                DV   = hypodescent, 
                M    = linkedfate_c,
                Mod  = sdo_c)
```

Most of the math occurs when `mdt_moderated` is evaluated. The `moderated_mediation_fit` that we just computed contains every linear model useful to assess moderated mediation, as described in Muller et al. [-@muller_when_2005].

As we can see, it is possible to see $a$, $a \times Mod$, $b$, and $b \times Mod$ in the `mdt_moderated` output.

```{r}
moderated_mediation_fit
```

If a moderated mediation model is significant, Yzerbyt et al. [-@yzerbyt_new_2018] recommend reporting the moderated mediation index. To compute this index, *JSmediation* offers the `add_index`method. In the case of moderated mediation, we will have to specify whether we are in a scenario where we assume that the moderator impacts the relation between or IV and the mediator (i.e., both $a \times Mod$ and $b$ are significant), the relation between the moderator and the DV (i.e., both $a$ and $b \times Mod$ are significant), or both. To do so, we must use the `stage` argument.

```{r}
moderated_mediation_fit_w_index <- moderated_mediation_fit %>%
  add_index(stage = "first")
```

The output of the new object now contains the index.

```{r}
moderated_mediation_fit_w_index
```

#### Reporting Moderated Mediation

The `moderated_mediation_fit_w_index` object that we computed contains every bit of information to report a moderated mediation in an analysis, following Yzerbyt et al.'s [-@yzerbyt_new_2018] recommendations:

> To assess whether SDO moderates the indirect effect of discrimination condition on hypodescent through linked fate perception, we conducted a moderated mediation analysis [@muller_when_2005]. This analysis first revealed that SDO moderates the effect of condition on linked fate perception, *t*(820) = 4.25, *p* \< .001. It also revealed that the effect of linked fate perception for a mean level of SDO, and controlling for the effect of the condition and for the moderation of the condition by SDO, predicted significantly hypodescent, *t*(818) = 3.75, *p* \< .001. This pattern reveals the existence of a moderated mediation. We also computed the first stage moderated mediation index consistent with our joint-significant analysis and it confirmed the moderated mediation, -0.0432, CI<sub>95%</sub> [-0.0778; -0.0171] (Monte Carlo simulation, 5000 simulations; Yzerbyt et al., 2018).

## Compute the indirect effect for a moderator's value

When reporting a moderated mediation analysis, it is sometimes useful to know what the indirect effect is for several values of the moderator. The `compute_indirect_effect_for` function serves that purpose.

`compute_indirect_effect_for` takes as the first argument a moderated mediation model for which we want to compute the indirect effect at a specific value of the moderator and as the second argument the value of the moderator.

In our example, we standardized our moderator. A mean value of the moderator therefore is `sdo_c = 0`. If we wanted to compute the effect of condition on hypodescent through linked fate for a mean value of SDO, we would have to run the following:

```{r}
compute_indirect_effect_for(moderated_mediation_fit, Mod = 0)
```

We could also compute this indirect effect for participants who score one standard deviation above the mean in terms of SDO.

```{r}
compute_indirect_effect_for(moderated_mediation_fit, Mod = 1)
```

As we can see, the indirect effect estimate decreases when the SDO increases. This result is consistent with the negative value of the moderated mediation index.

# References