fill_panel
fill_panel
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 bymulti_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 byImageMagick
as used throughmagick
, aHeatmap
orHeatmapList
object, aggplot
object , atrellis.object
, agList
object or agrob
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 (iflength(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 (iflength(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
andright_panel
.
Details
Currently supported as panel-representing objects (panel
) are
ComplexHeatmap
Heatmap
orHeatmapList
objects.ggplot2
ggplot
objects.lattice
trellis.object
s.Single
character
objects representing URLs or paths to image formats accessible byImageMagick
as used throughmagick
, 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.
Value
Returns the gtable
object fed to it
(figure
) with the addition of the panel
.
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
Examples
# NOT RUN {
# 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) %>%
setNames(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))
# }