Merge branch 'main' of github.com:r-spatial/sf

Author: edzer

NEWS.md

@@ -2,7 +2,7 @@
 
 * `[.sfc` works when setting argument `op`; #2320
 
-* `st_sample` for polygons is sensitive to setting `oriented = TRUE` to prevent wrongly correcting ring directions; #2308
+* `st_sample()` for polygons is sensitive to setting `oriented = TRUE` to prevent wrongly correcting ring directions; #2308
 
 * add support for the GDAL `footprint` utility (requiring GDAL >= 3.8.0) to `gdal_utils`; #2305, by @goergen95
 
@@ -42,9 +42,9 @@
 
 * if the env. variable `ADD_SF_NAMESPACE` is set to `true`, `sf` objects get a new attribute, `.sf_namespace`, which forces loading the `sf` namespace when it has not been loaded so far, e.g. for proper printing or plotting of an `sf` object; #2212 by Mike Mahoney
 
-* `distinct.sf` is type-safe for `sf` objects with zero rows; #2204
+* `distinct.sf()` is type-safe for `sf` objects with zero rows; #2204
 
-* `summarise.sf` raises an error if `.by` is given but no `across()` on the geometry; #2207
+* `summarise.sf()` raises an error if `.by` is given but no `across()` on the geometry; #2207
 
 * `st_write()` matches fields on name first, than on position; this matters for formats that have pre-defined names, such as GPX; #2202 
 
@@ -152,7 +152,7 @@
 
 * `sf_project()` accepts 3- or 4-column matrices, containing z and t values;
 
-* optimizations for `st_sfc()` by @paleolimbot; #1938, #1925
+* optimization for `st_sfc()` by @paleolimbot; #1938, #1925
 
 * `[<-.sfc()` recomputes the bounding box; `st_sfc()` gets parameter `compute_bbox`; #1965
 
@@ -819,7 +819,7 @@
 
 * have `st_graticule` return an empty graticule object when argument `datum` is `NA`; 
 
-* export `as_Spatial`, to make it easer for packages to convert `sfc` objects without importing `sf`
+* export `as_Spatial`, to make it easier for packages to convert `sfc` objects without importing `sf`
 
 * `st_distance` gains a parameter `by_element` to obtain pairwise distances; #437
 
@@ -1029,7 +1029,7 @@
 
 * add `st_proj_info`, modelled after `rgdal::projInfo`
 
-* overwriting datasets with `st_write` is no longer allowed; update=TRUE appends to them, permitted the driver supports appending.
+* overwriting datasets with `st_write()` is no longer allowed; `update=TRUE` appends to them, permitted the driver supports appending.
 
 * `st_write` gains an argument, `update`, which when `TRUE` will try to append to existing datasets (#204)
 

R/break_antimeridian.R

@@ -10,10 +10,10 @@
 #' the protruding geometries will also be split using the same \code{tol=} 
 #' values; in this case empty geometries will be dropped first.
 #'
-#' @param x object of class sf or sfc
+#' @param x object of class `sf` or `sfc`
 #' @param lon_0 target central longitude (degrees)
 #' @param tol half of break width (degrees, default 0.0001)
-#' @param ... ingnored here
+#' @param ... ignored here
 #' @export
 #' @name st_break_antimeridian
 #' @examples

R/crs.R

@@ -241,7 +241,7 @@ st_set_crs = function(x, value) {
 #'
 #' Assert whether simple feature coordinates are longlat degrees
 #' @param x object of class \link{sf} or \link{sfc}, or otherwise an object of a class that has an \link{st_crs} method returning a \code{crs} object
-#' @return TRUE if x has geographic coordinates, FALSE if it has projected coordinates, or NA if \code{is.na(st_crs(x))}.
+#' @return `TRUE` if `x` has geographic coordinates, `FALSE` if it has projected coordinates, or `NA` if \code{is.na(st_crs(x))}.
 #' @export
 st_is_longlat = function(x) {
 	crs = st_crs(x)

R/datasets.R

@@ -2,8 +2,8 @@
 #'
 #' Sudden Infant Death Syndrome (SIDS) sample data for North Carolina counties,
 #' two time periods (1974-78 and 1979-84). The details of the columns can be
-#' found on the seealso URL, spdep package's vignette. Please note that,
-#' though this is basically the same as \code{nc.sids} dataset in spData
+#' found in a [spdep package vignette](https://r-spatial.github.io/spdep/articles/sids.html). 
+#' Please note that, though this is basically the same as \code{nc.sids} dataset in spData
 #' package, \code{nc} only contains a subset of variables. The differences are
 #' also discussed on the vignette.
 #' @format A `sf` object 

R/geom-predicates.R

@@ -80,7 +80,7 @@ st_geos_binop = function(op, x, y, par = 0.0, pattern = NA_character_,
 #' @param x object of class \code{sf}, \code{sfc} or \code{sfg}
 #' @param y object of class \code{sf}, \code{sfc} or \code{sfg}
 #' @param pattern character; define the pattern to match to, see details.
-#' @param sparse logical; should a sparse matrix be returned (TRUE) or a dense matrix?
+#' @param sparse logical; should a sparse matrix be returned (`TRUE`) or a dense matrix?
 #' @return In case \code{pattern} is not given, \code{st_relate} returns a dense \code{character} matrix; element `[i,j]` has nine characters, referring to the DE9-IM relationship between `x[i]` and `y[j]`, encoded as IxIy,IxBy,IxEy,BxIy,BxBy,BxEy,ExIy,ExBy,ExEy where I refers to interior, B to boundary, and E to exterior, and e.g. BxIy the dimensionality of the intersection of the the boundary of `x[i]` and the interior of `y[j]`, which is one of: 0, 1, 2, or F; digits denoting dimensionality of intersection, F denoting no intersection. When \code{pattern} is given, a dense logical matrix or sparse index list returned with matches to the given pattern; see \link{st_intersection} for a description of the returned matrix or list. See also \url{https://en.wikipedia.org/wiki/DE-9IM} for further explanation.
 #' @export
 #' @examples
@@ -113,9 +113,9 @@ st_relate	= function(x, y, pattern = NA_character_, sparse = !is.na(pattern)) {
 #' @name geos_binary_pred
 #' @param x object of class \code{sf}, \code{sfc} or \code{sfg}
 #' @param y object of class \code{sf}, \code{sfc} or \code{sfg}; if missing, \code{x} is used
-#' @param sparse logical; should a sparse index list be returned (TRUE) or a dense logical matrix? See below.
+#' @param sparse logical; should a sparse index list be returned (`TRUE`) or a dense logical matrix? See below.
 #' @inheritDotParams s2::s2_options
-#' @param prepared logical; prepare geometry for x, before looping over y? See Details.
+#' @param prepared logical; prepare geometry for `x`, before looping over `y`? See Details.
 #' @details If \code{prepared} is \code{TRUE}, and \code{x} contains POINT geometries and \code{y} contains polygons, then the polygon geometries are prepared, rather than the points.
 #' @return If \code{sparse=FALSE}, \code{st_predicate} (with \code{predicate} e.g. "intersects") returns a dense logical matrix with element \code{i,j} \code{TRUE} when \code{predicate(x[i], y[j])} (e.g., when geometry of feature i and j intersect); if \code{sparse=TRUE}, an object of class \code{\link{sgbp}} with a sparse list representation of the same matrix, with list element \code{i} an integer vector with all indices j for which \code{predicate(x[i],y[j])} is \code{TRUE} (and hence a zero-length integer vector if none of them is \code{TRUE}). From the dense matrix, one can find out if one or more elements intersect by \code{apply(mat, 1, any)}, and from the sparse list by \code{lengths(lst) > 0}, see examples below.
 #' @details For most predicates, a spatial index is built on argument \code{x}; see \url{https://r-spatial.org/r/2017/06/22/spatial-index.html}.
@@ -218,8 +218,8 @@ st_overlaps		= function(x, y, sparse = TRUE, prepared = TRUE, ...)
 	st_geos_binop("overlaps", x, y, sparse = sparse, prepared = prepared, ...)
 
 #' @name geos_binary_pred
-#' @param retain_unique logical; if TRUE (and y is missing) return only indexes of points larger than the current index; this can be used to select unique geometries, see examples. This argument can be used for all geometry predictates; see als \link{distinct.sf} to find records where geometries AND attributes are distinct.
-#' @param remove_self logical; if TRUE (and y is missing) return only indexes of geometries different from the current index; this can be used to omit self-intersections; see examples. This argument can be used for all geometry predictates
+#' @param retain_unique logical; if `TRUE` (and `y` is missing) return only indexes of points larger than the current index; this can be used to select unique geometries, see examples. This argument can be used for all geometry predicates; see also \link{distinct.sf} to find records where geometries AND attributes are distinct.
+#' @param remove_self logical; if `TRUE` (and `y` is missing) return only indexes of geometries different from the current index; this can be used to omit self-intersections; see examples. This argument can be used for all geometry predicates
 #' @export
 st_equals		= function(x, y, sparse = TRUE, prepared = FALSE, ..., 
 							retain_unique = FALSE, remove_self = FALSE) {

R/geom-transformers.R

@@ -15,7 +15,7 @@
 #' @param mitreLimit numeric; limit of extension for a join if \code{joinStyle} 'MITRE' is used (default 1.0, minimum 0.0); see details
 #' @param singleSide logical; if \code{TRUE}, single-sided buffers are returned for linear geometries,
 #' in which case negative \code{dist} values give buffers on the right-hand side, positive on the left; see details
-#' @param ... passed on to \code{s2_buffer_cells}
+#' @param ... passed on to  [s2::s2_buffer_cells()]
 #' @return an object of the same class of \code{x}, with manipulated geometry.
 #' @export
 #' @details \code{st_buffer} computes a buffer around this geometry/each geometry. If any of \code{endCapStyle},
@@ -817,7 +817,7 @@ get_first_sfg = function(x) {
 #' @note To find whether pairs of simple feature geometries intersect, use
 #' the function \code{\link{st_intersects}} instead of \code{st_intersection}.
 #'
-#' When using GEOS and not using s2 polygons contain their boundary. When using s2 this is determined by the \code{model} defaults of \link[s2]{s2_options}, which can be overriden via the ... argument, e.g. \code{model = "closed"} to force DE-9IM compliant behaviour of polygons (and reproduce GEOS results).
+#' When using GEOS and not using s2 polygons contain their boundary. When using s2 this is determined by the \code{model} defaults of \link[s2]{s2_options}, which can be overridden via the ... argument, e.g. \code{model = "closed"} to force DE-9IM compliant behaviour of polygons (and reproduce GEOS results).
 #' @examples
 #' set.seed(131)
 #' library(sf)
@@ -899,7 +899,7 @@ st_difference.sfg = function(x, y, ...)
 #' numbers in the argument to \code{x}; geometries that are empty
 #' or contained fully inside geometries with higher priority are removed entirely.
 #' The \code{st_difference.sfc} method with a single argument returns an object with
-#' an \code{"idx"} attribute with the orginal index for returned geometries.
+#' an \code{"idx"} attribute with the original index for returned geometries.
 st_difference.sfc = function(x, y, ...) {
 	if (missing(y)) {
 		if (isTRUE(st_is_longlat(x)))
@@ -978,16 +978,21 @@ st_snap.sf = function(x, y, tolerance)
 
 #' @name geos_combine
 #' @export
-#' @param by_feature logical; if TRUE, union each feature if \code{y} is missing or else each pair of features; if FALSE return a single feature that is the geometric union of the set of features in \code{x} if \code{y} is missing, or else the unions of each of the elements of the Cartesian product of both sets
-#' @param is_coverage logical; if TRUE, use an optimized algorithm for features that form a polygonal coverage (have no overlaps)
+#' @param by_feature logical; if `TRUE`, union each feature if \code{y} is missing or else each pair of features; if `FALSE` return a single feature that is the geometric union of the set of features in \code{x} if \code{y} is missing, or else the unions of each of the elements of the Cartesian product of both sets
+#' @param is_coverage logical; if `TRUE`, use an optimized algorithm for features that form a polygonal coverage (have no overlaps)
 #' @param y object of class \code{sf}, \code{sfc} or \code{sfg} (optional)
 #' @param ... ignored
 #' @seealso \link{st_intersection}, \link{st_difference}, \link{st_sym_difference}
 #' @return If \code{y} is missing, \code{st_union(x)} returns a single geometry with resolved boundaries, else the geometries for all unioned pairs of `x[i]` and `y[j]`.
 #' @details
-#' If \code{st_union} is called with a single argument, \code{x}, (with \code{y} missing) and \code{by_feature} is \code{FALSE} all geometries are unioned together and an \code{sfg} or single-geometry \code{sfc} object is returned. If \code{by_feature} is \code{TRUE} each feature geometry is unioned individually. This can for instance be used to resolve internal boundaries after polygons were combined using \code{st_combine}. If \code{y} is provided, all elements of \code{x} and \code{y} are unioned, pairwise if \code{by_feature} is TRUE, or else as the Cartesian product of both sets. 
+#' If \code{st_union} is called with a single argument, \code{x}, (with \code{y} missing) and \code{by_feature} is \code{FALSE} all geometries are unioned together and an \code{sfg} or single-geometry \code{sfc} object is returned.
+#' If \code{by_feature} is \code{TRUE} each feature geometry is unioned individually.
+#' This can for instance be used to resolve internal boundaries after polygons were combined using \code{st_combine}. 
+#' If \code{y} is provided, all elements of \code{x} and \code{y} are unioned, pairwise if \code{by_feature} is TRUE, or else as the Cartesian product of both sets. 
 #'
-#' Unioning a set of overlapping polygons has the effect of merging the areas (i.e. the same effect as iteratively unioning all individual polygons together). Unioning a set of LineStrings has the effect of fully noding and dissolving the input linework. In this context "fully noded" means that there will be a node or endpoint in the output for every endpoint or line segment crossing in the input. "Dissolved" means that any duplicate (e.g. coincident) line segments or portions of line segments will be reduced to a single line segment in the output.	Unioning a set of Points has the effect of merging all identical points (producing a set with no duplicates).
+#' Unioning a set of overlapping polygons has the effect of merging the areas (i.e. the same effect as iteratively unioning all individual polygons together).
+#' Unioning a set of LineStrings has the effect of fully noding and dissolving the input linework. In this context "fully noded" means that there will be a node or endpoint in the output for every endpoint or line segment crossing in the input.
+#' "Dissolved" means that any duplicate (e.g. coincident) line segments or portions of line segments will be reduced to a single line segment in the output.	Unioning a set of Points has the effect of merging all identical points (producing a set with no duplicates).
 #' @examples
 #' plot(st_union(nc))
 st_union = function(x, y, ..., by_feature = FALSE, is_coverage = FALSE) UseMethod("st_union")

R/plot.R

@@ -29,7 +29,7 @@ kw_dflt = function(x, key.pos) {
 #' @param pal palette function, similar to \link{rainbow}, or palette values; if omitted, \code{sf.colors} is used
 #' @param nbreaks number of colors breaks (ignored for \code{factor} or \code{character} variables)
 #' @param breaks either a numeric vector with the actual breaks, or a name of a method accepted by the \code{style} argument of \link[classInt]{classIntervals}
-#' @param max.plot integer; lower boundary to maximum number of attributes to plot; the default value (9) can be overriden by setting the global option \code{sf_max.plot}, e.g. \code{options(sf_max.plot=2)}
+#' @param max.plot integer; lower boundary to maximum number of attributes to plot; the default value (9) can be overridden by setting the global option \code{sf_max.plot}, e.g. \code{options(sf_max.plot=2)}
 #' @param key.pos numeric; side to plot a color key: 1 bottom, 2 left, 3 top, 4 right; set to \code{NULL} to omit key completely, 0 to only not plot the key, or -1 to select automatically. If multiple columns are plotted in a single function call by default no key is plotted and every submap is stretched individually; if a key is requested (and \code{col} is missing) all maps are colored according to a single key. Auto select depends on plot size, map aspect, and, if set, parameter \code{asp}. If it has lenght 2, the second value, ranging from 0 to 1, determines where the key is placed in the available space (default: 0.5, center).
 #' @param key.width amount of space reserved for the key (incl. labels), thickness/width of the scale bar
 #' @param key.length amount of space reserved for the key along its axis, length of the scale bar

R/proj.R

@@ -83,7 +83,7 @@ sf_project = function(from = character(0), to = character(0), pts, keep = FALSE,
 #' 
 #' Query or manage PROJ search path and network settings
 #' @param paths the search path to be set; omit if paths need to be queried
-#' @param with_proj logical; if `NA` set for both GDAL and PROJ, otherwise set either for PROJ (TRUE) or GDAL (FALSE)
+#' @param with_proj logical; if `NA` set for both GDAL and PROJ, otherwise set either for PROJ (`TRUE`) or GDAL (`FALSE`)
 #' @return `sf_proj_search_paths()` returns the search path (possibly after setting it)
 #' @name proj_tools
 #' @export
@@ -103,7 +103,7 @@ sf_proj_search_paths = function(paths = character(0), with_proj = NA) {
 	}
 }
 
-#' @param enable logical; set this to enable (TRUE) or disable (FALSE) the proj network search facility
+#' @param enable logical; set this to enable (`TRUE`) or disable (`FALSE`) the proj network search facility
 #' @param url character; use this to specify and override the default proj network CDN 
 #' @return `sf_proj_network` when called without arguments returns a logical indicating whether
 #' network search of datum grids is enabled, when called with arguments it returns a character
@@ -117,8 +117,7 @@ sf_proj_network = function(enable = FALSE, url = character(0)) {
 		CPL_enable_network(url, enable)
 }
 
-#' @param source_crs object of class `crs` or character
-#' @param target_crs object of class `crs` or character
+#' @param source_crs,target_crs object of class `crs` or character
 #' @param authority character; constrain output pipelines to those of authority
 #' @param AOI length four numeric; desired area of interest for the resulting 
 #' coordinate transformations (west, south, east, north, in degrees).
@@ -133,15 +132,15 @@ sf_proj_network = function(enable = FALSE, url = character(0)) {
 #' registered in the grid_alternatives table of its database) were available. Used typically when 
 #' networking is enabled.)
 #' @param desired_accuracy numeric; only return pipelines with at least this accuracy
-#' @param strict_containment logical; default FALSE; permit partial matching of the area
-#' of interest; if TRUE strictly contain the area of interest.
+#' @param strict_containment logical; default `FALSE`; permit partial matching of the area
+#' of interest; if `TRUE` strictly contain the area of interest.
 #' The area of interest is either as given in AOI, or as implied by the
 #' source/target coordinate reference systems 
-#' @param axis_order_authority_compliant logical; if FALSE always 
+#' @param axis_order_authority_compliant logical; if `FALSE` always 
 #' choose ‘x’ or longitude for the first 
 #' axis; if TRUE, follow the axis orders given by the coordinate reference systems when 
-#' constructing the for the first axis; if FALSE, follow the axis orders given by
-#' @return `sf_proj_pipelines` returns a table with candidate coordinate transformation
+#' constructing the for the first axis; if `FALSE`, follow the axis orders given by
+#' @return `sf_proj_pipelines()` returns a table with candidate coordinate transformation
 #' pipelines along with their accuracy; `NA` accuracy indicates ballpark accuracy.
 #' @name proj_tools
 #' @export