qtm {tmap}

Quick thematic map plot

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 = NA,
  symbols.size = NULL,
  symbols.col = NULL,
  symbols.shape = NULL,
  dots.col = NULL,
  text = NULL,
  text.size = 1,
  text.col = NA,
  lines.lwd = NULL,
  lines.col = NULL,
  raster = NA,
  borders = NA,
  by = NULL,
  scale = NA,
  title = NA,
  projection = NULL,
  bbox = NULL,
  basemaps = NA,
  overlays = NA,
  style = NULL,
  format = NULL,
  ...
)

Arguments

shp

One of

• shape object, which is an object from a class defined by the sf or stars package. Objects from the packages sp and raster are also supported, but discouraged.

• Not specified, i.e. qtm() is executed. In this case a plain interactive map is shown.

• A OSM search string, e.g. qtm("Amsterdam"). In this case a plain interactive map is shown positioned according to the results of the search query (from OpenStreetMap nominatim)

fill

either a color to fill the polygons, or name of the data variable in shp to draw a choropleth. Only applicable when shp contains polygons. Set fill = NULL to draw only polygon borders. See also argument borders.

symbols.size

either the size of the symbols or a name of the data variable in shp that specifies the sizes of the symbols. See also the size argument of tm_symbols. Only applicable when shp contains spatial points, lines, or polygons.

symbols.col

either the color of the symbols or a name of the data variable in shp that specifies the colors of the symbols. See also the col arugment of tm_symbols. Only applicable when shp contains spatial points, lines, or polygons.

symbols.shape

either the shape of the symbols or a name of the data variable in shp that specifies the shapes of the symbols. See also the shape arugment of tm_symbols. Only applicable when shp contains spatial points, lines, or polygons.

dots.col

name of the data variable in shp for the dot map that specifies the colors of the dots. If dots.col is specified instead symbols.col, dots instead of bubbles are drawn (unless symbols.shape is specified).

text

Name of the data variable that contains the text labels. Only applicable when shp contains spatial points, lines, or polygons.

text.size

Font size of the text labels. Either a constant value, or the name of a numeric data variable. Only applicable when shp contains spatial points, lines, or polygons.

text.col

name of the data variable in shp for the that specifies the colors of the text labels. Only applicable when shp contains spatial points, lines, or polygons.

lines.lwd

either a line width or a name of the data variable that specifies the line width. Only applicable when shp contains spatial lines.

lines.col

either a line color or a name of the data variable that specifies the line colors. Only applicable when shp contains spatial lines.

raster

either a color or a name of the data variable that specifices the raster colors. Only applicable when shp is a spatial raster.

borders

color of the polygon borders. Use NULL to omit the borders.

by

data variable name by which the data is split, or a vector of two variable names to split the data by two variables (where the first is used for the rows and the second for the columns). See also tm_facets

scale

numeric value that serves as the global scale parameter. All font sizes, symbol sizes, border widths, and line widths are controlled by this value. The parameters symbols.size, text.size, and lines.lwd can be scaled seperately with respectively symbols.scale, text.scale, and lines.scale. See also ....

title

main title. For legend titles, use X.style, where X is the layer name (see ...).

projection

Either a crs object or a character value (PROJ.4 character string). By default, the projection is used that is defined in the shp object itself.

bbox

bounding box. Arugment passed on to tm_shape

basemaps

name(s) of the provider or an URL of a tiled basemap. It is a shortcut to tm_basemap. Set to NULL to disable basemaps. By default, it is set to the tmap option basemaps.

overlays

name(s) of the provider or an URL of a tiled overlay map. It is a shortcut to tm_tiles.

style

Layout options (see tm_layout) that define the style. See tmap_style for details.

format

Layout options (see tm_layout) that define the format. See tmap_format for details.

...

arguments passed on to the tm_* functions. The prefix of these arguments should be with the layer function name without "tm_" and a period. For instance, the palette for polygon fill color is called fill.palette. The following prefixes are supported: shape., fill., borders., polygons., symbols., dots., lines., raster., text., layout., grid., facets., and view.. Arguments that have a unique name, i.e. that does not exist in any other layer function, e.g. convert2density, can also be called without prefix.

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

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

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)