View source: R/multi_panel_figure.R
multi_panel_figure | R Documentation |
A convenience function building gtable
-based
infrastructure for the assembly of multipanel figures.
multi_panel_figure(
width = "auto",
columns = NULL,
height = "auto",
rows = NULL,
row_spacing = NaN,
column_spacing = NaN,
unit = "mm",
figure_name = "FigureX",
panel_label_type = c("upper-alpha", "lower-alpha", "decimal", "upper-roman",
"lower-roman", "upper-greek", "lower-greek", "none"),
...
)
width |
|
columns |
Single |
height |
|
rows |
Single |
row_spacing |
|
column_spacing |
|
unit |
Single |
figure_name |
Single |
panel_label_type |
A string specifying the marker style for the panel labels used for automated annotation. Defaults to uppercase Latin letters. |
... |
Argument to accomodate deprecated arguments |
The gtable
may be constructed in two ways:
Based on explicit width/height definitions for individual panels.
Based on total figure/gtable
dimensions given by
width
and height
together with the number of columns
and rows
requested.
The function automatically inserts whitespace of width
column_spacing
before column panels (and of height
row_spacing
before row panels), which has to be considered
for the total dimensions of the resulting gtable
. Width
of the gtable
in the former case, for example may be
calculated
W[total] = sum(width) + length(width) * column_spacing
while width of resulting panels in the latter table construction approach may be calculated
W[panel] = (width - columns * column_spacing) / columns
width
, height
, column_spacing
and
row_spacing
may be defined numerically or as
unit
objects.
Earlier implementations used parameters widhts
and heights
as
synonyms for width
and height
with length greater than one.
These parameters have been deprecated. They continue to work, but produce
a warning.
The two approaches to gtable
construction require
interdepending parameter sets:
Requires width
and
height
of lengths corresponding to the number of columns/rows
requested. Excludes the use of columns
and rows
.
gtable
/figure dimensions:Requires width
, columns
, height
and rows
of
length 1.
Returns an object of class multipanelfigure
as well as
gtable
object with the following additional attributes:
multipanelfigure.panelsFree
:A logical
matrix
with the dimensions of the gtable
indicating occupancy of the panels in the table.
multipanelfigure.panellabelsfree
:A character
vector
indicative of the panel_labels
still available.
multipanelfigure.unit
:A single character
object storing the corresponding value given during object creation.
Johannes Graumann
Graumann, J., and Cotton, R.J. (2018). multipanelfigure: Simple Assembly of Multiple Plots and Images into a Compound Figure. Journal of Statistical Software 84. doi: 10.18637/jss.v084.c03
fill_panel
for more examples of filling panels
figure_width
for inspecting figure dimensions
capture_base_plot
for including plots created using base graphics
gtable
for the underlying structure of a figure
## Not run:
# Figure construction based on the dimensions of the current device
figure1 <- multi_panel_figure(
columns = 2,
rows = 2,
figure_name = "figure1")
# With no panels, printing shows the layout
figure1
# Figure construction based on overall dimensions
figure2 <- multi_panel_figure(
width = 100,
columns = 4,
height = 90,
rows = 6,
figure_name = "figure2")
# Still no panels ...
figure2
# Figure construction based on individual panel dimensions
(figure3 <- multi_panel_figure(
width = c(40,30),
height = c(40,60),
row_spacing = c(5, 1),
column_spacing = c(0, 10),
figure_name = "figure3"))
# A more involved example including filling and printing to device ...
# Make a simple ggplot object to fill panels
ggp <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
ggplot2::geom_point()
# Fill panels
# ggplots and lattice plot objects are added directly
# The default position is the top-left panel
figure3 <- fill_panel(figure3, ggp)
# Raster images are added by passing the path to their file
jpg <- system.file("extdata/rhino.jpg", package = "multipanelfigure")
figure3 <- fill_panel(figure3, jpg, column = 2)
# Plots can take up multiple panels
figure3 <- fill_panel(figure3, ggp, row = 2, column = 1:2)
# Plot to appropriately sized png device
tmpFile <- tempfile(fileext = ".png")
ggplot2::ggsave(
tmpFile, figure3,
width = figure_width(figure3, "in"),
height = figure_height(figure3, "in"))
message(
paste0("Now have a look at '",tmpFile,"' - nicely sized PNG output."))
\donttest{ # Not testing due to use of external software
utils::browseURL(tmpFile)
}
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.