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 = 1)

Static maps (plot mode)

Maps in plot mode van be exported in many formats including:

pixel based png, jpg, bmp, tiff.

vectorized pdf, eps, svg, and

The width and height are specified in either pixels or inches (you can don't need to specify the units).

For the pixel based formats, the relation between pixels and inches are specified via the argument dpi (dots-per-inch).

Let's create a standard country level choropleth:

tm = tm_shape(World, crs = "+proj=robin") + 
  tm_polygons(
    fill = "gender", 
    fill.scale = tm_scale_continuous(values = "pu_gn"),
    fill.legend = tm_legend("Gender Inequality Index", orientation = "landscape")) +
    tm_credits("Human Development Report (2024)", position = c("RIGHT", "BOTTOM")) + 
tm_layout(inner.margins = c(0, 0, 0.05, 0.05))

Pixel based format

Exporting maps is done via tmap_save().

tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300)

Values of width and height less than 50 are considered inches, whereas greater than 50 pixels are considered pixels:

tmap_save(tm, filename = "world.png", width = 2100, height = 1200, dpi = 300)

Therefore, both examples result in the exactly the same file:

tm + tm_layout(scale = 1)

Vector based formats are preferred over pixel based, because of the scalability. In case pixel formats are used, please make to use a sufficient number of pixels. For web publications at least 144 dpi is required. This may seem overkill, but is required for retina (high point-per-inch) displaces. For printing 300 or even 600 dpi is required.

Aspect ratio

In case only one dimension is provided, the other dimension calculated using the aspect ratio of the map.

tmap_save(tm, filename = "world.png", width = 2100, dpi = 300)

tm + tm_layout(scale = 1)

Vector based format

Vector based formats will look (almost) the same.

tmap_save(tm, filename = "world.pdf", width = 7, height = 4, dpi = 300)

Small differences in font sizes, margins, symbol sizes between formats may occur.

Scaling

An important argument of tmap_save() is scale. It an option for the overall scale over the map, which is normally set via tm_layout(). It determines all font sizes, line widths, and symbol sizes.

Much smaller (0.5):

tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 0.5)

tm + tm_layout(scale = 0.5)

A bit smaller (0.8):

tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 0.8)

tm + tm_layout(scale = 0.8)

A bit larger (1.2):

tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 1.2)

tm + tm_layout(scale = 1.2)

Much larger (1.5):

tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 1.5)

tm + tm_layout(scale = 1.5)

View mode

Maps can also be exported as stand-alone HTML files.

tmap_save(tm, filename = "index.html", selfcontained = FALSE)

When selfcontained = FALSE, the required JavaScripts and CSS files are stored in a folder called index_files.

r-tmap/tmap documentation built on Feb. 28, 2025, 7:54 a.m.