Help for package tmaptools

Type:

Package

Title:

Thematic Map Tools

Version:

3.2

Description:

Set of tools for reading and processing spatial data. The aim is to supply the workflow to create thematic maps. This package also facilitates 'tmap', the package for visualizing thematic maps.

License:

GPL-3

Encoding:

UTF-8

Date:

2025-01-13

Depends:

R (≥ 3.5), methods

Imports:

sf (≥ 0.9.2), lwgeom (≥ 0.1-4), stars (≥ 0.4-1), units (≥ 0.6-1), grid, magrittr, RColorBrewer, viridisLite, stats, dichromat, XML

Suggests:

tmap, cols4all, rmapshaper, osmdata, OpenStreetMap, raster, png, shiny, shinyjs

URL:

https://github.com/r-tmap/tmaptools, https://r-tmap.github.io/tmaptools/

BugReports:

https://github.com/r-tmap/tmaptools/issues

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-01-13 22:01:21 UTC; mtes

Author:

Martijn Tennekes [aut, cre]

Maintainer:

Martijn Tennekes <mtennekes@gmail.com>

Repository:

CRAN

Date/Publication:

2025-01-13 22:40:02 UTC

Thematic Map Tools

Description

This package offers a set of handy tool functions for reading and processing spatial data. The aim of these functions is to supply the workflow to create thematic maps, e.g. read shape files, set map projections, append data, calculate areas and distances, and query OpenStreetMap. The visualization of thematic maps can be done with the tmap package.

Details

This page provides a brief overview of all package functions.

Tool functions (shape)

`approx_areas`	Approximate area sizes of polygons
`approx_distances`	Approximate distances
`bb`	Create, extract or modify a bounding box
`bb_poly`	Convert bounding box to a polygon
`get_asp_ratio`	Get the aspect ratio of a shape object
---------------------------	---------------------------------------------------------------------------------------------------

Tool functions (colors)

`get_brewer_pal`	Get and plot a (modified) Color Brewer palette
`map_coloring`	Find different colors for adjacent polygons
`palette_explorer`	Explore Color Brewer palettes
---------------------------	---------------------------------------------------------------------------------------------------

Spatial transformation functions

`crop_shape`	Crop shape objects
`simplify_shape`	Simplify a shape
---------------------------	---------------------------------------------------------------------------------------------------

Input and output functions

`geocode_OSM`	Get a location from an address description
`read_GPX`	Read a GPX file
`read_osm`	Read Open Street Map data
`rev_geocode_OSM`	Get an address description from a location
---------------------------	---------------------------------------------------------------------------------------------------

Author(s)

Maintainer: Martijn Tennekes mtennekes@gmail.com

Pipe operator

Description

The pipe operator from magrittr, %>%, can also be used in functions from tmaptools.

Arguments

lhs

Left-hand side

rhs

Right-hand side

Approximate area sizes of the shapes

Description

Approximate the area sizes of the polygons in real-world area units (such as sq km or sq mi), proportional numbers, or normalized numbers. Also, the areas can be calibrated to a prespecified area total. This function is a convenient wrapper around st_area.

Usage

approx_areas(shp, target = "metric", total.area = NULL)

Arguments

shp

shape object, i.e., an sf or sp object.

target

target unit, one of

"prop":: Proportional numbers. In other words, the sum of the area sizes equals one.
"norm":: Normalized numbers. All area sizes are normalized to the largest area, of which the area size equals one.
"metric" (default):: Output area sizes will be either "km" (kilometer) or "m" (meter) depending on the map scale
"imperial":: Output area sizes will be either "mi" (miles) or "ft" (feet) depending on the map scale
other:: Predefined values are "km^2", "m^2", "mi^2", and "ft^2". Other values can be specified as well, in which case to is required).

These units are the output units. See orig for the coordinate units used by the shape shp.

total.area

total area size of shp in number of target units (defined by target). Useful if the total area of the shp differs from a reference total area value. For "metric" and "imperial" units, please provide the total area in squared kilometers respectively miles.

Details

Note that the method of determining areas is an approximation, since it depends on the used projection and the level of detail of the shape object. Projections with equal-area property are highly recommended. See https://en.wikipedia.org/wiki/List_of_map_projections for equal area world map projections.

Value

Numeric vector of area sizes (class units).

Examples

if (require(tmap) && packageVersion("tmap") >= "3.99") {
    data(NLD_muni)

    NLD_muni$area <- approx_areas(NLD_muni, total.area = 33893)

    tm_shape(NLD_muni) +
        tm_bubbles(size="area",
                   size.legend = tm_legend(title = expression("Area in " * km^2)))


    # function that returns min, max, mean and sum of area values
    summary_areas <- function(x) {
        list(min_area=min(x),
             max_area=max(x),
             mean_area=mean(x),
             sum_area=sum(x))
    }

    # area of the polygons
    approx_areas(NLD_muni) %>% summary_areas()

    # area of the polygons, adjusted corrected for a specified total area size
    approx_areas(NLD_muni, total.area=33893) %>% summary_areas()

    # proportional area of the polygons
    approx_areas(NLD_muni, target = "prop") %>% summary_areas()

    # area in squared miles
    approx_areas(NLD_muni, target = "mi mi") %>% summary_areas()

    # area of the polygons when unprojected
    approx_areas(NLD_muni %>% sf::st_transform(crs = 4326)) %>% summary_areas()
}

Approximate distances

Description

Approximate distances between two points or across the horizontal and vertical centerlines of a bounding box.

Usage

approx_distances(x, y = NULL, projection = NULL, target = NULL)

Arguments

x

object that can be coerced to a bounding box with bb, or a pair of coordintes (vector of two). In the former case, the distance across the horizontal and vertical centerlines of the bounding box are approximated. In the latter case, y is also required; the distance between points x and y is approximated.

y

a pair of coordintes, vector of two. Only required when x is also a pair of coordintes.

projection

projection code, needed in case x is a bounding box or when x and y are pairs of coordinates. See get_proj4

target

target unit, one of: "m", "km", "mi", and "ft".

Value

If y is specifyed, a list of two: unit and dist. Else, a list of three: unit, hdist (horizontal distance) and vdist (vertical distance).

Examples

## Not run: 
if (require(tmap)) {
    data(NLD_prov)

    # North-South and East-West distances of the Netherlands
    approx_distances(NLD_prov)

    # Distance between Maastricht and Groningen
    p_maastricht <- geocode_OSM("Maastricht")$coords
    p_groningen <- geocode_OSM("Groningen")$coords
    approx_distances(p_maastricht, p_groningen, projection = 4326, target = "km")

    # Check distances in several projections
    sapply(c(3035, 28992, 4326), function(projection) {
        p_maastricht <- geocode_OSM("Maastricht", projection = projection)$coords
        p_groningen <- geocode_OSM("Groningen", projection = projection)$coords
        approx_distances(p_maastricht, p_groningen, projection = projection)
    })
}

## End(Not run)

Bounding box generator

Description

Swiss army knife for bounding boxes. Modify an existing bounding box or create a new bounding box from scratch. See details.

Usage

bb(
  x = NA,
  ext = NULL,
  cx = NULL,
  cy = NULL,
  width = NULL,
  height = NULL,
  xlim = NULL,
  ylim = NULL,
  relative = FALSE,
  asp.limit = NULL,
  current.projection = NULL,
  projection = NULL,
  output = c("bbox", "matrix", "extent")
)

Arguments

x

One of the following:

A shape from class sf, stars, sp, or raster.
A bounding box (st_bbox, Extent (raster package, which will no longer be supported in the future versions), numeric vector of 4 (default order: xmin, ymin, xmax, ymax), or a 2x2 matrix).
Open Street Map search query. The bounding is automatically generated by querying x from Open Street Map Nominatim. See geocode_OSM

ext

Extension factor of the bounding box. If 1, the bounding box is unchanged. Values smaller than 1 reduces the bounding box, and values larger than 1 enlarges the bounding box. This argument is a shortcut for both width and height with relative=TRUE. If a negative value is specified, then the shortest side of the bounding box (so width or height) is extended with ext, and the longest side is extended with the same absolute value. This is especially useful for bounding boxes with very low or high aspect ratios.

cx

center x coordinate

cy

center y coordinate

width

width of the bounding box. These are either absolute or relative (depending on the argument relative).

height

height of the bounding box. These are either absolute or relative (depending on the argument relative).

xlim

limits of the x-axis. These are either absolute or relative (depending on the argument relative).

ylim

limits of the y-axis. See xlim.

relative

boolean that determines whether relative values are used for width, height, xlim and ylim or absolute. If x is unspecified, relative is set to "FALSE".

asp.limit

maximum aspect ratio, which is width/height. Number greater than or equal to 1. For landscape bounding boxes, 1/asp.limit will be used. The returned bounding box will have an aspect ratio between 1/asp.limit and asp.limit.

current.projection

projection that corresponds to the bounding box specified by x.

projection

projection to transform the bounding box to.

output

output format of the bounding box, one of:

"bbox" a sf::bbox object, which is a numeric vector of 4: xmin, ymin, xmax, ymax. This representation used by the sf package.
"matrix" a 2 by 2 numeric matrix, where the rows correspond to x and y, and the columns to min and max. This representation used by the sp package.
"extent" an raster::extent object, which is a numeric vector of 4: xmin, xmax, ymin, ymax. This representation used by the raster package.

Details

An existing bounding box (defined by x) can be modified as follows:

Using the extension factor ext.
Changing the width and height with width and height. The argument relavitve determines whether relative or absolute values are used.
Setting the x and y limits. The argument relavitve determines whether relative or absolute values are used.

A new bounding box can be created from scratch as follows:

Using the extension factor ext.
Setting the center coorinates cx and cy, together with the width and height.
Setting the x and y limits xlim and ylim

Value

bounding box (see argument output)

Examples

if (require(tmap) && packageVersion("tmap") >= "2.0") {

    ## load shapes
    data(NLD_muni)
    data(World)

    ## get bounding box (similar to sp's function bbox)
    bb(NLD_muni)

    ## extent it by factor 1.10
    bb(NLD_muni, ext=1.10)

    ## convert to longlat
    bb(NLD_muni, projection=4326)

    ## change existing bounding box
    bb(NLD_muni, ext=1.5)
    bb(NLD_muni, width=2, relative = TRUE)
    bb(NLD_muni, xlim=c(.25, .75), ylim=c(.25, .75), relative = TRUE)

}

## Not run: 
if (require(tmap)) {
    bb("Limburg", projection = 28992)
    bb_italy <- bb("Italy", projection = "+proj=eck4")

    tm_shape(World, bbox=bb_italy) + tm_polygons()
    # shorter alternative: tm_shape(World, bbox="Italy") + tm_polygons()
}
## End(Not run)

Convert bounding box to a spatial polygon

Description

Convert bounding box to a spatial (sfc) object . Useful for plotting (see example). The function bb_earth returns a spatial polygon of the 'boundaries' of the earth, which can also be done in other projections (if a feasible solution exists).

Usage

bb_poly(x, steps = 100, stepsize = NA, projection = NULL)

bb_earth(
  projection = NULL,
  stepsize = 1,
  earth.datum = 4326,
  bbx = c(-180, -90, 180, 90),
  buffer = 1e-06
)

Arguments

x

object that can be coerced to a bounding box with bb

steps

number of intermediate points along the shortest edge of the bounding box. The number of intermediate points along the longest edge scales with the aspect ratio. These intermediate points are needed if the bounding box is plotted in another projection.

stepsize

stepsize in terms of coordinates (usually meters when the shape is projected and degrees of longlat coordinates are used). If specified, it overrules steps

projection

projection in which the coordinates of x are provided. For bb_earth, projection is the projection in which the bounding box is returned (if possible).

earth.datum

Geodetic datum to determine the earth boundary. By default EPSG 4326.

bbx

boundig box of the earth in a vector of 4 values: min longitude, max longitude, min latitude, max latitude. By default c(-180, 180, -90, 90). If for some projection, a feasible solution does not exist, it may be wise to choose a smaller bbx, e.g. c(-180, 180, -88, 88). However, this is also automatically done with the next argument, buffer.

buffer

In order to determine feasible earth bounding boxes in other projections, a buffer is used to decrease the bounding box by a small margin (default 1e-06). This value is subtracted from each the bounding box coordinates. If it still does not result in a feasible bounding box, this procedure is repeated 5 times, where each time the buffer is multiplied by 10. Set buffer=0 to disable this procedure.

Value

sfc object

Examples

if (require(tmap) && packageVersion("tmap") >= "2.0") {
    data(NLD_muni)

    current.mode <- tmap_mode("view")
    qtm(bb_poly(NLD_muni))

    # restore mode
    tmap_mode(current.mode)
}

Calculate densities

Description

Transpose quantitative variables to densitiy variables, which are often needed for choroplets. For example, the colors of a population density map should correspond population density counts rather than absolute population numbers.

Usage

calc_densities(
  shp,
  var,
  target = "metric",
  total.area = NULL,
  suffix = NA,
  drop = TRUE
)

Arguments

shp

a shape object, i.e., an sf object.

var

name(s) of a qualtity variable name contained in the shp data

target

the target unit, see approx_areas. Density values are calculated in var/target^2.

total.area

total area size of shp in number of target units (defined by unit), approx_areas.

suffix

character that is appended to the variable names. The resulting names are used as column names of the returned data.frame. By default, _sq_<target>, where target corresponds to the target unit, e.g. _sq_km

drop

boolean that determines whether an one-column data-frame should be returned as a vector

Value

Vector or data.frame (depending on whether length(var)==1 with density values.

Examples

if (require(tmap) && packageVersion("tmap") >= "3.99") {
data(NLD_muni)

NLD_muni_pop_per_km2 <- calc_densities(NLD_muni,
  target = "km km", var = c("population", "dwelling_total"))
NLD_muni <- sf::st_sf(data.frame(NLD_muni, NLD_muni_pop_per_km2))

tm_shape(NLD_muni) +
  tm_polygons(
    fill = c("population_km.2", "dwelling_total_km.2"),
    fill.legend =
      list(
        tm_legend(expression("Population per " * km^2)),
        tm_legend(expression("Dwellings per " * km^2)))) +
tm_facets(free.scales = TRUE) +
  tm_layout(panel.show = FALSE)
}

Crop shape object

Description

Crop a shape object (from class sf, stars, sp, or raster). A shape file x is cropped, either by the bounding box of another shape y, or by y itself if it is a SpatialPolygons object and polygon = TRUE.

Usage

crop_shape(x, y, polygon = FALSE, ...)

Arguments

x

shape object, i.e. an object from class sf, stars, sp, or raster.

y

bounding box, an st_bbox, extent (raster package), or a shape object from which the bounding box is extracted (unless polygon is TRUE and x is an sf object).

polygon

should x be cropped by the polygon defined by y? If FALSE (default), x is cropped by the bounding box of x. Polygon cropping only works when x is a spatial object and y is a SpatialPolygons object.

...

not used anymore

Details

This function is similar to crop from the raster package. The main difference is that crop_shape also allows to crop using a polygon instead of a rectangle.

Value

cropped shape, in the same class as x

Examples

if (require(tmap) && packageVersion("tmap") >= "3.99") {
    data(World, NLD_muni, land, metro)

    #land_NLD <- crop_shape(land, NLD_muni)

    #qtm(land_NLD, raster="trees", style="natural")

    metro_Europe <- crop_shape(metro, World[World$continent == "Europe", ], polygon = TRUE)

    qtm(World) +
    tm_shape(metro_Europe) +
    	tm_bubbles("pop2010",
    	           col="red",
    	           size.legend = tm_legend("European cities")) +
    	tm_legend(frame=TRUE)
}

Deprecated tmaptools functions

Description

The following functions are not used anymore or deprecated as of tmaptools version 3.0. These functions are based on the sp package and are not supported anymore. They have been migrated to https://github.com/mtennekes/oldtmaptools