NLD updated #967

r-tmap · Nov 28, 2024 · 3bfdfd5 · 3bfdfd5
1 parent 25d7a6f
commit 3bfdfd5
Show file tree

Hide file tree

Showing 26 changed files with 328 additions and 226 deletions.
diff --git a/R/data.R b/R/data.R
@@ -17,7 +17,7 @@
 #' | `gdp_cap_est`		| NED | GDP per capita (estimated) |
 #' | `life_exp`			| HPI | Life expectancy. The average number of years an infant born in that country is expected to live  |
 #' | `well_being`		| HPI | Well being. Self-reported from 0 (worst) to 10 (best) |
-#' | `footprint`		| HPI | Carbon footprint. Per capita greenhouse gas emissions associated with consumption and economic activity |
+#' | `footprint`		| HPI | Carbon footprint. Per capita greendwelling gas emissions associated with consumption and economic activity |
 #' | `HPI`				| HPI | Happy Planet Indicator. An index of human well-being and environmental impact that was introduced by the New Economics Foundation in 2006. Approximate formula: `(life_exp * well_being) / footprint` |
 #' | `inequality`		| WB | Income inequality: Gini coefficient (World Bank variable SI.POV.GINI) A value of 0 represents perfect equality, while 100 implies perfect inequality |
 #' | `gender`			| UNDP/OWiD | Gender Inequality Index (GII) Composite metric using reproductive health, empowerment and the labour market. A low value indicates low inequality between women and men, and vice-versa |
@@ -45,28 +45,55 @@
 
 #' Netherlands datasets
 #'
-#' Datasets of the Netherlands (province and municipality level),
-#' class [`sf`][`sf::sf`]
+#' Datasets of the Netherlands at three levels: `NLD_prov` (12) provinces, `NLD_muni` (345) municipalities and `NLD_dist` districts (3340), all class [`sf`][`sf::sf`]
 #'
-#' The default projections for these objects are
-#' Rijksdriehoekstelsel (Netherlands).
-#'
-#' **Important:** publication of these maps is only allowed when citing
-#' Statistics Netherlands (CBS) and Kadaster Nederland as source.
+#' @details
+#' The variables for `NLD_muni` and `NLD_dist` are identical. The data variables are:
+#'
+#' | variable        | description |
+#' | ------          | ----------- |
+#' | `code`		     | Code |
+#' | `name`		     | Name |
+#' | `prov_code`	 | Province code (corresponds to `code` column of `NLD_prov`) |
+#' | `area`		     | Total area in km2 |
+#' | `urbanity`		 | Level of urbanity. Five classes, determined by the number of addresses per km2 (break values are 2500, 1500, 1000, and 500). |
+#' | `population`	 | The total population count at 2022-01-01 |
+#' | `pop_0_14`		 | Percentage (rounded) of people between 0 and 15 |
+#' | `pop_15_24`	 | Percentage (rounded) of people between 15 and 25  |
+#' | `pop_25_44`	 | Percentage (rounded) of people between 25 and 45  |
+#' | `pop_45_64`	 | Percentage (rounded) of people between 45 and 65  |
+#' | `pop_65plus`	 | Percentage (rounded) of people of 65 and older |
+#' | `dwelling_total`	 | Number of dwellings |
+#' | `dwelling_value`	 | Average dwelling value (Dutch: WOZ-value) |
+#' | `dwelling_ownership`| Percentage of dwellings owned by the residents |
+#' | `employment_rate`|  Share of the employed population within the total population from 15-75 years old (working and non-working) |
+#' | `income_low`	 | Percentage of individuals in private households belonging to the lowest 40% of personal income nationwide. |
+#' | `income_high`	 | Percentage of individuals in private households belonging to the highest 20% of personal income nationwide. |
+#' | `edu_appl_sci`	 | Percentage of people aged 15 to 75 with a university of applied sciences (Dutch: HBO) or university (Dutch: WO) degree. |
+#'
+#' See source for more in-depth information of the variables.
+#'
+#' This dataset, created Noveber 2024, is an update from the datasets `NLD_muni` and `NLD_prov` used in tmap <= 3, which has been created around 2016. Note that the number of municipalities have been reduced (due to mergings). All old variables are included, except for variables related to ethnicity. Many new variable have been added, and moreover, district (Dutch: wijk) level data have added: `NLD_dist`.
+#'
+#' The CRS (coordinate reference system) used is the Rijksdriekhoekstelsel New, EPSG 28992. Coordinates have been rounded to meters to reduce filesize.
 #'
 #' @rdname Netherlands
 #' @docType data
 #' @format NULL
-#' @source <https://www.cbs.nl/> for `NLD_prov` and `NLD_muni`.
-#' @references Statistics Netherlands (2014), The Hague/Heerlen, Netherlands, <https://www.cbs.nl/>.
-#' @references Kadaster, the Netherlands' Cadastre, Land Registry, and Mapping Agency (2014), Apeldoorn, Netherlands, <https://www.kadaster.nl/>.
+#' @source https://www.cbs.nl/nl-nl/maatwerk/2024/11/kerncijfers-wijken-en-buurten-2022
+#' @references Statistics Netherlands (2022), The Hague/Heerlen, Netherlands, <https://www.cbs.nl/>.
 "NLD_prov"
 
 #' @rdname Netherlands
 #' @docType data
 #' @format NULL
 "NLD_muni"
 
+#' @rdname Netherlands
+#' @docType data
+#' @format NULL
+"NLD_dist"
+
 #' Spatial data of rivers
 #'
 #' @source <https://www.naturalearthdata.com>

diff --git a/R/misc_other.R b/R/misc_other.R
@@ -20,7 +20,7 @@ select_sf = function(shpTM, dt) {
 
 	shpSel = shp[sid] #sf::st_cast(shp[match(tid, tmapID)], "MULTIPOLYGON")
 
-	# assign prop_ vectors to data dt (to be used in plotting) e.g. prop_angle is determined in tmapTransCentroid when along.lines = TRUE
+	# assign prop_ vectors to data dt (to be used in plotting) e.g. prop_angle is determined in tmapTransCentroid when along_lines = TRUE
 	prop_vars = names(shpTM)[substr(names(shpTM), 1, 5) == "prop_"]
 	if (length(prop_vars)) {
 		for (p in prop_vars) {

diff --git a/R/tm_layers_sf.R b/R/tm_layers_sf.R
@@ -151,13 +151,13 @@ tm_sf = function(fill = tm_const(),
 #' @export
 opt_tm_sf = function(polygons.only = "yes",
 					 lines.only = "yes",
-					 points.only = "yes",
-					 point.per = "feature",
+					 points_only = "yes",
+					 point_per = "feature",
 					 points.icon.scale = 3,
 					 points.just = NA,
 					 points.grob.dim = c(width = 48, height = 48, render.width = 256, render.height = 256)) {
 
-	list(points = list(trans.args = list(points.only = points.only, point.per = point.per, along.lines = FALSE),
+	list(points = list(trans.args = list(points_only = points_only, point_per = point_per, on_surface = FALSE, along_lines = FALSE),
 					   mapping.args = list(icon.scale = points.icon.scale,
 					   					just = points.just,
 					   					grob.dim = points.grob.dim)),

diff --git a/R/tm_layers_symbols.R b/R/tm_layers_symbols.R
@@ -669,47 +669,52 @@ tm_markers = function(text = tm_const(),
 	tm_d = do.call(tm_dots, args_dots)
 	tm_d[[1]]$layer = c("markers", "symbols")
 
-	if (options$markers$markers.on.top.of.text) tm_t + tm_d else tm_d + tm_t
+	if (options$markers$markers_on_top_of_text) tm_t + tm_d else tm_d + tm_t
 }
 
 #' @inheritParams opt_tm_labels
-#' @param markers.on.top.of.text should markers be plot on top of the text (by default `FALSE`)
+#' @param markers_on_top_of_text should markers be plot on top of the text (by default `FALSE`)
 #' @param dots.icon.scale scaling number that determines how large the icons (or grobs) are in plot mode in comparison to proportional symbols (such as bubbles). In view mode, the size is determined by the icon specification (see \code{\link{tmap_icons}}) or, if grobs are specified by \code{grob.width} and \code{grob.height}
 #' @param dots.just justification of the text relative to the point coordinates. Either one of the following values: \code{"left"} , \code{"right"}, \code{"center"}, \code{"bottom"}, and \code{"top"}, or a vector of two values where first value specifies horizontal and the second value vertical justification. Besides the mentioned values, also numeric values between 0 and 1 can be used. 0 means left justification for the first value and bottom justification for the second value. Note that in view mode, only one value is used.
 #' @param dots.grob.dim vector of four values that determine how grob objects (see details) are shown in view mode. The first and second value are the width and height of the displayed icon. The third and fourth value are the width and height of the rendered png image that is used for the icon. Generally, the third and fourth value should be large enough to render a ggplot2 graphic successfully. Only needed for the view mode.
 #' @rdname tm_symbols
 #' @export
-opt_tm_markers = function(markers.on.top.of.text = FALSE,
-						  points.only = "ifany",
-						  point.per = "feature",
+opt_tm_markers = function(markers_on_top_of_text = FALSE,
+						  points_only = "ifany",
+						  point_per = "feature",
+						  on_surface = FALSE,
 						  shadow = FALSE,
 						  shadow.offset.x = 0.1,
 						  shadow.offset.y = 0.1,
 						  just = "center",
-						  along.lines = TRUE,
+						  along_lines = TRUE,
 						  bg.padding = 0.4,
 						  clustering = TRUE,
 						  point.label = TRUE,
 						  point.label.gap = 0.4,
 						  point.label.method = "SANN",
-						  remove.overlap = FALSE,
+						  remove_overlap = FALSE,
 						  dots.just = NA,
 						  dots.icon.scale = 3,
 						  dots.grob.dim = c(width=48, height=48, render.width=256, render.height=256)) {
-	list(markers = list(markers.on.top.of.text = markers.on.top.of.text),
-		 text = opt_tm_labels(points.only = points.only,
+	list(markers = list(markers_on_top_of_text = markers_on_top_of_text),
+		 text = opt_tm_labels(points_only = points_only,
+		 					 point_per = point_per,
+		 					 on_surface = on_surface,
 		 					 shadow = shadow,
 		 					 shadow.offset.x = shadow.offset.x,
 		 					 shadow.offset.y = shadow.offset.y,
 		 					 just = just,
-		 					 along.lines = along.lines,
+		 					 along_lines = along_lines,
 		 					 bg.padding = bg.padding,
 		 					 clustering = clustering,
 		 					 point.label = point.label,
 		 					 point.label.gap = point.label.gap,
 		 					 point.label.method = point.label.method,
-		 					 remove.overlap = remove.overlap),
-		 dots = opt_tm_dots(points.only = points.only,
+		 					 remove_overlap = remove_overlap),
+		 dots = opt_tm_dots(points_only = points_only,
+		 				   point_per = point_per,
+		 				   on_surface = on_surface,
 		 				   icon.scale = dots.icon.scale,
 		 				   just = dots.just,
 		 				   grob.dim = dots.grob.dim))
@@ -720,12 +725,13 @@ opt_tm_markers = function(markers.on.top.of.text = FALSE,
 #' @param grob.dim vector of four values that determine how grob objects (see details) are shown in view mode. The first and second value are the width and height of the displayed icon. The third and fourth value are the width and height of the rendered png image that is used for the icon. Generally, the third and fourth value should be large enough to render a ggplot2 graphic successfully. Only needed for the view mode.
 #' @rdname tm_symbols
 #' @export
-opt_tm_symbols = function(points.only = "ifany",
-						  point.per = "feature",
+opt_tm_symbols = function(points_only = "ifany",
+						  point_per = "feature",
+						  on_surface = FALSE,
 						  icon.scale = 3,
 						  just = NA,
 						  grob.dim = c(width=48, height=48, render.width=256, render.height=256)) {
-	list(trans.args = list(points.only = points.only, point.per = point.per, along.lines = FALSE),
+	list(trans.args = list(points_only = points_only, point_per = point_per, on_surface = on_surface, along_lines = FALSE),
 		 mapping.args = list(icon.scale = icon.scale,
 		 					just = just,
 		 					grob.dim = grob.dim))

diff --git a/R/tm_layers_text.R b/R/tm_layers_text.R
@@ -230,8 +230,8 @@ tm_text = function(text = tm_const(),
 
 
 
-		v4_opt_args = c("along.lines", "shadow", "just", "clustering", "point.label", "remove.overlap")
-		v3_opt_args = c("along.lines", "shadow", "just", "clustering", "auto.placement", "remove.overlap")
+		v4_opt_args = c("along_lines", "shadow", "just", "clustering", "point.label", "remove_overlap")
+		v3_opt_args = c("along_lines", "shadow", "just", "clustering", "auto.placement", "remove_overlap")
 		osel = which(v3_opt_args %in% names(args))
 		if (length(osel)) {
 			o3 = v3_opt_args[osel]
@@ -478,76 +478,81 @@ tm_labels_highlighted = function(text = tm_const(),
 	tm
 }
 
-#' @param points.only should only point geometries of the shape object (defined in [tm_shape()]) be plotted? By default `"ifany"`, which means `TRUE` in case a geometry collection is specified.
-#' @param point.per specification of how spatial points are mapped when the geometry is a multi line or a multi polygon. One of \code{"feature"}, \code{"segment"} or \code{"largest"}. The first generates a spatial point for every feature, the second for every segment (i.e. subfeature), the third only for the largest segment (subfeature). Note that the last two options can be significant slower.
+#' @param points_only should only point geometries of the shape object (defined in [tm_shape()]) be plotted? By default `"ifany"`, which means `TRUE` in case a geometry collection is specified.
+#' @param point_per specification of how spatial points are mapped when the geometry is a multi line or a multi polygon. One of \code{"feature"}, \code{"segment"} or \code{"largest"}. The first generates a spatial point for every feature, the second for every segment (i.e. subfeature), the third only for the largest segment (subfeature). Note that the last two options can be significant slower.
+#' @param on_surface In case of polygons, centroids are computed. Should the points be on the surface? If `TRUE`, which is slower than the default `FALSE`, centroids outside the surface are replaced with points computed with [sf::st_point_on_surface()].
 #' @param shadow Shadow behind the text. Logical or color.
 #' @param shadow.offset.x,shadow.offset.y Shadow offset in line heights
 #' @param just justification of the text relative to the point coordinates. Either one of the following values: \code{"left"} , \code{"right"}, \code{"center"}, \code{"bottom"}, and \code{"top"}, or a vector of two values where first value specifies horizontal and the second value vertical justification. Besides the mentioned values, also numeric values between 0 and 1 can be used. 0 means left justification for the first value and bottom justification for the second value. Note that in view mode, only one value is used.
-#' @param along.lines logical that determines whether labels are rotated along the spatial lines. Only applicable if a spatial lines shape is used.
+#' @param along_lines logical that determines whether labels are rotated along the spatial lines. Only applicable if a spatial lines shape is used.
 #' @param bg.padding The padding of the background in terms of line heights.
 #' @param clustering value that determines whether the text labels are clustered in \code{"view"} mode. One of: \code{TRUE}, \code{FALSE}, or the output of \code{\link[leaflet:markerClusterOptions]{markerClusterOptions}}.
 #' @param point.label logical that determines whether the labels are placed automatically. By default `FALSE` for `tm_text`, and `TRUE` for `tm_labels` if the number of labels is less than 500 (otherwise it will be too slow).
 #' @param point.label.gap numeric that determines the gap between the point and label
 #' @param point.label.method the optimization method, either `"SANN"` for simulated annealing (the default) or `"GA"` for a genetic algorithm.
-#' @param remove.overlap logical that determines whether the overlapping labels are removed
+#' @param remove_overlap logical that determines whether the overlapping labels are removed
 #' @rdname tm_text
 #' @export
-opt_tm_text = function(points.only = "ifany",
-					   point.per = "feature",
+opt_tm_text = function(points_only = "ifany",
+					   point_per = "feature",
+					   on_surface = FALSE,
 					   shadow = FALSE,
 					   shadow.offset.x = 0.1,
 					   shadow.offset.y = 0.1,
 					   just = "center",
-					   along.lines = FALSE,
+					   along_lines = FALSE,
 					   bg.padding = 0.4,
 					   clustering = FALSE,
 					   point.label = FALSE,
 					   point.label.gap = 0,
 					   point.label.method = "SANN",
-					   remove.overlap = FALSE) {
-	list(trans.args = list(points.only = points.only,
-						   point.per = point.per,
-						   along.lines = along.lines),
+					   remove_overlap = FALSE) {
+	list(trans.args = list(points_only = points_only,
+						   point_per = point_per,
+						   on_surface = on_surface,
+						   along_lines = along_lines),
 		 mapping.args = list(shadow = shadow,
 		 					shadow.offset.x = shadow.offset.x,
 		 					shadow.offset.y = shadow.offset.y,
 		 					just = just,
-		 					along.lines = along.lines,
+		 					along_lines = along_lines,
 		 					bg.padding = bg.padding,
 		 					clustering = clustering,
 		 					point.label = point.label,
 		 					point.label.gap = point.label.gap,
 		 					point.label.method = point.label.method,
-		 					remove.overlap = remove.overlap))
+		 					remove_overlap = remove_overlap))
 }
 
 #' @rdname tm_text
 #' @export
-opt_tm_labels = function(points.only = "ifany",
-						 point.per = "feature",
+opt_tm_labels = function(points_only = "ifany",
+						 point_per = "feature",
+						 on_surface = FALSE,
 						 shadow = FALSE,
 						 shadow.offset.x = 0.1,
 						 shadow.offset.y = 0.1,
 						 just = "center",
-						 along.lines = TRUE,
+						 along_lines = TRUE,
 						 bg.padding = 0.4,
 						 clustering = FALSE,
 						 point.label = NA,
 						 point.label.gap = 0.4,
 						 point.label.method = "SANN",
-						 remove.overlap = FALSE) {
-	list(trans.args = list(points.only = points.only,
-						   point.per = point.per,
-						   along.lines = along.lines),
+						 remove_overlap = FALSE) {
+	list(trans.args = list(points_only = points_only,
+						   point_per = point_per,
+						   on_surface = on_surface,
+						   along_lines = along_lines),
 		 mapping.args = list(shadow = shadow,
 		 					shadow.offset.x = shadow.offset.x,
 		 					shadow.offset.y = shadow.offset.y,
 		 					just = just,
-		 					along.lines = along.lines,
+		 					along_lines = along_lines,
 		 					bg.padding = bg.padding,
 		 					clustering = clustering,
 		 					point.label = point.label,
 		 					point.label.gap = point.label.gap,
 		 					point.label.method = point.label.method,
-		 					remove.overlap = remove.overlap))
+		 					remove_overlap = remove_overlap))
 }
diff --git a/R/tmapGridSymbols.R b/R/tmapGridSymbols.R
@@ -38,7 +38,7 @@ tmapGridSymbols = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page,
 
 	coords = sf::st_coordinates(shp)
 
-	# in case shp is a multipoint (point.per == "segment"), expand gp:
+	# in case shp is a multipoint (point_per == "segment"), expand gp:
 	cp = expand_coords_gp(coords, gp, ndt = nrow(dt))
 	coords = cp$coords
 	gp = cp$gp

diff --git a/R/tmapGridText.R b/R/tmapGridText.R
@@ -26,7 +26,7 @@ tmapGridText = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page, id
 
 	coords = sf::st_coordinates(shp)
 
-	# in case shp is a multipoint (point.per == "segment"), expand gp:
+	# in case shp is a multipoint (point_per == "segment"), expand gp:
 	cp = expand_coords_gp(coords, gp, ndt = nrow(dt))
 	coords = cp$coords
 	gp = cp$gp
@@ -90,7 +90,7 @@ tmapGridText = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page, id
 	with_shadow = (!identical(args$shadow, FALSE))
 
 
-	if (with_bg || with_shadow || args$remove.overlap || args$point.label) {
+	if (with_bg || with_shadow || args$remove_overlap || args$point.label) {
 		# grobs are processed seperately because of the order: backgrond1, shadow1, text1, background2, shadow2, text2, etc.
 		# becaues it is less efficient when there is no background/shadow (majority of use cases), this is a separate routine
 
@@ -111,7 +111,7 @@ tmapGridText = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page, id
 			grobTextShList = NULL
 		}
 
-		if (with_bg || args$remove.overlap) {
+		if (with_bg || args$remove_overlap) {
 			tGH = vapply(grobTextList, function(grb) {
 				grb$rot = 0
 				convertHeight(grobHeight(grb), "inch", valueOnly = TRUE)
@@ -147,7 +147,7 @@ tmapGridText = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page, id
 			grobTextBGList = NULL
 		}
 
-		#if (args$auto.placement || args$remove.overlap) {
+		#if (args$auto.placement || args$remove_overlap) {
 		# grobs to sf
 		s = do.call(c,lapply(grobTextBGList, .grob2Poly))
 		#}
@@ -193,7 +193,7 @@ tmapGridText = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page, id
 			}
 		}
 
-		if (args$remove.overlap) {
+		if (args$remove_overlap) {
 			im = sf::st_intersects(s, sparse = FALSE)
 			sel = rep(TRUE, length(s))
 			rs = rowSums(im)
@@ -208,7 +208,7 @@ tmapGridText = function(shpTM, dt, gp, bbx, facet_row, facet_col, facet_page, id
 			sel = TRUE
 		}
 
-		if (!with_bg && args$remove.overlap) {
+		if (!with_bg && args$remove_overlap) {
 			grobTextBGList = NULL
 		}