multi_panel_figure {multipanelfigure}

multi_panel_figure

Description

A convenience function building gtable-based infrastructure for the assembly of multipanel figures.

Usage

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"),
  ...
)

Arguments

width

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.

columns

Single numeric defining the number of columns in the resulting gtable. See 'Details' for dependent and interfering parameters.

height

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.

rows

Single numeric defining the number of rows in the resulting gtable. See 'Details' for dependent and interfering parameters.

row_spacing

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.

column_spacing

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.

unit

Single character object defining the unit of all dimensions defined. Must satisfy grid:::valid.units.

figure_name

Single character object defining the name of the resulting gtable.

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 widths and heights.

Details

The gtable may be constructed in two ways:

1. Based on explicit width/height definitions for individual panels.

2. 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:

Individual definition of panel dimensions:

Requires width and height of lengths corresponding to the number of columns/rows requested. Excludes the use of columns and rows.

Definition of global gtable/figure dimensions:

Requires width, columns, height and rows of length 1.

Value

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.

Author(s)

Johannes Graumann

References

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

See Also

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

Examples

## 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)