In r-tmap/tmap: Thematic Maps

knitr::opts_chunk$set(
  collapse = TRUE,
  out.width = "100%",
  dpi = 300,
  fig.width = 7.2916667,
  comment = "#>"
)
hook_output <- knitr::knit_hooks$get("output")
knitr::knit_hooks$set(output = function(x, options) {
   lines <- options$output.lines
   if (is.null(lines)) {
     return(hook_output(x, options))  # pass to default hook
   }
   x <- unlist(strsplit(x, "\n"))
   more <- "..."
   if (length(lines)==1) {        # first n lines
     if (length(x) > lines) {
       # truncate the output, but add ....
       x <- c(head(x, lines), more)
     }
   } else {
     x <- c(more, x[lines], more)
   }
   # paste these lines together
   x <- paste(c(x, ""), collapse = "\n")
   hook_output(x, options)
 })

library(tmap)
tmap_options(scale = 0.75)

Introduction

tmap is an R package for spatial data visualization.

Map layers

A (thematic) map consists of one or more map layers. Each map layer has a specific set of variables that determine how the objects of that layer are drawn. A visual variable changes the appearance of a spatial object, e.g. fill color or line width.

The following table shows which visual variables are used in standard map layers.

|Map layer |Visual variables | |:--------------|:--------------------------------------------------------------| |tm_polygons |fill (fill color), fill_alpha (fill transparency),
col (border color), col_alpha (border color transparency)
lwd (border line width), lty (border line type) | |tm_symbols |size, shape
fill (fill color), fill_alpha (fill transparency),
col (border color), col_alpha (border color transparency)
lwd (border line width) lty (border line type) | |tm_lines |col (border color), col_alpha (border color transparency)
lwd (line width) lty (line type) | |tm_raster |col (color), col_alpha (transparency) | |tm_text |text (the text itself), size (font size),
col (border color), col_alpha (border color transparency)
fontface (font face), fontfamily (font family) |

About the example data

A spatial data object contained in tmap is called World. It is a data frame with a row for each country. The columns are the following data variables plus an additional geometry column which contains the geometries (see sf package):

names(World)

We specify this object with tm_shape and for convenience assign it to s:

s <- tm_shape(World, crs = "+proj=eqearth")

Constant visual values

Each visual variable can be assigned with a contant value. E.g. fill = "red" or size = 2.

An example where several visual variables are specified with constant values:

s + 
  tm_polygons(
    fill = "#ffce00", # fill color
    col = "black",    # line color
    lwd = 0.5,        # line width
    lty = "dashed")   # line type

For advanced users: the default constant values are specified for combinations of visual variables and layer type. See tmap_options("value.const")

Data-driven visual variables

Each visual variable argument can also be specified with a data variable (e.g., a column name):

s + tm_polygons(fill = "press")    # a column in World

Another example, where a data-driven symbol layer is drawn on top of a polygon layer

s + 
  tm_polygons(fill = "grey90") +   # constant fill color 
  tm_symbols(size = "pop_est",     # data variable, mapped to symbol size
             fill = "well_being",  # data variable, mapped to symbol fill color
             shape = "income_grp") # data variable, mapped to symbol shape

In the following example a data-driven text layer is plotted.

s + 
  tm_polygons(fill = "economy") +
  tm_text(text = "name", size = "area")

Scales and legend

For each data-driven visual variable, a scale and legend can be specified. See other vignettes.

Facets

A facet map is created by specifying two data variables (columns in World) to the visual variable fill:

s + tm_polygons(fill = c("well_being", "life_exp"))

Improve the titles and remove (duplicate) legend titles

s + 
  tm_polygons(
    fill = c("well_being", "life_exp"),
    fill.legend = tm_legend("")) +
tm_layout(panel.labels = c("Well Being", "Life Expectancy"))