---
title: "Contrast analysis"
output: 
  rmarkdown::html_vignette:
    toc: true
    fig_width: 10.08
    fig_height: 6
tags: [r, estimate, marginal means, emmeans, contrast analysis, post hoc, pairwise t tests]
vignette: >
  %\VignetteIndexEntry{Contrast analysis}
  \usepackage[utf8]{inputenc}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
bibliography: bibliography.bib
---

```{r, include=FALSE}
library(knitr)
options(knitr.kable.NA = "")
knitr::opts_chunk$set(
  comment = ">",
  message = FALSE,
  warning = FALSE,
  out.width = "100%",
  dpi = 300
)
options(digits = 2)

if (!requireNamespace("ggplot2", quietly = TRUE) ||
  !requireNamespace("see", quietly = TRUE) ||
  !requireNamespace("rstanarm", quietly = TRUE)) {
  knitr::opts_chunk$set(eval = FALSE)
}

set.seed(333)
```

# Testing pairwise differences

In the [**previous tutorial**](https://easystats.github.io/modelbased/articles/estimate_means.html),
we computed marginal means at the 3 different `Species` levels from the
[`iris`](https://en.wikipedia.org/wiki/Iris_flower_data_set) dataset. However,
one might also want to **statistically test** the differences between each
levels, which can be achieved through **contrast analysis**. Although the
procedure is much more powerful, its aim is analogous to the ***post hoc***
analysis (pretty much consisting of pairwise *t*-tests), which are heavily
utilized in behavioral sciences as a way to follow up on hypotheses about global
differences tested by ANOVAs with more specific hypotheses about pairwise
differences.

Let's carry out contrast analysis on the simple model from the previous tutorial:

```{r}
library(ggplot2)
library(see)
library(modelbased)

model <- lm(Sepal.Width ~ Species, data = iris)
means <- estimate_means(model)

ggplot(means, aes(x = Species, y = Mean)) +
  geom_line(aes(group = 1)) +
  geom_pointrange(aes(color = Species, ymin = CI_low, ymax = CI_high)) +
  theme_modern()
```

**Contrast analysis** can be achieved through the `estimate_contrasts`
function:

```{r}
estimate_contrasts(model)
```

We can conclude that all pairwise differences are statistically significant.

# Complex model

Again, as contrast analysis is based on marginal means, it can be applied to
more complex models:

```{r}
model <- lm(Sepal.Width ~ Species * Petal.Width, data = iris)
contrasts <- estimate_contrasts(model)
contrasts
```

For instance, if we add `Petal.Width` in the model, we can see that the
difference between *versicolor* and *virginica* becomes not significant (and
even changes sign).

Note that we can plot simple contrast analysis through **lighthouse plots** with
the help of the `see` package:

```{r}
library(see)

plot(contrasts, estimate_means(model)) +
  theme_modern()
```

These represent the estimated means and their CI range (in black), while the
grey areas show the CI range of the difference (as compared to the point
estimate).

# Changes in difference

Interestingly, we can also see how these differences are modulated by another
continuous variable. Based on the model above (including the interaction with
`Petal.Width`), we will compute the contrasts at 100 equally-spaced points of
`Petal.Width`, that we will then visualise.

```{r, fig}
contrasts <- estimate_contrasts(model, by = "Petal.Width", length = 100)

# Create a variable with the two levels concatenated
contrasts$Contrast <- paste(contrasts$Level1, "-", contrasts$Level2)

# Visualise the changes in the differences
ggplot(contrasts, aes(x = Petal.Width, y = Difference)) +
  geom_ribbon(aes(fill = Contrast, ymin = CI_low, ymax = CI_high), alpha = 0.2) +
  geom_line(aes(colour = Contrast), size = 1) +
  geom_hline(yintercept = 0, linetype = "dashed") +
  theme_modern() +
  ylab("Difference")
```

As we can see, the difference between *versicolor* and *virginica* increases as
`Petal.Width` increases. 

# Conclusion

Contrast analysis can be a powerful tool to interpret and understand statistical
models.

# References
