fill_panel {multipanelfigure}

fill_panel

Description

A convenience function adding graphical objects to a gtable constructed by multi_panel_figure.

Usage

fill_panel(
  figure,
  panel,
  row = "auto",
  column = "auto",
  label = NULL,
  label_just = c("right", "bottom"),
  panel_clip = c("on", "off", "inherit"),
  scaling = c("none", "stretch", "fit", "shrink"),
  allow_panel_overwriting = FALSE,
  verbose = TRUE,
  ...
)

Arguments

figure

Object of classes multipanelfigure/ gtable as produced by multi_panel_figure and representing the figure the panel is to be placed in.

panel

Single character object representing URL or path to a bitmap image accessible by ImageMagick as used through magick, a Heatmap or HeatmapList object, a ggplot object , a trellis.object, a gList object or a grob object to be placed in a multipanel figure. See 'Details'.

row

numeric object of length 1 or a range, indicating the row indeces the panel that is to be placed in the figure, or "auto" to automatically pick the row (see details). May be used to define panel spanning (if length(row) > 1; see examples).

column

numeric object of length 1 or a range, indicating the column indeces of the panel that is to be placed in the figure, or "auto" to automatically pick the column (see details). May be used to define panel spanning (if length(column) > 1; see examples).

label

Single character object defining the panel label used for automated annotation.

label_just

Justification for the label within the interpanel spacing grob to the top-left of the panel content grob. Passed to textGrob.

panel_clip

Should the display of panel contents be clipped at the panel borders? See viewport.

scaling

Only used when importing image files. Either "none" to preserve the dimensions of an image, "stretch" to make it fit the panels, "fit" to shrink or enlarge it so that it fills one dimension of the panels while preserving the height to width ratio, or "shrink which does the same but won't enlarge it.

allow_panel_overwriting

A logical value. If TRUE, overwriting panels is allowed, with a warning. Otherwise (the default) it will cause an error.

verbose

A logical value. Reduces verbosity if FALSE.

...

Additional arguments. Used to deal with deprecated arguments top_panel, bottom_panel, left_panel and right_panel.

Details

Currently supported as panel-representing objects (panel) are

1. ComplexHeatmap Heatmap or HeatmapList objects.

2. ggplot2 ggplot objects.

3. grid grob, gList, and gTree objects.

4. lattice trellis.objects.

5. Single character objects representing URLs or paths to image formats accessible by ImageMagick as used through magick, which will be read and placed into panels as requested.

Native resolution is determined from attributes in the file. If the attributes are not present, then the DPI is determined by the the multipanelfigure.defaultdpi global option, or 300 if this has not been set.

lattice-generated trellis.objects are converted to grobs using grid.grabExpr(print(x)), as are Heatmap and HeatmapLists from ComplexHeatmap - the side effects of which with respect to plot formatting are not well studied.

If the row argument is "auto", then the first row with a free panel is used. If the column argument is "auto", then the first column in the row with a free panel is used.

Value

Returns the gtable object fed to it (figure) with the addition of the panel.

Author(s)

Johannes Graumann, Richard Cotton

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

gtable, multi_panel_figure

Examples

 # Not testing - slow grid graphics makes CRAN timing excessive
# Create the figure layout
(figure <- multi_panel_figure(
  width = c(30,40,60),
  height = c(40,60,60,60),
  panel_label_type = "upper-roman"))

# Fill the top-left panel using a grob object directly
a_grob <- grid::linesGrob(arrow = grid::arrow())
figure %<>% fill_panel(a_grob)

# Add a ggplot object directly to the top row, second column.
# The panels are chosen automatically, but you can achieve the same effect
# using column = 2
a_ggplot <- ggplot2::ggplot(mtcars, ggplot2::aes(disp, mpg)) +
  ggplot2::geom_point()
figure %<>% fill_panel(a_ggplot)

# Bitmap images are added by passing the path to their file.
image_files <- system.file("extdata", package = "multipanelfigure") %>%
  dir(full.names = TRUE) %>%
  magrittr::set_names(basename(.))

# Add the JPEG to the top row, third column
figure %<>% fill_panel(image_files["rhino.jpg"], column = 3)

# Add the PNG to the second and third row, first and second column
figure %<>% fill_panel(
  image_files["Rlogo.png"],
  row = 2:3, column = 1:2)

# Add the TIFF to the second row, third column
figure %<>% fill_panel(
  image_files["unicorn.svg"],
  row = 2, column = 3)

# lattice/trellis plot objects are also added directly
Depth <- lattice::equal.count(quakes$depth, number=4, overlap=0.1)
a_lattice_plot <- lattice::xyplot(lat ~ long | Depth, data = quakes)
# Add the lattice plot to the third row, third column
figure %<>% fill_panel(
  a_lattice_plot,
  row = 3, column = 3)

# Incorporate a gList object (such as produced by VennDigram)
if(requireNamespace("VennDiagram"))
{
  a_venn_plot <- VennDiagram::draw.pairwise.venn(50, 30, 20, ind = FALSE)
  # Add the Venn diagram to the fourth row, firstd column
  figure %<>% fill_panel(
    a_venn_plot,
    row = 4, column = 1)
}

# Incorporate a base plot figure
a_base_plot <- capture_base_plot(
 heatmap(
   cor(USJudgeRatings), Rowv = FALSE, symm = TRUE, col = topo.colors(16),
   distfun = function(c) as.dist(1 - c), keep.dendro = TRUE,
   cexRow = 0.5, cexCol = 0.5))
# Add the heatmap to the fourth row, second column
figure %<>% fill_panel(
  a_base_plot,
  row = 4, column = 2)

# Incorporate a ComplexHeatmap figure
require(ComplexHeatmap)
mat = matrix(rnorm(80, 2), 8, 10)
mat = rbind(mat, matrix(rnorm(40, -2), 4, 10))
rownames(mat) = letters[1:12]
colnames(mat) = letters[1:10]
ht = Heatmap(mat)
a_complex_heatmap <- ht + ht + ht
# Add the ComplexHeatmap to the fourth row, third column
(figure %<>% fill_panel(
  a_complex_heatmap,
  row = 4, column = 3))