With the tmap package, thematic maps can be generated with great flexibility. The syntax for creating plots is similar to that of ggplot2. The tmap package also contains many facility functions for reading and processing shape files (see overview). This vignette will focus on the core business of tmap, which is plotting maps.

Static plot and interactive view

Each map can be plotted as a static map and shown interactively. These two modes, called the "plot" mode and the "view" mode respectively, are described in vignette("tmap-modes"). In the remainder of this vignette, the "plot" mode is used.

Shape objects

We refer to shape objects as objects from the class Spatial or Raster, respectively from the sp and the raster package. The supported subclasses are:

Without data With data
Polygons SpatialPolygons SpatialPolygonsDataFrame
Points SpatialPoints SpatialPointsDataFrame
Lines SpatialLines SpatialLinesDataFrame
Raster SpatialGrid SpatialGridDataFrame
Raster SpatialPixels SpatialPixelsDataFrame
Raster RasterLayer
Raster RasterBrick
Raster RasterStack

Obviously, shape objects with data (the right-hand side column) are recommended, since data is what we want to show.

Load shape object of Europe (contained in this package):


Shape objects in ESRI format can be read with read_shape and written with write_shape. Projection can be get and set with get_projection and set_projection respectively. Note: projections can also directly (and temporarily) be set in the plotting method (as argument of tm_shape, see below).

Quick thematic map

The plotting syntax is based on that of ggplot2. The qtm function is tmap’s equivalent to ggplot2’s qplot. The first, and only required argument is a shape object:


So, by default, the polygons (in case the shape object is a SpatialPolygonsDataFrame) are filled with light grey, and the polygon borders are drawn in dark grey.

A choropleth is created with the following code:

qtm(Europe, fill="well_being", text="iso_a3", text.size="AREA", format="Europe", style="gray", 
    text.root=5, fill.title="Well-Being Index", fill.textNA="Non-European countries")

In this code, fill,text, and text.size serve as aesthetics. Both well_being and iso_a3 are variables of the data contained in the shape object Europe. A color palette, in this case the qualitative palette from yellow to brown, is mapped to the values of well_being. The variable iso_a3 contains the text labels, in this case the country codes. The value "AREA" is a derived variable that contains the polygon area sizes. So text is sized increasingly with coutry area size.

The two arguments format and style are predefined layout settings (see layout).

The other arguments are passed on to the layer functions, which are described below. The argument text.root determines how text size is increased; in this case, the fifth root of the area sizes are taken. The result is that the text label for Russia does not dominate the other text labels. The fill.title argument is the title for the fill-legend. The argument fill.textNA is the legend text for missing values.

The function qtm offers the same flexibility as the main plotting method (to be described next). However, for more complex plots, the main plotting method is recommended for tis readability.

Plotting with tmap elements

The main plotting method, the equivalent to ggplot2’s ggplot, consists of elements that start with tm_. The first element to start with is tm_shape, which specifies the shape object. Next, one, or a combination of the following drawing layers should be specified:

Drawing layer Description Aesthetics
Base layer
tm_polygons Draw polygons col
tm_symbols Draws symbols size, col, shape
tm_lines Draws polylines col, lwd
tm_raster Draws a raster col
tm_text Add text labels text, size, col
Derived layer
tm_fill Fills the polygons see tm_polygons
tm_borders Draws polygon borders none
tm_bubbles Draws bubbles see tm_symbols
tm_sqaures Draws squares see tm_symbols
tm_dots Draws dots see tm_symbols
tm_markers Draws markers see tm_symbols and tm_text
tm_iso Draws iso/contour lines see tm_lines and tm_text

Each aesthetic can take a constant value or a data variable name. For instance, tm_fill(col="blue") colors all polygons blue, while tm_fill(col="var1"), where "var1" is the name of a data variable in the shape object, creates a choropleth. If a vector of constant values or variable names are provided, small multiples are created.

The following layers are map attributes:

Attribute layer Description
tm_grid Add coordinate grid lines
tm_credits Add credits text label
tm_compass Add map compass
tm_scale_bar Add scale bar

The last plot is reproduced as follows:

tm_shape(Europe) +
    tm_polygons("well_being", textNA="Non-European countries", title="Well-Being Index") +
    tm_text("iso_a3", size="AREA", root=5) + 
tm_format_Europe() +

We refer to tm_shape and its subsequent drawing layers as a group. Multiple groups can be stacked. To illustrate this, let’s create a topographic map of Europe:

data(land, rivers, metro)

tm_shape(land) + 
    tm_raster("trees", breaks=seq(0, 100, by=20), legend.show = FALSE) +
tm_shape(Europe, is.master = TRUE) +
    tm_borders() +
tm_shape(rivers) +
    tm_lines(lwd="strokelwd", scale=5, legend.lwd.show = FALSE) +
tm_shape(metro) +
    tm_bubbles("pop2010", "red", border.col = "black", border.lwd=1, 
        size.lim = c(0, 11e6), sizes.legend = c(1e6, 2e6, 4e6, 6e6, 10e6), 
        title.size="Metropolitan Population") +
    tm_text("name", size="pop2010", scale=1, root=4, size.lowerbound = .6, 
        bg.color="white", bg.alpha = .75, 
        auto.placement = 1, legend.size.show = FALSE) + 
tm_format_Europe() +

Things to learn from this code:

Small multiples

Small multiples are generated in two ways:

1. By assigning multiple values to at least one of the aesthetic arguments:

tm_shape(Europe) +
    tm_polygons(c("HPI", "gdp_cap_est"), 
        style=c("pretty", "kmeans"),
        palette=list("RdYlGn", "Purples"),
        title=c("Happy Planet Index", "GDP per capita")) +
tm_format_Europe() + 

In this case, two independent maps are created, with different scales. All arugments of the layer functions can be vectorized, one for each small multiple. Arugments that normally can take a vector, such as palette should be placed in a list.

This method is normally used to show two totally different variables, such as in this example Happy Planet Index and GDP. However, it is also possible to show variables that are related, as if they are subsets from the same data:

tm_shape(metro) +
    tm_bubbles(size=c("pop1970", "pop2020"), title.size="Population") +
    tm_facets(free.scales=FALSE) +
tm_layout(panel.labels=c("1970", "2020"))

Notice that this plot uses panels and that the common legend is plot outside of the maps.

2. By defining a group-by variable in tm_facets:

tm_shape(Europe) +
    tm_polygons("well_being", title="Well-Being Index") +
    tm_facets("part") +

This plot also uses the panel layout with the common legend drawn outside the maps. These options can be changed with the arguments panel.show and legend.outside of tm_layout. By default, the panel/external legend layout is used when the group-by variable is specified, since in that case, the multiples share a common legend.

The scales of each aesthetic argument can be set to either fixed or free, and also, the coordinate ranges of the small multiples:

tm_shape(Europe[Europe$continent=="Europe",]) +
    tm_fill("part", legend.show = FALSE) +
    tm_facets("name", free.coords=TRUE, drop.units=TRUE)