Draw polygons

Creates a tmap-element that draws the polygons. tm_fill fills the polygons. Either a fixed color is used, or a color palette is mapped to a data variable. tm_borders draws the borders of the polygons. tm_polygons fills the polygons and draws the polygon borders.

tm_fill(col = NA, alpha = NA, palette = NULL, convert2density = FALSE,
  area = NULL, n = 5, style = ifelse(is.null(breaks), "pretty", "fixed"),
  breaks = NULL, interval.closure = "left", labels = NULL,
  auto.palette.mapping = TRUE, contrast = NA, max.categories = 12,
  colorNA = NA, textNA = "Missing", showNA = NA, thres.poly = 0,
  title = NA, = TRUE, legend.format = list(), = TRUE, legend.hist = FALSE, legend.hist.title = NA,
  legend.z = NA, legend.hist.z = NA, id = NA, popup.vars = NA,
  popup.format = list(), ...)

tm_borders(col = NA, lwd = 1, lty = "solid", alpha = NA)

tm_polygons(col = NA, alpha = NA, border.col = NA, border.alpha = NA, ...)

For tm_fill, it is one of
  • a single color value
  • the name of a data variable that is contained in shp. Either the data variable contains color values, or values (numeric or categorical) that will be depicted by a color palette (see palette. In the latter case, a choropleth is drawn.
  • "MAP_COLORS". In this case polygons will be colored such that adjacent polygons do not get the same color. See the underlying function map_coloring for details.

For tm_borders, it is a single color value that specifies the border line color. If multiple values are specified, small multiples are drawn (see details).

transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the col is used (normally 1).
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.
boolean that determines whether col is converted to a density variable. Should be TRUE when col consists of absolute numbers. The area size is either approximated from the shape object, or given by the argument area.
Name of the data variable that contains the area sizes in squared kilometer.
preferred number of classes (in case col is a numeric variable).
method to process the color scale when col is a numeric variable. Discrete options are "cat", "fixed", "sd", "equal", "pretty", "quantile", "kmeans", "hclust", "bclust", "fisher", and "jenks". A numeric variable is processed as a categorial variable when using "cat", i.e. each unique value will correspond to a distinct category. For the other discrete options, see the details in classIntervals. Continuous options are "cont" and "order". The former maps the values of col to a smooth gradient, whereas the latter maps the order of values of col to a smooth gradient. They are the continuous variants of respectively the discrete methods "equal" and quantile".
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 divering color palette.
value that determines whether where the intervals are closed: "left" or "right". Only applicable if col is a numerc variable.
labels of the classes.
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 respectively positive values. When categorical color palettes are used, this method stretches the palette if there are more levels than colors.
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).
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 and auto.palette.mapping is FALSE, then levels are combined.
color used 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.
number that specifies the threshold at which polygons are taken into account. The number itself corresponds to the proportion of the area sizes of the polygons to the total polygon size. By default, all polygons are drawn. To ignore polygons that are not visible in a normal plot, a value like 1e-05 is recommended.
title of the legend element
logical that determines whether the legend 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 scientically? 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, is used. If scientific=TRUE then "g", which means that numbers are formatted scientically, 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.
Character string to use to separate numbers in the legend (default: "to").
Character string to use to translate "Less than" (which is the default).
Character string to use to translate "or more" (which is the default).
Other arguments passed on to formatC
logical that determines whether the legend is in portrait mode (TRUE) or landscape (FALSE)
logical that determines whether a histogram is shown
title for the histogram. By default, one title is used for both the histogram and the normal legend.
index value that determines the position of the legend element 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 histogram legend element
name of the data variable that specifies the indices of the polygons. Only used for "view" mode (see tmap_mode).
names of data variables that are shown in the popups in "view" mode. If convert2density=TRUE, the derived density variable name is suffixed with _density. If NA (default), only aesthetic variables (i.e. specified by col and lwd) are shown). If they are not specified, all variables are shown. Set popup.vars to FALSE to disable popups. When a vector of variable names is provided, the names (if specified) are printed in the popups.
list of formatting options for the popup values. See the argument legend.format for options. Only applicable for numeric data variables. If one list of formatting options is provided, it is applied to all numeric variables of popup.vars. Also, a (named) list of lists can be provided. In that case, each list of formatting options is applied to the named variable.
for tm_polygons, these arguments passed to either tm_fill or tm_borders. For tm_fill, these arguments are passed on to map_coloring.
border line width (see par)
border line type (see par)
border line color
transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the col is used (normally 1).

Small multiples can be drawn in two ways: either by specifying the by argument in tm_facets, or by defining multiple variables in the aesthetic arguments. The aesthetic argument of tm_fill (and tm_polygons) is col. In the latter case, the arguments, except for thres.poly, and the ones starting with legend., can be specified for small multiples as follows. If the argument normally only takes a single value, such as n, then a vector of those values can be specified, one for each small multiple. If the argument normally can take a vector, such as palette, then a list of those vectors (or values) can be specified, one for each small multiple.



See Also


  • tm_fill
  • tm_borders
  • tm_polygons
data(World, Europe)

# Constant fill
tm_shape(World) + tm_fill("darkolivegreen3") + tm_format_World(title="A green World")

# Borders only
tm_shape(Europe) + tm_borders()

# Data variable containing colours values
Europe$isNLD <- ifelse(Europe$name=="Netherlands", "darkorange", "darkolivegreen3")
tm_shape(Europe) +
    tm_fill("isNLD") +
tm_layout("Find the Netherlands!")

# Categorical data variable
if (require(RColorBrewer)) {
pal <- brewer.pal(10, "Set3")[c(10, 8, 4, 5)]
tm_shape(Europe) +
	tm_polygons("EU_Schengen", palette=pal, title = "European Countries", showNA=FALSE) +

tm_shape(World) +
	tm_polygons("economy", title="Economy", id="name") +
	tm_text("iso_a3", size="AREA", scale=1.5) +

# Numeric data variable
tm_shape(World) +
	tm_polygons("HPI", palette="RdYlGn", style="cont", n=8, auto.palette.mapping=FALSE,
		title="Happy Planet Index", id="name") +
	tm_text("iso_a3", size="AREA", scale=1.5) +
tm_format_World() + 

## Not run: ------------------------------------
# data(NLD_muni, NLD_prov)
# tm_shape(NLD_muni) +
# 	tm_fill(col="population", convert2density=TRUE, 
# 		style="kmeans", title = expression("Population (per " * km^2 * ")"), 
# 		legend.hist=TRUE, id="name") +
# 	tm_borders("grey25", alpha=.5) + 
# tm_shape(NLD_prov) +
# 	tm_borders("grey40", lwd=2) +
# tm_format_NLD_wide(bg.color="white", frame = FALSE,"grey90")
# # Map coloring algorithm
# tm_shape(NLD_prov) +
#     tm_fill("name", = FALSE) +
# tm_shape(NLD_muni) +
#     tm_polygons("MAP_COLORS", palette="Greys", alpha = .25) +
# tm_shape(NLD_prov) +
#     tm_borders(lwd=2) +
#     tm_text("name", shadow=TRUE) +
# tm_format_NLD(title="Dutch provinces and\nmunicipalities", bg.color="white")
# # Cartogram
# if (require(cartogram)) {
# 	NLD_prov_pop <- cartogram(NLD_prov, "population")
# 	tm_shape(NLD_prov_pop) +
# 		tm_polygons("origin_non_west", title = "Non-western origin (%)")
# }
## ---------------------------------------------

# TIP: check out these examples in view mode, enabled with tmap_mode("view")
Documentation reproduced from package tmap, version 1.10, License: GPL-3

Community examples

Looks like there are no examples yet.