multipanelﬁgure : Simple Assembly of Multiple Plots and Images into a Compound Figure

In scholarly publications, multiple graphical elements such as plots or raster images are traditionally combined into a single compound ﬁgure using panels arranged in a grid. Package multipanelﬁgure is a GPL-3 licensed R package that eases assembly of such compound ﬁgures, allowing for straightforward integration of R speciﬁc plots using base graphics, lattice and ggplot2 plots, as well as grid grobs in general. Also provided are facilities to incorporate R external graphical output stored as SVG, PNG, JPEG, or TIFF formatted ﬁles.


Introduction
In scholarly writing of documents such as reports, journal articles or books, multiple figures are traditionally combined into multi-panel figures. Such figures represent graphical elements arranged in a grid, with individual panels often identified by labels for ease of cross-referencing. Component figures may be plots or raster images such as work flow diagrams and photographs. In the case of R (R Core Team 2018), plots may be created using base graphics, lattice (Sarkar 2008), ggplot2 (Wickham 2009), etc. or may even be raw grid grobs.
Organizing the layout of multi-panel figures may be performed interactively using dedicated desktop publishing, image editing, or office software. The manual nature of such assembly renders this prone to human error. Common mistakes are including elements of different resolutions, misalignment and heterogeneous font sizes. Being able to script the layout process is thus a feature useful in the context of aiming at high quality output, reproducible research and speedy generation of a press-ready final product.

Existing solutions
R provides several solutions for combining multiple plots and images. The layout function in package graphics allows users to arrange a matrix of base plots. ggmatrix in package GGally (Schloerke et al. 2017) provides similar functionality for plots from package ggplot2. The gtable (Wickham 2016) package and grid.arrange in package gridExtra (Auguie 2017) offer more flexible solutions with the same aim and allow for inclusion of arbitrary grid grobs. Providing a higher level convenience layer, package multipanelfigure (Graumann 2018) is based upon the functionality of package gtable and extends it to include base graphics, lattice-based output and images in PNG, JPEG, SVG and TIFF format with the addition of convenience functionality for panel labeling, handling of grob dimensions and capture of base graphics. The package falls back on functionality from package gridGraphics (Murrell 2018), the successor to package gridBase, for capturing base graphics as grobs and grid's rasterGrob to include raster images. Package multipanelfigure is available from the Comprehensive R Archive Network (CRAN) at https://CRAN.R-project.org/package=multipanelfigure.

Specifying the layout
The multi_panel_figure function is used to create the layout to hold individual panels. Two ways of specifying the dimensions of each panel within the structure have been implemented. Firstly, one may specify the width and height of the entire assembled object, along with the number of rows and columns of panels included. The following creates a multi-panel figure layout setup to arrange panels in two rows and three columns. Measurement units default to millimeters, but all units listed on the ?grid::unit help page are supported via the unit argument. Aside from this ggplot2-inspired interface, dimensions may also be provided as grid unit objects directly. The unit parameter is used to define an internal unique unit if different units are mixed. R> library("multipanelfigure") R> figure1 <-multi_panel_figure(width = 90, height = 30, columns = 3, + rows = 2) Printing a figure object without any panels shows its layout, as demonstrated by Figure 1.

R> figure1
Notice that in this case, all the rows and columns are the same size. Also notice that by default a 5 mm gap has been created before each row and column (used for panel labels). This may be changed or turned off by adjusting the row_spacing and column_spacing values.
The arguments width and height default to "auto", which will derive the figure's dimensions from the graphics device currently in use and works well for development.
A second way of specifying the dimensions of an assembled figure is to pass a vector of row heights and a vector of column widths. This method allows individual rows/columns to have different dimensions (see Figure 2 for an example). 5mm 5mm 25mm 5mm 25mm 5mm 5mm 10mm Figure 1: A multi-panel figure layout with equal row heights and column widths.

Filling panels
Panels are inserted into a pre-created figure layout using the function fill_panel. The first argument to this function is a 'multipanelfigure' object, and the second argument specifies the plot/grob/image to be included. The function defaults to utilizing the first row with a free panel, followed by the first column in that row with a free panel. Using the row and column parameters, this behavior may be overridden and specified panels filled instead. In the following example, a lattice plot is added by passing the object directly to fill_panel. Figure 3 uses the cars data set from the datasets package, representing stopping distances of cars by speed in the 1920s. Further down a JPEG will be inserted into this figure. As JPEG images are currently stretched to fill the specified panel, height in the following example is chosen to preserve the aspect ratio of the image used.

R> figure3
The signature of fill_panel is amenable for use with piping syntax. To facilitate use of that add-on functionality, package multipanelfigure reexports magrittr's (Bache and Wickham 2014) %>% forward pipe operator and %<>% compound assignment pipe operators to make them accessible without explicitly loading the package of origin.
The following example uses a pipe to update the 'multipanelfigure' object with an additional panel, in this case a photo of a car from the 1920s. To include an image file in the figure, simply pass a path to that image (either a path to a local file or a URL). The file type (in this case JPG) is determined from the file extension. The updated multi-panel figure is shown in Figure 4. By default, panels are labeled with uppercase letters. This may be changed by using the panel_label_type argument to multi_panel_figure. Alternatively, labels may be set for individual panels using the label argument to fill_panel.

Saving a figure
Wrapping functionality provided by ggplot2 (ggplot2::ggsave), save_multi_panel_figure provides a convenient means of exporting 'multipanelfigure' (or any grid) objects. The export maintains the dimensions defined for the figure and the syntax is piping-compatible. The graphics format used is derived from the extension of the supplied file name. Currently supported are "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" and "wmf" (Windows only). Figure 4 assembled above may thus be written to a portable network graphics (PNG) file using the following:

A more complex example
Extending the examples to more panels is simple: the creation of a 'multipanelfigure' object with more rows and columns is followed by further calls to fill_panel. The following example recreates Supplementary Figure 4 from Billing et al. (2016). This combines images, a ggplot, a grob, and a base plot. First we create the plot and grob objects.
Package ggplot2 plots from are included in the same way as lattice plots, by directly passing the 'ggplot' object.
R> library("colorspace") R> color_scale <-diverge_hcl(25, h = c(150, 0), c = 100) R> panel_g_heatmap <-capture_base_plot(heatmap(billing2016_suppfig4g, + margins = c(12, 5), col = color_scale, cexRow = 0.7, cexCol = 0.7)) Constructing the complete figure is simply a matter of calling multi_panel_figure, then chaining calls to fill_panel for each of the individual plots and images. In the following example, note the use of the column argument to specify the column positioning of the panels to be used. By setting it to a range column indices, a plot may span multiple columns. Likewise, by modifying row, a panel may take up multiple rows.

Summary
Package multipanelfigure is a GPL-3 licensed R package that enables the scriptable generation of compound figures. Such figures are commonly used in scholarly publications and the package provides an integrated, approachable high-level convenience interface to grid-based functionality drawn from packages gtable (Wickham 2016), gridGraphics (Murrell 2018) and grid itself. Inclusion of the corresponding raster graphics formats uses packages png (Urbanek 2013a), jpeg (Urbanek 2014) and tiff (Urbanek 2013b), respectively, and SVG images are imported via package rsvg (Ooms 2017).
The resulting tool set makes it possible to script the entire assembly of compound figures traditionally common in scientific literature in a straightforward manner. It thus removes sources of human error inherent to assembly using interactive program options, speeds up the process and renders it completely reproducible and documentable. In particular manuscript preparation with R-based statistical analysis and plotting using tools like packages rmarkdown (Allaire et al. 2018) and/or knitr (Xie 2015), may benefit from the capabilities of a high-level tool for the assembly of compound figures without the need to leave the chosen authoring/development environment.