--- title: "tmap v4: a sneak peek" author: "Martijn Tennekes" date: "`r Sys.Date()`" output: html_document: toc: true toc_float: collapsed: false smooth_scroll: false toc_depth: 2 link-citations: yes vignette: > \usepackage[utf8]{inputenc} %\VignetteIndexEntry{tmap v4: a sneak peek} %\VignetteEngine{knitr::rmarkdown} editor_options: chunk_output_type: console --- ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE, fig.width = 9, warning = FALSE) ``` ```{r, echo = FALSE, message = FALSE} library(tmap) data(World, metro) # tmap_design_mode() ``` The next major update of **tmap** will be a massive one. Although **tmap** is well-known and widely used in the R spatial community, there are a couple of bottlenecks that make it difficult to maintain and extend. The upcoming **tmap** version 4 (**tmap v4**) aims to overcome these shortcomings. It is still fully in the development, but now is a good time for a sneak peek. ## Extendability First and foremost, **tmap v4** will be fully extendable. More precisely, the following aspects can be extended: * Map layers: we are not limited anymore by the fixed set of `tm_polygons()`, `tm_lines()`, `tm_symbols()`, and `tm_raster()` (and their derivatives such as `tm_borders()` and `tm_dots()`), but any layer of interest can be developed as an extension of **tmap**. We will illustrate this below with `tm_cartogram()`. Other layers that are worthwhile to implement are `tm_donuts()`, `tm_hexagons()`, `tm_network()`, `tm_hillshade()`, etc. * Aesthetics: there will be many more visual variables available. We will illustrate this in the next section, where we already implemented 5 new aesthetics for `tm_polygons()`. Moreover, it will be much easier for developers to add new visual variables to map layer functions. * Graphics Engine: **tmap v3** contains two modes: `plot` and `view` (which are based on `grid` graphics and `leaflet` respectively) but the framework makes it possible to add other modes as well. * Spatial data classes: **tmap v3** is build on `sf` and `stars`. This will also be the case for **tmap v4**, but for developers, it will be easier to incorporate other classes as well, like `SpatRaster` and `SpatVector` from `terra`. ## Aesthetics As mentioned before, we have added more aesthetics (visual variables), and it will be easier for developers to add new aesthetics. We have reordered the arguments that specify and configure the aesthetics which will be illustrated below. The arguments that specify aesthetics themselves will remain the same. E.g., the main aesthetic in `tm_polygons()` is `fill`, which defines the fill color of the polygons. However, the other arguments of the layer functions are organized differently. Thus, each aesthetic will only have four arguments: - the aesthetic itself (`fill`) - the scale (`fill.scale`) - the legend (`fill.legend`) - an argument that decides whether scales are applied freely across facets (`fill.free`) The scales and legends are discussed in the next sections. Below you can see a basic comparison of the **tmap** version 3 and 4 syntax: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 tm_shape(World) + tm_polygons(fill = "HPI", palette = "Earth", title = "Happy Planet Index") ``` ```{r, class.source='bg-success'} # tmap v4 tm_shape(World) + tm_polygons(fill = "HPI", fill.scale = tm_scale_intervals(values = "purple_green"), fill.legend = tm_legend(title = "Happy Planet Index")) ``` In **tmap v4**, `tm_polygons()` will have the aesthetics `fill`, `col`, `fill_alpha`, `col_alpha`, `lwd`, `lty`, and eventually also `pattern`. The other standard map layers will also have additional aesthetics. A data variable can be mapped to each of them, using different scales (see next section for an overview). The next example uses `fill`, `lwd` (line width), and `lty` (line type) as aesthetics: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 # ... not possible :( ``` ```{r fig.height = 6, fig.width=9, class.source='bg-success'} # tmap v4 World$life_exp_class = cut(World$life_exp, breaks = seq(40, 85, by = 15)) tm_shape(World, crs = "+proj=eck4") + tm_polygons(fill = "HPI", fill.scale = tm_scale_continuous(values = "purple_green"), fill.legend = tm_legend(title = "Happy Planet Index"), lwd = "well_being", lwd.scale = tm_scale_continuous(value.neutral = 1, values = c(0, 5), label.na = ""), lwd.legend = tm_legend(title = "Well Being"), lty = "life_exp_class", lty.scale = tm_scale_ordinal(values = c("dotted", "dashed", "solid"), value.na = "blank", value.neutral = "solid", label.na = ""), lty.legend = tm_legend(title = "Life Expectancy") ) ``` Besides these **visual mapping aesthetics**, which map data variables to visual variables, there is also another group of aesthetics, namely **(data-driven) transformation aesthetics**. They are used to transform spatial objects. We call it data-driven, because content data are used as input for this spatial transformation. An example is the cartogram, which will be shown in the next section. The polygons are distorted such that the size will be (approximately) proportional to a data variable. ## Map layers (e.g. cartogram) It will be easy for developers to add new map layers as extension. We illustrate this by a new map layer, `tm_cartogram()`. Cartograms could already be made with **tmap v3**, but it explicitly required transforming the data using the **cartogram** package before mapping. ```{r, eval=FALSE, class.source='bg-warning'} # tmap v3 library(cartogram) World_carto = World |> sf::st_transform(World, crs = "+proj=eck4") |> cartogram_cont(weight = "pop_est") tm_shape(World_carto, crs = "+proj=eck4") + tm_polygons(fill, palette = "Earth", title = "Happy Planet Index") ``` In **tmap v4**, there will be a direct function `tm_cartogram()` (using the **cartogram** package under the hood), which uses the transformation aesthetic `size` and inherits all visual aesthetics from `tm_polygons()`: ```{r, class.source='bg-success', message=FALSE} # tmap v4 if (requireNamespace("cartogram")) { tm_shape(World, crs = "+proj=eck4") + tm_cartogram(size = "pop_est", fill = "HPI", fill.scale = tm_scale_intervals(values = "purple_green"), fill.legend = tm_legend(title = "Happy Planet Index")) + tm_place_legends_right(width = 0.2) } ``` A nice benefit of having cartograms directly in **tmap** is that it makes possible to use the available scaling functions. For example, suppose we want to apply a log 10 scale in order to make the cartogram a bit more "balanced": ```{r, eval=FALSE, class.source='bg-warning'} # tmap v3 library(cartogram) World_carto = World |> sf::st_transform(World, crs = "+proj=eck4") |> dplyr::mutate(pop_est_log10 = log10(pop_est)) |> cartogram_cont(weight = "pop_est_log10") tm_shape(World_carto) + tm_polygons(fill, palette = "Earth", title = "Happy Planet Index") ``` ```{r, class.source='bg-success',message=FALSE} # tmap v4 if (requireNamespace("cartogram")) { tm_shape(World, crs = "+proj=eck4") + tm_cartogram(size = "pop_est", size.scale = tm_scale_continuous_log1p(), fill = "HPI", fill.scale = tm_scale_intervals(values = "purple_green"), fill.legend = tm_legend(title = "Happy Planet Index")) + tm_place_legends_right(width = 0.2) } ``` ## Scales Scales are used to map data variables to visual variables. Scales are not new in **map v4**, but they are used more explicitly. The following table shows the scales that are currently available: | Scale | Main Data Type | Example | |--- |--- |--- | | `tm_scale_categorical()` | categorical (`factor`) | Fruit type | | `tm_scale_ordinal()` | categorical (`ordered`) | Education level | | `tm_scale_intervals()` | numerical (`integer` or `numeric`) | Age group | | `tm_scale_continuous()` | numerical (`numeric`) | Height | | `tm_scale_log10()` | numerical (`numeric`) | Income | | `tm_scale_discrete()` | numerical (`integer`) | Number of children | The main data type (second column) is the data type for which the scale is supposed to be applied. Any scale can be applied to any data type (even though it might not make sense), with one exception: continuous (and log10) scales cannot be applied to visual variables that can only take a finite set of values. Examples are symbol shape and line type. By default, `tm_scale_categorical()`, `tm_scale_ordinal()`, and `tm_scale_intervals()` are used for data of class `factor`, `ordered` and `numeric` respectively. Scales for date/time variables will be included as well. The main argument of each scale function is `values`, which are the values for the visual variables. The following table shows which type of values are required for which visual variable: | Visual variable | Type of values | |--- |--- | | `fill` and `col` | Color palette | | `size` and `lwd` | (Exponential) value range | | `lty` | Line types, e.g. `"dashed"` | | `shape` | Shapes (probably similar as in **tmap v3**) | | `fill_alpha` and `col_alpha` | Value range | The default values depend not only on the visual variable, but also on the scale and on whether data values are diverging. For instance, if `tm_scale_intervals()` is applied to a numeric variable with both negative and positive values where the visual variable is `fill`, then a diverging color palette is used. The following map illustrates what happens when the six scale functions are applied to the same data variable. We use the variable *life expectancy* (which we round in order to make sure the number of unique values is limited): ```{r, message=FALSE} data(World) Africa = World[World$continent == "Africa", ] Africa$life_exp = round(Africa$life_exp) ``` Scales existed in **tmap v3**, but they were applied implicitly via several arguments: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 tm_shape(Africa) + tm_polygons(rep("life_exp", 5), style = c("cat", "cat", "pretty", "cont", "log10"), palette = list("Set2", "YlOrBr", "YlOrBr", "YlOrBr", "YlOrBr"), title = "") + tm_layout(panel.labels = c("categorical scale", "ordinal scale", "intervals scale", "continuous scale", "log10 scale"), inner.margins = c(0.05, 0.2, 0.1, 0.05), legend.text.size = 0.5) # discrete scale is not possible directly, but only via interval breaks: tm_shape(Africa) + tm_polygons("life_exp", style = "fixed", palette = "YlOrBr", breaks = 49:76, as.count = TRUE, title = "") + tm_layout(panel.labels = "discrete scale", inner.margins = c(0.05, 0.2, 0.1, 0.05), legend.text.size = 0.5) ``` ```{r, class.source='bg-success',message=FALSE,fig.height=7} # tmap v4 tm_shape(Africa) + tm_polygons(rep("life_exp", 6), fill.scale = list(tm_scale_categorical(), tm_scale_ordinal(), tm_scale_intervals(), tm_scale_continuous(), tm_scale_continuous_log(), tm_scale_discrete()), fill.legend = tm_legend(title = "", position = tm_pos_in("left", "top"))) + tm_layout(panel.labels = c("tm_scale_categorical", "tm_scale_ordinal", "tm_scale_intervals", "tm_scale_continuous", "tm_scale_continuous_log", "tm_scale_discrete"), inner.margins = c(0.05, 0.2, 0.1, 0.05), legend.text.size = 0.5) ``` ## Multivariate Scales It will be possible to assign multiple variables for one aesthetic. This can be done with the function `tm_mv()` (which stands for multivariate). An example is the bivariate choropleth, which is not yet implemented, but will definitely be. ```{r, eval = TRUE, class.source='bg-success'} # tmap v4 tm_shape(World) + tm_symbols( fill = tm_vars(c("well_being", "footprint"), multivariate = TRUE), fill.scale = tm_scale_bivariate(scale1 = tm_scale_intervals(breaks = c(2, 5, 6, 8)), scale2 = tm_scale_intervals(breaks = c(0, 3, 6, 20)), values = "brewer.qualseq") ) ``` ## Legends As you may have noticed in the previous examples, the legends look a bit differently by default. ### Positioning Legends are currently placed outside the map by default in **tmap v4**. Why? Simply because there is often more space than inside the map. Furthermore, it is possible to place legends on different locations across the map: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 # ... not possible :( ``` ```{r fig.height = 6, fig.width=9, class.source='bg-success'} # tmap v4 tm_shape(World) + tm_symbols(fill = "HPI", size = "pop_est", shape = "income_grp", size.scale = tm_scale(value.neutral = 0.5), fill.legend = tm_legend("Happy Planet Index", position = tm_pos_in("left", "top")), size.legend = tm_legend("Population", position = tm_pos_out("left", "center")), shape.legend = tm_legend("Income Group", position = tm_pos_out("center", "bottom"))) ``` **tmap v3** contains many (often complicated) options for rather simple things. These options are set globally via `tmap_options()` or within a single plot with `tm_layout()`. In **tmap v4**, the directly related to the layout are accessible via `tm_layout()`. However, to ease its use, there will be a bunch of handy shortcut functions, such as `tm_place_legends_left()`: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 tm_shape(World) + tm_symbols(fill = "HPI", size = "pop_est", shape = "income_grp") + tm_layout(legend.outside.position = "left", legend.outside.size = 0.2) ``` ```{r fig.height = 6, fig.width=9, class.source='bg-success'} # tmap v4 tm_shape(World) + tm_symbols(fill = "HPI", size = "pop_est", shape = "income_grp", size.scale = tm_scale(value.neutral = 0.5)) + tm_place_legends_left(0.2) ``` ### Combined legends Another new feature is possibility to combine legends directly, which was quite a hassle in **tmap v3**. ```{r, eval=FALSE, class.source='bg-warning'} # tmap v3 tm_shape(metro) + tm_symbols(col = "pop2020", n = 4, size = "pop2020", legend.size.show = FALSE, legend.col.show = FALSE) + tm_add_legend("symbol", col = RColorBrewer::brewer.pal(4, "YlOrRd"), border.col = "grey40", size = ((c(10, 20, 30, 40) * 1e6) / 40e6) ^ 0.5 * 2, labels = c("0 mln to 10 mln", "10 mln to 20 mln", "20 mln to 30 mln", "30 mln to 40 mln"), title = "Population in 2020") + tm_layout(legend.outside = TRUE, legend.outside.position = "bottom") ``` ```{r, class.source='bg-success'} # tmap v4 tm_shape(metro) + tm_symbols(fill = "pop2020", fill.legend = tm_legend("Population in 2020"), size = "pop2020", size.scale = tm_scale_intervals(), size.legend = tm_legend_combine("fill")) ``` ### Spacing between items The design of the legends is (and will further be) improved. Most prominently, there is a `space` argument that determines the height of a legend item. More specifically, each legend item will be `1 + space` line-height. This is also useful to make continuous legends better. ## Facets In **tmap v4**, there are convenient wrappers `tm_facet_wrap()` and `tm_facet_grid()`, where the former wraps the facets, and the latter places the facets in a grid layout. Furthermore, each visual variable has a `free` argument, which determines whether scales are free (`TRUE`) or shared (`FALSE`) across facets. In **tmap v3** this `free` argument could be set via `tm_facets()`, whereas in **tmap v4** this argument has been moved to the layer functions: ```{r, eval=FALSE, class.source='bg-warning'} # tmap v3 tm_shape(World) + tm_borders() + tm_shape(World) + tm_polygons("life_exp") + tm_facets("continent", nrow = 1, free.scales.fill = FALSE, free.coords = FALSE) ``` ```{r, class.source='bg-success', fig.height=3} # tmap v4 tm_shape(World, crs = "+proj=robin") + tm_borders() + tm_shape(World) + tm_polygons("life_exp", fill.free = FALSE) + tm_facets_wrap("continent") ``` ```{r, eval=FALSE, class.source='bg-warning'} # tmap v3 tm_shape(World) + tm_borders() + tm_shape(World) + tm_polygons("life_exp") + tm_facets("continent", nrow = 1, free.scales.fill = TRUE, free.coords = FALSE) ``` ```{r, class.source='bg-success', fig.height=3} tm_shape(World, crs = "+proj=robin") + tm_borders() + tm_shape(World) + tm_polygons("life_exp", fill.free = TRUE) + tm_facets_stack("continent") ``` New in **tmap v4** is that for facet grid, the `free` argument can be specified differently for rows and columns, as we will show in the next complex (sorry for that) example: ```{r, eval = FALSE, class.source='bg-warning'} # tmap v3 # ... not possible :( ``` ```{r, class.source='bg-success'} # tmap v4 tm_shape(World, crs = "+proj=robin") + tm_borders() + tm_shape(World) + tm_polygons(fill = "life_exp", fill.scale = tm_scale_intervals(values = "brewer.greens"), fill.free = c(rows = FALSE, columns = TRUE)) + tm_symbols(size = "gdp_cap_est", size.free = c(rows = TRUE, columns = FALSE), fill = "red") + tm_facets_grid("income_grp", "economy") + tm_layout(meta.margins = c(.2, 0, 0,.1)) ``` What you see in the map is that life expectancy is shown as polygon fill in green, and GDP per capita as red bubbles. The maps are grouped by income group (rows) and economy (columns). The scale for life expectancy is set to free for the columns. This means that the scale will be applied for each column separately, with a legend per column. The scale for GDP per capita is applied separately for each row. ## Graphic Engines (modes) Just like **tmap v3**, there will be a `"plot"` and a `"view"` mode. However, the framework used in **tmap v4** also facilitates developers to write plotting methods for other modes. For instance, **CesiumJS** is a great JavaScript library for 3d globe visualizations. It would be awesome to include this in **R**. When there is a low-level interface between **CesiumJS** and **R** (similar to the R package **leaflet** being an interface between the JS library **leaflet** and **R**), it will be relatively easy for developers to add a new mode for these 3d visualizations in **tmap v4**. ## Backward compatibility In this early development stage, **tmap v3** code will not work with **tmap v4**. However, when **tmap v4** will be stable, it will be backwards compatible. Layer function arguments that are no longer used, such as `breaks` and `palette` will be deprecated, and internally redirected to the new scale functions. Furthermore, some of the options will have other options in **tmap v4**. For instance, legends will be placed outside of the maps by default, and there will be a small space between legend items as shown above. In order to keep the layout as close as possible to **tmap v3**, there will be a style which will set the options back to the settings used by default in **tmap v3**. This can be set with just one command: `tmap_style("tmap_v3")` ## Color palettes There will be a huge number of directly available color palettes. We have not settled on the exact details, e.g. which palettes to include, and how they can be obtained. Ideas are welcome (https://github.com/r-tmap/tmap/issues/566). In the current development version, there is a function similar to `tmaptools::palette_explorer()`, which renders a long png in the viewer pane of RStudio or the browser: ```{r, eval = FALSE, class.source='bg-success'} # tmap v4 tmap_show_palettes() ``` [![](https://user-images.githubusercontent.com/2444081/122732106-3ad8da80-d27c-11eb-98fd-1aafd6d7a52b.png)](https://user-images.githubusercontent.com/2444081/122725374-352bc680-d275-11eb-9a1c-0a88e4a97848.png) (click on the image to see the full png) It is also possible to render this for color blindness simulation, e.g.: `tmap_show_palettes(color_vision_deficiency = "deutan")`. All default palettes that we use will be usable for color blind people. ## Suggestions Do you have any suggestions? Please let us know! Via https://github.com/r-tmap/tmap/issues, and please use the **tmap_v4** tag.