| legend.grob {BoutrosLab.plotting.general} | R Documentation |
Generate a legend grob
Description
Takes a list and generates a grob representing one or more legends
Usage
legend.grob(
legends,
label.cex = 1,
title.cex = 1,
title.just = 'centre',
title.fontface = 'bold',
font.family = NULL,
size = 3,
border = NULL,
border.padding = 1,
layout = c(1, length(legends)),
between.col = 1,
between.row = 1,
use.legacy.settings = FALSE,
x = 0.5,
y = 0.5,
background.col = "white",
background.alpha = 0
);
Arguments
legends |
A list defining one or more legends. Each must be a separate component called 'legend'. Each component is a list with components 'colours', 'labels', 'border' (optional), 'title' (optional), and 'size' (optional). |
label.cex |
Size of text labels in the legends, defaults to 1. |
title.cex |
Size of titles in the legends, defaults to 1. |
title.just |
Justification of titles in the legends. Defaults to 'centre'. |
title.fontface |
Font face of titles in the legends ('plain', 'bold', 'italic', etc.) |
font.family |
Font to be used for legend text. If NULL, the default font is used. |
size |
Width of the legend boxes in 'character' units. If a 'size' argument is specified for a legend component, it will override this value. |
border |
A list of parameters (passed to |
border.padding |
The amount of empty space (split equally on both sides) to add between the legend and its border, in 'lines' units. Defaults to 1. |
layout |
Numeric vector of length 2 specifying the number of columns and rows for the legend layout. Defaults to a 1-column layout. Note that legends are added to the layout in a row-wise order. |
between.col |
Amount of space to add between columns in the layout, in 'lines' units. Defaults to 0.5. |
between.row |
Amount of space to add between rows in the layout, in 'lines' units. Defaults to 0.5. |
use.legacy.settings |
boolean to set wheter or not to use legacy mode settings (font) |
x |
x coordinate in npc coordinate system |
y |
y coordinate in npc coordinate system |
background.col |
colour for the background of the legend grob |
background.alpha |
alpha for the background of the legend grob |
Value
Returns an grob representing the legend(s)
Implementation
This function was initially created to be called from create.heatmap to draw a covariate legend.
The decision to use a grob (grid graphical object) to represent the legend was made based on the format of the levelplot function in the lattice package. Since the legend argument of the function requires grobs, it was easiest to create a grob to represent the legend and then, if necessary, add this to any existing grobs (dendrograms, etc.) in the create.heatmap function using a grid layout.
An alternative method of creating the legend using the barchart function was tested, but it was unclear how to merge this barchart with the heatmap since the c.trellis function attempts to unify the format of the two images, and the use of viewports required that the plots be drawn, eliminating the possibility of suppressing output and saving the final graph as a trellis object.
Author(s)
Lauren Chong
See Also
create.heatmap, draw.key, gpar
Examples
# The 'cairo' graphics is preferred but on M1 Macs this is not available
bitmap.type = getOption('bitmapType')
if (capabilities('cairo')) {
bitmap.type <- 'cairo';
}
# create list representing two legends
legends1 <- list(
legend = list(
colours = c('orange', 'chartreuse4', 'darkorchid4'),
labels = c('Group 1', 'Group 2', 'Group 3'),
border = c('orange', 'chartreuse4', 'darkorchid4'),
title = 'Legend #1'
),
legend = list(
colours = c('firebrick3', 'lightgrey'),
labels = c('Case', 'Control')
)
);
# create a legend grob using defaults
legend.grob1 <- legend.grob(
legends = legends1
);
tiff(
filename = tempfile(pattern = 'legend_grob1', fileext = '.tiff'),
type = bitmap.type,
width = 5,
height = 5,
units = 'in',
res = 800,
compression = 'lzw'
);
grid.draw(legend.grob1);
dev.off();
# create the same legend with some customizations
legend.grob2 <- legend.grob(
legends = legends1,
label.cex = 1.25,
title.cex = 1.25,
title.just = 'left',
title.fontface = 'bold.italic',
size = 4,
border = list(),
layout = c(2,1)
);
tiff(
filename = tempfile(pattern = 'legend_grob2', fileext = '.tiff'),
type = bitmap.type,
width = 5,
height = 5,
units = 'in',
res = 800,
compression = 'lzw'
);
grid.draw(legend.grob2);
dev.off();
# create a legend where the title is underlined (see ?plotmath), add space between rows
legends2 <- list(
legend = list(
colours = c('orange', 'chartreuse4', 'darkorchid4'),
labels = c('Group 1', 'Group 2', 'Group 3'),
title = expression(underline('Legend #1'))
),
# Use dots instead of rectangles
point = list(
colours = c('firebrick3', 'lightgrey'),
labels = c('A label', 'A longer label'),
# Set dot size
cex = 1.5
)
);
# create the new legend and use more complex border
legend.grob3 <- legend.grob(
legends = legends2,
border = list(col = 'blue', lwd = 2, lty = 3),
border.padding = 1.5,
between.row = 3
);
tiff(
filename = tempfile(pattern = 'legend_grob3', fileext = '.tiff'),
type = bitmap.type,
width = 5,
height = 5,
units = 'in',
res = 800,
compression = 'lzw'
);
grid.draw(legend.grob3);
dev.off();
# Make a legend where the size of boxes is customized
legends3 <- list(
legend = list(
colours = c('orange', 'chartreuse4', 'darkorchid4'),
labels = c('Group 1', 'Group 2', 'Group 3'),
title = 'Legend #1',
size = c(3,2,1)
),
legend = list(
colours = NULL,
labels = c('+', '-'),
border = 'transparent',
title = 'Disease status',
size = 0.5
)
);
legend.grob4 <- legend.grob(
legends = legends3
);
tiff(
filename = tempfile(pattern = 'legend_grob4', fileext = '.tiff'),
type = bitmap.type,
width = 5,
height = 5,
units = 'in',
res = 800,
compression = 'lzw'
);
grid.draw(legend.grob4);
dev.off();