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

data(Europe)


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:

qtm(Europe)


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


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:
• To assign fixed, constant values. For instance tm_fill(col="blue").
• To assign a data variable. For instance tm_fill(col="var1"), where "var1" is the name of a data variable in the shape object. This variable can be numerical, and in case of a color attribute, also categorical (i.e., factor). These 5 arguments are currently the only statistical attributes for which also a legend is generated.
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:

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_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"))


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. The plot tm_shape(rivers) + tm_lines("dodgerblue3") will show the rivers around the world in latitute longitude coordinates.
• The element tm_layout controls all layout options such as fonts, legends, and margins. The element tm_layout_Europe is identical with other defaults that are tailored for Europe: 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 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"))


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


### 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() + 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: rivers$constant <- factor("Rivers")
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.