Merge pull request #1000 from r-tmap/documentation-tune

Documentation fine tune + attempt to use dev leafem for vignettes

DESCRIPTION

@@ -61,7 +61,7 @@ Suggests:
     rstudioapi
 Config/Needs/check: Nowosad/spDataLarge, lwgeom
 Config/Needs/coverage: Nowosad/spDataLarge, lwgeom
-Config/Needs/website: bookdown, geofacet, rmarkdown, mapview, sits
+Config/Needs/website: bookdown, geofacet, rmarkdown, mapview, sits, r-spatial/leafem
 Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true

R/docs.R

@@ -85,14 +85,14 @@
 					zoom = "zoom")
 
 	extra_lookup = c(margins = " A vector of 4 values: bottom, left, top, right. The unit is the device height (for bottom and top) or width (for left and right).",
-					 double_line = " TRUE of FALSE.",
+					 double_line = " `TRUE` or `FALSE`.",
 					 extra = " A list of arguments.",
 					 padding = " A vector of 4 values: bottom, left, top, right. The unit is the device height (for bottom and top) or width (for left and right).",
 					 space = " In terms of number of line heights.",
 					 fontfamily = " See `graphics::par`, option 'family'.",
 					 fontface = " See `graphics::par`, option 'font'.",
 					 lwd = " See `graphics::par`, option 'lwd'.",
-					 show = " TRUE or FALSE.")
+					 show = " `TRUE` or `FALSE`.")
 
 	what_text = unname(what_lookup[what])
 	if (is.na(what_text)) what_text = what

R/step1_rearrange.R

@@ -205,10 +205,10 @@ step1_rearrange = function(tmel) {
 			}
 			sel_aux
 		})
-		if (all((!sel_aux))) {
+		if (!any(sel_aux)) {
 			#is_aux = FALSE
 			aux = list()
-		} else if (any(!sel_aux)) {
+		} else if (!all(sel_aux)) {
 			aux = aux[sel_aux]
 		}
 	} else {

R/tm_components.R

@@ -221,7 +221,7 @@ tm_minimap <- function(server,
 #' @param height height of the logo in number of text line heights. The width is scaled based the height and the aspect ratio of the logo.
 #'   If multiple logos are specified by a vector or list, the heights can be specified accordingly.
 #' @param margins margins
-#' @param between_margin between_margin
+#' @param between_margin Margin between
 #' @param stack stack
 #' @inheritParams tm_title
 #' @param group.frame group.frame

R/tm_scale_.R

@@ -33,10 +33,9 @@ tm_scale = function(...) {
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the
 #' layer functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function [tm_scale_asis()] is used to take data values as they are and use them as such for the visual variable.
+#' The function `tm_scale_asis()` is used to take data values as they are and use them as such for the visual variable.
 #'
-#' @param values.scale (generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as `size` of [tm_symbols()] and `lwd` of [tm_lines()].
-#' @param value.neutral (generic scale argument) Value that can be considered neutral. This is used for legends of other visual variables of the same map layer. E.g. when both `fill` and `size` are used for [tm_symbols()] (using filled circles), the size legend items are filled with the `value.neutral` color from the `fill.scale` scale, and fill legend items are bubbles of size `value.neutral` from the `size.scale` scale.
+#' @inheritParams tm_scale_categorical
 #' @param ... Arguments caught (and not used) from the automatic function [tm_scale()]
 #' @seealso [tm_scale()]
 #' @export
@@ -117,17 +116,13 @@ tm_scale_categorical = function(n.max = 30,
 #' @param n Number of intervals. For some styles (see argument `style` below) it is the preferred number rather than the exact number.
 #' @param style Method to create intervals. Options are `"cat"`, `"fixed"`, `"sd"`, `"equal"`, `"pretty"`, `"quantile"`, `"kmeans"`, `"hclust"`, `"bclust"`, `"fisher"`, `"jenks"`, `"dpih"`, `"headtails"`, and `"log10_pretty"`. See the details in [classInt::classIntervals()] (extra arguments can be passed on via `style.args`).
 #' @param style.args List of extra arguments passed on to [classInt::classIntervals()].
-#' @param breaks Interval breaks (only used and required when `style=="fixed"`)
+#' @param breaks Interval breaks (only used and required when `style = "fixed"`)
 #' @param interval.closure value that determines whether where the intervals are closed: `"left"` or `"right"`. If `as.count = TRUE`, `inverval.closure` is always set to `"left"`.
 #' @param midpoint The data value that is interpreted as the midpoint. By default it is set to 0 if negative and positive values are present. Useful when values are diverging colors. In that case, the two sides of the color palette are assigned to negative respectively positive values. If all values are positive or all values are negative, then the midpoint is set to `NA`, which means that the value that corresponds to the middle color class (see `style`) is mapped to the middle color. If it is specified for sequential color palettes (e.g. `"Blues"`), then this color palette will be treated as a diverging color palette.
 #' @param as.count Should the data variable be processed as a count variable? For instance, if `style = "pretty"`, `n = 2`, and the value range of the variable is 0 to 10, then the column classes for `as.count = TRUE` are 0; 1 to 5; 6 to 10 (note that 0 is regarded as an own category) whereas for `as.count = FALSE` they are 0 to 5; 5 to 10. Only applicable if `style` is `"pretty"`, `"fixed"`, or `"log10_pretty"`. By default `FALSE`.
+#' @inheritParams tm_scale_categorical
 #' @param values (generic scale argument) The visual values. For colors (e.g. `fill` or `col` for [tm_polygons()]) this is a palette name from the `cols4all` package (see [cols4all::c4a()]) or vector of colors, for size (e.g. `size` for `tm_symbols`) these are a set of sizes (if two values are specified they are interpret as range), for symbol shapes (e.g. `shape` for `tm_symbols`) these are a set of symbols, etc. The tmap option `values.var` contains the default values per visual variable and in some cases also per data type.
-#' @param values.repeat (generic scale argument) Should the values be repeated in case there are more categories?
 #' @param values.range (generic scale argument) Range of the values. Vector of two numbers (both between 0 and 1) where the first determines the minimum and the second the maximum. Full range, which means that all values are used, is encoded as `c(0, 1)`. For instance, when a gray scale is used for color (from black to white), `c(0,1)` means that all colors are used, `0.25, 0.75` means that only colors from dark gray to light gray are used (more precisely `"gray25"` to `"gray75"`), and `0, 0.5` means that only colors are used from black to middle grey (`"grey50"`). When only one number is specified, this is interpreted as the second number (where the first is set to 0). Default values can be set via the tmap option `values.range`.
-#' @param values.scale (generic scale argument) Scaling of the values. Only useful for size-related visual variables, such as `size` of [tm_symbols()] and `lwd` of [tm_lines()].
-#' @param value.na (generic scale argument) Value used for missing values. See tmap option `"value.na"` for defaults per visual variable.
-#' @param value.null (generic scale argument) Value used for NULL values. See tmap option `"value.null"` for defaults per visual variable. Null data values occur when out-of-scope features are shown (e.g. for a map of Europe showing a data variable per country, the null values are applied to countries outside Europe).
-#' @param value.neutral (generic scale argument) Value that can be considered neutral. This is used for legends of other visual variables of the same map layer. E.g. when both `fill` and `size` are used for [tm_symbols()] (using filled circles), the size legend items are filled with the `value.neutral` color from the `fill.scale` scale, and fill legend items are bubbles of size `value.neutral` from the `size.scale` scale.
 #' @param labels (generic scale argument) Labels
 #' @param label.na (generic scale argument) Label for missing values
 #' @param label.null (generic scale argument) Label for null (out-of-scope) values
@@ -199,7 +194,7 @@ tm_scale_discrete = function(ticks = NA,
 #' Scales in tmap are configured by the family of functions with prefix `tm_scale`.
 #' Such function should be used for the input of the `.scale` arguments in the layer
 #' functions (e.g. `fill.scale` in [tm_polygons()]).
-#' The function [tm_scale_continuous()] is used for continuous data.
+#' The function `tm_scale_continuous()` is used for continuous data.
 #' The functions `tm_scale_continuous_<x>()` use transformation functions x.
 #'
 #' @param n Preferred number of tick labels. Only used if `ticks` is not specified
@@ -268,7 +263,7 @@ tm_scale_continuous = function(n = NULL,
 #' @param label.na (generic scale argument) Label for missing values
 #' @param label.null (generic scale argument) Label for null (out-of-scope) values
 #' @param label.format (generic scale argument) Label formatting (similar to `legend.format` in tmap3)
-#' @param unit unit the unit name of the values. By default `"rank"`.
+#' @param unit The unit name of the values. By default `"rank"`.
 #' @seealso [tm_scale()]
 #' @export
 tm_scale_rank = function(n = NULL,

R/tmapGridComp.R

@@ -432,7 +432,7 @@ tmapGridComp = function(comp, o, facet_row = NULL, facet_col = NULL, facet_page,
 	grbs = do.call(grid::gList, lapply(1:5, function(i) {
 		id = get(paste0("w", i))
 		if (length(id)) {
-			if (any(!stack_auto[id])) {
+			if (!all(stack_auto[id])) {
 				# get first specified 'stack' argument
 				stck = stack[id][which(!stack_auto[id])[1]]
 			} else {

R/tmapGridComp_leg_landscape.R

@@ -202,7 +202,7 @@ tmapGridLegPlot.tm_legend_standard_landscape = function(comp, o, fH, fW) {
 			grTicksMargin = NULL
 		}
 
-		if (any(!ticks_in_margin)) {
+		if (!all(ticks_in_margin)) {
 			grTicksItem = do.call(c, lapply(ticks[!ticks_in_margin], function(y) {
 				mapply(function(i, id) gridCell(6, id, grid::linesGrob(x = c(0.5, 0.5), y = 1 - y, gp = grid::gpar(col = tick_col, lwd = comp$ticks.lwd * comp$scale))), 1L:ni, comp$item_ids[1L:ni], SIMPLIFY = FALSE)
 			}))

R/tmapGridComp_leg_portrait.R

@@ -368,7 +368,7 @@ tmapGridLegPlot.tm_legend_standard_portrait = function(comp, o, fH, fW) {
 			grTicksMargin = NULL
 		}
 
-		if (any(!ticks_in_margin)) {
+		if (!all(ticks_in_margin)) {
 			grTicksItem = do.call(c, lapply(ticks[!ticks_in_margin], function(x) {
 				mapply(function(i, id) gridCell(id, 3, grid::linesGrob(x = x, y = c(0.5, 0.5), gp = grid::gpar(col = tick_col, lwd = comp$ticks.lwd * comp$scale))), 1L:ni, comp$item_ids[1L:ni], SIMPLIFY = FALSE)
 			}))

R/tmapLeaflet_layers.R

@@ -43,7 +43,7 @@ impute_webgl = function(use_WebGL, dt, supported, checkif = NULL, type, hover, p
 			} else {
 				message_webgl_vars(supported, vary)
 			}
-		} else if (any(!checks)) {
+		} else if (!all(checks)) {
 			if (is.na(use_WebGL)) {
 				use_WebGL = FALSE
 			} else {

R/tmapShape.R

@@ -19,7 +19,7 @@ reproject_bbox = function(bbox, crs) {
 #' @param shp shp
 #' @param is.main is.main
 #' @param crs crs
-#' @param bbox bbox
+#' @param bbox Bounding box
 #' @param unit unit
 #' @param filter filter
 #' @param shp_name shp_name

R/tmap_options.R

@@ -36,8 +36,8 @@
 #' @param values.scale Default scales (as in object sizes) for values. See `values.range` of [tm_scale_categorical()]. A list is required with per visual variable a value.
 #' @param scales.var Default scale functions per visual variable and type of data variable. A list is required with per visual variable per data type.
 #' @param scale.misc.args Default values of scale function-specific arguments. A list is required with per scale function and optional per visual variable.
-#' @param continuous.nclass_per_legend_break The number of continuous legend breaks within one 'unit' (label).  The dafault value is 50.
-#' @param continuous.nclasses the number of classes of a continuous scale. Should be odd.  The dafault value is 101.
+#' @param continuous.nclass_per_legend_break The number of continuous legend breaks within one 'unit' (label).  The default value is 50.
+#' @param continuous.nclasses the number of classes of a continuous scale. Should be odd.  The default value is 101.
 #' @param label.format Format for the labels (was `legend.format` in tmap v3).
 #' @param label.na Default label for missing values.
 #' @param scale Overall scale of the map
@@ -81,8 +81,8 @@
 #' @param ylab.side `r .doc_opt("ylab.side")`
 #' @param panel.type `r .doc_opt("panel.type")`
 #' @param panel.wrap.pos The panel positions for wrapped facets created with [tm_facets_grid()]. One of `"left"`, `"right"`, `"top"` (default) or `"bottom"`.
-#' @param panel.xtab.pos The panel positions for grid facets created with [tm_facets_grid()]. Vector of two, where the first determines the location sof row panels (`"left"` or `"right"`) and the second the location of column panels ( `"top"` or `"bottom")
-#' @param unit `r .doc_opt("unit")`
+#' @param panel.xtab.pos The panel positions for grid facets created with [tm_facets_grid()]. Vector of two, where the first determines the locations of row panels (`"left"` or `"right"`) and the second the location of column panels ( `"top"` or `"bottom")
+#' @param unit Unit of the coordinate
 #' @param color.sepia_intensity `r .doc_opt("color.sepia_intensity")`
 #' @param color.saturation `r .doc_opt("color.saturation")`
 #' @param color_vision_deficiency_sim `r .doc_opt("color_vision_deficiency_sim")`
@@ -286,19 +286,17 @@
 #' @param panel.label.frame.r `r .doc_opt("panel.label.frame.r")`
 #' @param panel.label.height `r .doc_opt("panel.label.height")`
 #' @param panel.label.rot `r .doc_opt("panel.label.rot")`
-#' @param bbox `r .doc_opt("bbox")`
-#' @param set_bounds `r .doc_opt("set_bounds")`
-#' @param set_view `r .doc_opt("set_view")`
-#' @param set_zoom_limits `r .doc_opt("set_zoom_limits")`
+# For set_bounds, set_view, set_zoom_limits
+#' @inheritParams tm_view
 #' @param qtm.scalebar `r .doc_opt("qtm.scalebar")`
 #' @param qtm.minimap `r .doc_opt("qtm.minimap")`
 #' @param qtm.mouse_coordinates `r .doc_opt("qtm.mouse_coordinates")`
 #' @param earth_boundary `r .doc_opt("earth_boundary")`
 #' @param earth_boundary.color `r .doc_opt("earth_boundary.color")`
 #' @param earth_boundary.lwd `r .doc_opt("earth_boundary.lwd")`
-#' @param earth_datum `r .doc_opt("earth_datum")`
+#' @param earth_datum  Earth datum
 #' @param space.color `r .doc_opt("space.color")`
-#' @param check_and_fix `r .doc_opt("check_and_fix")`
+#' @param check_and_fix Should attempt to fix an invalid shapefile
 #' @param basemap.show `r .doc_opt("basemap.show")`
 #' @param basemap.server `r .doc_opt("basemap.server")`
 #' @param basemap.alpha `r .doc_opt("basemap.alpha")`
@@ -312,8 +310,10 @@
 #' @param main.title deprecated See [tm_title()]
 #' @param main.title.size,main.title.color,main.title.fontface,main.title.fontfamily,main.title.position deprecated. Use the `title.` options instead.
 #' @inheritParams tm_plot
-#' @inheritParams tm_view
+# For bbox
+#' @inheritParams tm_shape
 #' @export
+#' @name tmap_options
 tmap_options = function(..., crs, facet.max, facet.flip, free.scales, raster.max_cells, show.messages, show.warnings, output.format, output.size, output.dpi, animation.dpi, value.const, value.na, value.null, value.blank, values.var, values.range, value.neutral, values.scale, scales.var, scale.misc.args, continuous.nclass_per_legend_break, continuous.nclasses, label.format, label.na, scale, asp, bg.color, outer.bg.color, frame, frame.lwd, frame.r, frame.double_line, outer.margins, inner.margins, inner.margins.extra, meta.margins, meta.auto_margins, between_margin, panel.margin, component.offset, component.stack_margin, grid.mark.height, xylab.height, coords.height, xlab.show, xlab.text, xlab.size, xlab.color, xlab.rotation, xlab.space, xlab.fontface, xlab.fontfamily, xlab.side, ylab.show, ylab.text, ylab.size, ylab.color, ylab.rotation, ylab.space, ylab.fontface, ylab.fontfamily, ylab.side, panel.type, panel.wrap.pos, panel.xtab.pos, unit, color.sepia_intensity, color.saturation, color_vision_deficiency_sim, text.fontface, text.fontfamily, component.position, component.autoscale, legend.show, legend.design, legend.orientation, legend.position, legend.width, legend.height, legend.stack, legend.group.frame, legend.resize_as_group, legend.reverse, legend.na.show, legend.title.color, legend.title.size, legend.title.fontface, legend.title.fontfamily, legend.xlab.color, legend.xlab.size, legend.xlab.fontface, legend.xlab.fontfamily, legend.ylab.color, legend.ylab.size, legend.ylab.fontface, legend.ylab.fontfamily, legend.text.color, legend.text.size, legend.text.fontface, legend.text.fontfamily, legend.frame, legend.frame.lwd, legend.frame.r, legend.bg.color, legend.bg.alpha, legend.only, legend.settings.standard.portrait, legend.settings.standard.landscape, chart.show, chart.plot.axis.x, chart.plot.axis.y, chart.position, chart.width, chart.height, chart.stack, chart.group.frame, chart.resize_as_group, chart.reverse, chart.na.show, chart.title.color, chart.title.size, chart.title.fontface, chart.title.fontfamily, chart.xlab.color, chart.xlab.size, chart.xlab.fontface, chart.xlab.fontfamily, chart.ylab.color, chart.ylab.size, chart.ylab.fontface, chart.ylab.fontfamily, chart.text.color, chart.text.size, chart.text.fontface, chart.text.fontfamily, chart.frame, chart.frame.lwd, chart.frame.r, chart.bg.color, chart.bg.alpha, chart.object.color, title.show, title.size, title.color, title.fontface, title.fontfamily, title.bg.color, title.bg.alpha, title.padding, title.frame, title.frame.lwd, title.frame.r, title.stack, title.position, title.width, title.group.frame, title.resize_as_group, credits.show, credits.size, credits.color, credits.fontface, credits.fontfamily, credits.bg.color, credits.bg.alpha, credits.padding, credits.frame, credits.frame.lwd, credits.frame.r, credits.stack, credits.position, credits.width, credits.height, credits.group.frame, credits.resize_as_group, compass.north, compass.type, compass.text.size, compass.size, compass.show.labels, compass.cardinal.directions, compass.text.color, compass.color.dark, compass.color.light, compass.lwd, compass.bg.color, compass.bg.alpha, compass.margins, compass.show, compass.stack, compass.position, compass.frame, compass.frame.lwd, compass.frame.r, compass.group.frame, compass.resize_as_group, logo.height, logo.margins, logo.between_margin, logo.show, logo.stack, logo.position, logo.frame, logo.frame.lwd, logo.frame.r, logo.group.frame, logo.resize_as_group, scalebar.show, scalebar.breaks, scalebar.width, scalebar.text.size, scalebar.text.color, scalebar.color.dark, scalebar.color.light, scalebar.lwd, scalebar.bg.color, scalebar.bg.alpha, scalebar.size, scalebar.margins, scalebar.stack, scalebar.position, scalebar.frame, scalebar.frame.lwd, scalebar.frame.r, scalebar.group.frame, scalebar.resize_as_group, grid.show, grid.labels.pos, grid.x, grid.y, grid.n.x, grid.n.y, grid.crs, grid.col, grid.lwd, grid.alpha, grid.labels.show, grid.labels.size, grid.labels.col, grid.labels.rot, grid.labels.format, grid.labels.cardinal, grid.labels.margin.x, grid.labels.margin.y, grid.labels.space.x, grid.labels.space.y, grid.labels.inside_frame, grid.ticks, grid.lines, grid.ndiscr, mouse_coordinates.stack, mouse_coordinates.position, mouse_coordinates.show, minimap.server, minimap.toggle, minimap.stack, minimap.position, minimap.show, panel.show, panel.labels, panel.label.size, panel.label.color, panel.label.fontface, panel.label.fontfamily, panel.label.bg.color, panel.label.frame, panel.label.frame.lwd, panel.label.frame.r, panel.label.height, panel.label.rot, bbox, qtm.scalebar, qtm.minimap, qtm.mouse_coordinates, earth_boundary, earth_boundary.color, earth_boundary.lwd, earth_datum, space.color, check_and_fix, basemap.show, basemap.server, basemap.alpha, basemap.zoom, tiles.show, tiles.server, tiles.alpha, tiles.zoom, attr.color,
 						use_gradient, # plot mode
 						use_browser, use_WebGL, control.position, control.bases, control.overlays, set_bounds, # view mode