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
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/wrap_plots.R
\name{wrap_plots}
\alias{wrap_plots}
\title{Wrap plots into a patchwork}
\usage{
wrap_plots(
...,
ncol = NULL,
nrow = NULL,
byrow = NULL,
widths = NULL,
heights = NULL,
guides = NULL,
tag_level = NULL,
design = NULL,
axes = NULL,
axis_titles = axes
)
}
\arguments{
\item{...}{multiple \code{ggplot}s or a list containing \code{ggplot} objects}
\item{ncol, nrow}{The dimensions of the grid to create - if both are \code{NULL} it
will use the same logic as \link[ggplot2:facet_wrap]{facet_wrap()} to set the
dimensions}
\item{byrow}{Analogous to \code{byrow} in \link[base:matrix]{matrix()}. If \code{FALSE} the
plots will be filled in in column-major order}
\item{widths, heights}{The relative widths and heights of each column and row
in the grid. Will get repeated to match the dimensions of the grid. The
special value of \code{NA}/\verb{-1null} will behave as \verb{1null} unless a fixed aspect
plot is inserted in which case it will allow the dimension to expand or
contract to match the aspect ratio of the content}
\item{guides}{A string specifying how guides should be treated in the layout.
\code{'collect'} will collect guides below to the given nesting level, removing
duplicates. \code{'keep'} will stop collection at this level and let guides be
placed alongside their plot. \code{auto} will allow guides to be collected if a
upper level tries, but place them alongside the plot if not. If you modify
default guide "position" with \link[ggplot2:theme]{theme(legend.position=...)}
while also collecting guides you must apply that change to the overall
patchwork (see example).}
\item{tag_level}{A string (\code{'keep'} or \code{'new'}) to indicate how
auto-tagging should behave. See \code{\link[=plot_annotation]{plot_annotation()}}.}
\item{design}{Specification of the location of areas in the layout. Can either
be specified as a text string or by concatenating calls to \code{\link[=area]{area()}} together.
See the examples for further information on use.}
\item{axes}{A string specifying how axes should be treated. \code{'keep'} will
retain all axes in individual plots. \code{'collect'} will remove duplicated
axes when placed in the same run of rows or columns of the layout.
\code{'collect_x'} and \code{'collect_y'} will remove duplicated x-axes in the columns
or duplicated y-axes in the rows respectively.}
\item{axis_titles}{A string specifying how axis titltes should be treated.
\code{'keep'} will retain all axis titles in individual plots. \code{'collect'} will
remove duplicated titles in one direction and merge titles in the opposite
direction. \code{'collect_x'} and \code{'collect_y'} control this for x-axis titles
and y-axis titles respectively.}
}
\value{
A \code{patchwork} object
}
\description{
While the use of \code{+} is a natural way to add plots together, it can be
difficult to string together multiple plots programmatically if the number
of plots is not known beforehand. \code{wrap_plots} makes it easy to take a list
of plots and add them into one composition, along with layout specifications.
}
\details{
If \code{design} is specified as a text string \emph{and} the plots are named (e.g.
\code{wrap_plots(A = p1, ...)}) \emph{and} all plot names are single characters
represented in the design layout string, the plots will be matched to their
respective area by name. Otherwise the areas will be filled out
sequentially in the same manner as using the \code{+} operator. See the examples
for more.
}
\examples{
library(ggplot2)
p1 <- ggplot(mtcars) + geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) + geom_boxplot(aes(gear, disp, group = gear))
p3 <- ggplot(mtcars) + geom_bar(aes(gear)) + facet_wrap(~cyl)
p4 <- ggplot(mtcars) + geom_bar(aes(carb))
p5 <- ggplot(mtcars) + geom_violin(aes(cyl, mpg, group = cyl))
# Either add the plots as single arguments
wrap_plots(p1, p2, p3, p4, p5)
# Or add them as a list...
plots <- list(p1, p2, p3, p4, p5)
wrap_plots(plots)
# Match plots to areas by name
design <- "#BB
AA#"
wrap_plots(B = p1, A = p2, design = design)
# Compare to not using named plot arguments
wrap_plots(p1, p2, design = design)
}
|
