# fill_panel A convenience function adding graphical objects to a `gtable` constructed by `multi_panel_figure`. ```r 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`. ## Returns Returns the `gtable` object fed to it (`figure`) with the addition of the `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.object`s. 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.object`s are converted to `grob`s using `grid.grabExpr(print(x))`, as are `Heatmap` and `HeatmapList`s 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. ## Examples ```r # 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)) ``` ## 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` ## Author(s) Johannes Graumann, Richard Cotton

fill_panel function