Specify the shape object

Creates a tmap-element that specifies the shape object. 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).

tm_shape(shp, name = NULL, is.master = NA, projection = NULL,
  bbox = NULL, unit = getOption("tmap.unit"), simplify = 1, = c("segment", "midpoint"), ...)

shape object, which is one of

  1. SpatialPolygons(DataFrame)

  2. SpatialPoints(DataFrame)

  3. SpatialLines(DataFrame)

  4. SpatialGrid(DataFrame)

  5. SpatialPixels(DataFrame)

  6. RasterLayer, RasterStack, or RasterBrick

Simple features (sf objects) are also supported. For drawing layers tm_fill and tm_borders, 1 is required. For drawing layer tm_lines, 3 is required. Layers tm_symbols and tm_text accept 1 to 3. For layer tm_raster, 4, 5, or 6 is required.


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


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.


Either a CRS object or a character value. If it is a character, it can either be a PROJ.4 character string or a shortcut. See get_proj4 for a list of shortcut values. By default, the projection is used that is defined in the shp object itself, which can be obtained with get_projection.


bounding box. One of the following:

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


desired units of the map. One of "metric" (default), "imperial", "km", "m", "mi" and "ft". For other units, please specify orig and to, which are passed on to projection_units. Used to specify the scale bar (see tm_scale_bar) and to calculate densities for choropleths (see argument convert2density in tm_fill).


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

vector of two values specifying how the center of spatial lines is determined Only applicable if shp is a SpatialLines(DataFrame), and symbols, dots, and/or text labels are used for this shape. The two values are:

"feature", "single"

If "feature" is specified, a pair of coordinates (used for symbols, dots, and text labels) is chosen for each feature (i.e., a row in the SpatialLines(DataFrame)). If "segment" is specified, a pair of coordinates is chosed for each line segment.

"midpoint" or "centroid"

The midpoint is the middle point on the line, so the coordinates (used for symbols, dots, and text labels) correspond to the midpoints of the line segments. In case the first value is "feature", then per feature, the midpoint of the line segment that is closest to the centroid is taken.


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



See Also

read_shape to read ESRI shape files, set_projection, vignette("tmap-nutshell")

  • tm_shape
current.mode <- tmap_mode("plot")

data(World, metro, rivers)

tm_shape(World, projection="longlat") + 
    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="merc", 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="wintri") + 
    tm_polygons() +
"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) +
    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
# }
tm1 <- tm_shape(World, simplify = 0.05) + tm_polygons() + tm_layout("Simplification: 0.05")
tm2 <- tm_shape(World, simplify = 0.1) + tm_polygons() + tm_layout("Simplification: 0.1")
tm3 <- tm_shape(World, simplify = 0.25) + tm_polygons() + tm_layout("Simplification: 0.25")
tm4 <- tm_shape(World, simplify = 0.5) + tm_polygons() + tm_layout("Simplification: 0.5")

tmap_arrange(tm1, tm2, tm3, tm4)
# }
# three groups of layers, each starting with tm_shape
# }
tm_shape(World) +
    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), = FALSE)
# }
# restore current mode
# }
Documentation reproduced from package tmap, version 1.11, License: GPL-3

Community examples

Looks like there are no examples yet.