Package 'tmap'

Description

Thematic maps are geographical maps in which spatial data distributions are visualized. This package offers a flexible, layer-based, and easy to use approach to create thematic maps, such as choropleths and bubble maps. It is based on the grammar of graphics, and resembles the syntax of ggplot2.

Details

This page provides a brief overview of all package functions. See vignette("tmap_sneak_peek") for a short introduction with examples.

Quick plotting method

Main plotting method

Shape specification:

Aesthetics base layers:

Aesthetics derived layers:

Faceting (small multiples)

Attributes:

Layout element:

Change options:

Create icons:

Output functions

Spatial datasets

Author(s)

Martijn Tennekes [email protected]

References

Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, doi:10.18637/jss.v084.i06

See Also

vignette("tmap_sneak_peek"), https://r-tmap.github.io/tmap/

Description

Spatial data of global land cover, percent tree cover, and elevation of class stars. Two attributes in this object relates to global land cover. The cover layer classifies the status of land cover of the whole globe into 20 categories, while the cover_cls layer uses 8 simplified categories. Percent Tree Cover (trees) represents the density of trees on the ground, and the last attribute represents elevation.

Usage

land

Format

An object of class stars with 1080 rows and 540 columns.

Details

Important: publication of these maps is only allowed when cited to Tateishi et al. (2014), and when "Geospatial Information Authority of Japan, Chiba University and collaborating organizations." is shown.

References

Production of Global Land Cover Data - GLCNMO2008, Tateishi, R., Thanh Hoan, N., Kobayashi, T., Alsaaideh, B., Tana, G., Xuan Phong, D. (2014), Journal of Geography and Geology, 6 (3).

Description

metro includes a population time series from 1950 to (forecasted) 2030. All metro areas with over 1 million inhabitants in 2010 are included.

Usage

metro

Format

An object of class sf (inherits from data.frame) with 436 rows and 13 columns.

Source

https://population.un.org/wup/

References

United Nations, Department of Economic and Social Affairs, Population Division (2014). World Urbanization Prospects: The 2014 Revision, CD-ROM Edition.

Description

The family of ⁠opt_*()⁠ functions can be used to specify options in the different ⁠tm_*()⁠ functions.

Usage

opt_tm_cartogram(type = "cont", itermax = 15, ...)

opt_tm_cartogram_ncont(type = "ncont", expansion = 1, inplace = FALSE, ...)

opt_tm_cartogram_dorling(type = "dorling", share = 5, itermax = 1000, ...)

opt_tm_lines(lines.only = "ifany")

opt_tm_polygons(polygons.only = "ifany")

opt_tm_rgb(interpolate = FALSE)

opt_tm_sf(
  polygons.only = "yes",
  lines.only = "yes",
  points.only = "yes",
  point.per = "feature",
  points.icon.scale = 3,
  points.just = NA,
  points.grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)
)

opt_tm_symbols(
  points.only = "ifany",
  point.per = "feature",
  icon.scale = 3,
  just = NA,
  grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)
)

opt_tm_dots(
  points.only = "ifany",
  point.per = "feature",
  icon.scale = 3,
  just = NA,
  grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)
)

opt_tm_markers(
  markers.on.top.of.text = FALSE,
  points.only = "ifany",
  point.per = "feature",
  shadow = FALSE,
  shadow.offset.x = 0.1,
  shadow.offset.y = 0.1,
  just = "center",
  along.lines = TRUE,
  bg.padding = 0.4,
  clustering = TRUE,
  point.label = TRUE,
  point.label.gap = 0.4,
  point.label.method = "SANN",
  remove.overlap = FALSE,
  dots.just = NA,
  dots.icon.scale = 3,
  dots.grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)
)

opt_tm_bubbles(
  points.only = "ifany",
  point.per = "feature",
  icon.scale = 3,
  just = NA,
  grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)
)

opt_tm_squares(
  points.only = "ifany",
  point.per = "feature",
  icon.scale = 3,
  just = NA,
  grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)
)

opt_tm_text(
  points.only = "ifany",
  point.per = "feature",
  shadow = FALSE,
  shadow.offset.x = 0.1,
  shadow.offset.y = 0.1,
  just = "center",
  along.lines = FALSE,
  bg.padding = 0.4,
  clustering = FALSE,
  point.label = FALSE,
  point.label.gap = 0,
  point.label.method = "SANN",
  remove.overlap = FALSE
)

opt_tm_labels(
  points.only = "ifany",
  point.per = "feature",
  shadow = FALSE,
  shadow.offset.x = 0.1,
  shadow.offset.y = 0.1,
  just = "center",
  along.lines = TRUE,
  bg.padding = 0.4,
  clustering = TRUE,
  point.label = TRUE,
  point.label.gap = 0.4,
  point.label.method = "SANN",
  remove.overlap = FALSE
)

Arguments

Examples

tm_shape(World) +
  tm_polygons(
   
   )

Description

Draw thematic map

Usage

## S3 method for class 'tmap'
print(
  x,
  return.asp = FALSE,
  show = TRUE,
  vp = NULL,
  knit = FALSE,
  options = NULL,
  in.shiny = FALSE,
  proxy = FALSE,
  ...
)

## S3 method for class 'tmap'
knit_print(x, ..., options = NULL)

Arguments

Description

Draw a thematic map quickly. This function is a convenient wrapper of the main plotting method of stacking tmap-elements. Without arguments or with a search term, this functions draws an interactive map.

Usage

qtm(
  shp,
  fill = tm_const(),
  col = tm_const(),
  size = tm_const(),
  shape = tm_const(),
  lwd = tm_const(),
  lty = tm_const(),
  fill_alpha = tm_const(),
  col_alpha = tm_const(),
  text = tm_const(),
  text_col = tm_const(),
  text_size = tm_const(),
  by = NULL,
  scale = NULL,
  title = NULL,
  crs = NULL,
  bbox = NULL,
  basemaps = NULL,
  overlays = NULL,
  zindex = NA,
  group = NA,
  group.control = "check",
  style = NULL,
  format = NULL,
  ...
)

Arguments

Details

The first argument is a shape object (normally specified by tm_shape()). The next arguments, from fill to raster, are the aesthetics from the main layers. The remaining arguments are related to the map layout. Any argument from any main layer function, such as tm_polygons(), can be specified (see ...). It is also possible to stack tmap-elements on a qtm plot. See examples.

By default, a scale bar is shown. This option can be set with tmap_options() (argument qtm.scalebar). A minimap is shown by default when qtm is called without arguments of with a search term. This option can be set with tmap_options() (argument qtm.minimap).

Value

A tmap-element

References

Tennekes, M., 2018, tmap: Thematic Maps in R, Journal of Statistical Software, 84(6), 1-39, doi:10.18637/jss.v084.i06

See Also

vignette("tmap_sneak_peek")

Examples

data(World, rivers, metro)

# just the map
qtm(World)

# choropleth
qtm(World, fill = "economy", format = "World", style = "col_blind", projection = "+proj=eck4")

# choropleth with more specifications
qtm(World, fill="HPI", fill.n = 9, fill.palette = "div",
    fill.title = "Happy Planet Index", fill.id = "name", 
    style = "gray", format = "World", projection = "+proj=eck4")
# this map can also be created with the main plotting method,
# which is recommended in this case.
## Not run: 
tm_shape(World, projection = "+proj=eck4") +
    tm_polygons("HPI", n = 9, palette = "div",
        title = "Happy Planet Index", id = "name") +
tm_style("gray") +
tm_format("World")

## End(Not run)

# bubble map
## Not run: 
qtm(World, borders = NULL) + 
qtm(metro, symbols.size = "pop2010", 
    symbols.title.size= "Metropolitan Areas", 
    symbols.id= "name",
    format = "World")

## End(Not run)

# dot map
## Not run: 
current.mode <- tmap_mode("view")
qtm(metro, bbox = "China")
tmap_mode(current.mode) # restore mode

## End(Not run)

## Not run: 
# without arguments, a plain interactive map is shown (the mode is set to view)
qtm()

# search query for OpenStreetMap nominatim
qtm("Amsterdam")

## End(Not run)

Description

Use tmapOutput to create a UI element, and renderTmap to render the tmap map. To update the map in view mode, use tmapProxy. Adding layers is as usual via the map layer functions like tm_polygons. Removing layers can be done , removing with the function tm_remove_layer.

Usage

renderTmap(
  expr,
  env = parent.frame(),
  quoted = FALSE,
  execOnResize = TRUE,
  mode = NA
)

tmapOutput(outputId, width = "100%", height = 400, mode = NA)

tmapProxy(mapId, session = shiny::getDefaultReactiveDomain(), x, mode = NA)

tm_remove_layer(zindex)

Arguments

Details

Two features from tmap are not (yet) supported in Shiny: small multiples (facets) and colored backgrounds (argument bg.color of tm_layout). Workarounds for small multiples: create multiple independent maps or specify as.layers = TRUE in tm_facets.

Examples

if (interactive() && require("shiny")) {
	
	data(World)
	world_vars <- setdiff(names(World), c("iso_a3", "name", "sovereignt", "geometry"))
	
	tmap_mode("plot")

	shinyApp(
		ui = fluidPage(
			tmapOutput("map", height = "600px"),
			selectInput("var", "Variable", world_vars)
		),
		server <- function(input, output, session) {
			output$map <- renderTmap({
				tm_shape(World) +
					tm_polygons(input$var, zindex = 401)
			})
		}
	)
	
	tmap_mode("view")

	shinyApp(
		ui = fluidPage(
			tmapOutput("map", height = "600px"),
			selectInput("var", "Variable", world_vars)
		),
		server <- function(input, output, session) {
			output$map <- renderTmap({
				tm_shape(World, id = "iso_a3") +
					tm_polygons(world_vars[1], zindex = 401)
			})
			observe({
				var <- input$var
				tmapProxy("map", session, {
					tm_remove_layer(401) +
						tm_shape(World, id = "iso_a3") +
						tm_polygons(var, zindex = 401)
				})
			})
		},options = list(launch.browser=TRUE)
	)
}

Description

Spatial data of rivers

Usage

rivers

Format

An object of class sf (inherits from data.frame) with 1616 rows and 5 columns.

Source

https://www.naturalearthdata.com

Description

ggplot2 theme for proportional symbols. By default, this theme only shows the plotting area, so without titles, axes, and legend.

Usage

theme_ps(
  base_size = 12,
  base_family = "",
  plot.axes = FALSE,
  plot.legend = FALSE
)

Arguments

Description

Map component that adds a manual legend

Usage

tm_add_legend(
  ...,
  labels,
  type = "symbols",
  title = "",
  design = NULL,
  orientation = NULL,
  group = NA,
  group.control = "check",
  resize.as.group = FALSE,
  z = as.integer(NA)
)

Arguments

Description

Map layer that draws tiles from a tile server. tm_basemap() draws the tile layer as basemap, i.e. as bottom layer. In contrast, tm_tiles() draws the tile layer as overlay layer, where the stacking order corresponds with the order in which this layer is called, just like other map layers.

Usage

tm_basemap(
  server = NULL,
  alpha = NULL,
  zoom = NULL,
  max.native.zoom = 17,
  zindex = 0,
  group = NA,
  group.control = "radio"
)

tm_tiles(
  server = NULL,
  alpha = NULL,
  zoom = NULL,
  max.native.zoom = 1,
  zindex = NA,
  group = NA,
  group.control = "check"
)

Arguments

Examples

if (requireNamespace("maptiles")) {
	tm_basemap() +
		tm_shape(World) +
		tm_polygons("HPI")
	
	tm_basemap("OpenTopoMap") +
		tm_shape(World) + 
		tm_polygons(fill = NA, col = "black")
	
	## Not run: 
	tm_basemap("CartoDB.PositronNoLabels") +
	tm_shape(NLD_prov, crs = 4236) +
		tm_borders() +
		tm_facets_wrap("name") +
		tm_tiles("CartoDB.PositronOnlyLabels")
	
## End(Not run)
}

Description

Map layer that draws a cartogram

Usage

tm_cartogram(
  size = 1,
  size.scale = tm_scale(),
  size.legend = tm_legend_hide(),
  size.chart = tm_chart_none(),
  size.free = NA,
  plot.order = tm_plot_order("size", reverse = FALSE),
  options = opt_tm_cartogram(),
  ...
)

tm_cartogram_ncont(
  size = 1,
  size.scale = tm_scale(),
  size.legend = tm_legend_hide(),
  size.chart = tm_chart_none(),
  size.free = NA,
  plot.order = tm_plot_order("size", reverse = FALSE),
  options = opt_tm_cartogram_ncont(),
  ...
)

tm_cartogram_dorling(
  size = 1,
  size.scale = tm_scale(),
  size.legend = tm_legend_hide(),
  size.chart = tm_chart_none(),
  size.free = NA,
  plot.order = tm_plot_order("size", reverse = FALSE),
  options = opt_tm_cartogram_dorling(),
  ...
)

Arguments

Description

Legend charts are small charts that are added to the map, usually in addition to legends.

Usage

tm_chart_histogram(
  breaks,
  plot.axis.x,
  plot.axis.y,
  extra.ggplot2,
  position,
  width,
  height,
  stack,
  z,
  group.frame,
  resize.as.group
)

tm_chart_bar(
  plot.axis.x,
  plot.axis.y,
  extra.ggplot2,
  position,
  width,
  height,
  stack,
  z,
  group.frame,
  resize.as.group
)

tm_chart_donut(position, width, height, stack, z, group.frame, resize.as.group)

tm_chart_violin(
  position,
  width,
  height,
  stack,
  z,
  group.frame,
  resize.as.group
)

tm_chart_box(position, width, height, stack, z, group.frame, resize.as.group)

tm_chart_none()

tm_chart_heatmap(
  position,
  width,
  height,
  stack,
  z,
  group.frame,
  resize.as.group
)

Arguments

Details

Note that these charts are different from charts drawn inside the map. Those are called glyphs (to be implemented).

Examples

## numerical variable

tm_shape(World) + 
  tm_polygons("HPI", 
    fill.scale = tm_scale_intervals(), 
    fill.chart = tm_chart_histogram())

tm_shape(World) + 
	tm_polygons("HPI", 
				fill.scale = tm_scale_continuous(), 
				fill.chart = tm_chart_histogram(
					position = tm_pos_out("center", "bottom"),
					width = 30)
				)

tm_shape(World) + 
	tm_polygons("HPI", 
				fill.scale = tm_scale_intervals(), 
				fill.chart = tm_chart_donut())

tm_shape(World) + 
	tm_polygons("HPI", 
				fill.scale = tm_scale_intervals(), 
				fill.chart = tm_chart_box())

tm_shape(World) + 
	tm_polygons("HPI", 
				fill.scale = tm_scale_intervals(), 
				fill.chart = tm_chart_violin())

# with additional ggplot2 code
require(ggplot2)
tm_shape(World) + 
	tm_polygons("HPI", 
				fill.scale = tm_scale_intervals(), 
				fill.chart = tm_chart_bar(
					extra.ggplot2 = theme(
						panel.grid.major.y = element_line(colour = "red")
					))
				)

tm_shape(land) +
	tm_raster("trees",
			  col.chart = tm_chart_histogram())

## categorical variable
tm_shape(World) + 
	tm_polygons("economy", 
				fill.scale = tm_scale_categorical(), 
				fill.chart = tm_chart_bar())

tm_shape(World) + 
	tm_polygons("economy", 
				fill.scale = tm_scale_categorical(), 
				fill.chart = tm_chart_donut())

tm_shape(World) +
	tm_polygons(tm_vars(c("HPI", "well_being"), multivariate = TRUE),
				fill.chart = tm_chart_heatmap())

Description

Map component that adds a compass

Usage

tm_compass(
  north,
  type,
  text.size,
  size,
  show.labels,
  cardinal.directions,
  text.color,
  color.dark,
  color.light,
  lwd,
  position,
  bg.color,
  bg.alpha,
  stack,
  just,
  frame,
  frame.lwd,
  frame.r,
  margins,
  z
)

Arguments

Description

tmap function to define a constant visual value

Usage

tm_const()

Description

Map component that adds a text, typically used as credits

Usage

tm_credits(
  text,
  size,
  color,
  padding,
  fontface,
  fontfamily,
  stack,
  just,
  frame,
  frame.lwd,
  frame.r,
  bg.color,
  bg.alpha,
  position,
  width,
  height,
  group.frame,
  resize.as.group,
  z
)

Arguments

Description

• tm_facets_wrap() specify facets for one grouping variable (so one faceting dimension).

• ⁠tm_facets_(hv)stack()⁠ stacks the facets either horizontally or vertically (one grouping variable).

• tm_facets_grid() supports up to three faceting dimensions.

• tm_facets_pagewise() can be used to replace the old along argument.

• tm_facets_flip() can be used to flip facets.

• tm_facets() is the core function, but it is recommended to use the other functions.

Usage

tm_facets(
  by = NULL,
  rows = NULL,
  columns = NULL,
  pages = NULL,
  as.layers = FALSE,
  nrows = NA,
  ncols = NA,
  byrow = TRUE,
  orientation = NA,
  free.coords = NA,
  drop.units = TRUE,
  drop.empty.facets = TRUE,
  drop.NA.facets = FALSE,
  sync = TRUE,
  na.text = NA,
  scale.factor = 2,
  type = NA,
  along = NULL,
  free.scales = NULL,
  ...
)

tm_facets_grid(rows = NULL, columns = NULL, pages = NULL, ...)

tm_facets_wrap(by = "VARS__", nrows = NA, ncols = NA, byrow = TRUE, ...)

tm_facets_pagewise(by = "VARS__", nrows = 1, ncols = 1, byrow = TRUE, ...)

tm_facets_stack(by = "VARS__", orientation = NA, ...)

tm_facets_hstack(by = "VARS__", ...)

tm_facets_vstack(by = "VARS__", ...)

tm_facets_flip(...)

Arguments

Description

Draw latitude and longitude graticules. It creates a tmap-element that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. See tm_grid() for drawing horizontal lines.

Usage

tm_graticules(
  x = NA,
  y = NA,
  n.x = NA,
  n.y = NA,
  crs = 4326,
  labels.format = list(suffix = intToUtf8(176)),
  labels.cardinal = TRUE,
  ...
)

Arguments

Examples

current.mode <- tmap_mode("plot")

tm_shape(NLD_muni) + 
	tm_polygons() +
	tm_grid()

tm_shape(NLD_muni) + 
	tm_polygons() +
	tm_grid(crs = 4326)

tm_shape(NLD_muni) + 
	tm_polygons() +
	tm_grid(crs = 3035, labels.inside.frame = TRUE)

tm_shape(World) +
	tm_polygons() +
	tm_facets(by = "continent") +
	tm_grid(labels.inside.frame = TRUE)

tm_shape(NLD_muni) +
	tm_polygons() +
	tm_graticules()

tm_shape(NLD_muni) +
	tm_polygons() +
	tm_graticules(labels.pos = c("right", "top"))


data(NLD_muni, World)

tmap_arrange(
	qtm(NLD_muni, borders = NULL) + tm_grid(),
	qtm(NLD_muni, borders = NULL) + tm_graticules()
)

qtm(World, shape.crs = "+proj=robin", style = "natural") +
	tm_graticules(ticks = FALSE) +
	tm_layout(frame=FALSE)

tmap_mode(current.mode)

Description

• tm_grid() draws horizontal and vertical lines according to the coordinate system of the (master) shape object.

Creates a tmap-element that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers. See tm_graticules() to draw latitude and longitude graticules.

Usage

tm_grid(
  x = NA,
  y = NA,
  n.x = NA,
  n.y = NA,
  crs = NA,
  col = NA,
  lwd = 1,
  alpha = NA,
  labels.show = TRUE,
  labels.pos = c("left", "bottom"),
  labels.size = 0.6,
  labels.col = NA,
  labels.rot = c(0, 0),
  labels.format = list(big.mark = ","),
  labels.cardinal = FALSE,
  labels.margin.x = 0,
  labels.margin.y = 0,
  labels.space.x = NA,
  labels.space.y = NA,
  labels.inside.frame = FALSE,
  ticks = labels.show & !labels.inside.frame,
  lines = TRUE,
  ndiscr = 100,
  zindex = NA,
  group = NA,
  group.control = "none",
  ...
)

Arguments

Examples

current.mode <- tmap_mode("plot")

tm_shape(NLD_muni) + 
	tm_polygons() +
	tm_grid()

tm_shape(NLD_muni) + 
	tm_polygons() +
	tm_grid(crs = 4326)

tm_shape(NLD_muni) + 
	tm_polygons() +
	tm_grid(crs = 3035, labels.inside.frame = TRUE)

tm_shape(World) +
	tm_polygons() +
	tm_facets(by = "continent") +
	tm_grid(labels.inside.frame = TRUE)

tm_shape(NLD_muni) +
	tm_polygons() +
	tm_graticules()

tm_shape(NLD_muni) +
	tm_polygons() +
	tm_graticules(labels.pos = c("right", "top"))


data(NLD_muni, World)

tmap_arrange(
	qtm(NLD_muni, borders = NULL) + tm_grid(),
	qtm(NLD_muni, borders = NULL) + tm_graticules()
)

qtm(World, shape.crs = "+proj=robin", style = "natural") +
	tm_graticules(ticks = FALSE) +
	tm_layout(frame=FALSE)

tmap_mode(current.mode)

Description

Map layer that draws iso (contour) lines. Stack of tm_lines() and tm_labels_highlighted.

Usage

tm_iso(
  col,
  text,
  ...,
  options_lines = opt_tm_lines(),
  options_labels = opt_tm_labels()
)

Arguments

Description

Legend specification

Usage

tm_legend(
  title,
  show,
  orientation,
  design,
  reverse,
  na.show,
  position,
  width,
  height,
  stack,
  z,
  group.frame,
  resize.as.group,
  title.color,
  title.size,
  title.fontface,
  title.fontfamily,
  title.padding,
  text.color,
  text.size,
  text.fontface,
  text.fontfamily,
  format,
  frame,
  frame.lwd,
  frame.r,
  bg.color,
  bg.alpha,
  item.height,
  item.width,
  item.space,
  item.na.height,
  item.na.width,
  item.na.space,
  item.shape,
  ticks,
  ticks.disable.na,
  ticks.col,
  ticks.lwd,
  title.align,
  margins,
  margin.item.text,
  ...
)

tm_legend_hide()

tm_legend_combine(variable)

Arguments

Value

OUTPUT_DESCRIPTION

Description

Map layer that draws lines. Supported visual variables are: col (the color), lwd (line width), lty (line type), and col_alpha (color alpha transparency).

Usage

tm_lines(
  col = tm_const(),
  col.scale = tm_scale(),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  lwd = tm_const(),
  lwd.scale = tm_scale(),
  lwd.legend = tm_legend(),
  lwd.chart = tm_chart_none(),
  lwd.free = NA,
  lty = tm_const(),
  lty.scale = tm_scale(),
  lty.legend = tm_legend(),
  lty.chart = tm_chart_none(),
  lty.free = NA,
  col_alpha = tm_const(),
  col_alpha.scale = tm_scale(),
  col_alpha.legend = tm_legend(),
  col_alpha.chart = tm_chart_none(),
  col_alpha.free = NA,
  linejoin = "round",
  lineend = "round",
  plot.order = tm_plot_order("lwd", reverse = TRUE, na.order = "bottom"),
  zindex = NA,
  group = NA,
  group.control = "check",
  popup.vars = NA,
  popup.format = list(),
  hover = NA,
  id = "",
  options = opt_tm_lines(),
  ...
)

Arguments

Details

The visual variable arguments (e.g. col) can be specified with either a data variable name (e.g., a spatial vector attribute or a raster layer of the object specified in tm_shape()), or with a visual value (for col, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with tm_facets().

• The ⁠*.scale⁠ arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available ⁠tm_scale_*()⁠ functions. The default is specified by the tmap option (tm_options()) scales.var.

• The ⁠*.legend⁠ arguments determine the used legend, specified with tm_legend(). The default legend and its settings are determined by the tmap options (tm_options()) legend. .

• The ⁠*.chart⁠ arguments specify additional charts, specified with tm_chart_, e.g. tm_chart_histogram()

• The ⁠*.free⁠ arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see tm_facets()). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (tm_facets_grid()). For instance, col.free = c(TRUE, FALSE, FALSE) means that for the visual variable col, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (tm_facets_wrap() and tm_facets_stack()) there is only one facet dimension, so the ⁠*.free⁠ argument requires only one logical value.

Examples

tm_shape(rivers) +
	tm_lines(lwd = "strokelwd",
			 lwd.scale = tm_scale_asis(values.scale = 0.2, value.neutral = 2),
			 col = "scalerank",
			 col.scale = tm_scale_categorical(values = "seaborn.dark"))

tm_shape(World) +
	tm_lines(col = "continent",
			 col.scale = tm_scale_categorical(values = "seaborn.dark"),
			 lty = "continent",
			 lwd = 1.5,
			 lty.legend = tm_legend_combine("col"))

Description

Map component that adds a scale bar. As of version 4.0, tm_scalebar() is used instead of tm_scale_bar() (now deprecated), because of the potential confusion with the ⁠tm_scale_*()⁠ scaling functions (like tm_scale_continuous()).

Usage

tm_logo(
  file,
  height,
  margins,
  between.margin,
  stack,
  position,
  frame,
  frame.lwd,
  frame.r,
  group.frame,
  resize.as.group,
  z
)

Arguments

Examples

data(World)

tm_shape(World) +
	tm_polygons("HPI", fill.scale = tm_scale_intervals(values = "RdYlGn")) +
	tm_logo(c("https://www.r-project.org/logo/Rlogo.png", 
			  system.file("img/tmap.png", package="tmap"))) +
	tm_logo("http://blog.kulikulifoods.com/wp-content/uploads/2014/10/logo.png", 
			height=5, position = c("left", "top")) +
	tm_format("World")

Description

Map component that adds a minimap in view mode

Usage

tm_minimap(server, toggle, stack, position, z, ...)

Arguments

See Also

addMiniMap

Description

Map component that adds mouse coordinates

Usage

tm_mouse_coordinates(stack, position, z)

Arguments

Description

tmap layout: helper functions

Usage

tm_place_legends_right(width = NA)

tm_place_legends_left(width = NA)

tm_place_legends_bottom(height = NA)

tm_place_legends_top(height = NA)

tm_place_legends_inside(pos.h = NULL, pos.v = NULL)

tm_extra_innner_margin(left = 0, right = 0, top = 0, bottom = 0)

Arguments

Description

Plot mode options. This option is specific to the plot mode.

Usage

tm_plot(use.gradient)

Arguments

Description

Determine plotting order of features.

Usage

tm_plot_order(
  aes,
  reverse = TRUE,
  na.order = c("mix", "bottom", "top"),
  null.order = c("bottom", "mix", "top"),
  null.below.na = TRUE
)

Arguments

Description

Map layer that draws polygons. Supported visual variables are: fill (the fill color), col (the border color), lwd (line width), lty (line type), fill_alpha (fill color alpha transparency) and col_alpha (border color alpha transparency).

Usage

tm_polygons(
  fill = tm_const(),
  fill.scale = tm_scale(),
  fill.legend = tm_legend(),
  fill.chart = tm_chart_none(),
  fill.free = NA,
  col = tm_const(),
  col.scale = tm_scale(),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  lwd = tm_const(),
  lwd.scale = tm_scale(),
  lwd.legend = tm_legend(),
  lwd.chart = tm_chart_none(),
  lwd.free = NA,
  lty = tm_const(),
  lty.scale = tm_scale(),
  lty.legend = tm_legend(),
  lty.chart = tm_chart_none(),
  lty.free = NA,
  fill_alpha = tm_const(),
  fill_alpha.scale = tm_scale(),
  fill_alpha.legend = tm_legend(),
  fill_alpha.chart = tm_chart_none(),
  fill_alpha.free = NA,
  col_alpha = tm_const(),
  col_alpha.scale = tm_scale(),
  col_alpha.legend = tm_legend(),
  col_alpha.chart = tm_chart_none(),
  col_alpha.free = NA,
  linejoin = "round",
  lineend = "round",
  plot.order = tm_plot_order("lwd", reverse = TRUE, na.order = "bottom"),
  zindex = NA,
  group = NA,
  group.control = "check",
  popup.vars = NA,
  popup.format = list(),
  hover = NA,
  id = "",
  options = opt_tm_polygons(),
  ...
)

tm_fill(...)

tm_borders(col = tm_const(), ...)

Arguments

Details

The visual variable arguments (e.g. col) can be specified with either a data variable name (e.g., a spatial vector attribute or a raster layer of the object specified in tm_shape()), or with a visual value (for col, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with tm_facets().

• The ⁠*.scale⁠ arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available ⁠tm_scale_*()⁠ functions. The default is specified by the tmap option (tm_options()) scales.var.

• The ⁠*.legend⁠ arguments determine the used legend, specified with tm_legend(). The default legend and its settings are determined by the tmap options (tm_options()) legend. .

• The ⁠*.chart⁠ arguments specify additional charts, specified with tm_chart_, e.g. tm_chart_histogram()

• The ⁠*.free⁠ arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see tm_facets()). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (tm_facets_grid()). For instance, col.free = c(TRUE, FALSE, FALSE) means that for the visual variable col, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (tm_facets_wrap() and tm_facets_stack()) there is only one facet dimension, so the ⁠*.free⁠ argument requires only one logical value.

Examples

# load Africa country data
data(World)
Africa = World[World$continent == "Africa", ]
Africa_border = sf::st_make_valid(sf::st_union(sf::st_buffer(Africa, 0.001))) # slow and ugly

# without specifications
tm_shape(Africa_border) + tm_polygons()
tm_shape(Africa_border) + tm_fill()
tm_shape(Africa_border) + tm_borders()

# specification with visual variable values
tm_shape(Africa) + 
  tm_polygons(fill = "limegreen", col = "purple", lwd = 2, lty = "solid", col_alpha = 0.3) +
  tm_text("name", options = opt_tm_text(remove.overlap = TRUE)) +
tm_shape(Africa_border) +
  tm_borders("darkred", lwd = 3)

# specification with a data variable
tm_shape(Africa) +
  tm_polygons(fill = "income_grp", fill.scale = tm_scale_categorical(values = "-tol.muted"))

# continuous color scale with landscape legend
tm_shape(Africa) +
  tm_polygons(fill = "inequality", 
    fill.scale = tm_scale_continuous(values = "-scico.roma"),
    fill.legend = tm_legend(
    	title = "", orientation = "landscape",
    	position = tm_pos_out("center", "bottom"), frame = FALSE
    	)) + 
tm_shape(Africa_border) +
	tm_borders(lwd = 2) +
tm_title("Inequality index", position = tm_pos_in("right", "TOP"), frame = FALSE) +
tm_layout(frame = FALSE)

# bivariate scale
tm_shape(World) +
	tm_polygons(tm_vars(c("inequality", "well_being"), multivariate = TRUE))

Description

Set the position of map components, such as legends, title, compass, scale bar, etc. tm_pos() is the function to position these components: tm_pos_out() places the components outside the map area and tm_pos_in() inside the map area. Each position argument of a map layer or component should be specified with one of these functions. The functions tm_pos_auto_out() and tm_pos_auto_in() are used to set the components automatically, and should be used via tmap_options(). See Details how the positioning works.

Usage

tm_pos(cell.h, cell.v, pos.h, pos.v, align.h, align.v, just.h, just.v)

tm_pos_in(pos.h, pos.v, align.h, align.v, just.h, just.v)

tm_pos_out(cell.h, cell.v, pos.h, pos.v, align.h, align.v, just.h, just.v)

tm_pos_auto_out(cell.h, cell.v, pos.h, pos.v, align.h, align.v, just.h, just.v)

tm_pos_auto_in(align.h, align.v, just.h, just.v)

Arguments

Details

tm_pos_in() sets the position of the component(s) inside the maps area, which is equivalent to the center-center cell (in case there are facets, these are all drawn in this center-center cell).

tm_pos_out() sets the position of the component(s) outside the map.

The amount of space that the top and bottom rows, and left and right columns occupy is determined by the tm_layout() arguments meta.margins and meta.auto.margins. The former sets the relative space of the bottom, left, top, and right side. In case these are set to NA, the space is set automatically based on 1) the maximum relative space specified by meta.auto.margins and 2) the presence and size of components in each cell. For instance, if there is one landscape oriented legend in the center-bottom cell, then the relative space of the bottom row is set to the height of that legend (given that it is smaller than the corresponding value of meta.auto.margins), while the other four sides are set to 0.

tm_pos_auto_out() is more complex: the cell.h and cell.v arguments should be set to one of the four corners. It does not mean that the components are drawn in a corner. The corner represents the sides of the map that the components are drawn. By default, legends are drawn either at the bottom or on the right-side of the map by default (see tmap_options("legend.position")). Only when there are row- and column-wise legends and a general legend (using tm_facets_grid()), the general legend is drawn in the corner, but in practice this case will be rare.

The arguments pos.h and pos.v determine where the components are drawn within the cell. Again, with "left", "center", and "right" for pos.h and "top", "center", and "bottom" for pos.v. The values can also be specified in upper-case, which influences the offset with the cell borders, which is determined by tmap option component.offset. By default, there is a small offset when components are drawn inside and no offset when they are drawn outside or with upper-case.

tm_pos_auto_in() automatically determines pos.h and pos.v given the available space inside the map. This is similar to the default positioning in tmap3.

In case multiple components are draw in the same cell and the same position inside that cell, they are stacked (determined which the stack argument in the legend or component function). The align.h and align.v arguments determine how these components will be justified with each other.

Note that legends and components may be different for a facet row or column. This is the case when tm_facets_grid() or tm_facets_stack() are applied and when scales are set to free (with the .free argument of the map layer functions). In case a legends or components are draw row- or column wise, and the position of the legends (or components) is right next to the maps, these legends (or components) will be aligned with the maps.

Description

Map layer that draws rasters. Supported visual variable is: col (the color).

Usage

tm_raster(
  col = tm_vars(),
  col.scale = tm_scale(value.na = "#00000000"),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  col_alpha = tm_const(),
  col_alpha.scale = tm_scale(),
  col_alpha.legend = tm_legend(),
  col_alpha.chart = tm_chart_none(),
  col_alpha.free = NA,
  zindex = NA,
  group = NA,
  group.control = "check",
  options = opt_tm_raster(),
  ...
)

opt_tm_raster(interpolate = FALSE)

Arguments

Details

The visual variable arguments (e.g. col) can be specified with either a data variable name (e.g., a spatial vector attribute or a raster layer of the object specified in tm_shape()), or with a visual value (for col, a color is expected). Multiple values can be specified: in that case facets are created. These facets can be combined with other faceting data variables, specified with tm_facets().

• The ⁠*.scale⁠ arguments determine the used scale to map the data values to visual variable values. These can be specified with one of the available ⁠tm_scale_*()⁠ functions. The default is specified by the tmap option (tm_options()) scales.var.

• The ⁠*.legend⁠ arguments determine the used legend, specified with tm_legend(). The default legend and its settings are determined by the tmap options (tm_options()) legend. .

• The ⁠*.chart⁠ arguments specify additional charts, specified with tm_chart_, e.g. tm_chart_histogram()

• The ⁠*.free⁠ arguments determine whether scales are applied freely across facets, or shared. A logical value is required. They can also be specified with a vector of three logical values; these determine whether scales are applied freely per facet dimension. This is only useful when facets are applied (see tm_facets()). There are maximally three facet dimensions: rows, columns, and pages. This only applies for a facet grid (tm_facets_grid()). For instance, col.free = c(TRUE, FALSE, FALSE) means that for the visual variable col, each row of facets will have its own scale, and therefore its own legend. For facet wraps and stacks (tm_facets_wrap() and tm_facets_stack()) there is only one facet dimension, so the ⁠*.free⁠ argument requires only one logical value.

Examples

# load land data
data(land, World)

tm_shape(land) +
	tm_raster() +
	tm_facets_hstack()

tm_shape(land) +
	tm_raster("elevation", col.scale = tm_scale_continuous(values = terrain.colors(9))) +
	tm_shape(World) +
	tm_borders()

Description

Map layer that an rgb image.. The used (multivariate) visual variable is col, which should be specified with 3 or 4 variables for tm_rgb() and tm_rgba() respectively. The first three correspond to the red, green, and blue channels. The optional fourth is the alpha transparency channel.

Usage

tm_rgb(
  col = tm_vars(n = 3, multivariate = TRUE),
  col.scale = tm_scale_rgb(),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  options = opt_tm_rgb(),
  ...
)

tm_rgba(
  col = tm_vars(n = 4, multivariate = TRUE),
  col.scale = tm_scale_rgba(),
  col.legend = tm_legend(),
  col.chart = tm_chart_none(),
  col.free = NA,
  options = opt_tm_rgb()
)

Arguments

Examples

require(stars)
file = system.file("tif/L7_ETMs.tif", package = "stars")

L7 = stars::read_stars(file)

tm_shape(L7) +
	tm_rgb()

## Not run: 
# the previous example was a shortcut of this call
tm_shape(L7) +
	tm_rgb(col = tm_vars("band", dimvalues = 1:3))

# alternative format: using a stars dimension instead of attributes
L7_alt = split(L7, "band")
tm_shape(L7_alt) +
	tm_rgb()

# with attribute names
tm_shape(L7_alt) +
	tm_rgb(col = tm_vars(c("X1", "X2", "X3"), multivariate = TRUE))

# with attribute indices
tm_shape(L7_alt) +
	tm_rgb(col = tm_vars(1:3, multivariate = TRUE))

if (requireNamespace("terra")) {
	L7_terra = terra::rast(file)
	
	tm_shape(L7_terra) +
		tm_rgb()

	# with layer names
	tm_shape(L7_terra) +
		tm_rgb(tm_vars(names(L7_terra)[1:3], multivariate = TRUE))

	# with layer indices
	tm_shape(L7_alt) +
		tm_rgb(col = tm_vars(1:3, multivariate = TRUE))
	
}

## End(Not run)

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale() is a scale that is set automatically given by the data type (factor, numeric, and integer) and the visual variable. The tmap option scales.var contains information which scale is applied when.

Usage

tm_scale(...)

Arguments

See Also

tm_scale_asis(), tm_scale_ordinal(), tm_scale_categorical(), tm_scale_intervals(), tm_scale_discrete(), tm_scale_continuous(), tm_scale_rank(), tm_scale_continuous_log(), tm_scale_continuous_log2(), tm_scale_continuous_log10(), tm_scale_continuous_log1p(), tm_scale_continuous_sqrt(), tm_scale_continuous_pseudo_log(), tm_scale_rgb(), tm_scale_bivariate()

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale_asis() is used to take data values as they are and use them as such for the visual variable.

Usage

tm_scale_asis(values.scale = NA, value.neutral = NA, ...)

Arguments

See Also

tm_scale()

Description

This function was renamed to tm_scalebar() in tmap v4.0

Usage

tm_scale_bar(...)

Arguments

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale_bivariate() is used for bivariate.scales.

Usage

tm_scale_bivariate(
  scale1 = tm_scale(),
  scale2 = tm_scale(),
  values = NA,
  values.repeat = FALSE,
  values.range = NA,
  values.scale = 1,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  labels = NULL,
  label.na = NA,
  label.null = NA
)

Arguments

See Also

tm_scale()

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale_continuous() is used for continuous data. The functions ⁠tm_scale_continuous_<x>()⁠ use transformation functions x.

Usage

tm_scale_continuous(
  n = NULL,
  limits = NULL,
  outliers.trunc = NULL,
  ticks = NULL,
  trans = NULL,
  midpoint = NULL,
  values = NA,
  values.repeat = FALSE,
  values.range = NA,
  values.scale = NA,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  labels = NULL,
  label.na = NA,
  label.null = NA,
  label.format = list(),
  trans.args = list()
)

tm_scale_continuous_log(..., base = exp(1))

tm_scale_continuous_log2(...)

tm_scale_continuous_log10(...)

tm_scale_continuous_log1p(...)

tm_scale_continuous_sqrt(...)

tm_scale_continuous_pseudo_log(..., base = exp(1), sigma = 1)

Arguments

See Also

tm_scale()

Examples

tm_shape(World) +
  tm_polygons(
  	fill = "HPI",
    fill.scale = tm_scale_continuous(values = "scico.roma", midpoint = 30))

tm_shape(metro) +
  tm_bubbles(
  	size = "pop1950", 
    size.scale = tm_scale_continuous(
      values.scale = 1),
    size.legend = tm_legend("Population in 1950", frame = FALSE))

tm_shape(metro) +
  tm_bubbles(
    size = "pop1950", 
    size.scale = tm_scale_continuous(
      values.scale = 2, 
      limits = c(0, 12e6), 
      ticks = c(1e5, 3e5, 8e5, 4e6, 1e7), 
      labels = c("0 - 200,000", "200,000 - 500,000", "500,000 - 1,000,000", 
        "1,000,000 - 10,000,000", "10,000,000 or more"), 
      outliers.trunc = c(TRUE, TRUE)),
    size.legend = tm_legend("Population in 1950", frame = FALSE))
# Note that for this type of legend, we recommend tm_scale_intervals()

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale_discrete() is used for discrete numerical data, such as integers.

Usage

tm_scale_discrete(
  ticks = NA,
  midpoint = NULL,
  values = NA,
  values.repeat = FALSE,
  values.range = NA,
  values.scale = NA,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  labels = NULL,
  label.na = NA,
  label.null = NA,
  label.format = list()
)

Arguments

See Also

tm_scale()

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale_intervals() is used for numerical data.

Usage

tm_scale_intervals(
  n = 5,
  style = ifelse(is.null(breaks), "pretty", "fixed"),
  style.args = list(),
  breaks = NULL,
  interval.closure = "left",
  midpoint = NULL,
  as.count = NA,
  values = NA,
  values.repeat = FALSE,
  values.range = NA,
  values.scale = NA,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  labels = NULL,
  label.na = NA,
  label.null = NA,
  label.format = list()
)

Arguments

See Also

tm_scale()

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The functions tm_scale_categorical() and tm_scale_ordinal() are used for categorical data. The only difference between these functions is that the former assumes unordered categories whereas the latter assumes ordered categories. For colors (the visual variable fill or col), different default color palettes are used (see the tmap option values.var).

Usage

tm_scale_ordinal(
  n.max = 30,
  values = NA,
  values.repeat = FALSE,
  values.range = 1,
  values.scale = NA,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  levels = NULL,
  levels.drop = FALSE,
  labels = NULL,
  label.na = NA,
  label.null = NA,
  label.format = list()
)

tm_scale_categorical(
  n.max = 30,
  values = NA,
  values.repeat = TRUE,
  values.range = NA,
  values.scale = NA,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  levels = NULL,
  levels.drop = FALSE,
  labels = NULL,
  label.na = NA,
  label.null = NA,
  label.format = list()
)

Arguments

See Also

tm_scale()

Description

Scales in tmap are configured by the family of functions with prefix tm_scale. Such function should be used for the input of the .scale arguments in the layer functions (e.g. fill.scale in tm_polygons()). The function tm_scale_rank() is used to rank numeric data.

Usage

tm_scale_rank(
  n = NULL,
  ticks = NULL,
  values = NA,
  values.repeat = FALSE,
  values.range = NA,
  values.scale = NA,
  value.na = NA,
  value.null = NA,
  value.neutral = NA,
  labels = NULL,
  label.na = NA,
  label.null = NA,
  label.format = list(),
  unit = "rank"
)