tmap/README.Rmd at master · r-tmap/tmap · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
---
output: github_document
editor_options:
  chunk_output_type: console
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  out.width = "100%",
  dpi = 300,
  fig.width = 7.2916667,
  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 <img src="man/figures/logo.png" align="right" height="139" alt="" />

<!-- badges: start -->
[![R-CMD-check](https://github.com/r-tmap/tmap/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-tmap/tmap/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/r-tmap/tmap/branch/master/graph/badge.svg)](https://app.codecov.io/gh/r-tmap/tmap?branch=master)
[![CRAN](https://www.r-pkg.org/badges/version/tmap)](https://cran.r-project.org/package=tmap)
[![CRAN checks](https://badges.cranchecks.info/worst/tmap.svg)](https://cran.r-project.org/web/checks/check_results_tmap.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/tmap?color=brightgreen)](https://www.r-pkg.org:443/pkg/tmap)
[![License](https://img.shields.io/badge/License-GPL%20v3-brightgreen.svg?style=flat)](https://www.gnu.org/licenses/gpl-3.0.html)
[![r-universe](https://r-tmap.r-universe.dev/badges/tmap)](https://r-tmap.r-universe.dev/tmap)
<!-- badges: end -->

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

## Installation

Installation of **tmap** is straightforward:

```{r eval=FALSE}
install.packages("tmap")
```

In case it fails, please check the dependencies below.

### Development version

The development version can be installed from the GitHub repository using one of the following functions:

```{r eval=FALSE}
# install.packages("remotes")
remotes::install_github("r-tmap/tmap")

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

## Dependencies

tmap depend on other R packages, which will automatically be installed along. However, two packages **sf** and **s2** have additional system requirements: for Windows users, these are also installed along. For Linux and MacOS users, these additional libraries may need to be installed manually.

Instructions for the libraries GEOS, GDAL and PROJ (required by **sf**): see the installation instructions of **terra** which requires the same libraries: [MacOS](https://rspatial.github.io/terra/index.html?q=installation#macos) and [Linux](https://rspatial.github.io/terra/index.html?q=installation#linux)

Instructions for the libraries Abseil and OpenSS (required by **s2**): see the [installation instructions](https://r-spatial.github.io/s2/#installation).

## Getting started

```{r echo=FALSE, message=FALSE}
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**:

```{r fig.height=3.5, message=FALSE}
tm_shape(World) +
	tm_polygons(fill = "HPI")
```

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

```{r fig.height=4.5}
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)
				)
```

<!--
## Online tmap course

10-14 November 2025, organized jointly by [PRStats](https://www.prstats.org/course/spatial-data-visualisation-and-mapping-using-tmap-tmap02/) and [Instats](https://instats.org/seminar/spatial-data-analysis-and-visualization-1)
-->

## Additional Resources for Learning **tmap**

For more in-depth learning on the **tmap** package, refer to the following resources:

- **Book Chapter:** [Geocomputation with R](https://r.geocompx.org/) includes a chapter on [Making Maps with R](https://r.geocompx.org/adv-map), which covers **tmap**.
- **Official Vignettes:** A collection of vignettes at [r-tmap.github.io](https://r-tmap.github.io/tmap/articles/) covers both basic and advanced topics with examples.
- **Work-in-Progress Book:** *Spatial Data Visualization with tmap: A Practical Guide to Thematic Mapping in R* is an upcoming book available at [tmap.geocompx.org](https://tmap.geocompx.org/).

These resources provide a solid foundation for working with **tmap** in R.

[3]: https://cran.r-project.org/package=ggplot2
[4]: https://vita.had.co.nz/papers/layered-grammar.pdf