tmap in a nutshell

With the tmap package, thematic maps can be generated with great flexability. The syntax for creating plots is very similar to ggplot2. It also contains functions to deal with shape objects. Many of these functions are convenient wrappers of functions from other packages such as sp and rgeos.

Shape objects

We refer to shape objects as objects from the class Spatial from the package sp. The six supported subclasses are:

Without data With data
Polygons SpatialPolygons SpatialPolygonsDataFrame
Points SpatialPoints SpatialPointsDataFrame
Lines SpatialLines SpatialLinesDataFrame

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 saved with write_shape.

Projection can be get and set with get_projection and set_projection respectively.

Quick thematic map

Although the plotting syntax is based on ggplot, a crucial difference is that the elements are functional building blocks rather than layers from the grammar of graphics.

The qtm function is tmap's equivalent to ggplot2's qplot. The first, and only required argument is a shape object:


plot of chunk unnamed-chunk-2

A choropleth is created with one line of code:

qtm(Europe, fill="gdp_cap_est", text="iso_a3", text.cex="pop_est", title="GDP per capita", 
    textNA="Non-European countries", theme="Europe")

plot of chunk unnamed-chunk-3

The function qtm offers the same flexibility as the main plotting method (see below). However, it only supports one shape object.

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 Main arguments
tm_fill col1
tm_bubbles size1, col1
tm_lines col1, lwd1
tm_text text2, cex3
tm_borders col4, lwd4

where the numbers mean the following:

  1. These arguments can be used in two ways:
  2. The text attribute of tm_text should be the name of a data variable.
  3. The cex attribute of tm_text can be used for a constant value and a statistical variable (like number 2), but no legend is generated.
  4. Only constant values can be assigned to these arguments. For instance tm_borders(col="gray50", lwd=2).

The last plot is reproduced as follows:

tm_shape(Europe) +
    tm_fill("gdp_cap_est", textNA="Non-European countries") +
    tm_borders() +
    tm_text("iso_a3", cex="pop_est") + 
tm_layout_Europe("GDP per capita")

We call tm_shape plus the drawing layers (all of the elements in the last example except tm_layout) a group. Multiple groups can be stacked. To illustrate this, let's create a simple topographic map of Europe:


tm_shape(Europe) +
    tm_fill("pop_est_dens", style="kmeans", textNA="Non-European countries") +
    tm_borders() +
tm_shape(rivers) +
    tm_lines("dodgerblue3") +
tm_shape(cities) +
    tm_text("name", cex="pop_max", scale=1, ymod=-.02, root=4, cex.lowerbound = .60, 
            bg.color="yellow", bg.alpha = 150) + 
    tm_bubbles("pop_max", "red", border.col = "black", border.lwd=1, size.lim = c(0, 2e7)) +
tm_shape(Europe) +
    tm_text("name", cex="area", scale=1.5, root=8, cex.lowerbound = .40, 
            fontface="bold", case=NA, fontcolor = "gray35") + 
tm_layout_Europe("Map of Europe", legend.titles = c(fill="Country population density (people per km2)", 
                                                    bubble.size="City Population"))

plot of chunk unnamed-chunk-5

Thinks 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 5 main arguments (in the table above indicated by the number 1)
tm_shape(Europe) +
    tm_fill(c("pop_est_dens", "gdp_cap_est"), style="kmeans") +
tm_layout_Europe(scale=2, title = c("Population density", "GDP per capita"))

plot of chunk unnamed-chunk-6

  1. By defining a group by variable in tm_facets:
tm_shape(Europe) +
    tm_fill("gdp_cap_est", style="kmeans") +
    tm_facets("part") +
tm_layout_Europe(scale=4, legend.titles = c(fill="GDP per capita"))

plot of chunk unnamed-chunk-7

Complete workflow

Besides the ggplot2-style plotting functions, the package also offers functions to set up a workflow that is sufficient for most statistical applications.

Miscellaneous functions

Other functions, which are still in experimental stage, are:

Tips n' tricks

  1. Selections can be made by treating the data.frame of the shape object:
tm_shape(Europe[Europe$name=="Austria", ]) +
    tm_fill() +

plot of chunk unnamed-chunk-10

  1. A one-item legend can be generated by using a categorical data variable with a one category, and assigning a single color value to palette:
rivers$constant <- factor("Rivers")
tm_shape(rivers) +
    tm_lines(col="constant", palette="dodgerblue3") +
    tm_layout_World("World map")

plot of chunk unnamed-chunk-11

  1. Each drawing element has a scalar arguemnt called scale. The overall scaling and font sizes can be set by the scale argument in tm_layout.

  2. When the element tm_grid is added to the plot, grid lines are plotted.