Getting Started
Patchwork is a package designed to make plot composition in R extremely simple and powerful. It is mainly intended for users of ggplot2 and goes to great lengths to make sure ggplots are properly aligned no matter the complexity of your composition.
In this tutorial we’ll work through the basics of using patchwork. In the end you’ll have a fairly good understanding of the API, and will be ready to dive into some of the more advanced topics covered in the other vignettes.
Example plots
We’ll start by creating some example plots to use throughout this tutorial:
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')These plots are fairly meaningless and only serve to illustrate plot composition - don’t read anything into the resulting plots.
Basic use
The absolute simplest use is the extension of the +
operator used in ggplot2, to allow adding plots together:
When adding plots together, the last added plot will be the active one, and will receive any addition of new ggplot2 objects such as geoms, labels, etc:
Controlling layout
By default, patchwork will try to keep the grid square, and fill it out in row order
This can be controlled with the addition of a
plot_layout()
plot_layout() have all sorts of amazing features for
controlling the layout of your composition. See the Layout
vignette for a full rundown of all its options.
Stacking and packing plots
Often you want to place plots on top of each other, or beside each
other, rather than fill out a grid. While this can be accomplished by
adding a one-row or one-column layout, patchwork also provides two
operators that does this directly and further provides visual cues to
the layout. | will place the plots beside each other, while
/ will stack them:
As patchworks can be nested, these two operators are often enough to create rather complex layouts:
Annotating the composition
It is often necessary to add titles, captions, tags, etc. to a
composition. This can be achieved by adding a
plot_annotation() to the patchwork:
Patchwork also provides auto-tagging capabilities, in order to identify subplots in text:
The tagging can be either arabic or roman numbers, or latin letters, and separate tags can be given for different nesting levels. See the Annotation vignette for more information.
Want more?
This is enough to get you started, but we have only scratched the surface of what patchwork is capable of. Look into the other guides to find out more about, e.g. how to collect all legends in one place and remove duplicates or aligning plots across multiple pages.
[](https://github.com/thomasp85/patchwork/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=patchwork)
[](https://CRAN.R-project.org/package=patchwork)
[](https://app.codecov.io/gh/thomasp85/patchwork?branch=main)
The goal of `patchwork` is to make it ridiculously simple to combine
separate ggplots into the same graphic. As such it tries to solve the
same problem as `gridExtra::grid.arrange()` and `cowplot::plot_grid` but
using an API that incites exploration and iteration, and scales to
arbitrarily complex layouts.
## Installation
You can install patchwork from CRAN using
`install.packages('patchwork')`. Alternatively you can grab the
development version from github using devtools:
``` r
# install.packages("devtools")
devtools::install_github("thomasp85/patchwork")
```
## Basic example
The usage of `patchwork` is simple: just add plots together!
``` r
library(ggplot2)
library(patchwork)
p1 <- ggplot(mtcars) + geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) + geom_boxplot(aes(gear, disp, group = gear))
p1 + p2
```
patchwork provides rich support for arbitrarily complex layouts with
full alignment. As an example, check out this very readable code for
nesting three plots on top of a third:
``` r
p3 <- ggplot(mtcars) + geom_smooth(aes(disp, qsec))
p4 <- ggplot(mtcars) + geom_bar(aes(carb))
(p1 | p2 | p3) /
p4
```
## Learn more
patchwork can do so much more. Check out the guides for learning
everything there is to know about all the different features:
- [Getting
Started](https://patchwork.data-imaginist.com/articles/patchwork.html)
- [Assembling
Plots](https://patchwork.data-imaginist.com/articles/guides/assembly.html)
- [Defining
Layouts](https://patchwork.data-imaginist.com/articles/guides/layout.html)
- [Adding
Annotation](https://patchwork.data-imaginist.com/articles/guides/annotation.html)
- [Aligning across
pages](https://patchwork.data-imaginist.com/articles/guides/multipage.html)
## Code of Conduct
Please note that the patchwork project is released with a [Contributor
Code of
Conduct](https://patchwork.data-imaginist.com/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.
patchwork/build/ 0000755 0001762 0000144 00000000000 14671764317 013373 5 ustar ligges users patchwork/build/vignette.rds 0000644 0001762 0000144 00000000320 14671764317 015725 0 ustar ligges users mPK0-P?`P. 8.6P/eΓ$37,Ƙ8טn`j8ktqfi¸.
H B!K T9q}@"` b!եN:Ad<
v >mVZyyyV[iߔ]oWoiG]`XyÆ
jժdɒ-|ayzj[jUeWd~[k?lܸ"EK8/t|ի~/.-
In eh@ @ `@$7@ @ 2@ b4 @z @e 1@ @ X`=
@ @ 2 h P h@F @ V 4XOrC @ (C F# +@ '! !P97zʕc٢E젃nݺF @ _:t`֭3}~N{7 @ @ *#%x_nWv7{_ PIP O?d6m
/0 O`ŊOؼyW ѵn|C̝vm
@z-[fw͙3'a P!P [UklC.]# @e ɧ״iS1c.\SN97 @ @ *+@ ZBVZַoC $ @ @ @bb"@ @ @$ @ @ @0M:ƍgK.3A &zW\q1&Æ
; O 4zsժU't͝;7 @ @ *#@ {7^jm }o*>" TF ԧ`dڼyլY`# TP w뭷^éUV5k u^z%wވwO2XPꛜ .h x͚5P" %Р$@ @ )Ф@ @ (Р$@ @ )Ф@ @ ( J* ͼq߄Vr%_ '`Dxu7 /o܉eb9*n*@Ю^~ߠ?7&O_~ I LvzZȯ5r_>e^5'4G?z,e8mڴXVLH }I;k=3lu 1y?j
d}e>s28ɥ k!Ki0UsIW*0j\*CAj4r&] gѠfHEle: D@ Zyx?͛7ϭL^J3[Z7tSNF /{"hGk.\;[oe\pA,N#[o[3fG«t[w}4WUGq mVBv#H
K+ri\ya ;M|诜AggJ@KA< ' SzrMkdrf3DHҸ;l6h ;eFt$(h"U||COƢPh";bg)b7J ,
@zzTai 栃 kp&J=(!\,ri=
htƥ 7C1F
>@ y3f+SFo-Ӂ N9唔)Ν;#n!wjDۻϏ>(۶m;֎FHx5?5DLsK \ʐXGJWe
:m / :] K9(lLBv*w =υ[.
!f#y@ !,h> sKyv8i. {1g Q :{ /`ʱo4)3f8So.]Ib2rT~5?\} G@5V>F7_~e0`@55u,TAN5SjA
?t:իWy{BnT'?TGo ɥ,\Gr-` DV + vaH/A/4 v % MFȤ_|Mndr=ȘVP )]RM뮻IO?G 6hC>þY# Cos5 _tEYːbPQe <.)Gҏa vg%5R >HqvȐ!k
)lM D@믿,L?3(xzx3z] O6[@ \ Sn6g)={i =z?p\hG>uF9>CSHJ" hD-~VGi2jAB7 lMoU]fI㠭A j#]iEsa#g) ҇zGMky睮-e&vr W%5kI?e/X?tMA?V\xkD_s9ǭ0>'2'g*1&={#wW4邦۴itI}}% k
#:mWmtwt@+"&q EJ wN9ߔ3gNVgZ㪫{[nT;*֭[fqG/dT/<h 䐋{
9.>/{_ח>ZQT).ɑ3 ^ g7
qמaʉN/̓w,<ERzbpdEMN l6+P<ITu8Ö xT
O 'hP9
vF%R-Q/U;9癟_\̞][mղ]RuϾz!>na
á$2<_ޒBl ɘjw!d
-h.̍#g=:̻`A-Ӟ7h.)Z967
w5eoh>ur?c