tmap in a nutshell

With the tmap package, thematic maps can be generated with great flexibility. The syntax for creating plots is similar to that of ggplot2. Also, the standard work flow that is needed to create a thematic map is embedded in tmap; convenient functions for reading and writing ESRI shape files, setting the proper projection, and appending data are contained in the tmap package.

Shape objects

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

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

data(Europe)

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.

Quick thematic map

Although the plotting syntax is based on that of 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:

qtm(Europe)

So, by default, the polygons (in case the shape object is a SpatialPolygons) 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="gdp_cap_est", text="iso_a3", text.cex="AREA", root=5, title="GDP per capita", 
    fill.textNA="Non-European countries", theme="Europe")

In this code, fill and text serve as aesthetics. Both gdp_cap_est 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 green, is mapped to the values of gdp_cap_est. The variable iso_a3 contained the text labels, in this case the country codes. The arguments text.cex and root determine the fontsizes of the text labels (in this case, the fifth root of the area sizes are taken). The title argument speaks for itself. The argument fill.textNA is the legend text for missing values (the gdp_cap_est variable has missing values for non-European countries). The theme argument specifies predefined layout settings for this shape object (which are in this case the inner margins).

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:

The arguments with superscript symbols can be used as aesthetics. Both constant values as well as data variable names can be assigned to these arguments. 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. Only for the five arguments with a ^*, a legend is created (and by default shown).

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="AREA", root=5) + 
tm_layout_Europe("GDP per capita")

We refer to tm_shape and its subsequent drawing layers (all of the elements in the last example except tm_layout) as a group. Multiple groups can be stacked. To illustrate this, let's create a complex map of Europe:

data(rivers)
data(cities)

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_min", scale=1, ymod=-.02, root=4, cex.lowerbound = .60, 
            bg.color="yellow", bg.alpha = .5) + 
    tm_bubbles("pop_max", "red", border.col = "black", border.lwd=1, size.lim = c(0, 11e6), sizes.legend = seq(2e6,10e6, by=2e6)) +
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 (per km2)", 
                                                    bubble.size="City Population"))

Thinks to learn from this code:

• This plot has 4 groups of layers, respectively from the shape objects Europe, rivers, cities, and again Europe. The order of (groups of) layers corresponds to the plotting order.
• The shape objects can have different projections, and can also cover different areas (bounding boxes). Both the projection and the covered area are taken from the first layer shape object. Notice that the rivers shape object also contains rivers outside Europe: see tm_shape(rivers) + tm_lines("dodgerblue3").
• The element tm_layout controls all layout options such as fonts, legends, and margins. The element tm_layout_Europe is a wrapper function with some other defaults that are tailored for Europe: for instance, the left inner margin is increased to make space for the legend.

Small multiples

Small multiples are generated in two ways:

1. By assigning multiple values to at least one of the 5 aesthetic arguments (in the table above indicated by the ^{* symbol)}

tm_shape(Europe) +
    tm_fill(c("pop_est_dens", "gdp_cap_est"), style="kmeans") +
tm_layout_Europe(title = c("Population density", "GDP per capita"))

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(legend.titles = c(fill="GDP per capita"))

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", thres.poly = 0) +
tm_facets("name", free.coords=TRUE, drop.shapes=TRUE) +
    tm_layout(legend.show = FALSE, title.position = c("center", "center"), title.cex = 2)

Remarks: the argument drop.shapes is used to drop all non-selected shapes. If drop.shapes=FALSE then neighboring countries are also visible. The argument thres.poly is set to 0 in order to calculate the aesthetics for all polygons, so also for very small ones, like Vatican.

Complete work flow for creating thematic maps

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

• Loading and preprocessing shape objects

  • read ESRI shape files and write them with respectively read_shape and write_shape;
  • check and if necessary change map projections with get_projection and set_projection;
  • crop shape objects with crop_shape;
  • append data with append_data;
  • approximate area sizes and calculate density variables respectively with approx_areas and calc_densities.
  • split or combine shape objects with split and sbind

• Plotting shape objects

  • With the quick plotting function qtm, or the main plotting method.

• Saving the output for publication and presentation

  • With the usual R functions to save a pdf, png, jpeg, etc.:

  pdf("my_map.pdf", width=10, height=6)
  tm_shape(Europe) +
      tm_fill("gdp_cap_est", textNA="Non-European countries") +
      tm_borders() +
      tm_text("iso_a3", cex="AREA", root=5) + 
  tm_layout("GDP per capita")      
  dev.off()
  

  The scale argument in tm_layout is very useful as overall scalar (similar to the scale argument in ggplot2's ggsave).

  • Create animations (gif or mpeg) from a series of tmap plots animation_tmap:

  animation_tmap({
      tm_shape(Europe) + 
          tm_fill("yellow") + 
          tm_borders() + 
          tm_facets(by = "name", nrow=1,ncol=1)
  }, width=1200, height=800, filename="my_animation.gif")
  

  Notice that, in order to create a series of plots where one map is shown at a time, both nrow and ncol are set to 1 in tm_facets.

Miscellaneous functions

Some other functions which may be helpful:

• convert shape data to different regional classifications with convert_shape_data;
• get ID's of the shape items with get_IDs;
• get ranges of the polygons with get_polygon_ranges.

Miscellaneous functions for processing purposes, which are in experimental stage:

• double_line to create a double polyline (railway track);
• fit_polylines to fit a polyline from a set of spatial points;
• get_' and 'set_polygon_directions to get and set the polygon directions;
• map_points_to_line to map points to a spatial lines object;
• split_lines_equal to split polylines into parts of equal length;
• split_lines_poly to split polylines by a polygon shape object.

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() +
    tm_borders()

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:

data(World)

rivers$constant <- factor("Rivers")
tm_shape(World) +
    tm_fill() +
tm_shape(rivers) +
    tm_lines(col="constant", palette="dodgerblue3") +
    tm_layout_World("World map")

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.