Learn R Programming

tmap (version 1.2)

tm_text: Add text labels

Description

Creates a tmap-element that adds text labels.

Usage

tm_text(text, size = 1, col = NA, root = 3, size.lim = NA,
  sizes.legend = NULL, sizes.legend.labels = NULL,
  sizes.legend.text = "Abc", n = 5, style = ifelse(is.null(breaks),
  "pretty", "fixed"), breaks = NULL, palette = NULL, labels = NULL,
  labels.text = NA, auto.palette.mapping = TRUE, contrast = 1,
  max.categories = 12, colorNA = NA, textNA = "Missing", fontface = NA,
  fontfamily = NA, alpha = NA, case = NA, shadow = FALSE,
  bg.color = NA, bg.alpha = NA, size.lowerbound = 0.4,
  print.tiny = FALSE, scale = 1, auto.placement = FALSE,
  remove.overlap = FALSE, along.lines = FALSE, overwrite.lines = FALSE,
  xmod = 0, ymod = 0, title.size = NA, title.col = NA,
  legend.size.show = TRUE, legend.col.show = TRUE, legend.format = list(),
  legend.size.is.portrait = FALSE, legend.col.is.portrait = TRUE,
  legend.hist = FALSE, legend.hist.title = NA, legend.size.z = NA,
  legend.col.z = NA, legend.hist.z = NA, id = NA)

Arguments

text
name of the variable in the shape object that contains the text labels
size
relative size of the text labels (see note). Eiter one number, a name of a numeric variable in the shape data that is used to scale the sizes proportionally, or the value "AREA", where the text size is proportional to the area size of the pol
col
color of the text labels. Either a color value or a data variable name. If multiple values are specified, small multiples are drawn (see details).
root
root number to which the font sizes are scaled. Only applicable if size is a variable name or "AREA". If root=2, the square root is taken, if root=3, the cube root etc.
size.lim
vector of two limit values of the size variable. Only text labels are drawn whose value is greater than or equal to the first value. Text labels whose values exceed the second value are drawn at the size of the second value. Only applicable w
sizes.legend
vector of text sizes that are shown in the legend. By default, this is determined automatically.
sizes.legend.labels
vector of labels for that correspond to sizes.legend.
sizes.legend.text
vector of example text to show in the legend next to sizes.legend.labels. By default "Abc". When NA, examples from the data variable whose sizes are close to the sizes.legend are taken and "NA" for classes where no match is found
n
preferred number of color scale classes. Only applicable when col is a numeric variable name.
style
method to process the color scale when col is a numeric variable. Discrete options are "cat", "fixed", "sd", "equal", "pretty", "quantile", "kmeans", <
breaks
in case style=="fixed", breaks should be specified
palette
color palette (see RColorBrewer::display.brewer.all) for the text. Only when col is set to a variable. The default palette is taken from tm_layout's argument aes.palette
labels
labels of the color classes, applicable if col is a data variable name
labels.text
Example text to show in the legend next to the labels. When NA (default), examples from the data variable are taken and "NA" for classes where they don't exist.
auto.palette.mapping
When diverging colour palettes are used (i.e. "RdBu") this method automatically maps colors to values such that the middle colors (mostly white or yellow) are assigned to values of 0, and the two sides of the color palette are assigned to negative respect
contrast
vector of two numbers that determine the range that is used for sequential and diverging palettes (applicable when auto.palette.mapping=TRUE). Both numbers should be between 0 and 1. The first number determines where the palette begins, and t
max.categories
in case col is the name of a categorical variable, this value determines how many categories (levels) it can have maximally. If the number of levels is higher than max.categories, then levels are combined.
colorNA
colour for missing values
textNA
text used for missing values. Use NA to omit text for missing values in the legend
fontface
font face of the text labels. By default, determined by the fontface argument of tm_layout.
fontfamily
font family of the text labels. By default, determined by the fontfamily argument of tm_layout.
alpha
transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the fontcolor is used (normally 1).
case
case of the font. Use "upper" to generate upper-case text, "lower" to generate lower-case text, and NA to leave the text as is.
shadow
logical that determines whether a shadow is depicted behind the text. The color of the shadow is either white or yellow, depending of the fontcolor.
bg.color
background color of the text labels. By default, bg.color=NA, so no background is drawn.
bg.alpha
number between 0 and 1 that specifies the transparancy of the text background (0 is totally transparent, 1 is solid background).
size.lowerbound
lowerbound for size. Only applicable when size is not a constant. If print.tiny is TRUE, then all text labels which relative text is smaller than size.lowerbound are depicted at relative siz
print.tiny
boolean, see size.lowerbound
scale
text size multiplier, useful in case size is variable or "AREA".
auto.placement
logical (or numeric) that determines whether the labels are placed automatically. If TRUE, the labels are placed next to the coordinate points with as little overlap as possible using the simulated annealing algorithm. Therefore, it is recomm
remove.overlap
logical that determines whether the overlapping labels are removed
along.lines
logical that determines whether labels are rotated along the spatial lines. Only applicabel if a spatial lines shape is used.
overwrite.lines
logical that determines whether the part of the lines below the text labels is removed. Only applicabel if a spatial lines shape is used.
xmod
horizontal position modification of the text (relatively): 0 means no modification, and 1 corresponds to the height of one line of text. Either a single number for all polygons, or a numeric variable in the shape data specifying a number for each polygon.
ymod
vertical position modification. See xmod.
title.size
title of the legend element regarding the text sizes
title.col
title of the legend element regarding the text colors
legend.size.show
logical that determines whether the legend for the text sizes is shown
legend.col.show
logical that determines whether the legend for the text colors is shown
legend.format
list of formatting options for the legend numbers. Only applicable if labels is undefined. Parameters are: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]
legend.size.is.portrait
logical that determines whether the legend element regarding the text sizes is in portrait mode (TRUE) or landscape (FALSE)
legend.col.is.portrait
logical that determines whether the legend element regarding the text colors is in portrait mode (TRUE) or landscape (FALSE)
legend.hist
logical that determines whether a histogram is shown regarding the text colors
legend.hist.title
title for the histogram. By default, one title is used for both the histogram and the normal legend for text colors.
legend.size.z
index value that determines the position of the legend element regarding the text sizes with respect to other legend elements. The legend elements are stacked according to their z values. The legend element with the lowest z value is placed on top.
legend.col.z
index value that determines the position of the legend element regarding the text colors. (See legend.size.z)
legend.hist.z
index value that determines the position of the histogram legend element. (See legend.size.z)
id
name of the data variable that specifies the indices of the text labels. Only used for SVG output (see itmap).

Value

See Also

../doc/tmap-nutshell.html{vignette("tmap-nutshell")}

Examples

Run this code
data(World, Europe, metro)

tm_shape(World) +
    tm_text("name", size="AREA")

tm_shape(Europe) +
    tm_polygons() +
    tm_text("iso_a3", size="AREA", col = "grey20", root=4, shadow = TRUE, scale=2,
        size.lowerbound = .1) +
tm_shape(Europe) +
    tm_text("name", size="AREA", root=4, scale=1,
        ymod=-1 * approx_areas(Europe, unit = "norm")^(1/4))

tm_shape(Europe) +
	tm_polygons() +
tm_shape(metro) +
	tm_bubbles("pop2010", size.lim = c(0, 15e6), legend.size.is.portrait = TRUE, 
			   title.size = "European metropolitan areas") +
tm_shape(metro[metro$pop2010>=2e6, ]) +
	tm_text("name", auto.placement = TRUE)

tm_shape(World) +
	tm_text("name", size="pop_est", col="continent", palette="Dark2", 
			title.size = "Population", title.col="Continent")

Run the code above in your browser using DataLab