ch09.Rmd

---
output:
  bookdown::html_document2:
    fig_caption: yes
editor_options:
  chunk_output_type: console
---

```{r echo = FALSE, cache = FALSE}
# This block needs cache=FALSE to set fig.width and fig.height, and have those
# persist across cached builds.

source("utils.R", local = TRUE)
knitr::opts_chunk$set(fig.width = 3.5, fig.height = 3.5)
```

Controlling the Overall Appearance of Graphs {#CHAPTER-APPEARANCE}
============================================

In this chapter I'll discuss how to control the overall appearance of graphics made by ggplot2. The grammar of graphics that underlies ggplot2 is concerned with how data is processed and displayed -- it's not concerned with things like fonts, background colors, and so on. When it comes to presenting your data, there's a good chance that you'll want to tune the appearance of these things. ggplot2's theming system provides control over the appearance of non-data elements. I touched on the theme system in the previous chapter, and here I'll explain a bit more about how it works.

Setting the Title of a Graph {#RECIPE-APPEARANCE-TITLE}
----------------------------

### Problem

You want to add a title to your plot.

### Solution

Use `ggtitle()` to add a title, as shown in Figure \@ref(fig:FIG-APPEARANCE-TITLE):

(ref:cap-FIG-APPEARANCE-TITLE) Scatter plot with a title added (left); With a `\n` for a newline (right)

```{r FIG-APPEARANCE-TITLE, fig.show="hold", fig.cap="(ref:cap-FIG-APPEARANCE-TITLE)"}
library(gcookbook)  # Load gcookbook for the heightweight data set

hw_plot <- ggplot(heightweight, aes(x = ageYear, y = heightIn)) +
  geom_point()

hw_plot +
  ggtitle("Age and Height of Schoolchildren")

# Use \n for a newline
hw_plot +
  ggtitle("Age and Height\nof Schoolchildren")
```

### Discussion

`ggtitle()` is equivalent to using `labs(title = "Title text")`.

You can add a subtitle by providing a string as the second argument of `ggtitle()`. By default it will display with slightly smaller text than the main title.

```{r FIG-APPEARANCE-TITLE-SUBTITLE, fig.show="hold", fig.cap="Scatter plot with a subtitle"}
hw_plot +
  ggtitle("Age and Height of Schoolchildren", "11.5 to 17.5 years old")
```

If you want to move the title inside the plotting area, you can use one of two methods, both of which are a little bit of a hack (Figure \@ref(fig:FIG-APPEARANCE-TITLE-INSIDE)). The first method is to use `ggtitle()` with a negative `vjust` value. The drawback of this method is that it still reserves blank space above the plotting region for the title.

The second method is to instead use a text annotation, setting its *x* position to the middle of the *x* range and its *y* position to `Inf`, which places it at the top of the plotting region. This also requires a positive `vjust` value to bring the text fully inside the plotting region:

(ref:cap-FIG-APPEARANCE-TITLE-INSIDE) Title with ggtitle and a negative `vjust` value (note the extra space above the plotting area) (left); With a text annotation at the top of the figure (right)

```{r FIG-APPEARANCE-TITLE-INSIDE, fig.show="hold", fig.cap="(ref:cap-FIG-APPEARANCE-TITLE-INSIDE)"}
# Move the title inside
hw_plot +
  ggtitle("Age and Height of Schoolchildren") +
  theme(plot.title = element_text(vjust = -8))

# Use a text annotation instead
hw_plot +
  annotate("text", x = mean(range(heightweight$ageYear)), y = Inf,
           label = "Age and Height of Schoolchildren", vjust = 1.5, size = 4.5)
```


Changing the Appearance of Text {#RECIPE-APPEARANCE-TEXT-APPEARANCE}
-------------------------------

### Problem

You want to change the appearance of text in a plot.

### Solution

To set the appearance of theme items such as the title, axis labels, and axis tick marks, use theme() and set the item with `element_text()`. For example, `axis.title.x` controls the appearance of the x-axis label and `plot.title` controls the appearance of the title text (Figure \@ref(fig:FIG-APPEARANCE-TEXT-APPEARANCE-THEME)):


(ref:cap-FIG-APPEARANCE-TEXT-APPEARANCE-THEME) `axis.title.x` (left); `plot.title` (right)

```{r FIG-APPEARANCE-TEXT-APPEARANCE-THEME, fig.show="hold", fig.cap="(ref:cap-FIG-APPEARANCE-TEXT-APPEARANCE-THEME)"}
library(gcookbook)  # Load gcookbook for the heightweight data set

# Base plot
hw_plot <- ggplot(heightweight, aes(x = ageYear, y = heightIn)) +
  geom_point()

# Controlling appearance of theme items
hw_plot +
  theme(axis.title.x = element_text(
    size = 16, lineheight = .9,
    family = "Times", face = "bold.italic", colour = "red"
  ))

hw_plot +
  ggtitle("Age and Height\nof Schoolchildren") +
  theme(plot.title = element_text(
    size = rel(1.5), lineheight = .9,
    family = "Times", face = "bold.italic", colour = "red"
  ))

# rel(1.5) means that the font will be 1.5 times the base font size of the theme.
# For theme elements, font size is in points.
```

To set the appearance of text geoms (text that's in the plot itself, with `geom_text()` or `annotate()`), set the text properties. For example (Figure \@ref(fig:FIG-APPEARANCE-TEXT-APPEARANCE-GEOM)):


(ref:cap-FIG-APPEARANCE-TEXT-APPEARANCE-GEOM) `annotate("text")` (left); `geom_text()` (right)
```{r FIG-APPEARANCE-TEXT-APPEARANCE-GEOM, fig.show="hold", fig.cap="(ref:cap-FIG-APPEARANCE-TEXT-APPEARANCE-GEOM)"}
hw_plot +
  annotate("text", x = 15, y = 53, label = "Some text",
    size = 7, family = "Times", fontface = "bold.italic", colour = "red")

hw_plot +
  geom_text(aes(label = weightLb), size = 4, family = "Times", colour = "red")

# For text geoms, font size is in mm
```

### Discussion

There are two kinds of text items in ggplot2: theme elements and text geoms. Theme elements are all the non-data elements in the plot: the title, legends, and axes. Text geoms are things that are part of the plot itself, and reflect the data content.

There are differences in the parameters, as shown in Table \@ref(tab:TABLE-APPEARANCE-PROPERTIES).

Table: (\#tab:TABLE-APPEARANCE-PROPERTIES) Text properties of theme elements and text geoms

+----------------------+----------------------+-----------------------+
| Theme elements       | Text geoms           | Description           |
+======================+======================+=======================+
| `family`             | `family`             | Helvetica, Times,     |
|                      |                      | Courier               |
+----------------------+----------------------+-----------------------+
| `face`               | `fontface`           | `plain`, `bold`, `italic,` |
|                      |                      | `bold.italic`         |
+----------------------+----------------------+-----------------------+
| `colour`             | `colour`             | Color (name or        |
|                      |                      | "#RRGGBB")            |
+----------------------+----------------------+-----------------------+
| `size`               | `size`               | Font size (in points  |
|                      |                      | for theme elements;   |
|                      |                      | in mm for geoms)      |
+----------------------+----------------------+-----------------------+
| `hjust`              | `hjust`              | Horizontal alignment: |
|                      |                      | 0 = left, 0.5 = center, |
|                      |                      | 1 = right             |
+----------------------+----------------------+-----------------------+
| `vjust`              | `vjust`              | Vertical alignment:   |
|                      |                      | 0 = bottom, 0.5 = middle, |
|                      |                      | 1 = top               |
+----------------------+----------------------+-----------------------+
| `angle`              | `angle`              | Angle in degrees      |
+----------------------+----------------------+-----------------------+
| `lineheight`         | `lineheight`         | Line spacing          |
|                      |                      | multiplier            |
+----------------------+----------------------+-----------------------+

The theme elements are listed in Table \@ref(tab:TABLE-APPEARANCE-THEME-TEXT-ELEMENTS). Most of them are straightforward. Some are shown in Figure \@ref(fig:FIG-APPEARANCE-TEXT-APPEARANCE-PROPERTIES).

Table: (\#tab:TABLE-APPEARANCE-THEME-TEXT-ELEMENTS) Theme items that control text appearance in `theme()`

+-----------------------------------+-----------------------------------+
| Element name                      | Description                       |
+===================================+===================================+
| `axis.title`                      | Appearance of axis labels on both |
|                                   | axes                              |
+-----------------------------------+-----------------------------------+
| `axis.title.x`                    | Appearance of x-axis label        |
+-----------------------------------+-----------------------------------+
| `axis.title.y`                    | Appearance of y-axis label        |
+-----------------------------------+-----------------------------------+
| `axis.ticks`                      | Appearance of tick labels on both |
|                                   | axes                              |
+-----------------------------------+-----------------------------------+
| `axis.ticks.x`                    | Appearance of x tick labels       |
+-----------------------------------+-----------------------------------+
| `axis.ticks.y`                    | Appearance of y tick labels       |
+-----------------------------------+-----------------------------------+
| `legend.title`                    | Appearance of legend title        |
+-----------------------------------+-----------------------------------+
| `legend.text`                     | Appearance of legend items        |
+-----------------------------------+-----------------------------------+
| `plot.title`                      | Appearance of overall plot title  |
+-----------------------------------+-----------------------------------+
| `strip.text`                      | Appearance of facet labels in     |
|                                   | both directions                   |
+-----------------------------------+-----------------------------------+
| `strip.text.x`                    | Appearance of horizontal facet    |
|                                   | labels                            |
+-----------------------------------+-----------------------------------+
| `strip.text.y`                    | Appearance of vertical facet      |
|                                   | labels                            |
+-----------------------------------+-----------------------------------+

(ref:cap-FIG-APPEARANCE-TEXT-APPEARANCE-PROPERTIES) Aligning with `hjust` and `vjust`, and spacing with `lineheight`

```{r FIG-APPEARANCE-TEXT-APPEARANCE-PROPERTIES, fig.cap="(ref:cap-FIG-APPEARANCE-TEXT-APPEARANCE-PROPERTIES)", echo=FALSE, fig.width=8, fig.height=4}
ggplot(data.frame()) +
  geom_vline(xintercept = 1, linetype = "dashed", colour = "red") +
  annotate("text", x = 1, y = 1,    label = "hjust = 1",   hjust = 1) +
  annotate("text", x = 1, y = 0.75, label = "hjust = 0.5", hjust = 0.5) +
  annotate("text", x = 1, y = 0.5,  label = "hjust = 0",   hjust = 0) +
  geom_hline(yintercept = 2, linetype = "dashed", colour = "red") +
  annotate("text", x = 2.5, y = 2, label = "vjust = 1",   vjust = 1) +
  annotate("text", x = 2,   y = 2, label = "vjust = 0.5", vjust = 0.5) +
  annotate("text", x = 1.5, y = 2, label = "vjust = 0",   vjust = 0) +
  annotate("text", x = 1.75, y = 1, label = "spacing with\nlineheight = 0.9", lineheight = 0.9) +
  annotate("text", x = 2.5, y = 1, label = "spacing with\nlineheight = 1", lineheight = 1) +
  annotate("text", x = 3.25, y = 1, label = "spacing with\nlineheight = 1.2", lineheight = 1.2) +
  xlim(0.5, 3.5) +
  ylim(0, 2.5)
```

Using Themes {#RECIPE-APPEARANCE-THEME}
------------

### Problem

You want to use premade themes to control the overall plot appearance.

### Solution

There are many premade themes that are already included in ggplot2. The default ggplot2 theme is `theme_grey()`, but the examples below also showcase `theme_bw()`, `theme_minimal()`, and `theme_classic()`.

To use a premade theme, add `theme_bw()` or another theme to your plot (Figure \@ref(fig:FIG-APPEARANCE-THEME)):


(ref:cap-FIG-APPEARANCE-THEME) Scatter plot with `theme_grey()` (the default, top left); with `theme_bw()` (top right); with `theme_minimal()` (bottom left); with `theme_classic()` (bottom right)

```{r FIG-APPEARANCE-THEME, fig.show="hold", fig.cap="(ref:cap-FIG-APPEARANCE-THEME)"}
library(gcookbook)  # Load gcookbook for the heightweight data set

# Create the base plot
hw_plot <- ggplot(heightweight, aes(x = ageYear, y = heightIn)) +
  geom_point()

# Grey theme (the default)
hw_plot +
  theme_grey()

# Black-and-white theme
hw_plot +
  theme_bw()

# Minimal theme without background annotations
hw_plot +
  theme_minimal()

# Classic theme, with axis lines but no gridlines
hw_plot +
  theme_classic()
```

Another theme included in ggplot2 is `theme_void()`, which makes all plot elements blank and only shows your data (Figure \@ref(fig:FIG-APPEARANCE-THEME-VOID). This is especially useful if you don't want any default theme settings, and instead want a blank slate on which to choose your own theme elements.

(ref:cap-FIG-APPEARANCE-THEME-VOID) Scatter plot with `theme_void()`

```{r FIG-APPEARANCE-THEME-VOID, fig.show="hold", fig.cap="(ref:cap-FIG-APPEARANCE-THEME-VOID)"}
hw_plot +
  theme_void()
```

### Discussion

Some commonly used properties of theme elements in ggplot2 are those things that are controlled by `theme()`. Most of these things, like the title, legend, and axes, are outside the plot area, but some of them are inside the plot area, such as grid lines and the background coloring.

Besides the themes included in ggplot2, it is also possible to create your own.

You can set the base font family and size with either of the included themes (the default base font family is Helvetica, and the default size is 12):

```{r, eval=FALSE}
hw_plot +
  theme_grey(base_size = 16, base_family = "Times")
```

You can set the default theme for the current R session with `theme_set()`, although it's generally not a good idea to set options globally because it may affect other plots that are unrelated to your current project:

```{r, eval=FALSE}
# Set default theme for current session
theme_set(theme_bw())

# This will use theme_bw()
hw_plot

# Reset the default theme back to theme_grey()
theme_set(theme_grey())
```

### See Also

To see additional complete themes included in ggplot2, see <https://ggplot2.tidyverse.org/reference/ggtheme.html>.

To modify a theme, see Recipe \@ref(RECIPE-APPEARANCE-THEME-MODIFY).

To create your own themes, see Recipe \@ref(RECIPE-APPEARANCE-THEME-CREATE).

See `?theme` to see all the available theme properties.


Changing the Appearance of Theme Elements {#RECIPE-APPEARANCE-THEME-MODIFY}
-----------------------------------------

### Problem

You want to change the appearance of theme elements.

### Solution

To modify a theme, add `theme()` with a corresponding `element_`*xx* object. These include `element_line`, `element_rect`, and `element_text`. The following code shows how to modify many of the commonly used theme properties (Figure \@ref(fig:FIG-APPEARANCE-THEME-MODIFY)):

```{r FIG-APPEARANCE-THEME-MODIFY, fig.show="hold", fig.cap="Clockwise from top left: modifying theme properties for the plotting area, the legend, the facets, and the text items"}
library(gcookbook)  # Load gcookbook for the heightweight data set

# Create the base plot
hw_plot <- ggplot(heightweight, aes(x = ageYear, y = heightIn, colour = sex)) +
  geom_point()

# Options for the plotting area
hw_plot +
  theme(
    panel.grid.major = element_line(colour = "red"),
    panel.grid.minor = element_line(colour = "red", linetype = "dashed", size = 0.2),
    panel.background = element_rect(fill = "lightblue"),
    panel.border = element_rect(colour = "blue", fill = NA, size = 2)
  )

# Options for the legend
hw_plot +
  theme(
    legend.background = element_rect(fill = "grey85", colour = "red", size = 1),
    legend.title = element_text(colour = "blue", face = "bold", size = 14),
    legend.text = element_text(colour = "red"),
    legend.key = element_rect(colour = "blue", size = 0.25)
  )

# Options for text items
hw_plot +
  ggtitle("Plot title here") +
  theme(
    axis.title.x = element_text(colour = "red", size = 14),
    axis.text.x  = element_text(colour = "blue"),
    axis.title.y = element_text(colour = "red", size = 14, angle = 90),
    axis.text.y  = element_text(colour = "blue"),
    plot.title = element_text(colour = "red", size = 20, face = "bold")
  )

# Options for facets
hw_plot +
  facet_grid(sex ~ .) +
  theme(
    strip.background = element_rect(fill = "pink"),
    strip.text.y = element_text(size = 14, angle = -90, face = "bold")
  )  # strip.text.x is the same, but for horizontal facets
```

### Discussion

If you want to use a saved theme and tweak a few parts of it with `theme()`, the `theme()` must come after the theme specification. Otherwise, anything set by `theme()` will be unset by the theme you add:

```{r eval=FALSE}
# theme() has no effect if before adding a complete theme
hw_plot +
  theme(axis.title.x = element_text(colour = "red")) +
  theme_bw()

# theme() works if after a complete theme
hw_plot +
  theme_bw() +
  theme(axis.title.x = element_text(colour = "red", size = 12))
```

Many of the commonly used theme properties are shown in Table \@ref(tab:TABLE-APPEARANCE-THEME-ELEMENTS).


Table: (\#tab:TABLE-APPEARANCE-THEME-ELEMENTS) Theme items that control text appearance in `theme()`

+----------------------+----------------------+-----------------------+
| Name                 | Description          | Element type          |
+======================+======================+=======================+
| `text`               | All text elements    | `element_text()`      |
+----------------------+----------------------+-----------------------+
| `rect`               | All rectangular      | `element_rect()`      |
|                      | elements             |                       |
+----------------------+----------------------+-----------------------+
| `line`               | All line elements    | `element_line()`      |
+----------------------+----------------------+-----------------------+
| `axis.line`          | Lines along axes     | `element_line()`      |
+----------------------+----------------------+-----------------------+
| `axis.title`         | Appearance of both   | `element_text()`      |
|                      | axis labels          |                       |
+----------------------+----------------------+-----------------------+
| `axis.title.x`       | X-axis label         | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `axis.title.y`       | Y-axis label         | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `axis.text`          | Appearance of tick   | `element_text()`      |
|                      | labels on both axes  |                       |
+----------------------+----------------------+-----------------------+
| `axis.text.x `       | X-axis tick label    | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `axis.text.y`        | Y-axis tick label    | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `legend.background`  | Background of legend | `element_rect()`      |
+----------------------+----------------------+-----------------------+
| `legend.text`        | Legend item          | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `legend.title`       | Legend title         | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `legend.position`    | Position of the      | `"left"`, `"right"`,  |
|                      | legend               | `"bottom"`, `"top"`, or |
|                      |                      | two-element numeric   |
|                      |                      | vector if you wish to |
|                      |                      | place it inside the   |
|                      |                      | plot area (for more   |
|                      |                      | on legend placement,  |
|                      |                      | see Recipe            |
|                      |                      | \@ref(RECIPE-LEGEND-POSITION)) |
+----------------------+----------------------+-----------------------+
| `panel.background`   | Background of        | `element_rect()`      |
|                      | plotting area        |                       |
+----------------------+----------------------+-----------------------+
| `panel.border`       | Border around        | `element_rect(linetype="dashed")` |
|                      | plotting area        |                       |
+----------------------+----------------------+-----------------------+
| `panel.grid.major`   | Major grid lines     | `element_line()`      |
|                      |                      |                       |
+----------------------+----------------------+-----------------------+
| `panel.grid.major.x` | Major grid lines,    | `element_line()`      |
|                      | vertical             |                       |
+----------------------+----------------------+-----------------------+
| `panel.grid.major.y` | Major grid lines,    | `element_line()`      |
|                      | horizontal           |                       |
+----------------------+----------------------+-----------------------+
| `panel.grid.minor`   | Minor grid lines     | `element_line()`      |
|                      |                      |                       |
+----------------------+----------------------+-----------------------+
| `panel.grid.minor.x` | Minor grid lines,    | `element_line()`      |
|                      | vertical             |                       |
+----------------------+----------------------+-----------------------+
| `panel.grid.minor.y` | Minor grid lines,    | `element_line()`      |
|                      | horizontal           |                       |
+----------------------+----------------------+-----------------------+
| `plot.background`    | Background of the    | `element_rect(fill = "white", colour = NA)` |
|                      | entire plot          |                       |
+----------------------+----------------------+-----------------------+
| `plot.title`         | Title text           | `element_text()`      |
|                      | appearance           |                       |
+----------------------+----------------------+-----------------------+
| `strip.background`   | Background of facet  | `element_rect()`      |
|                      | labels               |                       |
+----------------------+----------------------+-----------------------+
| `strip.text`         | Text appearance for  | `element_text()`      |
|                      | vertical and         |                       |
|                      | horizontal facet     |                       |
|                      | labels               |                       |
+----------------------+----------------------+-----------------------+
| `strip.text.x`       | Text appearance for  | `element_text()`      |
|                      | horizontal facet     |                       |
|                      | labels               |                       |
+----------------------+----------------------+-----------------------+
| `strip.text.y`       | Text appearance for  | `element_text()`      |
|                      | vertical facet       |                       |
|                      | labels               |                       |
+----------------------+----------------------+-----------------------+


Creating Your Own Themes {#RECIPE-APPEARANCE-THEME-CREATE}
------------------------

### Problem

You want to create your own theme.

### Solution

You can create your own theme by adding elements to an existing theme (Figure \@ref(fig:FIG-APPEARANCE-THEME-SAVE)):

```{r FIG-APPEARANCE-THEME-SAVE, fig.cap="A modified default theme"}
library(gcookbook) # Load gcookbook for the heightweight data set

# Start with theme_bw() and modify a few things
mytheme <- theme_bw() +
  theme(
    text = element_text(colour = "red"),
    axis.title = element_text(size = rel(1.25))
  )

# Create the base plot
hw_plot <- ggplot(heightweight, aes(x = ageYear, y = heightIn)) +
  geom_point()

# Plot with the modified theme we created
hw_plot +
  mytheme
```

### Discussion

With ggplot2, you can not only make use of the default themes, but also modify these themes to suit your needs. You can add new theme elements or change the values of existing ones, and apply your changes globally or to a single plot.

### See Also

The options for modifying themes are listed in Recipe \@ref(RECIPE-APPEARANCE-THEME-MODIFY).


Hiding Grid Lines {#RECIPE-APPEARANCE-HIDE-GRIDLINES}
-----------------

### Problem

You want to hide the grid lines in a plot.

### Solution

The major grid lines (those that align with the tick marks) are controlled with `panel.grid.major`. The minor grid lines (the ones between the major lines) are controlled with `panel.grid.minor`. This will hide them both, as shown in Figure \@ref(fig:FIG-APPEARANCE-HIDE-GRIDLINES) (left):

```{r FIG-APPEARANCE-HIDE-GRIDLINES-1, eval=FALSE}
library(gcookbook)  # Load gcookbook for the heightweight data set

hw_plot <- ggplot(heightweight, aes(x = ageYear, y = heightIn)) +
  geom_point()

hw_plot +
  theme(
    panel.grid.major = element_blank(),
    panel.grid.minor = element_blank()
  )
```

### Discussion

It's possible to hide just the vertical or horizontal grid lines, as shown in the middle and right-hand graphs in Figure \@ref(fig:FIG-APPEARANCE-HIDE-GRIDLINES), with `panel.grid.major.x`, `panel.grid.major.y`, `panel.grid.minor.x`, and `panel.grid.minor.y`:

```{r FIG-APPEARANCE-HIDE-GRIDLINES-2, eval=FALSE}
# Hide the vertical grid lines (which intersect with the x-axis)
hw_plot +
  theme(
    panel.grid.major.x = element_blank(),
    panel.grid.minor.x = element_blank()
  )

# Hide the horizontal grid lines (which intersect with the y-axis)
hw_plot +
  theme(
    panel.grid.major.y = element_blank(),
    panel.grid.minor.y = element_blank()
  )
```

```{r FIG-APPEARANCE-HIDE-GRIDLINES, ref.label=c("FIG-APPEARANCE-HIDE-GRIDLINES-1", "FIG-APPEARANCE-HIDE-GRIDLINES-2"), echo=FALSE, fig.show="hold", fig.cap="No grid lines (left); No vertical lines (middle); No horizontal lines (right)", fig.height=2.5, fig.width=2.5}
```