tm_fill: Draw polygons

Description

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. By default, a divering color palette is used for numeric variables and a qualitative palette for categorical variables. 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"),
  breaks = NULL, labels = NULL, auto.palette.mapping = TRUE,
  contrast = 1, max.categories = 12, colorNA = NA, textNA = "Missing",
  thres.poly = 1e-05, title = NA, legend.show = TRUE,
  legend.format = list(), legend.is.portrait = TRUE, legend.hist = FALSE,
  legend.hist.title = NA, legend.z = NA, legend.hist.z = NA, id = NA,
  ...)

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

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

Arguments

col

For tm_fill, it is one of

a single color value
the name of a data variable that is contained inshp. Either the data variable contains color values, or values (numeric or categorical) that will be depicted by a co

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 RColorBrewer::display.brewer.all() for the named palette. Use a "-" as prefix to reverse the palette. The default palette is taken from tm_layout

convert2density

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).

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.

labels

labels of the classes.

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

color used for missing values

textNA

text used for missing values. Use NA to omit text for missing values in the legend

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.

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: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

legend.is.portrait

logical that determines whether the legend is in portrait mode (TRUE) or landscape (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

name of the data variable that specifies the indices of the polygons. Only used for SVG output (see itmap).

...

for tm_polygons, these arguments passed to either tm_fill or tm_borders. For tm_fill, these arguments are passed on to map_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).

Value

tmap-element

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.

Examples

Run this code

data(World, Europe, NLD_muni, NLD_prov)

# 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!")

# Numeric data variable
tm_shape(NLD_muni) +
    tm_fill(col="population", convert2density=TRUE, 
        style="kmeans", title="Population (per km2)", legend.hist=TRUE) +
    tm_borders("grey25", alpha=.5) + 
tm_shape(NLD_prov) +
    tm_borders("grey40", lwd=2) +
tm_format_NLD_wide(bg.color="white", frame = FALSE, legend.hist.bg.color="grey90")

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

# Categorical data variable
tm_shape(World) +
    tm_polygons("economy", title="Economy") +
    tm_text("iso_a3", size="AREA", scale=1.5) +
tm_format_World()

# 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")