diff --git a/DESCRIPTION b/DESCRIPTION index 2d57a70f..e4f79f9f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -65,7 +65,7 @@ Suggests: rstudioapi Config/Needs/check: Nowosad/spDataLarge, lwgeom Config/Needs/coverage: Nowosad/spDataLarge, lwgeom -Config/Needs/website: bookdown, geofacet, rmarkdown, mapview, sits, r-spatial/leafem, mapsf +Config/Needs/website: bookdown, geofacet, rmarkdown, mapview, sits, r-spatial/leafem, mapsf, r-tmap/tmap.glyphs, r-tmap/tmap.networks, r-tmap/tmap.deckgl sfnetworks Config/testthat/edition: 3 Encoding: UTF-8 LazyData: true diff --git a/vignettes/adv_extensions.Rmd b/vignettes/adv_extensions.Rmd index bef5d83b..780279f6 100644 --- a/vignettes/adv_extensions.Rmd +++ b/vignettes/adv_extensions.Rmd @@ -50,4 +50,96 @@ tmap_options(scale = 0.75) ``` -## To do +## extension types + +There are three types of tmap extensions: + +1. New map layer types +2. New spatial data classes +3. New output modes + +Rather than explaining how to extend tmap for each of these three types (which is rather complex), it is easier to demonstrate with proof-of-concept extension packages: + +## New map layer types + +This type of extension requires: + +* Specification of visual variables. For new visual variable, options need to be added. +* Spatial transformation function needs to be specified: e.g. should centroids be used? +* The mapping between visual variables and (standard) visual or transformation parameters. + +See [`tmap.glyphs`](https://github.com/r-tmap/tmap.glyphs). A layer function `tm_donuts` is added. More glyph types layer functions will follow, e.g. `tm_pies`, or `tm_radars`. + +```{r, fig.height = 6} +library(tmap.glyphs) +ZH_muni = NLD_muni[NLD_muni$province == "Zuid-Holland", ] +ZH_muni$income_middle = 100 - ZH_muni$income_high - ZH_muni$income_low + +tm_shape(ZH_muni) + + tm_polygons() + + tm_donuts( + parts = tm_vars(c("income_low", "income_middle", "income_high"), multivariate = TRUE), + fill.scale = tm_scale_categorical(values = "-pu_gn_div"), + size = "population", + size.scale = tm_scale_continuous(ticks = c(50000, 100000, 250000, 500000))) +``` + +## New spatial data classes + +This type of extension requires methods to obtain: + +* the spatial geometries (cast to either vectorized objects (`sfc`) or a stars object with indices) and +* the data variables and its levels (if any) + +See [`tmap.networks`](https://github.com/r-tmap/tmap.networks) which supports `sfnetworks` + +```{r} +library(sfnetworks) +library(tmap.networks) + +(sfn = as_sfnetwork(roxel)) +``` + +Besides this new spatial data class `"sfnetwork"`, this package also features new map layers, albeit very basic so far: + +```{r, fig.height = 8} +tm_shape(sfn) + + tm_network() +``` + +```{r, fig.height = 8} +tm_shape(sfn) + + tm_edges(col = "type", lwd = 4) + + tm_nodes() +``` + +### New mode + +This type of extension is by far the most difficult one. It requires: + +* Initialization +* Loading of the used spatial object +* Plotting function for each map layer type +* A function for each map component +* Functions to preprocess and show the legends +* Run the plot +* Shiny integration functions + +As a proof of concept we created [`tmap.deckgl`](https://github.com/r-tmap/tmap.deckgl). It remains a proof-of-concept because the underlying package [`deckgl`](https://github.com/crazycapivara/deckgl) hasn't been updated the last 2 years. + +For this proof of concept, only one map layer is `tm_polygons()`. The shiny integration does not work yet. + +```{r} +library(tamp.deckgl) + +tm_shape(NLD_dist) + + tm_polygons( + fill = "employment_rate", + fill.scale = tm_scale_intervals(values = "scico.roma"), + lwd = 0.1) + +tm_shape(NLD_muni) + + tm_polygons(fill = NULL, lwd = 1) + +tm_deck(pitch = 75) +``` + + diff --git a/vignettes/adv_multivariate.Rmd b/vignettes/adv_multivariate.Rmd index 0ec28386..09fb64e9 100644 --- a/vignettes/adv_multivariate.Rmd +++ b/vignettes/adv_multivariate.Rmd @@ -1,5 +1,5 @@ --- -title: "tmap basics: multivariate visual variables" +title: "tmap advanced: multiple visual variables" output: bookdown::html_vignette2: pkgdown: @@ -51,4 +51,98 @@ tmap_options(scale = 0.75) -### To do +## Multiple visual variables + +Usually we specify a data-driven visual variable with **one** data variable (see [vignette about visual variables](https://r-tmap.github.io/tmap/articles/basics_vv)). However, in several use cases, it is useful to use a few data variables for one visual variables. + +There are two ways to use multiple data variables for one visual variable: for creating facets, and for multivariate mapping. + +## Creating facets + +Recall from the [vigentte about facets](https://r-tmap.github.io/tmap/articles/03_basics_facets) + +```{r, fig.height = 5} +tm_shape(NLD_muni) + + tm_polygons( + fill = c("pop_0_14", "pop_25_44", "pop_65plus"), + fill.legend = tm_legend("Percentage"), + fill.free = FALSE) +``` + +A facet is create for each specified data variable. More options to select variables are available via the underlying function `tm_vars()`. For instance, variables 12 to 18 (so columns 12 to 18, disregarding the geometry column) + +```{r, fig.height = 5} +tm_shape(NLD_muni) + + tm_polygons( + fill = tm_vars(12:18)) +``` + +Or the first 3 variables: + +```{r} +tm_shape(NLD_muni, fig.height = 5) + + tm_polygons( + fill = tm_vars(n = 3)) +``` + +1. For creating facets. This is the standard way. +2. For multivariate mapping. + +These cases can be divived into two g +Before going through these cases, there is one important +There are two + + +## Multivariate mapping + +There are (at least) two use cases: + +### RGB image + +```{r} +library(stars) +tif = system.file("tif/L7_ETMs.tif", package = "stars") +(L7 = read_stars(tif)) +``` + +Note that the channels are included in the dimenison `"band"`. We can use the argument `dimvalues` to select them: + +```{r} +tm_shape(L7) + + tm_rgb(col = tm_vars(dimvalues = 3:1, multivariate = TRUE)) +``` + +Alternatively, we can split the `stars` object: + +```{r} +(L7split = split(L7)) +``` + +and plot it like this: + +```{r} +tm_shape(L7split) + + tm_rgb(col = tm_vars(3:1, multivariate = TRUE)) +``` + +### Glyphs + +Glyph are small charts plotted as symbols. See the [extention package [`tmap.glyphs`](https://github.com/r-tmap/tmap.glyphs). + +```{r, fig.height = 6} +library(tmap.glyphs) + +ZH_muni = NLD_muni[NLD_muni$province == "Zuid-Holland", ] +ZH_muni$income_middle = 100 - ZH_muni$income_high - ZH_muni$income_low + +tm_shape(ZH_muni) + + tm_polygons() + + tm_donuts( + parts = tm_vars(c("income_low", "income_middle", "income_high"), multivariate = TRUE), + fill.scale = tm_scale_categorical(values = "-pu_gn_div"), + size = "population", + size.scale = tm_scale_continuous(ticks = c(50000, 100000, 250000, 500000))) +``` + +The visual variable `parts` (introduced in `tmap.glyphs`) is specified as multivariate visual variable. It specifies the parts (slices) of the donut charts and uses this also for the `fill` color. + diff --git a/vignettes/basics_modes.Rmd b/vignettes/basics_modes.Rmd index 01ac4fca..5f05b0c1 100644 --- a/vignettes/basics_modes.Rmd +++ b/vignettes/basics_modes.Rmd @@ -2,10 +2,6 @@ title: "tmap basics: modes" output: bookdown::html_vignette2: -pkgdown: - as_is: true -template: - math-rendering: mathjax bibliography: '`r system.file("tmap.bib", package="tmap")`' csl: "`r system.file('ieee.csl', package = 'tmap')`" editor_options: @@ -53,7 +49,8 @@ tmap_options(scale = 0.75) ## Modes -tmap facilitates two output modes: `"plot"`, which produces static maps, and `"view"` which produces (using the same tmap code) interactive maps. As of version 4, tmap can also be extended with other modes see ([vignette about extensions](https://r-tmap.github.io/tmap/articles/44_adv_extensions)). +tmap facilitates two output modes: `"plot"`, which produces static maps, and `"view"` which produces (using the same tmap code) interactive maps. As of version 4, tmap can also be extended with other modes, as demonstrated below. + ## Switching between modes @@ -126,3 +123,18 @@ tm + For a more detailed description of options, see [vignette about options](https://r-tmap.github.io/tmap/articles/42_adv_options). + +## Other modes + +As of version 4, tmap can be extended with other modes. See ([vignette about extensions](https://r-tmap.github.io/tmap/articles/44_adv_extensions)). + + +```{r, message=FALSE} +library(tmap.deckgl) +tmap_mode("deck") +tm +``` + +The proof-of-concept package `tmap.deckgl` only features the map layer function `tm_polygons()` (so the bubbles are not working yet). + +