multi_panel_figure

Description

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

Usage

1
2
3
4
5
multi_panel_figure(width = NULL, widths = NULL, columns = NULL,
  height = NULL, heights = NULL, rows = NULL, inter_row_spacing = NaN,
  inter_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

Single link{numeric} defining the width of the resulting gtable (unit depending on unit). See 'Details' for dependent and interfering parameters.

widths

vector of numerics defining the actual widths of panels/columns in the resulting gtable (unit depending on unit). 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

Single link{numeric} defining the height of the resulting gtable (unit depending on unit). See 'Details' for dependent and interfering parameters.

heights

vector of numerics defining the actual heights of panels/rows in the resulting gtable (unit depending on unit). 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.

inter_row_spacing

The amount of white space automatically inserted between row panels. Defaults to 5 mm unless explicitly given, in which case the value depends on the unit parameter. Recycled to the number of rows.

inter_column_spacing

The amount of white space automatically inserted between column panels. Defaults to 5 mm unless explicitly given, in which case the value 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.

Details

The gtable may be constructed in two ways:

  1. Based on explicit width/height definitions for individual panels handed to it via widths and heights.

  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 inter_column_spacing before column panels (and of height inter_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(widths) + length(widths) * inter_column_spacing

while width of resulting panels in the latter table construction approach may be calculated

W[panel] = (width - columns * inter_column_spacing) / columns

The two approaches to gtable construction require mutually exclusive parameter sets:

Individual definition of panel dimensions:

Requires widths and heights. Excludes the use of width, columns, heights and rows.

Definition of global gtable/figure dimensions:

Requires width, columns, heights and rows. Excludes the use of widths and heights.

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

See Also

add_panel for more examples of adding panels simple_grob_width for inspecting figure dimensions capture_base_plot for including plots created using base graphics gtable for the underlying structure of a figure

Examples

 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
# Figure construction based on overall dimensions
figure1 <- multi_panel_figure(
   width = 100,
   columns = 4,
   height = 90,
   rows = 6,
   figure_name = "figure1")
# With no panels, printing shows the layout
figure1

# Figure construction based on individual panel dimensions
(figure2 <- multi_panel_figure(
   widths = c(40,30),
   heights = c(40,60),
   inter_row_spacing = c(5, 1),
   inter_column_spacing = c(0, 10),
   figure_name = "figure2"))

# 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
figure2 <- add_panel(figure2, ggp)
# JPEG, PNG, and TIFF images are added by passing the path to their file
jpg <- system.file("extdata/rhino.jpg", package = "multipanelfigure")
figure2 <- add_panel(figure2, jpg, left_panel = 2)
# Plots can take up multiple panels
figure2 <- add_panel(figure2, ggp, top_panel = 2, left_panel = 1, right_panel = 2)
# Plot to appropriately sized png device
tmpFile <- tempfile(fileext = ".png")
ggplot2::ggsave(
  tmpFile, figure2,
  width = simple_grob_width(figure2, "in"),
  height = simple_grob_height(figure2, "in"))
message(
  paste0("Now have a look at '",tmpFile,"' - nicely sized PNG output."))
 # Not testing due to use of external software
utils::browseURL(tmpFile)