tm_shape: Specify the shape object

Description

Creates a tmap-element that specifies a spatial data object, which we refer to as shape. Also the projection and covered area (bounding box) can be set. It is possible to use multiple shape objects within one plot (see tmap-element).

Usage

tm_shape(
  shp,
  name = NULL,
  is.master = NA,
  projection = NULL,
  bbox = NULL,
  unit = NULL,
  simplify = 1,
  point.per = NA,
  line.center = "midpoint",
  filter = NULL,
  raster.downsample = TRUE,
  raster.warp = TRUE,
  ...
)

Value

tmap-element

Arguments

shp

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.

name

name of the shape object (character) as it appears in the legend in "view" mode. Default value is the name of shp.

is.master

logical that determines whether this tm_shape is the master shape element. The bounding box, projection settings, and the unit specifications of the resulting thematic map are taken from the tm_shape element of the master shape object. By default, the first master shape element with a raster shape is the master, and if there are no raster shapes used, then the first tm_shape is the master shape element.

projection

Map projection (CRS). 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. One of the following:

A bounding box (an sf bbox object, see st_bbox, or any object that can be read by bb.
Open Street Map search query. The bounding is automatically generated by querying q from Open Street Map Nominatim. See https://wiki.openstreetmap.org/wiki/Nominatim.
Another shape object, from which the bounding box is extracted.

If unspecified, the current bounding box of shp is taken. The bounding box is feed to bb (as argument x. The other arguments of bb can be specified directly as well (see ..).

unit

desired units of the map. One of "metric" (default), "imperial", "km", "m", "mi" and "ft". Used to specify the scale bar (see tm_scale_bar) and to calculate densities for choropleths (see argument convert2density in tm_fill).

simplify

simplification factor for spatial polygons and spatial lines. A number between 0 and 1 that indicates how many coordinates are kept. See the underlying function simplify_shape, from which the arguments keep.units and keep.subunits can be passed on (see ...). This requires the suggested package rmapshaper.

point.per

specification of how points or text labels are plotted when the geometry is a multi line or a multi polygon. One of "feature", "segment" or "largest". The first generates a point/label for every feature, the second for every segment (i.e. subfeature), the third only for the largest segment (subfeature). Note that the last two options can be significant slower. By default, it is set to "segment" if the geometry of shp is a (multi)points geometry or a geometrycollection, and "feature" otherwise.

line.center

specification of where points are placed for (multi)line geometries. Either "midpoint" or "centroid". The former places a point at the middle of the line, the latter at the controid.

filter

logical vector which indicated per feature whether it should be included. Features for which filter is FALSE will be colored light gray (see the colorNULL argument in the layer functions)

raster.downsample

Should a raster shape (i.e. stars object) be downsampled when it is loo large? What is too large is determined by the tmap option max.raster (see tmap_options). If it is downsampled, it will be downsampled to approximately max.raster cells. A message will be shown with the exact size.

raster.warp

Should a raster shape (i.e. stars object) be warped when the map is shown in different map projection (CRS)? If TRUE (default) the raster is warped to a regular grid in the new projection. Otherwise, the raster shape is transformed where the original raster cells are kept intact. Warping a raster is much faster than transforming. Note that any raster shape with a projection other than 4326 will have to be warped or transformed in view mode.

...

Arguments passed on to bb (e.g. ext can be used to enlarge or shrinke a bounding box), and simplify_shape (the arguments keep.units and keep.subunits)

References

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

Examples

Run this code

current.mode <- tmap_mode("plot")

data(World, metro, rivers)

tm_shape(World) + 
    tm_polygons() + 
tm_layout("Long lat coordinates (WGS84)", inner.margins=c(0,0,.1,0), title.size=.8)

World$highlighted <- ifelse(World$iso_a3 %in% c("GRL", "AUS"), "gold", "gray75")
tm_shape(World, projection=3857, ylim=c(.1, 1), relative = TRUE) + 
    tm_polygons("highlighted") + 
tm_layout("Web Mercator projection. Although widely used, it is discouraged for
statistical purposes. In reality, Australia is 3 times larger than Greenland!",
    inner.margins=c(0,0,.1,0), title.size=.6)

tm_shape(World, projection="+proj=robin") + 
    tm_polygons() +
tm_layout(
"Winkel-Tripel projection, adapted as default by the National Geographic Society for world maps.",
    inner.margins=c(0,0,.1,0), title.size=.8)

tm_shape(World, projection="+proj=eck4") +
    tm_polygons() + 
tm_layout("Eckhart IV projection. Recommended in statistical maps for its equal-area property.",
    inner.margins=c(0,0,.1,0), title.size=.8)


# different levels of simplification
if (FALSE) {
tm1 <- tm_shape(World, projection="+proj=eck4", simplify = 0.05) + tm_polygons() + 
    tm_layout("Simplification: 0.05")
tm2 <- tm_shape(World, projection="+proj=eck4", simplify = 0.1) + tm_polygons() + 
    tm_layout("Simplification: 0.1")
tm3 <- tm_shape(World, projection="+proj=eck4", simplify = 0.25) + tm_polygons() + 
    tm_layout("Simplification: 0.25")
tm4 <- tm_shape(World, projection="+proj=eck4", simplify = 0.5) + tm_polygons() + 
    tm_layout("Simplification: 0.5")

require(tmaptools)
tmap_arrange(tm1, tm2, tm3, tm4)
}

# three groups of layers, each starting with tm_shape
if (FALSE) {
tm_shape(World, projection="+proj=eck4") +
    tm_fill("darkolivegreen3") +
tm_shape(metro) +
    tm_bubbles("pop2010", col = "grey30", scale=.5) +
tm_shape(rivers) +
    tm_lines("lightcyan1") +
tm_layout(bg.color="lightcyan1", inner.margins=c(0,0,.02,0), legend.show = FALSE)
}

# restore current mode
tmap_mode(current.mode)