added components and positioning vigs, improved tmap_options_mode(), …

…updated pkgdown menu
r-tmap · Jan 8, 2025 · c2b4e29 · c2b4e29
1 parent 71cf192
commit c2b4e29
Show file tree

Hide file tree

Showing 14 changed files with 220 additions and 14 deletions.
diff --git a/R/process_breaks.R b/R/process_breaks.R
@@ -159,7 +159,7 @@ fancy_breaks <- function(vec, as.count = FALSE, intervals=FALSE, interval.closur
 
 num2breaks <- function(x, n, style, breaks, approx=FALSE, interval.closure="left", var = NULL, as.count = FALSE, args = list()) {
 
-	tmapOptions = tmap_options_mode()
+	tmapOptions = tmap_options_mode(mode.specific = FALSE)
 	show.warnings <- tmapOptions$show.warnings
 
 	nobs <- sum(!is.na(x))

diff --git a/R/qtm.R b/R/qtm.R
@@ -108,7 +108,7 @@ qtm = function(shp = NULL,
 		args_called = args_new$called
 	}
 
-	o = tmap_options_mode()
+	o = tmap_options_mode(mode.specific = FALSE)
 	show.warnings = o$show.warnings
 
 	if (missing(shp) || is.character(shp)) {

diff --git a/R/step1_rearrange.R b/R/step1_rearrange.R
@@ -3,7 +3,7 @@ step1_rearrange = function(tmel) {
 	dev = getOption("tmap.devel.mode")
 
 	# get options (mode specific)
-	o = tmap_options_mode()
+	o = tmap_options_mode(mode.specific = FALSE)
 
 	# reset symbols
 	assign("shapeLib", list(), envir = .TMAP)
@@ -97,7 +97,7 @@ step1_rearrange = function(tmel) {
 		}
 
 		if ("style" %in% names(o2) && !is.na(o2$style)) { #() {
-			o = tmap_options_mode(default.options = TRUE)
+			o = tmap_options_mode(default.options = TRUE, mode.specific = FALSE)
 			styleOptions <- get("tmapStyles", envir = .TMAP)[[o2$style]]
 			if (!is.null(styleOptions)) o = complete_options(styleOptions, o)
 			o2$style = NULL

diff --git a/R/step2_helper_facets.R b/R/step2_helper_facets.R
@@ -163,7 +163,7 @@ subStr = function(x, k) {
 
 limit_nx = function(nx) {
 	# bound number of facets
-	tmapOptions <- tmap::tmap_options_mode()
+	tmapOptions <- tmap::tmap_options_mode(mode.specific = FALSE)
 	mode = getOption("tmap.mode")
 
 	ox = tmapOptions$facet.max

diff --git a/R/tm_components.R b/R/tm_components.R
@@ -73,7 +73,7 @@ tm_credits = function(text, size, color, padding, fontface, fontfamily, alpha, s
 #' Map component that adds a compass
 #'
 #' @param north north
-#' @param type Compass type
+#' @param type compass type, one of: \code{"arrow"}, \code{"4star"}, \code{"8star"}, \code{"radar"}, \code{"rose"}. The default is controlled by \code{\link{tm_layout}} (which uses \code{"arrow"} for the default style)
 #' @param text.size text.size
 #' @param size size
 #' @param show.labels show.labels

diff --git a/R/tmap_options.R b/R/tmap_options.R
@@ -469,10 +469,11 @@ tmap_options = function(..., crs, facet.max, facet.flip, free.scales, raster.max
 
 #' @param mode mode, e.g. `"plot"` or `"view"`
 #' @param style style. If specified, the style specific options are returned
+#' @param mode.specific Should only mode-specific options be returned? `TRUE` by default.
 #' @param default.options return the default options or the current options?
 #' @rdname tmap_options
 #' @export
-tmap_options_mode = function(mode = NA, style = NULL, default.options = FALSE) {
+tmap_options_mode = function(mode = NA, style = NULL, mode.specific = TRUE, default.options = FALSE) {
 	if (default.options) {
 		o = .defaultTmapOptions
 	} else {
@@ -489,12 +490,21 @@ tmap_options_mode = function(mode = NA, style = NULL, default.options = FALSE) {
 	opt2 = o$modes[[mode]]
 
 	specified = attr(o, "specified")
+
+	# all general options with mode-specific defaults (except the specified ones tmap_options(bg.color = "red")
 	int_opt = setdiff(intersect(names(o), names(opt2)), specified)
+
+	# all mode-specific options
 	diff_opt = setdiff(names(opt2), names(o))
 
 	if (length(int_opt)) o[int_opt] = opt2[int_opt]
 	if (length(diff_opt)) o = c(o, opt2[diff_opt])
-	o
+
+	if (mode.specific) {
+		o[setdiff(names(opt2), "name")]
+	} else {
+		o
+	}
 }
 
 

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -168,13 +168,17 @@ navbar:
           href: articles/31_versus_ggplot2
         - text: tmap vs mapview
           href: articles/32_versus_mapview
+        - text: tmap vs mapsf
+          href: articles/33_versus_mapsf
 
     advanced:
       text: Advanced
       menu:
+        - text: Positioning of components
+          href: articles/41_adv_positions
         - text: Options
-          href: articles/41_options
+          href: articles/42_adv_options
         - text: Margins and aspect ratio
-          href: articles/42_margins
+          href: articles/43_adv_margins
         - text: Extending tmap
-          href: articles/43_extensions
+          href: articles/44_adv_extensions
diff --git a/man/tm_compass.Rd b/man/tm_compass.Rd
diff --git a/man/tmap_options.Rd b/man/tmap_options.Rd
diff --git a/vignettes/07_basics_components.Rmd b/vignettes/07_basics_components.Rmd
@@ -49,6 +49,51 @@ library(tmap)
 tmap_options(scale = 0.75)
 ```
 
+## What are 'components' in tmap?
 
+Components are non-spatial parts of the plots:
 
-### To do
+* titles and credits: [tm_title()] and [tm_credits()]
+* scale bars and compasses: [tm_scalebar()] and [tm_compass()]
+* legends: specified with the `.legend` compoments in the data layer functions (e.g. [tm_polygons()]).
+
+## Title and credits
+
+[tm_title()] and [tm_credits()] add text to the map in the form a title and a credits/attribution text respectively. The underlying function and all the options are the same, but the default value differ: titles are by default larger and placed above the map (outside the frame), while credits are place inside the frame at the bottom right. 
+
+
+```{r, fig.height = 6}
+tm_shape(NLD_muni) +
+  tm_polygons(
+    fill = "edu_appl_sci") +
+tm_title("Population share with (applied) university degree in 2022") +
+tm_credits("Statistics Netherlands (CBS)")
+```
+
+
+##  Scale bar and compass
+
+```{r, fig.height = 6}
+tm_shape(NLD_muni) +
+  tm_polygons() +
+	tm_compass(type = "8star") +
+	tm_scalebar()
+```
+
+## Positioning of components (basics)
+
+The position of a map component can be specified with the general argument `position`.
+
+It takes a vector of two, the first is the horizontal position (`"left"`, `"center"`, `"right"`), the second one the vertical position (`"top"`, `"center"`, `"bottom"`)
+
+```{r, fig.height = 6}
+tm_shape(NLD_muni) +
+  tm_polygons(
+    fill = "edu_appl_sci",
+    fill.legend = tm_legend(position = c("left", "top"))) +
+tm_credits("Statistics Netherlands (CBS)", position = c("left", "bottom")) +
+tm_compass(type = "8star", position = c("right", "bottom")) +
+tm_scalebar(position = c("right", "bottom"))
+```
+
+There are much more options to position map componets via [tm_pos()], see [vignette about positions](https://r-tmap.github.io/tmap/articles/41_position)
diff --git a/vignettes/41_adv_positions.Rmd b/vignettes/41_adv_positions.Rmd
@@ -0,0 +1,140 @@
+---
+title: "tmap advanced: positioning of components"
+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: 
+  chunk_output_type: console
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  out.width = "100%",
+  dpi = 300,
+  fig.width = 7.2916667,
+  comment = "#>"
+)
+hook_output <- knitr::knit_hooks$get("output")
+knitr::knit_hooks$set(output = function(x, options) {
+   lines <- options$output.lines
+   if (is.null(lines)) {
+     return(hook_output(x, options))  # pass to default hook
+   }
+   x <- unlist(strsplit(x, "\n"))
+   more <- "..."
+   if (length(lines)==1) {        # first n lines
+     if (length(x) > lines) {
+       # truncate the output, but add ....
+       x <- c(head(x, lines), more)
+     }
+   } else {
+     x <- c(more, x[lines], more)
+   }
+   # paste these lines together
+   x <- paste(c(x, ""), collapse = "\n")
+   hook_output(x, options)
+ })
+
+```
+
+
+```{r, echo = FALSE, message = FALSE}
+library(tmap)
+tmap_options(scale = 0.75)
+```
+
+## Component positionining
+
+Recall from [vignette about components](https://r-tmap.github.io/tmap/articles/07_basic_components) that the `position` argument of map components and legends is used to position them.
+
+Let's enable the 'design mode' of tmap for the rest of this vignette
+
+```{r}
+tmap_design_mode()
+```
+
+
+## Shortcut (quick and easy)
+
+Quick and easy: a vector of two, the first is the horizontal position (`"left"`, `"center"`, `"right"`), the second one the vertical position (`"top"`, `"center"`, `"bottom"`)
+
+```{r, fig.height = 6}
+tm_shape(NLD_muni) +
+  tm_polygons(
+    fill = "edu_appl_sci",
+    fill.legend = tm_legend(position = c("left", "top"))) +
+tm_credits("Statistics Netherlands (CBS)", position = c("left", "bottom")) +
+tm_compass(type = "8star", position = c("right", "bottom")) +
+tm_scalebar(position = c("right", "bottom"))
+```
+
+It is also possible to specify two numbers to set the location. The coordinates are between 0 and 1, where (0,0) is bottom left.
+
+```{r, fig.height = 6}
+tm_shape(NLD_muni) +
+  tm_polygons(
+    fill = "edu_appl_sci",
+    fill.legend = tm_legend(position = c(0.05, 0.7))) +
+tm_credits("Statistics Netherlands (CBS)", position = c(0.05, 0.05)) +
+tm_compass(type = "8star", position = c(0.8, 0.2)) +
+tm_scalebar(position = c(0.3, 0.15))
+```
+
+Note that these shortcuts always draws the components in the map frame. 
+
+## Advanced: [tm_pos()]
+
+
+[tm_pos_in()] draws the component inside the map frame and [tm_pos_out()] draws the component outside the map frame.
+
+#### `cell.h` and `cell.v`
+
+The total plot area (i.e. device) is a 3 x 3 grid. The map is draw in the middle grid cell.
+
+```{r, fig.height = 4}
+tm1 = tm_shape(NLD_muni) + tm_polygons() +
+		tm_compass(type = "8star", size = 8, position = tm_pos_out(cell.h = "left", cell.v = "center"))
+tm2 = tm_shape(NLD_muni) + tm_polygons() +
+		tm_compass(type = "8star", size = 8, position = tm_pos_out(cell.h = "center", cell.v = "bottom"))
+tm3 = tm_shape(NLD_muni) + tm_polygons() +
+		tm_compass(type = "8star", size = 8, position = tm_pos_out(cell.h = "right", cell.v = "bottom"))
+tmap_arrange(tm1, tm2, tm3, ncol = 3)
+
+```
+
+Notes: 
+
+* the sizes of the cells are automatically determined based on the content and the [margins](https://r-tmap.github.io/tmap/articles/42_margins)
+* [tm_pos_in()] is a shortcut for [tm_pos_out()] with both `cell.h` and `cell.v` set to `"center"`.
+
+#### `pos.h` and `pos.v`
+
+The position of a component within a cell:
+
+```{r, fig.height = 4}
+tm_shape(NLD_muni) + tm_polygons() +
+		tm_compass(type = "8star", size = 8, position = tm_pos_out(cell.h = "left", cell.v = "center", pos.v = "bottom"))
+```
+
+### `align.h` and `align.v`
+
+The alignment of components within the same cell:
+
+```{r, fig.height = 4}
+tm1 = tm_shape(NLD_muni) + tm_polygons() +
+	tm_compass(type = "8star", position = tm_pos_in(pos.h = "right", pos.v = "bottom", align.h = "left")) +
+	tm_scalebar(position = tm_pos_in(pos.h = "right", pos.v = "bottom", align.h = "left"))
+tm2 = tm_shape(NLD_muni) + tm_polygons() +
+	tm_compass(type = "8star", position = tm_pos_in(pos.h = "right", pos.v = "bottom", align.h = "center")) +
+	tm_scalebar(position = tm_pos_in(pos.h = "right", pos.v = "bottom", align.h = "left"))
+tm3 = tm_shape(NLD_muni) + tm_polygons() +
+	tm_compass(type = "8star", position = tm_pos_in(pos.h = "right", pos.v = "bottom", align.h = "right")) +
+	tm_scalebar(position = tm_pos_in(pos.h = "right", pos.v = "bottom", align.h = "left"))
+tmap_arrange(tm1, tm2, tm3, ncol = 3)
+```
diff --git a/vignettes/41_options.Rmd → vignettes/42_adv_options.Rmd b/vignettes/41_options.Rmd → vignettes/42_adv_options.Rmd
diff --git a/vignettes/42_margins.Rmd → vignettes/43_adv_margins.Rmd b/vignettes/42_margins.Rmd → vignettes/43_adv_margins.Rmd
diff --git a/vignettes/43_extensions.Rmd → vignettes/44_adv_extensions.Rmd b/vignettes/43_extensions.Rmd → vignettes/44_adv_extensions.Rmd