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"),
...
)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.
numeric or link[grid]{unit} defining the
width(s) of the resulting gtable if
length(width) == 1 or individual column widths. Units depends on
unit if not provided as unit object. The default
'auto' sets the parameter to the width of the currently used device.
See 'Details' for dependent and interfering parameters.
Single numeric defining the number of columns in
the resulting gtable. See 'Details' for dependent and
interfering parameters.
numeric or link[grid]{unit} defining the
height of the resulting gtable if
length(height) == 1 or individual row heights.nits depends on
unit if not provided as unit object. The default
'auto' sets the parameter to the height of the currently used device.
See 'Details' for dependent and interfering parameters.
Single numeric defining the number of rows in
the resulting gtable. See 'Details' for dependent and
interfering parameters.
numeric or #' unit
defining the amount of white space automatically inserted between row panels.
Defaults to 5 mm unless explicitly given, in which case the value may
depend on the unit parameter. Recycled to the number of rows.
numeric or unit
defining the amount of white space automatically inserted between column
panels. Defaults to 5 mm unless explicitly given, in which case the
value may depends on the unit parameter. Recycled to the number of
columns.
Single character object defining the unit of all
dimensions defined. Must satisfy grid:::valid.units.
Single character object defining the name of
the resulting gtable.
A string specifying the marker style for the panel labels used for automated annotation. Defaults to uppercase Latin letters.
Argument to accomodate deprecated arguments widths and
heights.
Johannes Graumann
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.
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