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

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

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)

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(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)
	)
}

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,
  position = NULL,
  group = NA,
  group.control = "check",
  resize.as.group = FALSE,
  z = NA_integer_
)

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

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

Arguments

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

See Also

Vignette about charts

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

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,
  facet.flip,
  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.color,
  outer.bg.color,
  frame,
  frame.lwd,
  frame.r,
  frame.double_line,
  outer.margins,
  inner.margins,
  inner.margins.extra,
  meta.margins,
  meta.auto_margins,
  between_margin,
  panel.margin,
  component.offset,
  component.stack_margin,
  grid.mark.height,
  xylab.height,
  coords.height,
  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,
  text.alpha,
  component.position,
  component.autoscale,
  legend.show,
  legend.design,
  legend.orientation,
  legend.position,
  legend.width,
  legend.height,
  legend.stack,
  legend.group.frame,
  legend.resize_as_group,
  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.fontface,
  legend.xlab.fontfamily,
  legend.xlab.alpha,
  legend.ylab.color,
  legend.ylab.size,
  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.lwd,
  legend.frame.r,
  legend.bg.color,
  legend.bg.alpha,
  legend.only,
  legend.absolute_fontsize,
  legend.settings.standard.portrait,
  legend.settings.standard.landscape,
  chart.show,
  chart.plot.axis.x,
  chart.plot.axis.y,
  chart.position,
  chart.width,
  chart.height,
  chart.stack,
  chart.group.frame,
  chart.resize_as_group,
  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.lwd,
  chart.frame.r,
  chart.bg.color,
  chart.bg.alpha,
  chart.object.color,
  title.size,
  title.color,
  title.fontface,
  title.fontfamily,
  title.alpha,
  title.bg.color,
  title.bg.alpha,
  title.padding,
  title.frame,
  title.frame.lwd,
  title.frame.r,
  title.stack,
  title.position,
  title.width,
  title.group.frame,
  title.resize_as_group,
  credits.size,
  credits.color,
  credits.fontface,
  credits.fontfamily,
  credits.alpha,
  credits.bg.color,
  credits.bg.alpha,
  credits.padding,
  credits.frame,
  credits.frame.lwd,
  credits.frame.r,
  credits.stack,
  credits.position,
  credits.width,
  credits.height,
  credits.group.frame,
  credits.resize_as_group,
  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.bg.color,
  compass.bg.alpha,
  compass.margins,
  compass.stack,
  compass.position,
  compass.frame,
  compass.frame.lwd,
  compass.frame.r,
  compass.group.frame,
  compass.resize_as_group,
  logo.height,
  logo.margins,
  logo.between_margin,
  logo.stack,
  logo.position,
  logo.frame,
  logo.frame.lwd,
  logo.frame.r,
  logo.group.frame,
  logo.resize_as_group,
  scalebar.breaks,
  scalebar.width,
  scalebar.text.size,
  scalebar.text.color,
  scalebar.color.dark,
  scalebar.color.light,
  scalebar.lwd,
  scalebar.bg.color,
  scalebar.bg.alpha,
  scalebar.size,
  scalebar.margins,
  scalebar.stack,
  scalebar.position,
  scalebar.frame,
  scalebar.frame.lwd,
  scalebar.frame.r,
  scalebar.group.frame,
  scalebar.resize_as_group,
  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.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.stack,
  mouse_coordinates.position,
  mouse_coordinates.show,
  minimap.server,
  minimap.toggle,
  minimap.stack,
  minimap.position,
  minimap.show,
  panel.show,
  panel.labels,
  panel.label.size,
  panel.label.color,
  panel.label.fontface,
  panel.label.fontfamily,
  panel.label.alpha,
  panel.label.bg.color,
  panel.label.frame,
  panel.label.frame.lwd,
  panel.label.frame.r,
  panel.label.height,
  panel.label.rot,
  bbox,
  qtm.scalebar,
  qtm.minimap,
  qtm.mouse_coordinates,
  earth_boundary,
  earth_boundary.color,
  earth_boundary.lwd,
  earth_datum,
  space.color,
  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,
  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 = "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 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

See Also

Vignette about components

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.color,
  bg.alpha,
  position,
  width,
  height,
  group.frame,
  resize_as_group,
  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)

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() 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,
  nrow = NA,
  ncol = 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__", nrow = NA, ncol = NA, byrow = TRUE, ...)

tm_facets_pagewise(by = "VARS__", nrow = 1, ncol = 1, byrow = TRUE, ...)

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

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

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

tm_facets_flip(...)

Arguments

See Also

Vignette about facets

Examples

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

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

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

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.alpha,
  title.padding,
  title.align,
  text.color,
  text.size,
  text.fontface,
  text.fontfamily,
  text.alpha,
  format,
  frame,
  frame.lwd,
  frame.r,
  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.fontface,
  xlab.fontfamily,
  xlab.alpha,
  xlab.padding,
  xlab.align,
  ylab.color,
  ylab.size,
  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",
      design = "standard",
      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.vars = NA,
  popup.format = list(),
  hover = NA,
  id = "",
  options = opt_tm_lines(),
  ...
)

opt_tm_lines(lines.only = "ifany")

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

See Also

Terrain map example

Examples

tm_shape(World_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 logo.

Usage

tm_logo(
  file,
  height,
  margins,
  between_margin,
  stack,
  position,
  frame,
  frame.lwd,
  frame.r,
  group.frame,
  resize_as_group,
  z
)

Arguments

See Also

Vignette about components

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("help", "figures", "logo.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

Vignette about components

Description

Map component that adds mouse coordinates

Usage

tm_mouse_coordinates(stack, position, z)

Arguments

See Also

Vignette about components

Description

tmap options

Usage

tm_options(
  crs,
  facet.max,
  facet.flip,
  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.color,
  outer.bg.color,
  frame,
  frame.lwd,
  frame.r,
  frame.double_line,
  outer.margins,
  inner.margins,
  inner.margins.extra,
  meta.margins,
  meta.auto_margins,
  between_margin,
  panel.margin,
  component.offset,
  component.stack_margin,
  grid.mark.height,
  xylab.height,
  coords.height,
  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,
  text.alpha,
  component.position,
  component.autoscale,
  legend.show,
  legend.design,
  legend.orientation,
  legend.position,
  legend.width,
  legend.height,
  legend.stack,
  legend.group.frame,
  legend.resize_as_group,
  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.fontface,
  legend.xlab.fontfamily,
  legend.xlab.alpha,
  legend.ylab.color,
  legend.ylab.size,
  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.lwd,
  legend.frame.r,
  legend.bg.color,
  legend.bg.alpha,
  legend.only,
  legend.absolute_fontsize,
  legend.settings.standard.portrait,
  legend.settings.standard.landscape,
  chart.show,
  chart.plot.axis.x,
  chart.plot.axis.y,
  chart.position,
  chart.width,
  chart.height,
  chart.stack,
  chart.group.frame,
  chart.resize_as_group,
  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.lwd,
  chart.frame.r,
  chart.bg.color,
  chart.bg.alpha,
  chart.object.color,
  title.size,
  title.color,
  title.fontface,
  title.fontfamily,
  title.alpha,
  title.bg.color,
  title.bg.alpha,
  title.padding,
  title.frame,
  title.frame.lwd,
  title.frame.r,
  title.stack,
  title.position,
  title.width,
  title.group.frame,
  title.resize_as_group,
  credits.size,
  credits.color,
  credits.fontface,
  credits.fontfamily,
  credits.alpha,
  credits.bg.color,
  credits.bg.alpha,
  credits.padding,
  credits.frame,
  credits.frame.lwd,
  credits.frame.r,
  credits.stack,
  credits.position,
  credits.width,
  credits.height,
  credits.group.frame,
  credits.resize_as_group,
  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.bg.color,
  compass.bg.alpha,
  compass.margins,
  compass.stack,
  compass.position,
  compass.frame,
  compass.frame.lwd,
  compass.frame.r,
  compass.group.frame,
  compass.resize_as_group,
  logo.height,
  logo.margins,
  logo.between_margin,
  logo.stack,
  logo.position,
  logo.frame,
  logo.frame.lwd,
  logo.frame.r,
  logo.group.frame,
  logo.resize_as_group,
  scalebar.breaks,
  scalebar.width,
  scalebar.text.size,
  scalebar.text.color,
  scalebar.color.dark,
  scalebar.color.light,
  scalebar.lwd,
  scalebar.bg.color,
  scalebar.bg.alpha,
  scalebar.size,
  scalebar.margins,
  scalebar.stack,
  scalebar.position,
  scalebar.frame,
  scalebar.frame.lwd,
  scalebar.frame.r,
  scalebar.group.frame,
  scalebar.resize_as_group,
  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.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.stack,
  mouse_coordinates.position,
  mouse_coordinates.show,
  minimap.server,
  minimap.toggle,
  minimap.stack,
  minimap.position,
  minimap.show,
  panel.show,
  panel.labels,
  panel.label.size,
  panel.label.color,
  panel.label.fontface,
  panel.label.fontfamily,
  panel.label.alpha,
  panel.label.bg.color,
  panel.label.frame,
  panel.label.frame.lwd,
  panel.label.frame.r,
  panel.label.height,
  panel.label.rot,
  bbox,
  qtm.scalebar,
  qtm.minimap,
  qtm.mouse_coordinates,
  earth_boundary,
  earth_boundary.color,
  earth_boundary.lwd,
  earth_datum,
  space.color,
  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,
  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,
  style,
  ...
)

Arguments