vigs: components and exporting

vignettes/basics_components.Rmd

@@ -96,4 +96,6 @@ tm_compass(type = "8star", position = c("right", "bottom")) +
 tm_scalebar(position = c("right", "bottom"))
 ```
 
+If the components should be placed tighter to the frame, use capital case instead; e.g. `c("LEFT", "BOTTOM") in stead of `c("left", "bottom")`.
+
 There are much more options to position map componets via `tm_pos()`, see the [vignette about positions](https://r-tmap.github.io/tmap/articles/41_position)

vignettes/basics_exporting.Rmd

@@ -46,74 +46,133 @@ knitr::knit_hooks$set(output = function(x, options) {
 
 ```{r, echo = FALSE, message = FALSE}
 library(tmap)
-tmap_options(scale = 0.75)
+tmap_options(scale = 1)
 ```
 
 
 
-### About the data
+## Static maps (plot mode)
 
-A spatial data object contained in tmap is called `World`. It is a data frame with a row for each country. The columns are the following data variables plus an additional geometry column which contains the geometries (see sf package):
+Maps in plot mode van be exported in many formats including: 
+
+**pixel based** png, jpg, bmp, tiff.
+
+**vectorized** pdf, eps, svg, and 
+
+The `width` and `height` are specified in either pixels or inches (you can don't need to specify the units).
+
+For the pixel based formats, the relation between pixels and inches are specified via the argument `dpi` (dots-per-inch).
+
+Let's create a standard country level choropleth:
+
+```{r}
+tm = tm_shape(World, crs = "+proj=robin") + 
+  tm_polygons(
+    fill = "gender", 
+    fill.scale = tm_scale_continuous(values = "pu_gn"),
+    fill.legend = tm_legend("Gender Inequality Index", orientation = "landscape")) +
+	tm_credits("Human Development Report (2024)", position = c("RIGHT", "BOTTOM")) + 
+tm_layout(inner.margins = c(0, 0, 0.05, 0.05))
+```
+
+### Pixel based format
+
+Exporting maps is done via `tmap_save()`. 
 
 ```{r}
-names(World)
+tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300)
 ```
 
-We specify this object with `tm_shape` (see other vignette) and for convenience assign it to `s`:
+Values of `width` and `height` less than 50  are considered inches, whereas greater than 50 pixels are considered pixels:
 
 ```{r}
-s = tm_shape(World, crs = "+proj=eqearth")
+tmap_save(tm, filename = "world.png", width = 2100, height = 1200, dpi = 300)
+```
+
+Therefore, both examples result in the exactly the same file:
+
+```{r, echo = FALSE, fig.width = 7, fig.height = 4}
+tm + tm_layout(scale = 1)
 ```
 
+Vector based formats are preferred over pixel based, because of the scalability. In case pixel formats are used, please make to use a sufficient number of pixels. For **web publications** at least 144 dpi is required. This may seem overkill, but is required for *retina* (high point-per-inch) displaces. For **printing** 300 or even 600 dpi is required.
+
+### Aspect ratio
 
-## Scales: numeric data
+In case only *one* dimension is provided, the other dimension calculated using the aspect ratio of the map.
 
-Each visual variable, e.g. `fill` in `tm_polygons` can represent a data variable:
+```{r}
+tmap_save(tm, filename = "world.png", width = 2100, dpi = 300)
+```
 
-```{r, fig.height = 3.5}
-s + tm_polygons(fill = "HPI")
+```{r, echo = FALSE, fig.width = 7, fig.height = 3.5329}
+tm + tm_layout(scale = 1)
 ```
 
-A *scale* defines how to map the data values to visual values. Numeric data variables (e.g. `"HPI"` which stands for Happy Planex Index) are by default mapped with a class interval scale to the polygon fill. This can be set explicitly with `tm_scale_intervals`, via which the intervals can be specified, as well as the visual values (in this case polygon fill colors):
+
+### Vector based format
+
+Vector based formats will look (almost) the same. 
 
 ```{r, eval = FALSE}
-s + tm_polygons(
-  fill = "HPI",
-  fill.scale = tm_scale_intervals(
-    style = "fisher",      # a method to specify the classes
-    n = 7,                 # number of classes
-    midpoint = 38,         # data value mapped to the middle palette color
-    values = "pu_gn_div"   # color palette; 
-                           # run cols4all::c4a_gui() to explore color palettes
-  ))
+tmap_save(tm, filename = "world.pdf", width = 7, height = 4, dpi = 300)
 ```
 
+Small differences in font sizes, margins, symbol sizes between formats may occur.
 
-An alternative for numeric data variables is the continuous scale:
+### Scaling
 
-```{r, fig.height = 3.5}
-s + 
-  tm_polygons(
-    fill = "HPI",
-    fill.scale = tm_scale_continuous(
-      limits = c(10, 60),
-      values = "scico.hawaii"))
+An important argument of `tmap_save()` is `scale`. It an option for the overall scale over the map, which is normally set via `tm_layout()`.  It determines all font sizes, line widths, and symbol sizes.
+
+Much smaller (0.5):
+
+```{r, eval = FALSE}
+tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 0.5)
 ```
 
+```{r, echo = FALSE, fig.width = 7, fig.height = 4}
+tm + tm_layout(scale = 0.5)
+```
 
-## Scales: categorical data
 
-```{r, fig.height = 3.5}
-s + 
-  tm_polygons(
-    fill = "economy",
-    fill.scale = tm_scale_categorical())
+A bit smaller (0.8):
+
+```{r, eval = FALSE}
+tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 0.8)
 ```
 
-```{r, fig.height = 3.5}
-s + 
-  tm_polygons(
-    fill = "income_grp",
-    fill.scale = tm_scale_ordinal(values = "matplotlib.summer"))
+```{r, echo = FALSE, fig.width = 7, fig.height = 4}
+tm + tm_layout(scale = 0.8)
+```
+
+A bit larger (1.2):
+
+```{r, eval = FALSE}
+tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 1.2)
+```
+
+```{r, echo = FALSE, fig.width = 7, fig.height = 4}
+tm + tm_layout(scale = 1.2)
 ```
 
+Much larger (1.5):
+
+```{r, eval = FALSE}
+tmap_save(tm, filename = "world.png", width = 7, height = 4, dpi = 300, scale = 1.5)
+```
+
+```{r, echo = FALSE, fig.width = 7, fig.height = 4}
+tm + tm_layout(scale = 1.5)
+```
+
+
+## View mode
+
+Maps can also be exported as stand-alone HTML files.
+
+```{r, eval = FALSE}
+tmap_save(tm, filename = "index.html", selfcontained = FALSE)
+```
+
+When `selfcontained = FALSE`, the required JavaScripts and CSS files are stored in a folder called `index_files`.
+