Add manual legend — tm_add

Creates a tmap-element that adds a manual legend.

Usage

tm_add_legend(
  type = c("fill", "symbol", "text", "line", "title"),
  labels = NULL,
  col = NULL,
  size = NULL,
  shape = NULL,
  lwd = NULL,
  lty = NULL,
  text = NULL,
  alpha = NA,
  border.col = "black",
  border.lwd = 1,
  border.alpha = NA,
  title = "",
  is.portrait = TRUE,
  legend.format = list(),
  reverse = FALSE,
  z = NA,
  zindex = NA,
  group = NULL
)

Arguments

type: type of legend. One of "fill", "symbol", "text", "line", or "title". The last option only displays a title.
labels: legend labels
col: legend colors
size: legend symbol sizes (if type=="symbol"). See example how to replicate the sizes of symbols created with tm_symbols. If not specified, the symbols will have the same size as when calling tm_symbols without specifying the size argument.
shape: legend symbol shapes (if type=="symbol")
lwd: legend line widths (if type=="line")
lty: legend line types (if type=="line")
text: legend texts (if type=="text")
alpha: legend fill transparency
border.col: legend border col (if type is "fill" or "symbol")
border.lwd: legend border width (if type is "fill" or "symbol")
border.alpha: legend border alpha (if type is "fill" or "symbol")
title: legend title
is.portrait: is legend portrait (TRUE) or landscape (FALSE)?
legend.format: options to format the legend, see tm_symbols (the description of the argument legend.format) for details. Note that many of these arguments are not applicable for tm_add_legend since labels should be a character vector. However, some options could still be handy, e.g. list(text.align = "right").
reverse: are the legend items reversed (by default FALSE)?
z: legend stack position
zindex: zindex of the pane in view mode to which the legend belongs (if any).
group: name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. By default NULL, which means that the legend will not be shown in the layer control item.

Examples

# This example adds a manual legend that combines the tm_symbols color and size legend.
if (FALSE) {
data(World)
data(metro)

# legend bubble size (10, 20, 30, 40 million) are
# - are normlized by upper limit (40e6),
# - square rooted (see argument perceptual of tm_symbols), and 
# - scaled by 2:
bubble_sizes <- ((c(10, 20, 30, 40) * 1e6) / 40e6) ^ 0.5 * 2 

tm_shape(World) + 
  tm_polygons() + 
tm_shape(metro) +
  tm_symbols(col='pop2020', 
    breaks = c(0, 15, 25, 35, 40) * 1e6,
    n=4,
    palette = 'YlOrRd',
    size='pop2020',
    sizes.legend = c(10, 20, 30, 40) * 1e6,
    size.lim = c(0, 40e6),
    scale = 2,
    legend.size.show = FALSE,    # comment this line to see the original size legend
    legend.col.show = FALSE,     # comment this line to see the original color legend
    legend.size.is.portrait = TRUE) + 
tm_add_legend('symbol', 
  col = RColorBrewer::brewer.pal(4, "YlOrRd"),
  border.col = "grey40",
  size = bubble_sizes,
  labels = c('0-15 mln','15-25 mln','25-35 mln','35-40 mln'),
  title="Population Estimate")
}

# See also the documentation of tm_symbols for another example