forked from thomasp85/patchwork
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.Rmd
More file actions
164 lines (121 loc) · 5.04 KB
/
Copy pathREADME.Rmd
File metadata and controls
164 lines (121 loc) · 5.04 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
message = FALSE
)
```
# patchwork <a href='https://patchwork.data-imaginist.com'><img src='man/figures/logo.png' align="right" height="131.5" /></a>
<!-- badges: start -->
[](https://github.com/thomasp85/patchwork/actions?workflow=R-CMD-check)
[](https://CRAN.R-project.org/package=patchwork)
[](https://CRAN.R-project.org/package=patchwork)
[](https://www.tidyverse.org/lifecycle/#experimental)
<!-- badges: end -->
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.
## Installation
You can install patchwork from github with:
```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("thomasp85/patchwork")
```
## Basic example
The usage of `patchwork` is simple: just add plots together!
```{r example}
library(ggplot2)
library(patchwork)
p1 <- ggplot(mtcars) + geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) + geom_boxplot(aes(gear, disp, group = gear))
p1 + p2
```
You are of course free to also add the plots together as part of the same
plotting operation:
```{r}
ggplot(mtcars) +
geom_point(aes(mpg, disp)) +
ggplot(mtcars) +
geom_boxplot(aes(gear, disp, group = gear))
```
## Layout and nesting
Layouts can be specified by adding a `plot_layout()` call to the assemble. This
lets you define the dimensions of the grid and how much space to allocate to the
different rows and columns.
```{r}
p1 + p2 + plot_layout(ncol = 1, heights = c(3, 1))
```
If you need to add a bit of space between your plots you can use `plot_spacer()`
to fill a cell in the grid with nothing.
```{r}
p1 + plot_spacer() + p2
```
You can make nested plots layout by wrapping part of the plots in parentheses.
In this case the layout is scoped to the different nesting levels.
```{r}
p3 <- ggplot(mtcars) + geom_smooth(aes(disp, qsec))
p4 <- ggplot(mtcars) + geom_bar(aes(carb))
p4 + {
p1 + {
p2 +
p3 +
plot_layout(ncol = 1)
}
} +
plot_layout(ncol = 1)
```
## Annotating Plots
In many cases, one doesn't want to just assemble plots together, but also **label** them or `annotate` them
enabling one to easily refer to each piece, as well as adding titles to the whole. Enter the
`plot_annotation` function
```{r}
p1 + p2 + plot_annotation(title = "A great plot!", tag_levels = "A")
```
### Advanced features
In addition to adding plots and layouts together, `patchwork` defines some other
operators that might be of interest. `-` behaves like `+` but puts the left
and right side in the same nesting level (as opposed to putting the right side
into the left side's nesting level). Observe:
```{r}
p1 + p2 + p3 + plot_layout(ncol = 1)
```
This is basically the same as without braces (just like standard math
arithmetic) - the plots are added sequentially to the same nesting level. Now
consider:
```{r}
p1 + p2 - p3 + plot_layout(ncol = 1)
```
Now `p1 + p2` and `p3` are on the same level...
> A note on semantics. If `-` is read as *minus* its use makes little sense
as we are not removing plots. Think of it as a *hyphen* instead...
Often you are interested in just putting plots besides or on top of each other.
`patchwork` provides both `|` and `/` for horizontal and vertical layouts
respectively. They can, of course, be combined for a very readable layout syntax:
```{r}
(p1 | p2 | p3) /
p4
```
There are two additional operators that are used for a slightly different
purpose, namely to reduce code repetition. Consider the case where you want to
change the theme for all plots in an assembly. Instead of modifying all plots
individually you can use `&` or `*` to add elements to all subplots. The two
differ in that `*` will only affect the plots on the current nesting level:
```{r}
(p1 + (p2 + p3) + p4 + plot_layout(ncol = 1)) * theme_bw()
```
whereas `&` will recurse into nested levels:
```{r}
p1 + (p2 + p3) + p4 + plot_layout(ncol = 1) & theme_bw()
```
> Note that parentheses are required in the former case due to the higher precedence
of the `*` operator. The latter case is the most common so it deserves the
easiest use.
This is all `patchwork` does for now, but stay tuned as more functionality is added, such as collapsing guides, etc...
## Code of Conduct
Please note that the patchwork project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/1/0/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.