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.

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

Main documentation

Description

Get basemap tile providers and their credits (attribution text). tmap_providers() returns a list or vector of provider names or credits. tmap_provider_credits() returns the attribution text for a specific provider.

Usage

.tmap_providers

tmap_provider_credits(provider)

tmap_providers(mode, credits = FALSE, as.list = credits)

Arguments

Details

.tmap_providers is an environment populated with all available provider names as named entries. Its primary purpose is to enable autocomplete in IDEs such as RStudio: typing .tmap_providers$ in the console or a script triggers a dropdown list of all available providers, making it easy to discover and select provider names without consulting the documentation. It is not intended to be called as a function.

Value

tmap_providers() returns a list or vector (see as.list) of provider names or credits. tmap_provider_credits() returns the attribution text for the specified provider. .tmap_providers is an environment; see Details.

Examples

# List all providers for the current mode
tmap_providers()

# Use IDE autocomplete to discover providers interactively:
# type .tmap_providers$ in the RStudio console

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

Datasets of the Netherlands for 2022 at three levels: NLD_prov (12) provinces, NLD_muni (345) municipalities and NLD_dist (3340) districts , all class sf

Usage

NLD_prov

NLD_muni

NLD_dist

Details

The data variables for NLD_muni and NLD_dist are identical:

See source for detailed information about the variables.

This dataset, created Noveber 2024, is an update from the datasets NLD_muni and NLD_prov used in tmap <= 3, which has been created around 2016. Note that the number of municipalities have been reduced (due to mergings). All old variables are included, except for variables related to ethnicity. Many new variable have been added, and moreover, district (Dutch: wijk) level data have added: NLD_dist.

The CRS (coordinate reference system) used is the Rijksdriekhoekstelsel New, EPSG 28992. Coordinates have been rounded to meters to reduce file size.

Source

https://www.cbs.nl/nl-nl/maatwerk/2024/11/kerncijfers-wijken-en-buurten-2022

References

Statistics Netherlands (2024), The Hague/Heerlen, Netherlands, https://www.cbs.nl/.

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 = NULL,
  fill = tmap::tm_const(),
  col = tmap::tm_const(),
  size = tmap::tm_const(),
  shape = tmap::tm_const(),
  lwd = tmap::tm_const(),
  lty = tmap::tm_const(),
  fill_alpha = tmap::tm_const(),
  col_alpha = tmap::tm_const(),
  text = tmap::tm_const(),
  text_col = tmap::tm_const(),
  text_size = tmap::tm_const(),
  by = NULL,
  scale = NULL,
  title = NULL,
  crs = NULL,
  bbox = NULL,
  basemaps = NA,
  overlays = NA,
  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).

zindex and pane names

In view mode, each layer is rendered in a Leaflet pane named "tmap{zindex}" (e.g., "tmap401", "tmap402"), with base tile layers placed in the standard "tile" pane.

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

Examples

data(World, World_rivers, metro)

# just the map
qtm(World)

# choropleth
qtm(World, fill = "economy", style = "cobalt", crs = "+proj=eck4")

qtm(World, col = NULL) +
qtm(metro, size = "pop2010",
	size.legend = tm_legend("Metropolitan Areas"))

# 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

• tmapOutput() creates a UI element

• renderTmap() renders a tmap map

• tmapProxy() updates a tmap map in view mode

Adding layers is as usual via the map layer functions like tm_polygons(). Removing layers can be done, removing with 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)

renderTmapGS(x, ...)

tmapOutputGS(x, ...)

tmapProxyGS(x, ...)

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

	current.mode <- 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(fill = world_vars[1], zindex = 401)
			})
			observe({
				var <- input$var
				tmapProxy("map", session, {
					tm_remove_layer(401) +
						tm_shape(World, id = "iso_a3") +
						tm_polygons(fill = var, zindex = 401)
				})
			})
		},options = list(launch.browser=TRUE)
	)

	tmap_mode(current.mode)
}

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 = "",
  orientation = NULL,
  position = NULL,
  group_id = NA_character_,
  group = NA,
  group.control = "check",
  z = NA_integer_
)

Arguments

Examples

## Not run: 
tm_shape(NLD_muni) +
	tm_borders() +
	tm_basemap("OpenStreetMap") +
	tm_add_legend(labels = c("Motorway", "Primary road", "Secondary road", "Railway"),
				  col = c("#E892A1", "#FCD6A4", "#F8FABF", "#707070"),
				  lty = c("solid", "solid", "solid", "dotted"),
				  lwd = 3,
				  type = "lines",
				  bg.color = "grey92",
				  bg.alpha = 1)

## End(Not run)

Description

Specify an animation from a tmap plot. This is similar to creating facets with tm_facets(). The animation subsequently can be exported to a gif or video file (e.g. mp4) with tmap_animation(). If the tmap plot with tm_animate() is printed, the animation will be previewed. The default tm_animate() will show the individual frames slowly (frame per seconds (fps) set to 2) whereas tm_animate_fast() will show them like a movie (with a fps set to 24).

Usage

tm_animate_fast(
  frames = "VARS__",
  nframes = 60L,
  fps = 24L,
  play = c("loop", "pingpong", "once"),
  dpr = 2,
  ...
)

tm_animate(
  frames = "VARS__",
  nframes = 60L,
  fps = 2L,
  play = c("loop", "pingpong", "once"),
  dpr = 2,
  ...
)

Arguments

Note

In older versions (< 4.1) tm_facets() with page specification was used to create animations frames and tmap_animation() to create the animation itself using inputs like the frame rate specification. As of version 4.2, the whole animation, including frame rate, is specified in tm_animate(). The animation can still be saved via tmap_animation().

See Also

tm_facets() which is the core function, and tmap_animation() used to save the animation

Examples

if (interactive()) {
	tm_shape(NLD_prov) +
		tm_polygons("yellow") +
		tm_animate(frames = "name")

	tm_shape(metro) +
		tm_symbols(size = paste0("pop", seq(1950, 2030, by=10)),
				   size.free = FALSE,
				   size.legend = tm_legend("Population")) +
		tm_layout(panel.labels = seq(1970, 2030, by=10)) +
		tm_animate()
}

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 = NA,
  alpha = NULL,
  zoom = NULL,
  api = NULL,
  max.native.zoom = 17,
  sub = "abc",
  zindex = 0,
  group = NA,
  group.control = "radio"
)

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

Arguments

Details

API keys. For Stadia and Thunderforest maps, an API key is required. This can be set via the argument api. Alternatively they can be stored in environment variables "STADIA_MAPS" and THUNDERFOREST_MAPS with Sys.setenv

In view mode, each layer is rendered in a Leaflet pane named "tmap{zindex}" (e.g., "tmap401", "tmap402"), with base tile layers placed in the standard "tile" pane.

See Also

Basemap examples

Examples

## Not run: 
if (requireNamespace("maptiles")) {
	# view mode
	current_mode = tmap_mode("view")
	tm_basemap("Stadia.StamenWatercolor") +
		tm_shape(World) +
		tm_polygons(
		  "HPI",
		  fill.scale = tm_scale(values = "reds"),
		  fill_alpha.scale = 0.5)

	tm_shape(World, crs = "+proj=eqearth") +
		tm_polygons(
			"HPI",
			fill.scale = tm_scale(values = "reds"),
			fill_alpha.scale = 0.5) +
	tm_basemap(NULL)

	# plot mode:
	tmap_mode("plot")
	tm_basemap() +
		tm_shape(World) +
		tm_polygons("HPI")

	tm_basemap("OpenTopoMap") +
		tm_shape(World) +
		tm_polygons(fill = NA, col = "black")

	tm_basemap("CartoDB.PositronNoLabels") +
	tm_shape(NLD_prov, crs = 4236) +
		tm_borders() +
		tm_facets_wrap("name") +
		tm_tiles("CartoDB.PositronOnlyLabels")

	# restore mode
	tmap_mode(current_mode)
}

## End(Not run)

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,
  group_id,
  width,
  height,
  stack,
  z,
  ...
)

tm_chart_bar(
  plot.axis.x,
  plot.axis.y,
  extra.ggplot2,
  position,
  group_id,
  width,
  height,
  stack,
  z,
  ...
)

tm_chart_donut(position, group_id, width, height, stack, z, ...)

tm_chart_violin(position, group_id, width, height, stack, z, ...)

tm_chart_box(position, group_id, width, height, stack, z, ...)

tm_chart_none()

tm_chart_heatmap(position, group_id, width, height, stack, z, ...)

Arguments

Details

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

See Also

Vignette about charts

Examples

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

Description

Get or set the tmap options globally. For map specific options, we recommend to use tm_options() or tm_layout() via which the layout-related options can be set. tmap_options() functions similar to base::options().

Usage

tm_check_fix()

tmap_options(
  ...,
  crs,
  facet.max,
  free.scales,
  raster.max_cells,
  raster.warp,
  show.messages,
  show.warnings,
  output.format,
  output.size,
  output.dpi,
  animation.dpi,
  value.const,
  value.na,
  value.null,
  value.blank,
  values.var,
  values.range,
  value.neutral,
  values.scale,
  scales.var,
  scale.misc.args,
  continuous.nclass_per_legend_break,
  continuous.nclasses,
  label.format,
  label.na,
  scale,
  asp,
  bg,
  bg.color,
  outer.bg,
  outer.bg.color,
  frame,
  frame.color,
  frame.alpha,
  frame.lwd,
  frame.r,
  frame.double_line,
  outer.margins,
  inner.margins,
  inner.margins.extra,
  meta.margins,
  meta.auto_margins,
  between_margin,
  panel.margin,
  xlab.show,
  xlab.text,
  xlab.size,
  xlab.color,
  xlab.rotation,
  xlab.space,
  xlab.fontface,
  xlab.fontfamily,
  xlab.alpha,
  xlab.side,
  ylab.show,
  ylab.text,
  ylab.size,
  ylab.color,
  ylab.rotation,
  ylab.space,
  ylab.fontface,
  ylab.fontfamily,
  ylab.alpha,
  ylab.side,
  panel.type,
  panel.wrap.pos,
  panel.xtab.pos,
  unit,
  color.sepia_intensity,
  color.saturation,
  color_vision_deficiency_sim,
  text.fontface,
  text.fontfamily,
  r,
  component.position,
  component.offset,
  component.stack_margin,
  component.autoscale,
  component.resize_as_group,
  component.frame_combine,
  component.stack,
  legend.stack,
  chart.stack,
  component.equalize,
  component.frame,
  component.frame.color,
  component.frame.alpha,
  component.frame.lwd,
  component.frame.r,
  component.bg,
  component.bg.color,
  component.bg.alpha,
  legend.show,
  legend.orientation,
  legend.position,
  legend.width,
  legend.height,
  legend.reverse,
  legend.na.show,
  legend.title.color,
  legend.title.size,
  legend.title.fontface,
  legend.title.fontfamily,
  legend.title.alpha,
  legend.xlab.color,
  legend.xlab.size,
  legend.xlab.rot,
  legend.xlab.fontface,
  legend.xlab.fontfamily,
  legend.xlab.alpha,
  legend.ylab.color,
  legend.ylab.size,
  legend.ylab.rot,
  legend.ylab.fontface,
  legend.ylab.fontfamily,
  legend.ylab.alpha,
  legend.text.color,
  legend.text.size,
  legend.text.fontface,
  legend.text.fontfamily,
  legend.text.alpha,
  legend.frame,
  legend.frame.color,
  legend.frame.alpha,
  legend.frame.lwd,
  legend.frame.r,
  legend.bg,
  legend.bg.color,
  legend.bg.alpha,
  legend.only,
  legend.absolute_fontsize,
  legend.settings.portrait,
  legend.settings.landscape,
  add_legend.position,
  chart.show,
  chart.plot.axis.x,
  chart.plot.axis.y,
  chart.position,
  chart.width,
  chart.height,
  chart.reverse,
  chart.na.show,
  chart.title.color,
  chart.title.size,
  chart.title.fontface,
  chart.title.fontfamily,
  chart.title.alpha,
  chart.xlab.color,
  chart.xlab.size,
  chart.xlab.fontface,
  chart.xlab.fontfamily,
  chart.xlab.alpha,
  chart.ylab.color,
  chart.ylab.size,
  chart.ylab.fontface,
  chart.ylab.fontfamily,
  chart.ylab.alpha,
  chart.text.color,
  chart.text.size,
  chart.text.fontface,
  chart.text.fontfamily,
  chart.text.alpha,
  chart.frame,
  chart.frame.color,
  chart.frame.alpha,
  chart.frame.lwd,
  chart.frame.r,
  chart.bg,
  chart.bg.color,
  chart.bg.alpha,
  chart.object.color,
  title.size,
  title.color,
  title.fontface,
  title.fontfamily,
  title.alpha,
  title.padding,
  title.frame,
  title.frame.color,
  title.frame.alpha,
  title.frame.lwd,
  title.frame.r,
  title.position,
  title.width,
  credits.size,
  credits.color,
  credits.fontface,
  credits.fontfamily,
  credits.alpha,
  credits.padding,
  credits.position,
  credits.width,
  credits.height,
  compass.north,
  compass.type,
  compass.text.size,
  compass.size,
  compass.show.labels,
  compass.cardinal.directions,
  compass.text.color,
  compass.color.dark,
  compass.color.light,
  compass.lwd,
  compass.margins,
  compass.position,
  inset.position,
  logo.height,
  logo.margins,
  logo.between_margin,
  logo.position,
  inset_map.height,
  inset_map.width,
  inset_map.margins,
  inset_map.between_margin,
  inset_map.position,
  inset_map.frame,
  inset.height,
  inset.width,
  inset.margins,
  inset.between_margin,
  inset.frame,
  inset.bg,
  inset.bg.color,
  inset.bg.alpha,
  inset_grob.height,
  inset_grob.width,
  inset_gg.height,
  inset_gg.width,
  scalebar.breaks,
  scalebar.width,
  scalebar.allow_clipping,
  scalebar.text.size,
  scalebar.text.color,
  scalebar.text.fontface,
  scalebar.text.fontfamily,
  scalebar.color.dark,
  scalebar.color.light,
  scalebar.lwd,
  scalebar.size,
  scalebar.margins,
  scalebar.position,
  grid.show,
  grid.labels.pos,
  grid.x,
  grid.y,
  grid.n.x,
  grid.n.y,
  grid.crs,
  grid.col,
  grid.lwd,
  grid.alpha,
  grid.labels.show,
  grid.labels.size,
  grid.labels.col,
  grid.labels.fontface,
  grid.labels.fontfamily,
  grid.labels.rot,
  grid.labels.format,
  grid.labels.cardinal,
  grid.labels.margin.x,
  grid.labels.margin.y,
  grid.labels.space.x,
  grid.labels.space.y,
  grid.labels.inside_frame,
  grid.ticks,
  grid.lines,
  grid.ndiscr,
  mouse_coordinates.position,
  minimap.server,
  minimap.toggle,
  minimap.position,
  panel.show,
  panel.labels,
  panel.label.size,
  panel.label.color,
  panel.label.fontface,
  panel.label.fontfamily,
  panel.label.alpha,
  panel.label.bg,
  panel.label.bg.color,
  panel.label.bg.alpha,
  panel.label.frame,
  panel.label.frame.color,
  panel.label.frame.alpha,
  panel.label.frame.lwd,
  panel.label.frame.r,
  panel.label.height,
  panel.label.rot,
  qtm.scalebar,
  qtm.minimap,
  qtm.mouse_coordinates,
  earth_boundary,
  earth_boundary.color,
  earth_boundary.lwd,
  earth_datum,
  space,
  space.color,
  space_overlay,
  check_and_fix,
  basemap.show,
  basemap.server,
  basemap.alpha,
  basemap.zoom,
  tiles.show,
  tiles.server,
  tiles.alpha,
  tiles.zoom,
  attr.color,
  crs_extra,
  crs_global,
  crs_basemap,
  use_gradient,
  use_browser,
  use_WebGL,
  control.position,
  control.bases,
  control.overlays,
  control.collapse,
  set_bounds,
  set_view,
  set_zoom_limits,
  use_circle_markers,
  leaflet.options,
  title = NULL,
  main.title = NULL,
  main.title.size = NULL,
  main.title.color = NULL,
  main.title.fontface = NULL,
  main.title.fontfamily = NULL,
  main.title.position = NULL,
  fontface = NULL,
  fontfamily = NULL
)

tmap_options_mode(
  mode = NA,
  style = NULL,
  mode.specific = TRUE,
  default.options = FALSE
)

tmap_options_diff()

tmap_options_reset()

tmap_options_save(style)

Arguments

Examples

# get all options
opt = tmap_options()

# print as a tree
if (requireNamespace("lobstr")) {
	lobstr::tree(opt)
}

# a fancy set of options:
tmap_options(
  bg.color = "steelblue",
  outer.bg.color = "salmon",
  frame.color = "purple3",
  frame.lwd = 5,
  compass.type = "8star",
  legend.bg.color = "gold",
  legend.position = tm_pos_in(pos.h = "left", pos.v = "top")
 )

if (requireNamespace("lobstr")) {
	lobstr::tree(
		tmap_options_diff()
	)
}

tm_shape(World) +
	tm_polygons("footprint")

tmap_options_save("fancy")

# the default style:
tmap_style("white")

tm_shape(World) +
	tm_polygons("footprint")

tmap_style("fancy")

tm_shape(World) +
	tm_polygons("footprint")

# reset all options
tmap_options_reset()

Description

Map layer that draws circles with geographically fixed radii — i.e. the radius is expressed in meters and the circles scale with zoom in interactive (view) mode. This is in contrast to tm_bubbles(), where the symbol size is a fixed number of screen pixels.

Usage

tm_circles(
  size = tm_const(),
  size.scale = tm_scale(),
  size.legend = tm_legend(),
  size.chart = tm_chart_none(),
  size.free = NA,
  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,
  plot.order = tm_plot_order("size"),
  zindex = NA,
  group = NA,
  group.control = "check",
  popup = tm_popup(),
  popup.vars = NA,
  popup.format = tm_label_format(),
  hover = NA,
  id = "",
  blend = "over",
  options = opt_tm_circles(),
  ...
)

opt_tm_circles(
  points_only = "ifany",
  point_per = "feature",
  on_surface = FALSE
)

Arguments

Details

Supported visual variables: fill (fill colour), col (border colour), size (radius in meters), lwd (line width), lty (line type), fill_alpha (fill transparency), col_alpha (border transparency).

See Also

• tm_bubbles() for screen-fixed proportional circles (pixel radius).

• tm_symbols() for the general symbol layer with configurable shapes.

• tm_scale_asis() to pass data values directly as metre radii.

Examples

## Three concentric layers of geographic circles at different administrative
## levels, each with a fixed radius that corresponds to a real-world distance.
## Because the radius is in meters the circles scale with zoom in view mode.
tm_shape(NLD_prov) +
	tm_circles(size = 5000, fill = "#0033ff", col = NULL) +
tm_shape(NLD_muni) +
	tm_circles(size = 2000, fill = "#99dd99", col = NULL) +
tm_shape(NLD_dist) +
	tm_circles(size = 1000, fill = "#ff8833", col = NULL)

## Use a units object — any linear unit is accepted and converted to meters
NLD_prov$one_mile <- units::as_units(1:12, "mi")
tm_shape(NLD_prov) +
	tm_circles(size = "one_mile", size.scale = tm_scale_asis())

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,
  group_id,
  bg,
  bg.color,
  bg.alpha,
  stack,
  just,
  frame,
  frame.color,
  frame.alpha,
  frame.lwd,
  frame.r,
  margins,
  z,
  ...
)

Arguments

See Also

Vignette about components

Description

Group components

Usage

tm_components(
  group_id = "",
  position,
  stack,
  frame_combine,
  equalize,
  resize_as_group,
  stack_margin,
  offset,
  frame,
  frame.color,
  frame.alpha,
  frame.lwd,
  frame.r,
  bg,
  bg.color,
  bg.alpha
)

Arguments

Value

A tmap-element

Description

tmap function to define a constant visual value

Usage

tm_const()

Description

Map component that adds a text, typically used as credits. This function is the same as tm_title() but with different default values.

Usage

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

Arguments

See Also

Vignette about components

Description

This function sets the map projection. It can also be set via tm_shape(), but tm_crs is generally recommended for most cases. It can also be determined automatically (see details); however, this is still work-in-progress.

Usage

tm_crs(crs = NA, property = NA, bbox = NULL)

Arguments

Details

The map projection (crs) determines in which coordinate system the spatial object is processed and plotted. See vignette about CRS. The crs can be specified in two places: 1) tm_shape() and tm_crs(). In both cases, the map is plotted into the specified crs. The difference is that in the first option, the crs is also taken into account in spatial transformation functions, such as the calculation of centroids and cartograms. In the second option, the crs is only used in the plotting phase.

The automatic crs recommendation (which is still work-in-progress) is the following:

For further info about the available "generic" projects see: for utm: https://proj.org/en/9.4/operations/projections/utm.html for laea: https://proj.org/en/9.4/operations/projections/laea.html for aeqd: https://proj.org/en/9.4/operations/projections/aeqd.html for pconic: https://proj.org/en/9.4/operations/projections/pconic.html for eqdc: https://proj.org/en/9.4/operations/projections/eqdc.html

Note

Plans are to migrate the functionality regarding generic crs and automatic crs recommendation to a separate package.

See Also

vignette about CRS

Examples

SA = World[World$continent == "South America", ]

# latlon coordinates (WGS84)
tm_shape(SA) +
	tm_polygons() +
	tm_graticules() +
	tm_crs(4326)

tm_list = lapply(c("global", "area", "distance", "shape"), FUN = function(property) {
	tm_shape(SA) +
		tm_polygons() +
		tm_graticules() +
		tm_crs(property = property)	+
	tm_title(property)
})

tmap_arrange(tm_list, nrow = 1)

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() specify facets for two grouping variables in a grid of rows and columns.

• tm_facets_pagewise() same as wrap, but the facets are drawn on different plots (pages). Replaces the along argument from version 3.

• 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,
  nrow = NA,
  ncol = NA,
  byrow = TRUE,
  orientation = NA,
  free.coords = NA,
  drop.units = TRUE,
  drop.empty.facets = TRUE,
  drop.NA.facets = FALSE,
  sync = TRUE,
  swipe = FALSE,
  na.text = NA,
  scale.factor = 2,
  type = NA,
  free.scales = NULL,
  ...
)

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

tm_facets_wrap(by = "VARS__", nrow = NA, ncol = NA, byrow = TRUE, ...)

tm_facets_pagewise(by = "VARS__", byrow = TRUE, ...)

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

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

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

tm_facets_flip(...)

Arguments

Note

In older versions (< 4.1) tm_facets() with page specification was used to create animations frames and tmap_animation() to create the animation itself using inputs like the frame rate specification. As of version 4.2, the whole animation, including frame rate, is specified in tm_animate(). The animation can still be saved via tmap_animation().

See Also

tm_animate()

Vignette about facets

Examples

## Not run: 
tm_shape(NLD_dist) +
  tm_polygons("edu_appl_sci",
    fill.scale = tm_scale_intervals(values = "pu_gn", style = "kmeans", n = 7)) +
  tm_facets(by = "province") +
tm_shape(NLD_muni) +
  tm_borders(lwd = 3) +
  tm_facets(by = "province") +
tm_title("Population with a univeristy degree (incl appl. sciences), percentages")

tm_shape(World) +
  tm_polygons(c("gender", "press"),
    fill.scale = list(tm_scale_intervals(values = "bu_br_div", midpoint = 0.5),
      tm_scale_intervals(values = "pu_gn_div", midpoint = 50)),
    fill.legend = tm_legend("")) +
tm_layout(panel.labels = c("Gender Inequality Index (GII)", "World Press Freedom Index"))

## End(Not run)

Description

Draws horizontal and vertical lines according to a coordinate reference system (CRS). tm_grid() uses the CRS of the (master) shape object, and tm_graticules() uses latitude and longitude coordinates (EPSG 4326). It creates a tmap-element that draws coordinate grid lines. It serves as a layer that can be drawn anywhere between other layers.

Usage

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

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

Details

#' In view mode, each layer is rendered in a Leaflet pane named "tmap{zindex}" (e.g., "tmap401", "tmap402"), with base tile layers placed in the standard "tile" pane.

Examples

## Not run: 
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) + tm_grid(),
	qtm(NLD_muni) + tm_graticules()
)

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

tmap_mode(current.mode)

## End(Not run)

Description

Controls the layer groups in interactive maps (view mode): the layer control box (radio buttons or check boxes) and at which zoom levels the layers are displayed at.

Usage

tm_group(name, control = NA, zoom_levels = NA)

Arguments

See Also

vignette about layer groups

Description

Map component that adds an inset object, e.g. a mini map

Usage

tm_inset(
  x = NULL,
  height,
  width,
  margins,
  between_margin,
  position,
  group_id,
  frame,
  frame.color,
  frame.alpha,
  frame.lwd,
  frame.r,
  bg,
  bg.color,
  bg.alpha,
  box_frame,
  box_frame.color,
  box_frame.alpha,
  box_frame.lwd,
  box_frame.lty,
  box_bg,
  box_bg.color,
  box_bg.alpha,
  main_frame,
  main_frame.r,
  main_frame.color,
  main_frame.alpha,
  main_frame.lwd,
  z
)

Arguments

Examples

## map
bb = tmaptools::bb(NLD_prov[NLD_prov$name == "Utrecht",], ext = 1.05)

bb_Randstad =
  sf::st_bbox(c(xmin = 120000, xmax = 150000, ymin = 460000, ymax = 500000), crs = 28992)

tm_shape(NLD_dist) +
	tm_polygons(
		fill = "dwelling_value",
		fill.scale = tm_scale_continuous_pseudo_log(values = "-cols4all.pu_gn_div"),
		col = NULL) +
tm_shape(NLD_muni) +
	tm_borders(col = "black", lwd = 0.5) +
tm_shape(NLD_prov) +
	tm_borders(col = "black", lwd = 1.5) +
tm_inset(bb_Randstad, height = 12, width = 12, position = c("left", "top")) +
	tm_compass(position = c("left", "top"), )

## ggplot2
if (requireNamespace("ggplot2")) {
	library(ggplot2)
	p = ggplot(World, aes(x = gender, y = press, colour = continent)) +
		geom_point() +
		theme_bw()

	tm_shape(World) +
		tm_polygons(
			fill = "gender",
			fill.scale = tm_scale(values = "-cols4all.pu_gn_div")) +
		tm_inset(p, height = 15, width = 20, position = tm_pos_in("left", "bottom"))
}

Description

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

Usage

tm_iso(
  col = tm_const(),
  text = tm_vars(x = 1),
  ...,
  options_lines = opt_tm_lines(),
  options_labels = opt_tm_labels()
)

Arguments

Description

tmap function to specify labels used in the scale functions, e.g. via the argument label.format in tm_scale_intervals().

Usage

tm_label_format(
  fun,
  scientific,
  format,
  digits,
  interval.disjoint,
  big.num.abbr,
  prefix,
  suffix,
  text.separator,
  text.less.than,
  text.less.than_as.prefix,
  text.or.more,
  text.or.more_as.prefix,
  text.align,
  text.to.columns,
  html.escape,
  ...
)

Arguments

Value

list with formatting options

Description

Legend specification

Usage

tm_legend(
  title,
  show,
  orientation,
  reverse,
  na.show,
  position,
  group_id,
  width,
  height,
  z,
  title.color,
  title.size,
  title.fontface,
  title.fontfamily,
  title.alpha,
  title.padding,
  title.align,
  text.color,
  text.size,
  text.fontface,
  text.fontfamily,
  text.alpha,
  format,
  frame,
  frame.lwd,
  frame.r,
  bg,
  bg.color,
  bg.alpha,
  absolute_fontsize,
  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,
  margins,
  item_text.margin,
  ...
)

tm_legend_hide()

tm_legend_combine(variable)

tm_legend_bivariate(
  xlab,
  ylab,
  xlab.color,
  xlab.size,
  xlab.rot,
  xlab.fontface,
  xlab.fontfamily,
  xlab.alpha,
  xlab.padding,
  xlab.align,
  ylab.color,
  ylab.size,
  ylab.rot,
  ylab.fontface,
  ylab.fontfamily,
  ylab.alpha,
  ylab.padding,
  ylab.align,
  ...
)

Arguments

Value

A tm_legend component

See Also

Vignette about legends

Examples

# Example using different settings from tm_legend()

tm_shape(World) +
  tm_polygons(
    fill = "HPI",
    fill.legend = tm_legend(
      title = "Home Price Index",
      title.color = "orange",
      bg.color = "purple",
      show = TRUE
	),
    id = "name",
    # Format the labels using dollar sign
    fill.scale = tm_scale_intervals(
      label.format = function(x) format(x, big.mark = " ")),
)

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 = tm_popup(),
  popup.vars = NA,
  popup.format = tm_label_format(),
  hover = NA,
  id = "",
  blend = "over",
  options = opt_tm_lines(),
  ...
)

opt_tm_lines(lines.only = "ifany", hitbox = "auto")

Arguments

\item{"plusX"}{Adds \code{X} pixels to the visible line width to compute
the interaction width: \code{line_width + X}. For example, \code{"plus8"}
widens the clickable area by 4 pixels on each side.}

\item{"pmaxX"}{Ensures a minimum interaction width of \code{X} pixels:
\code{pmax(line_width, X)}. For example, \code{"pmax8"} guarantees at
least 8 pixels. Useful for very thin lines.}

\item{"auto"}{\code{"pmax8"} if and only if interactive features are
enabled (popup or hover), lines are thin (median line width < 4), and
there are fewer than 10000 features. Otherwise \code{"none"}.}

Details

The visual variable arguments (e.g. col) can be specified with a data variable name (e.g., a spatial vector attribute or a raster layer of the object specified in tm_shape()), with a visual value (for col, a color is expected), or with a geometry-derived variable (see below). See vignette about visual variables.

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(). See vignette about 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. See vignette about scales.

• 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. . See vignette about legends.

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

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

Currently, three geometry-derived variables are implemented:

• "AREA" (polygons only), which uses the feature area;

• "LENGTH" (lines only), which uses the feature length; and

• "MAP_COLORS", which assigns values so that adjacent features receive different values, making it particularly suitable for coloring neighbouring polygons.

Note that geometry-derived variables do not generate a legend automatically. If a legend is required, compute the corresponding variable explicitly, for example with sf::st_area(), sf::st_length(), or tmaptools::map_coloring(), and use the resulting values instead.

Visual variable units

Every visual variable maps data values to a specific output unit. Knowing the unit matters when supplying constant values via tm_const(), or output ranges via values.range / values.scale in the scale functions.

Symbol size (size in tm_symbols, tm_bubbles, tm_squares, tm_dots)

"Lines" is a typographic unit: one line is approximately 1/6 inch (the default base line-height in R graphics). The global multiplier tmap_options(values.scale = list(size.bubbles = 1.5)) scales all symbol sizes without changing the data mapping.

Circle size (size in tm_circles)

The value is a geographic radius in meters. A plain numeric vector is interpreted as meters; a units object (from the units package) is automatically converted, so units::as_units(1, "mi") gives a 1-mile radius. Because the radius is geographic, circles scale with zoom in interactive (view) mode – unlike bubble symbols which keep a fixed screen size.