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.
Usage
tm_fill(
col = NA,
alpha = NA,
palette = NULL,
convert2density = FALSE,
area = NULL,
n = 5,
style = ifelse(is.null(breaks), "pretty", "fixed"),
style.args = list(),
as.count = NA,
breaks = NULL,
interval.closure = "left",
labels = NULL,
drop.levels = FALSE,
midpoint = NULL,
stretch.palette = TRUE,
contrast = NA,
colorNA = NA,
textNA = "Missing",
showNA = NA,
colorNULL = NA,
thres.poly = 0,
title = NA,
legend.show = TRUE,
legend.format = list(),
legend.is.portrait = TRUE,
legend.reverse = FALSE,
legend.hist = FALSE,
legend.hist.title = NA,
legend.z = NA,
legend.hist.z = NA,
id = NA,
interactive = TRUE,
popup.vars = NA,
popup.format = list(),
zindex = NA,
group = NA,
auto.palette.mapping = NULL,
max.categories = NULL,
...
)
tm_borders(
col = NA,
lwd = 1,
lty = "solid",
alpha = NA,
zindex = NA,
group = NA
)
tm_polygons(
col = NA,
alpha = NA,
border.col = NA,
border.alpha = NA,
zindex = NA,
group = NA,
...
)
Arguments
- col
For
tm_fill
, it is one ofa 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 (seepalette
. 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 functionmap_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).- alpha
transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the
col
is used (normally 1).- palette
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 fromtm_layout
's argumentaes.palette
, which typically depends on the style. The type of palette fromaes.palette
is automatically determined, but can be overwritten: use"seq"
for sequential,"div"
for diverging, and"cat"
for categorical.- convert2density
boolean that determines whether
col
is converted to a density variable. Should beTRUE
whencol
consists of absolute numbers. The area size is either approximated from the shape object, or given by the argumentarea
.- area
Name of the data variable that contains the area sizes in squared kilometer.
- n
preferred number of classes (in case
col
is a numeric variable).- style
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 inclassIntervals
(extra arguments can be passed on viastyle.args
). Continuous gradient options are"cont"
,"order"
, and"log10"
. The first maps the values ofcol
to a smooth gradient, the second maps the order of values ofcol
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. Seeas.count
.- style.args
arguments passed on to
classIntervals
, the function that determine color classes (see alsostyle
).- as.count
when
col
is a numeric variable, should it be processed as a count variable? For instance, ifstyle = "pretty"
,n = 2
, and the value range of the variable is 0 to 10, then the column classes foras.count = TRUE
are 0; 1 to 5; 6 to 10 (note that 0 is regarded as an own category) whereas foras.count = FALSE
they are 0 to 5; 5 to 10. Only applicable ifstyle
is"pretty"
,"fixed"
, or"log10_pretty"
. By default,TRUE
ifstyle
is one of these, and the variable is an integer.- breaks
in case
style=="fixed"
, breaks should be specified. Thebreaks
argument can also be used whenstyle="cont"
. In that case, the breaks are mapped evenly to the sequential or diverging color palette.- interval.closure
value that determines whether where the intervals are closed:
"left"
or"right"
. Only applicable ifcol
is a numeric variable. Ifas.count = TRUE
,inverval.closure
is always set to"left"
.- labels
labels of the classes.
- drop.levels
should unused classes be omitted?
FALSE
by default.- midpoint
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 (seestyle
) is mapped to the middle color. Only applies whencol
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.- stretch.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). IfFALSE
, the palette is repeated.- 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 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).- colorNA
color used for missing values. Use
NULL
for transparency.- textNA
text used for missing values.
- showNA
logical that determines whether missing values are named in the legend. By default (
NA
), this depends on the presence of missing values.- colorNULL
colour for polygons that are shown on the map that are out of scope
- thres.poly
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
title of the legend element
- legend.show
logical that determines whether the legend is shown
- legend.format
list of formatting options for the legend numbers. Only applicable if
labels
is undefined. Parameters are:- fun
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
, anddigits
(see below) are not used.- scientific
Should the labels be formatted scientifically? If so, square brackets are used, and the
format
of the numbers is"g"
. Otherwise,format="f"
, andtext.separator
,text.less.than
, andtext.or.more
are used. Also, the numbers are automatically rounded to millions or billions if applicable.- format
By default,
"f"
, i.e. the standard notationxxx.xxx
, is used. Ifscientific=TRUE
then"g"
, which means that numbers are formatted scientifically, i.e.n.dddE+nn
if needed to save space.- digits
Number of digits after the decimal point if
format="f"
, and the number of significant digits otherwise.- big.num.abbr
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 isc("mln" = 6, "bln" = 9)
. For layers wherestyle
is set tolog10
orlog10_pretty
, the default isNA
.- prefix
Prefix of each number
- suffix
Suffix of each number
- text.separator
Character string to use to separate numbers in the legend (default: "to").
- text.less.than
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
- text.or.more
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
- text.align
Value that determines how the numbers are aligned,
"left"
,"center"
or"right"
. By default"left"
for legends in portrait format (legend.is.protrait = TRUE
), and"center"
otherwise.- text.to.columns
Logical that determines whether the text is aligned to three columns (from, text.separator, to). By default
FALSE
.- html.escape
Logical that determins whther HTML code is escaped in the popups in view mode. By default
TRUE
. If set toFALSE
HTML code can be added, e.g. to added white space via
.- ...
Other arguments passed on to
formatC
- legend.is.portrait
logical that determines whether the legend is in portrait mode (
TRUE
) or landscape (FALSE
)- legend.reverse
logical that determines whether the items are shown in reverse order, i.e. from bottom to top when
legend.is.portrait = TRUE
and from right to left whenlegend.is.portrait = FALSE
- legend.hist
logical that determines whether a histogram is shown
- legend.hist.title
title for the histogram. By default, one title is used for both the histogram and the normal legend.
- legend.z
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.
- legend.hist.z
index value that determines the position of the histogram legend element
- id
name of the data variable that specifies the indices of the polygons. Only used for
"view"
mode (seetmap_mode
).- interactive
logical that determines whether this layer is interactive in view mode (e.g. hover text, popup, and click event in shiny apps)
- popup.vars
names of data variables that are shown in the popups in
"view"
mode. Ifconvert2density=TRUE
, the derived density variable name is suffixed with_density
. IfNA
(default), only aesthetic variables (i.e. specified bycol
andlwd
) are shown). If they are not specified, all variables are shown. Set popup.vars toFALSE
to disable popups. When a vector of variable names is provided, the names (if specified) are printed in the popups.- popup.format
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 ofpopup.vars
. Also, a (named) list of lists can be provided. In that case, each list of formatting options is applied to the named variable.- zindex
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, ifzindex
is set to 500, the pane will be named"tmap500"
.- 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. 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 intm_shape
).- auto.palette.mapping
deprecated. It has been replaced by
midpoint
for numeric variables andstretch.palette
for categorical variables.- max.categories
deprecated. It has moved to
tmap_options
.- ...
for
tm_polygons
, these arguments passed to eithertm_fill
ortm_borders
. Fortm_fill
, these arguments are passed on tomap_coloring
.- lwd
border line width (see
par
)- lty
border line type (see
par
)- border.col
border line color
- border.alpha
transparency number between 0 (totally transparent) and 1 (not transparent). By default, the alpha value of the
col
is used (normally 1).
Details
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.
References
Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, doi:10.18637/jss.v084.i06
Examples
data(World)
# Constant fill
tm_shape(World) + tm_fill("darkolivegreen3") + tm_format("World", title="A green World")
# Borders only
tm_shape(World) + tm_borders()
# Data variable containing colours values
World$isNLD <- ifelse(World$name=="Netherlands", "darkorange", "darkolivegreen3")
tm_shape(World) +
tm_fill("isNLD") +
tm_layout("Find the Netherlands!")
tm_shape(World, projection = "+proj=eck4") +
tm_polygons("economy", title="Economy", id="name") +
tm_text("iso_a3", size="AREA", scale=1.5) +
tm_format("World")
# Numeric data variable
tm_shape(World, projection = "+proj=eck4") +
tm_polygons("HPI", palette="RdYlGn", style="cont", n=8,
title="Happy Planet Index", id="name") +
tm_text("iso_a3", size="AREA", scale=1.5) +
tm_style("grey") +
tm_format("World")
if (FALSE) {
data(NLD_prov, NLD_muni)
# Map coloring algorithm
tm_shape(NLD_prov) +
tm_fill("name", legend.show = 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")