Source: vignettes/guides/annotation.Rmd
annotation.Rmd
library(patchwork)
Sometimes you simply want to put multiple plots side by side and callit a day, but often you want the end result to stand forth like acollective thing. To achieve that you would often add a title and othertextual cues. This guide will teach you how to do that.
As always, we start with some plots.
library(ggplot2)p1 <- ggplot(mtcars) + geom_point(aes(mpg, disp)) + ggtitle('Plot 1')p2 <- ggplot(mtcars) + geom_boxplot(aes(gear, disp, group = gear)) + ggtitle('Plot 2')p3 <- ggplot(mtcars) + geom_point(aes(hp, wt, colour = mpg)) + ggtitle('Plot 3')p4 <- ggplot(mtcars) + geom_bar(aes(gear)) + facet_wrap(~cyl) + ggtitle('Plot 4')
Titles, subtitles and captions
One of the most needed things is to add descriptive text to your plotensemble. To achieve this, you simply add it to your patchwork usingplot_annotation()
patchwork <- (p1 + p2) / p3patchwork + plot_annotation( title = 'The surprising truth about mtcars', subtitle = 'These 3 plots will reveal yet-untold secrets about our beloved data-set', caption = 'Disclaimer: None of these plots are insightful')
It is important to note that plot annotations only have an effect onthe top-level patchwork. Any annotation added to nested patchworks are(currently) lost. If you need to have annotations for a nested patchworkyou’ll need to wrap it in wrap_elements()
with theside-effect that alignment no longer works.
Tagging
Often, especially in scientific literature, multiple plots arecollected in a single figure and referred to by a tag. While such tagscould be added manually, it is much simpler to let patchwork handle itfor you, using the auto-tagging functionality. This is turned on bysetting tag_level
in plot_annotation()
to avalue indicating the family of symbols to use for tagging:'1'
for Arabic numerals, 'A'
for uppercaseLatin letters, 'a'
for lowercase Latin letters,'I'
for uppercase Roman numerals, and 'i'
forlowercase Roman numerals.
patchwork + plot_annotation(tag_levels = 'A')
Tags uses the theming of the plot they are applied to, so make surethey match up, or modify the theming of all plots using&
(see the Plot Assemblyguide).
patchwork + plot_annotation(tag_levels = 'A') & theme(plot.tag = element_text(size = 8))
When the patchwork contains nested layouts the tagging will recurseinto them by default, but you can tell it to define a new tagging levelwith the tag_level
argument in plot_layout()
.You can then provide multiple tag-types to tag_levels
todefine how subtagging should be enumerated.
patchwork[[1]] <- patchwork[[1]] + plot_layout(tag_level = 'new')patchwork + plot_annotation(tag_levels = c('A', '1'))
With plot_annotation()
it is also possible to defineseparator, prefix, and suffix for the tag, but don’t go overboard withit:
patchwork + plot_annotation(tag_levels = c('A', '1'), tag_prefix = 'Fig. ', tag_sep = '.', tag_suffix = ':')
The default ggplot2 theme puts the tag in its own row and column thatwill expand to fit. For longer tag text this will look weird, so it isbetter to place it on top of the plot region:
patchwork + plot_annotation(tag_levels = c('A', '1'), tag_prefix = 'Fig. ', tag_sep = '.', tag_suffix = ':') & theme(plot.tag.position = c(0, 1), plot.tag = element_text(size = 8, hjust = 0, vjust = 0))
Lastly it is also possible to provide you own tag sequence instead ofrelying on the build in ones. Passing a list of character vectors willdo just that (note that this can be mixed with the standardsequences):
If you provide more plots than your custom sequence support theexcess plots will get empty tags so make sure that there’s enough.
Styling the patchwork
Most of the style of the patchwork is made up by the themes of theindividual patches. For a coherent look, don’t mix widely differentlooks. Setting the background colour of a single plot to a differentshade is an effective way to highlight it, but e.g.different fonts orline widths will just look like a mess. The patchwork itself has a fewelements itself that is susceptible to theming: A background, a margin,and title, subtitle & caption. The theme of the patchwork is bydefault the default ggplot2 theme. It can be changed though, in twodifferent ways. The easiest is to simply use &
with atheme element. This operator will add to the theme of all subplots aswell as to the theme of the patchwork itself:
patchwork + plot_annotation(title = 'The surprising truth about mtcars') & theme(text = element_text('mono'))
If you need to address only the theme of the patchwork itself(e.g.for making the patchwork title larger than the plot titles), itcan be done with the theme
argument inplot_annotation()
(note that the use of one does notexclude the other):
patchwork + plot_annotation(title = 'The surprising truth about mtcars', theme = theme(plot.title = element_text(size = 18))) & theme(text = element_text('mono'))
Want more?
Now you know how to annotate and style your patchwork. Read the otherguides about assembling and laying out patchwork to master all ofpatchwork.