forked from r-tmap/tmap
/
tmap-changes.Rmd
167 lines (127 loc) · 8.08 KB
/
tmap-changes.Rmd
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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
---
title: "tmap: version changes"
output:
rmarkdown::html_vignette:
keep_md: true
toc: true
self_contained: no
vignette: >
%\VignetteIndexEntry{tmap: version changes}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
---
```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(collapse = TRUE, fig.width=6, fig.height=3)
#devtools::install_github(`mtennekes/tmaptools`)
library(tmap)
library(sf)
```
This vignette summarizes the main changes in tmap 2.x/3.x in comparison to tmap 1.11-2, which is described in detail in the [JSS paper](https://www.jstatsoft.org/article/view/v084i06). The code of this paper for version 2.x/3.x can be found in [`vignette("tmap-JSS-code")`](../doc/tmap-JSS-code.html).
For people who are new to tmap, see [`vignette("tmap-getstarted")`](../doc/tmap-getstarted.html).
### Function renaming: tm_ and tmap_
As of version 2.0, all tmap functions have the prefix `tm_` or `tmap_`, with the exception of the function `qtm`.
Just like in tmap version 1.x, the layer functions start with `tm_`.
In tmap 1.x, the names of the other functions where inconsistent, e.g. `animation_tmap` and `tmap_arrange`.
In tmap 2.x/3.x, these functions are prefixed with `tmap_`.
For instance `animation_tmap` has been renamed to `tmap_animation`.
### Spatial data classes
tmap 1.x uses `sp` for representing vector data, and `raster` for raster data.
tmap 2.x uses `sf` for representing vector data, and `raster` for raster data.
tmap 3.x uses `sf` for representing vector data, and `stars` for raster data.
`sf` (**s**imple **f**eatures) objects have a simpler structure than `sp` objects.
An `sf` object is nothing more than a `data.frame` with a special geometry column that contains the geometries for the corresponding rows.
Such a geometry can be of type spatial point(s), line(s) or polygon(s) or any combination of these in a 'geometrycollection' (see [`vignette("sf1")`](https://CRAN.R-project.org/package=sf/vignettes/sf1.html)).
The layers functions, such as `tm_polygons`, will only draw what they are supposed to draw (in this case polygons).
The newly added layer function `tm_sf` will draw all geometries.
Finally, all data objects in `tmap` (except `land`) have been transformed into `sf` objects.
The object `land` has been transformed into a `stars` object.
### tm_tiles
Layer functions have been added to facilitate tile layers.
In version 1.x, it was already possible to add basemaps.
In version 2.0, this is facilitated by the explicit layer functions `tm_basemap` and `tm_tiles`.
The former creates a basemap tile and the latter an overlay tile.
The difference is that `tm_basemap` layers are always drawn at the bottom, whereas the plotting order of (overlay) `tm_tiles` layers is derived from the plot call.
Overlay layers should be semi-transparent to be useful.
Tip: all tilemaps from https://leaflet-extras.github.io/leaflet-providers/preview/ can be used.
The names of these maps can also be found in the list object `leaflet::providers`.
```{r, eval = FALSE}
data(World, metro)
tmap_mode("view")
tm_basemap(leaflet::providers$CartoDB.PositronNoLabels, group = "CartoDB basemap") +
tm_shape(World) +
tm_polygons("HPI", group = "Countries") +
tm_tiles(leaflet::providers$CartoDB.PositronOnlyLabels, group = "CartoDB labels") +
tm_shape(metro) +
tm_dots(col = "red", group = "Metropolitan areas")
```
<img src="images/tmap_tiles_labels.jpg" alt="sigma" data-toggle="tooltip" data-placement="right" title="" data-original-title="Note this is just a screenshot of the visualization so it's not interactive. You can play with the interactive version by running the code above." onload="$(this).tooltip()">
### tmap options, styles, and formats
There are many options in tmap.
In version 1.x, the default values were stored in `tm_layout` and `tm_view`.
Wrapper functions like `tm_style_gray` and `tm_format_World` where used to change these options.
In version 2.0, the options are stored in a similar fashion to the global options.
A list of tmap options can be retrieved and options can be set with the function `tmap_options`.
Its behavior is similar to the base function `options`.
A style is a configuration of the options used to style a map in a specific way.
When set with `tmap_style`, the current options are overwritten according to the new style.
The changes can be seen with `tmap_options_diff` and can be reset with `tmap_options_reset`.
```{r, fig.height=3}
data(World)
qtm(World, fill = "life_exp")
tmap_style("classic")
qtm(World, fill = "life_exp")
tmap_options_diff()
tmap_options_reset()
```
Styles included in tmap are: `"white"`, `"gray"`, `"natural"`, `"cobalt"`, `"col_blind"`, `"albatross"`, `"beaver"`, `"bw"`, `"classic"`.
New styles can saved and loaded with `tmap_style_save` and `tmap_style_load` respectively.
In version 1.x, `tmap` contained a couple of predefined format functions, such as `tm_format_World`.
In version 2.0, these have been replaced by the general function `tm_format`.
With this function, the available formats can be retrieved, as well as the configuration of a specific format.
With the function `tm_format_add` new formats can be created.
```{r}
tmap_format()
panorama <- tmap_format("World")
panorama$asp <- 6
tmap_format_add(panorama, name = "panorama")
tmap_format()
```
Unlike a style, a format cannot be set globally.
Instead, it has to be specified in each plot:
```{r, fig.height = 1}
tm_shape(World) + tm_polygons("HPI") + tm_format("panorama")
# or: qtm(World, fill = "HPI", format = "panorama")
```
### color palettes
Viridis palettes (from the `viridis`/`viridisLite` package) are supported natively.
E.g. `qtm(World, "HPI", fill.palette = "-plasma")`.
Notice that, like with the color brewer palette names, a minus sign will reverse the palette.
See `tmaptools::palette_explorer()` to explore the color brewer and viridis palettes interactively.
The arguments that define the color palette mapping has been made more intuitive.
The newly added layer function arguments `midpoint` and `stretch.palette` replace `auto.palette.mapping`:
* Categorical palettes.
The argument `stretch.palette` determines whether a palette is stretched out when there are more categories than available colors.
If set to `FALSE`, the palette is repeated.
* Diverging palettes.
The argument `midpoint` determines which value should be mapped to the middle (neutral) color of the diverging color palette.
By default, it is set to 0 if there are positive and negative values.
This could mean that only a part of the color palette is used, e.g. when the value range is [-5, 20] and the palette is `"RdBu"`, the colors will range from light red (-5) to white (0) to dark blue (20).
If there are only positive or only negative values, the full palette is shown.
* Sequential palettes.
Nothing has changed for sequential palettes.
When `midpoint` has been specified, the palette is regarded as a diverging palette, with the middle color interpreted as the neutral color.
### filter, difference between NA and NULL
The argument filter has been added to `tm_shape`.
Features that are included will be visualized as usual.
Excluded features will still be visualized but without color being mapped.
Instead, they will be colored with `colorNULL`, a new argument of the layer functions.
Note the difference with `colorNA`, which is used to color features with missing data.
To show the potiential of this filter the following code chunk creates a map in which only European countries are colored:
```{r, eval = FALSE}
tm_shape(World, filter = World$continent=="Europe") +
tm_polygons("HPI", id = "name")
```
<img src="images/tmap_filter.jpg" alt="sigma" data-toggle="tooltip" data-placement="right" title="" data-original-title="Note this is just a screenshot of the visualization so it's not interactive. You can play with the interactive version by running the code above." onload="$(this).tooltip()">
Countries outside Europe are colored with `colorNULL`, which is `grey95` by default.
It can be adjusted in the layer functions, such as `tm_polygons`, and in `tmap_options`.
There are also missing values in the data (Kosovo and Moldova) which are colored with the `colorNA` (by default `grey85`).