new vignettes (extension packages)

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

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)
+```
+
+

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.
+

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).
+
+