patchwork.Rmd

---
title: "Patchwork"
output:
  html_notebook:
    highlight: pygments
    theme: sandstone
    toc: yes
  html_document:
    highlight: pygments
    theme: sandstone
    df_print: paged
    toc: yes
editor_options:
  chunk_output_type: inline
---

```{r setup, include=FALSE}
# options for the knitted html document
knitr::opts_chunk$set(
  echo = T,
  message = F,
  warning = F,
  comment = NA,
  R.options = list(width = 120),
  cache.rebuild = F,
  cache = T,
  fig.align = 'center',
  fig.asp = .7,
  dev = 'svg',
  dev.args = list(bg = 'transparent')
)
```




## Getting started

### Installation

`Patchwork` is not yet available on CRAN. You'll need to install it as follows.

```{r install}
# install.packages("devtools")   # if you don't have devtools
# devtools::install_github("thomasp85/patchwork")
```

### Other packages

These packages should be enough for our purposes.

```{r packages}
# Packages you need
library(tidyverse); library(patchwork)

# Packages you may not have and can install
library(ggrepel)
```


## Demo plots

Here are a couple plots that will serve as a basis for some examples or can just give you a ready ggplot object to do your own exploration.

```{r basic_plots}
load('data/starwars_df.RData')  # load starwars data frames

bar = people_df %>% 
  mutate(homeworld = fct_lump(homeworld, n = 4)) %>% 
  drop_na(homeworld) %>% 
  ggplot() + 
  geom_bar(aes(x = homeworld, fill = homeworld), show.legend = F)

smooth = people_df %>% 
  filter(!is.na(gender) & !grepl(name, pattern = 'Jabba')) %>% 
  ggplot(aes(x=mass, y=height)) + 
  geom_point() + 
  geom_smooth()

scatter = vehicles_df %>% 
  ggplot(aes(x=length, y=cost_in_credits)) + 
  geom_point(size = 5, color = '#ff5500') +
  geom_text_repel(aes(label = name), size=2, color = 'gray50')  # requires ggrepel

box = people_df %>% 
  mutate(species = fct_lump(species, n = 2)) %>% 
  drop_na(species) %>% 
  ggplot(aes(x= species, y = mass)) +
  geom_boxplot()
```


## Above & Below

Basics.  A good way to start is that you create the two separate plots and plotting side by side is the first step.  Either of these will work.


```{r side_by_side}
bar + smooth  # note this could be the actual underlying code of the plots
```

```{r side_by_side2}
bar | box
```



If we want the second plot below, you can just use a divisor.

```{r top_bottom}
bar / smooth
```


## Grouping & Nesting

If we have multiple plots, we may want to group them a certain way.

```{r grouping}
(bar + smooth) / box
```

This is what it would look like if we hadn't nested. Operations take similar
mathematical precedence.

```{r grouping2}
bar + smooth / box
```

We can take this further to use *nesting* to further enhance the plot.

```{r nesting}
bar / {
  box + {
    scatter / 
      smooth
    }
  }
```


## Layout

Layouts provide more customization over the look.

```{r layout1}
box + smooth + bar + scatter +
  plot_layout(ncol = 2)
```

We have additional options.

```{r layout2}
box + 
  smooth + 
  bar + 
  scatter +
  plot_layout(
    ncol = 2,            # 2 columns
    byrow = T            # enter plots by row
  )
```



We can also use it with nesting.

```{r layout3}
bar + {
  box + 
    scatter + 
    plot_layout(ncol = 1)
  } + 
  smooth
```

### Sizing

We can alter relative sizes of plots.

```{r sizing}
box + 
  smooth + 
  bar + 
  scatter +
  plot_layout(
    ncol = 2,            # 2 columns
    byrow = T,           # enter plots by row
    widths = c(1,2),     # relative column widths
    heights = c(1,1.5)   # relative row heights
  )
```

### Spacing

Add some space between plots. This is all it does at present.

```{r spacing}
box + 
  plot_spacer() +
  smooth 
```

### Applying modifications to all plots

You may have some layouts or themes you'd like to apply to each plot.  First we'll start with the usual approach.


```{r apply_theme1}
box + smooth + bar + theme_bw()
```

We could do the following, but it's tedious.

```{r apply_theme2}
box + theme_bw() + smooth + theme_bw() + bar + theme_bw()
```

Instead, we can just nest/group the plots and use `*` to apply the theme to all. This is much easier.  

```{r apply_theme3}
(box + smooth + bar) * theme_bw()
```

Using `&` will apply through all levels of nesting.

```{r apply_theme4}
box / {
  smooth + 
    bar
  } * theme_bw()


box / {
  smooth + 
    bar
  } & theme_bw()
```

## Annotation

Annotating applies only on the 'top-level' plot.

```{r annotation}
# plot annotation must be applied to the whole set of plots. I nested everything
# so that I could also use the `&` operator for a common theme.
{box / {
  smooth + 
    bar
  }   & 
  theme_bw()
  } + 
  plot_annotation(title = 'Star Wars Plots', 
                  subtitle = 'Shenanigans', 
                  theme = theme(title = element_text(size= 24))) 
```

## Summary

The `patchwork` package provides the easiest way yet to stitch multiple plots together to create the visual story you want to convey.  More development will come, so keep an eye on it!