Creates a tmap-element that adds text labels.
tm_text(
text,
size = 1,
col = NA,
root = 3,
clustering = FALSE,
size.lim = NA,
sizes.legend = NULL,
sizes.legend.labels = NULL,
sizes.legend.text = "Abc",
n = 5,
style = ifelse(is.null(breaks), "pretty", "fixed"),
style.args = list(),
as.count = NA,
breaks = NULL,
interval.closure = "left",
palette = NULL,
labels = NULL,
drop.levels = FALSE,
labels.text = NA,
midpoint = NULL,
stretch.palette = TRUE,
contrast = NA,
colorNA = NA,
textNA = "Missing",
showNA = NA,
colorNULL = NA,
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,
just = "center",
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.size.reverse = FALSE,
legend.col.reverse = FALSE,
legend.hist = FALSE,
legend.hist.title = NA,
legend.size.z = NA,
legend.col.z = NA,
legend.hist.z = NA,
id = NA,
zindex = NA,
group = NA,
auto.palette.mapping = NULL,
max.categories = NULL
)name of the variable in the shape object that contains the text labels
relative size of the text labels (see note). Either 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 polygons.
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 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.
value that determines whether the text labels are clustered in "view" mode. One of: TRUE, FALSE, or the output of markerClusterOptions.
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 when size is the name of a numeric variable of shp. See also size.lowerbound which is a threshold of the relative font size.
vector of text sizes that are shown in the legend. By default, this is determined automatically.
vector of labels for that correspond to sizes.legend.
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.
preferred number of color scale classes. Only applicable when col is a numeric variable name.
method to process the color scale when col is a numeric variable. Discrete gradient options are "cat", "fixed", "sd", "equal", "pretty", "quantile", "kmeans", "hclust", "bclust", "fisher", "jenks", "dpih", "headtails", and "log10_pretty". A numeric variable is processed as a categorical variable when using "cat", i.e. each unique value will correspond to a distinct category. For the other discrete gradient options (except "log10_pretty"), see the details in classIntervals (extra arguments can be passed on via style.args). Continuous gradient options are "cont", "order", and "log10". The first maps the values of col to a smooth gradient, the second maps the order of values of col to a smooth gradient, and the third uses a logarithmic transformation. The numeric variable can be either regarded as a continuous variable or a count (integer) variable. See as.count.
arguments passed on to classIntervals, the function that determine color classes (see also style).
when col is a numeric variable, should it be processed as a count variable? For instance, if style = "pretty", n = 2, and the value range of the variable is 0 to 10, then the column classes for as.count = TRUE are 0; 1 to 5; 6 to 10 (note that 0 is regarded as an own category) whereas for as.count = FALSE they are 0 to 5; 5 to 10. Only applicable if style is "pretty", "fixed", or "log10_pretty". By default, TRUE if style is one of these, and the variable is an integer.
in case style=="fixed", breaks should be specified. The breaks argument can also be used when style="cont". In that case, the breaks are mapped evenly to the sequential or diverging color palette.
value that determines whether where the intervals are closed: "left" or "right". Only applicable if col is a numeric variable. If as.count = TRUE, inverval.closure is always set to "left".
a palette name or a vector of colors. See tmaptools::palette_explorer() for the named palettes. Use a "-" as prefix to reverse the palette. The default palette is taken from tm_layout's argument aes.palette, which typically depends on the style. The type of palette from aes.palette is automatically determined, but can be overwritten: use "seq" for sequential, "div" for diverging, and "cat" for categorical.
labels of the color classes, applicable if col is a data variable name
should unused color classes be omitted? FALSE by default.
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.
The value mapped to the middle color of a diverging palette. By default it is set to 0 if negative and positive values are present. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to NA, which means that the value that corresponds to the middle color class (see style) is mapped to the middle color. Only applies when col is a numeric variable. If it is specified for sequential color palettes (e.g. "Blues"), then this color palette will be treated as a diverging color palette.
Logical that determines whether the categorical color palette should be stretched if there are more categories than colors. If TRUE (default), interpolated colors are used (like a rainbow). If FALSE, the palette is repeated.
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 the second number where it ends. For sequential palettes, 0 means the brightest color, and 1 the darkest color. For diverging palettes, 0 means the middle color, and 1 both extremes. If only one number is provided, this number is interpreted as the endpoint (with 0 taken as the start).
colour for missing values. Use NULL for transparency.
text used for missing values.
logical that determines whether missing values are named in the legend. By default (NA), this depends on the presence of missing values.
colour for polygons that are shown on the map that are out of scope
font face of the text labels. By default, determined by the fontface argument of tm_layout.
font family of the text labels. By default, determined by the fontfamily argument of tm_layout.
transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the fontcolor is used (normally 1).
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.
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.
background color of the text labels. By default, bg.color=NA, so no background is drawn.
number between 0 and 1 that specifies the transparency of the text background (0 is totally transparent, 1 is solid background).
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 size size.lowerbound. If print.tiny is FALSE, then text labels are only depicted if their relative sizes are at least size.lowerbound (in other words, tiny labels are omitted).
boolean, see size.lowerbound
text size multiplier, useful in case size is variable or "AREA".
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 recommended for labeling spatial dots or symbols. If a numeric value is provided, this value acts as a parameter that specifies the distance between the coordinate points and the text labels in terms of text line heights.
logical that determines whether the overlapping labels are removed
logical that determines whether labels are rotated along the spatial lines. Only applicable if a spatial lines shape is used.
logical that determines whether the part of the lines below the text labels is removed. Only applicable if a spatial lines shape is used.
justification of the text relative to the point coordinates. Either one of the following values: "left" , "right", "center", "bottom", and "top", or a vector of two values where first value specifies horizontal and the second value vertical justification. Besides the mentioned values, also numeric values between 0 and 1 can be used. 0 means left justification for the first value and bottom justification for the second value. Note that in view mode, only one value is used.
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. Together with ymod, it determines position modification of the text labels. In most coordinate systems (projections), the origin is located at the bottom left, so negative xmod move the text to the left, and negative ymod values to the bottom.
vertical position modification. See xmod.
title of the legend element regarding the text sizes
title of the legend element regarding the text colors
logical that determines whether the legend for the text sizes is shown
logical that determines whether the legend for the text colors is shown
list of formatting options for the legend numbers. Only applicable if labels is undefined. Parameters are:
Function to specify the labels. It should take a numeric vector, and should return a character vector of the same size. By default it is not specified. If specified, the list items scientific, format, and digits (see below) are not used.
Should the labels be formatted scientifically? If so, square brackets are used, and the format of the numbers is "g". Otherwise, format="f", and text.separator, text.less.than, and text.or.more are used. Also, the numbers are automatically rounded to millions or billions if applicable.
By default, "f", i.e. the standard notation xxx.xxx, is used. If scientific=TRUE then "g", which means that numbers are formatted scientifically, i.e. n.dddE+nn if needed to save space.
Number of digits after the decimal point if format="f", and the number of significant digits otherwise.
Vector that defines whether and which abbrevations are used for large numbers. It is a named numeric vector, where the name indicated the abbreviation, and the number the magnitude (in terms on numbers of zero). Numbers are only abbrevation when they are large enough. Set it to NA to disable abbrevations. The default is c("mln" = 6, "bln" = 9). For layers where style is set to log10 or log10_pretty, the default is NA.
Prefix of each number
Suffix of each number
Prefix of each number
Suffix of each number
Character string to use to separate numbers in the legend (default: "to").
Character value(s) to use to translate "Less than". When a character vector of length 2 is specified, one for each word, these words are aligned when text.to.columns = TRUE
Character value(s) to use to translate "or more". When a character vector of length 2 is specified, one for each word, these words are aligned when text.to.columns = TRUE
Value that determines how the numbers are aligned, "left", "center" or "right". By default "left" for legends in portrait format (legend.is.portrait = TRUE), and "center" otherwise.
Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default FALSE.
Other arguments passed on to formatC
logical that determines whether the legend element regarding the text sizes is in portrait mode (TRUE) or landscape (FALSE)
logical that determines whether the legend element regarding the text colors is in portrait mode (TRUE) or landscape (FALSE)
logical that determines whether the items of the legend regarding the text sizes are shown in reverse order, i.e. from bottom to top when legend.size.is.portrait = TRUE and from right to left when legend.size.is.portrait = FALSE
logical that determines whether the items of the legend regarding the text colors are shown in reverse order, i.e. from bottom to top when legend.col.is.portrait = TRUE and from right to left when legend.col.is.portrait = FALSE
logical that determines whether a histogram is shown regarding the text colors
title for the histogram. By default, one title is used for both the histogram and the normal legend for text colors.
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.
index value that determines the position of the legend element regarding the text colors. (See legend.size.z)
index value that determines the position of the histogram legend element. (See legend.size.z)
name of the data variable that specifies the indices of the text labels. Only used for "view" mode (see tmap_mode).
zindex of the pane in view mode. By default, it is set to the layer number plus 400. By default, the tmap layers will therefore be placed in the custom panes "tmap401", "tmap402", etc., except for the base tile layers, which are placed in the standard "tile". This parameter determines both the name of the pane and the z-index, which determines the pane order from bottom to top. For instance, if zindex is set to 500, the pane will be named "tmap500".
name of the group to which this layer belongs in view mode. Each group can be selected or deselected in the layer control item. Set group = NULL to hide the layer in the layer control item. By default, it will be set to the name of the shape (specified in tm_shape).
deprecated. It has been replaced by midpoint for numeric variables and stretch.palette for categorical variables.
deprecated. It has moved to tmap_options.
Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, 10.18637/jss.v084.i06
# NOT RUN {
current.mode <- tmap_mode("plot")
data(World, metro)
tm_shape(World) +
tm_text("name", size="AREA")
tm_shape(World) +
tm_text("name", size="pop_est", col="continent", palette="Dark2",
title.size = "Population", title.col="Continent") +
tm_legend(outside = TRUE)
tmap_mode("view")
# }
# NOT RUN {
require(tmaptools)
metro_aus <- crop_shape(metro, bb("Australia"))
tm_shape(metro_aus) +
tm_dots() +
tm_text("name", just = "top")
# alternative
tm_shape(metro_aus) +
tm_markers(text = "name")
# }
# NOT RUN {
# restore current mode
tmap_mode(current.mode)
# }
Run the code above in your browser using DataLab