---

output: github_document
editor_options:
chunk_output_type: console

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
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)
 })

tmap: thematic maps in R

tmap is an R package for drawing thematic maps. The API is based on A Layered Grammar of Graphics and resembles the syntax of ggplot2, a popular R-library for drawing charts.

Installation

Installation of tmap (version 4) is straightforward:

# install.packages("remotes")
install_github("r-tmap/tmap")

# On Linux, with pak
# install.packages("pak")
pak::pak("r-tmap/tmap")

# Or from r-universe
install.packages("tmap", repos = c("https://r-tmap.r-universe.dev", "https://cloud.r-project.org"))

The old version of tmap (version 3) is available on , but we recommend to use version 4, which will be on CRAN soon.

For Linux and macOS users who are new to working with spatial data in R, this may fail since additional (non-R) libraries are required (which are automatically installed for Windows users).

Windows
No additional installation required.

Linux (Ubuntu)
See https://geocompx.org/post/2020/installing-r-spatial-packages-linux/. Please address installation issues in this issue.

macOS
See https://www.kyngchaos.com/. Please address installation issues in this issue.

Getting started

library(tmap)

Plot a World map of the happy planet index (HPI) per country.
The object World is an example spatial data (sf) object that is contained in tmap:

tm_shape(World) +
	tm_polygons(fill = "HPI")

This map can be enhanced in several ways.
For instance:

tm_shape(World, crs = "+proj=robin") +
	tm_polygons(fill = "HPI",
				fill.scale = tm_scale_continuous(values = "matplotlib.rd_yl_bu"),
				fill.legend = tm_legend(title = "Happy Planet Index",
										orientation = "landscape", 
										frame = FALSE)
				)

Book chapter about tmap

The book Geocomputation with R provides a chapter on Making maps with R, including a section on tmap.