tm_add_legend {tmap}

Add manual legend

Description

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.

See Also

tm_symbols for another example

Examples

# This example adds a manual legend that combines the tm_symbols color and size legend.
## Not run: 
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")

## End(Not run)

# See also the documentation of tm_symbols for another example