---
title: "Introduction: Plotting Marginal Effects"
author: "Daniel Lüdecke"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction: Plotting Marginal Effects}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r set-options, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", dev = "png", fig.width = 7, fig.height = 4, message = FALSE, warning = FALSE)
options(width = 800)
if (!requireNamespace("ggplot2", quietly = TRUE) ||
    !requireNamespace("lme4", quietly = TRUE) ||
    !requireNamespace("survival", quietly = TRUE) ||
    !requireNamespace("sjmisc", quietly = TRUE)) {
  knitr::opts_chunk$set(eval = FALSE)
}
```

# plot()-method

This vignettes demonstrates the `plot()`-method of the **ggeffects**-package. It is recommended to read the [general introduction](ggeffects.html) first, if you haven't done this yet.

If you don't want to write your own ggplot-code, **ggeffects** has a `plot()`-method with some convenient defaults, which allows quickly creating ggplot-objects. `plot()` has some arguments to tweak the plot-appearance. For instance, `ci` allows you to show or hide confidence bands (or error bars, for discrete variables), `facets` allows you to create facets even for just one grouping variable, or `colors` allows you to quickly choose from some color-palettes, including black & white colored plots. Use `add.data` to add the raw data points to the plot.

**ggeffects** supports [labelled data](https://strengejacke.github.io/sjlabelled/) and the `plot()`-method automatically sets titles, axis - and legend-labels depending on the value and variable labels of the data.

```{r}
library(ggeffects)
library(sjmisc)
data(efc)
efc$c172code <- to_label(efc$c172code)
fit <- lm(barthtot ~ c12hour + neg_c_7 + c161sex + c172code, data = efc)
```

## Facet by Group

```{r}
dat <- ggpredict(fit, terms = c("c12hour", "c172code"))
plot(dat, facet = TRUE)
```

## No Facets, in Black & White

```{r}
# don't use facets, b/w figure, w/o confidence bands
plot(dat, colors = "bw", ci = FALSE)
```

## Add Data Points to Plot

```{r}
dat <- ggpredict(fit, terms = c("c12hour", "c172code"))
plot(dat, add.data = TRUE)
```

## Automatic Facetting

```{r}
# for three variables, automatic facetting
dat <- ggpredict(fit, terms = c("c12hour", "c172code", "c161sex"))
plot(dat)
```

## Automatic Selection of Error Bars or Confidence Bands

```{r}
# categorical variables have errorbars
dat <- ggpredict(fit, terms = c("c172code", "c161sex"))
plot(dat)
```

## Connect Discrete Data Points with Lines

```{r}
# point-geoms for discrete x-axis can be connected with lines
plot(dat, connect.lines = TRUE)
```

## Create Panel Plots for more than three Terms

For three grouping variable (i.e. if `terms` is of length four), one plot per `panel` (the values of the fourth variable in `terms`) is created, and a single, integrated plot is produced by default. Use `one.plot = FALSE` to return one plot per panel.

```{r fig.height = 8}
# for four variables, automatic facetting and integrated panel
dat <- ggpredict(fit, terms = c("c12hour", "c172code", "c161sex", "neg_c_7"))
# use 'one.plot = FALSE' for returning multiple single plots
plot(dat, one.plot = TRUE)
```

# Change appearance of confidence bands

In some plots, the the confidence bands are not represented by a shaded area (ribbons), but rather by error bars (with line), dashed or dotted lines. Use `ci.style = "errorbar"`, `ci.style = "dash"` or `ci.style = "dot"` to change the style of confidence bands.

## Dashed Lines for Confidence Intervals

```{r}
# dashed lines for CI
dat <- ggpredict(fit, terms = "c12hour")
plot(dat, ci.style = "dash")
```

## Error Bars for Continuous Variables

```{r}
# facet by group
dat <- ggpredict(fit, terms = c("c12hour", "c172code"))
plot(dat, facet = TRUE, ci.style = "errorbar", dot.size = 1.5)
```

## Dotted Error Bars

The style of error bars for plots with categorical x-axis can also be changed. By default, these are "error bars", but `ci.style = "dot"` or `ci.style = "dashed"` works as well

```{r}
dat <- ggpredict(fit, terms = "c172code")
plot(dat, ci.style = "dot")
```

# Log-transform y-axis for binomial models

For binomial models, the y-axis indicates the predicted probabilities of an event. In this case, error bars are not symmetrical.

```{r}
library("lme4")
m <- glm(
  cbind(incidence, size - incidence) ~ period, 
  family = binomial, 
  data = lme4::cbpp
)

dat <- ggpredict(m, "period")

# normal plot, asymmetrical error bars
plot(dat)
```

Here you can use `log.y` to log-transform the y-axis. The `plot()`-method will automatically choose axis breaks and limits that fit well to the value range and log-scale.
 
```{r}
# plot with log-transformed y-axis
plot(dat, log.y = TRUE)
```

# Control y-axis appearance

Furthermore, arguments in `...` are passed down to `ggplot::scale_y_continuous()` (resp. `ggplot::scale_y_log10()`, if `log.y = TRUE`), so you can control the appearance of the y-axis.

```{r}
# plot with log-transformed y-axis, modify breaks
plot(
  dat, log.y = TRUE, 
  breaks = c(.05, .1, .15, .2, .25, .3),
  limits = c(.01, .3)
)
```

# Survival models

`ggpredict()` also supports `coxph`-models from the **survival**-package and is able to either plot risk-scores (the default), probabilities of survival (`type = "surv"`) or cumulative hazards (`type = "cumhaz"`).

Since probabilities of survival and cumulative hazards are changing across time, the time-variable is automatically used as x-axis in such cases, so the `terms`-argument only needs up to two variables.

```{r}
data("lung", package = "survival")
# remove category 3 (outlier, not nice in the plot)
lung <- subset(lung, subset = ph.ecog %in% 0:2)
lung$sex <- factor(lung$sex, labels = c("male", "female"))
lung$ph.ecog <- factor(lung$ph.ecog, labels = c("good", "ok", "limited"))

m <- survival::coxph(survival::Surv(time, status) ~ sex + age + ph.ecog, data = lung)

# predicted risk-scores
pr <- ggpredict(m, c("sex", "ph.ecog"))
plot(pr)
```

```{r}
# probability of survival
pr <- ggpredict(m, c("sex", "ph.ecog"), type = "surv")
plot(pr)
```

```{r}
# cumulative hazards
pr <- ggpredict(m, c("sex", "ph.ecog"), type = "cumhaz")
plot(pr)
```

# Custom color palettes

The **ggeffects**-package has a few pre-defined color-palettes that can be used with the `colors`-argument. Use `show_pals()` to see all available palettes.

```{r}
show_pals()
```

Here are two examples showing how to use pre-defined colors:

```{r}
dat <- ggpredict(fit, terms = c("c12hour", "c172code"))
plot(dat, facet = TRUE, colors = "circus")
```

```{r}
dat <- ggpredict(fit, terms = c("c172code", "c12hour [quart]"))
plot(dat, colors = "hero", dodge = 0.4) # increase space between error bars
```
