Separate binary operations documentation.

Author: olivroy

DESCRIPTION

@@ -133,6 +133,7 @@ Collate:
     'wkb.R'
     'wkt.R'
     'plot.R'
+    'geos_binary_pred.R'
     'geom-measures.R'
     'geom-predicates.R'
     'geom-transformers.R'

R/geom-predicates.R

@@ -107,10 +107,9 @@ st_relate	= function(x, y, pattern = NA_character_, sparse = !is.na(pattern)) {
 		st_geos_binop("relate", x, y, sparse = FALSE)
 }
 
-#' Geometric binary predicates on pairs of simple feature geometry sets
+#' Identify if `x` and `y` share any space
 #'
-#' Geometric binary predicates on pairs of simple feature geometry sets
-#' @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.
@@ -121,12 +120,13 @@ st_relate	= function(x, y, pattern = NA_character_, sparse = !is.na(pattern)) {
 #' @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}.
 #' Specifically, \code{st_intersects}, \code{st_disjoint}, \code{st_touches} \code{st_crosses}, \code{st_within}, \code{st_contains}, \code{st_contains_properly}, \code{st_overlaps}, \code{st_equals}, \code{st_covers} and \code{st_covered_by} all build spatial indexes for more efficient geometry calculations. \code{st_relate}, \code{st_equals_exact}, and do not; \code{st_is_within_distance} uses a spatial index for geographic coordinates when \code{sf_use_s2()} is true.
 #'
-#' If \code{y} is missing, `st_predicate(x, x)` is effectively called, and a square matrix is returned with diagonal elements `st_predicate(x[i], x[i])`.
+#' If \code{y} is missing, `st_<predicate>(x, x)` is effectively called, and a square matrix is returned with diagonal elements `st_predicate(x[i], x[i])`.
 #'
 #' Sparse geometry binary predicate (\code{\link{sgbp}}) lists have the following attributes: \code{region.id} with the \code{row.names} of \code{x} (if any, else \code{1:n}), \code{ncol} with the number of features in \code{y}, and \code{predicate} with the name of the predicate used.
 #'
 #' @note For intersection on pairs of simple feature geometries, use
 #' the function \code{\link{st_intersection}} instead of \code{st_intersects}.
+#' @family geometric binary predicates for two spatial objects
 #'
 #' @examples
 #' pts = st_sfc(st_point(c(.5,.5)), st_point(c(1.5, 1.5)), st_point(c(2.5, 2.5)))
@@ -193,18 +193,22 @@ st_crosses		= function(x, y, sparse = TRUE, prepared = TRUE, ...)
 st_within	= function(x, y, sparse = TRUE, prepared = TRUE, ...)
 	st_geos_binop("within", x, y, sparse = sparse, prepared = prepared, ...)
 
-#' @name geos_binary_pred
+#' Identify if y is within x
+#' 
+#' * `st_contains()` is true if 
+#' * `st_contains_properly(x, y)` is true if `x` intersects `y`'s interior, but not its edges or exterior; `x` contains `x`, but `x` does not properly contain `x`.
 #' @param model character; polygon/polyline model; one of
 #' "open", "semi-open" or "closed"; see Details.
 #' @details for \code{model}, see https://github.com/r-spatial/s2/issues/32
+#' @inheritParams st_intersects
 #' @export
+#' @family geometric binary predicates for two spatial objects
 st_contains	= function(x, y, sparse = TRUE, prepared = TRUE, ..., model = "open")
 	st_geos_binop("contains", x, y, sparse = sparse, prepared = prepared, ..., model = model)
 
-#' @name geos_binary_pred
+#' @rdname st_contains
 #' @export
-#' @details `st_contains_properly(A,B)` is true if A intersects B's interior, but not its edges or exterior; A contains A, but A does not properly contain A.
-#'
+#' @details 
 #' See also \link{st_relate} and \url{https://en.wikipedia.org/wiki/DE-9IM} for a more detailed description of the underlying algorithms.
 st_contains_properly = function(x, y, sparse = TRUE, prepared = TRUE, ...) {
 	if (! prepared)
@@ -217,10 +221,20 @@ st_contains_properly = function(x, y, sparse = TRUE, prepared = TRUE, ...) {
 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 predicates; see also \link{distinct.sf} to find records where geometries AND attributes are distinct.
+
+#' Verify if geographies are equal
+#' 
+#' * `st_equals()` validate if x and y are equal.
+#' * `st_equals_exact()` returns true for two geometries of the same type and their vertices corresponding by index are equal up to a specified tolerance.
+#' 
+#' @inheritParams st_intersects
+#' @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
+#' @family geometric binary predicates for two spatial objects
 st_equals		= function(x, y, sparse = TRUE, prepared = FALSE, ..., 
 							retain_unique = FALSE, remove_self = FALSE) {
 	if (prepared)
@@ -241,10 +255,9 @@ st_covered_by = function(x, y = x, sparse = TRUE, prepared = TRUE, ..., model =
 	st_geos_binop("covered_by", x, y, sparse = sparse, prepared = prepared, ...)
 
 
-#' @name geos_binary_pred
+#' @rdname st_equals
 #' @export
 #' @param par numeric; parameter used for "equals_exact" (margin);
-#' @details \code{st_equals_exact} returns true for two geometries of the same type and their vertices corresponding by index are equal up to a specified tolerance.
 st_equals_exact = function(x, y, par, sparse = TRUE, prepared = FALSE, ...) {
 	if (prepared)
 		stop("prepared geometries not supported for st_equals_exact")

R/geos_binary_pred.R

@@ -0,0 +1,31 @@
+#' Geometric binary predicates on pairs of simple feature geometry sets
+#'
+#' @description
+#'
+#' For most predicates, a spatial index is built on argument `x`;
+#' see \url{https://r-spatial.org/r/2017/06/22/spatial-index.html}.
+#'
+#' If `prepared = TRUE`, `x` contains POINT geometries, and `y` contains polygons,
+#' then the polygon geometries are prepared, rather than the points.
+#' @name geos_binary_pred
+#' @family geometric binary predicates for two spatial objects
+#' @examples
+#' pts = st_sfc(st_point(c(.5,.5)), st_point(c(1.5, 1.5)), st_point(c(2.5, 2.5)))
+#' pol = st_polygon(list(rbind(c(0,0), c(2,0), c(2,2), c(0,2), c(0,0))))
+#' (lst = st_intersects(pts, pol))
+#' (mat = st_intersects(pts, pol, sparse = FALSE))
+#' # which points fall inside a polygon?
+#' apply(mat, 1, any)
+#' lengths(lst) > 0
+#' # which points fall inside the first polygon?
+#' st_intersects(pol, pts)[[1]]
+#' # remove duplicate geometries:
+#' p1 = st_point(0:1)
+#' p2 = st_point(2:1)
+#' p = st_sf(a = letters[1:8], geom = st_sfc(p1, p1, p2, p1, p1, p2, p2, p1))
+#' st_equals(p)
+#' st_equals(p, remove_self = TRUE)
+#' (u = st_equals(p, retain_unique = TRUE))
+#' # retain the records with unique geometries:
+#' p[-unlist(u),]
+NULL

R/sgbp.R

@@ -21,16 +21,22 @@ sgbp = function(x, predicate, region.id, ncol, sparse = TRUE, remove_self = FALS
 		ret
 }
 
-#' Methods for dealing with sparse geometry binary predicate lists
+#' Sparse Geometry Binary Predicate Lists.
 #' 
+#' @description
 #' Methods for dealing with sparse geometry binary predicate lists
+#'  \code{sgbp} are sparse matrices, stored as a list with integer vectors holding
+#'  the ordered \code{TRUE} indices of each row. This means that for a dense,
+#'  \eqn{m \times n}{m x n} matrix \code{Q} and a list \code{L}, 
+#'  if \code{Q[i,j]} is \code{TRUE} then \eqn{j} is an element of \code{L[[i]]}.
+#'  
+#'  Reversed: when \eqn{k} is the value of \code{L[[i]][j]}, then \code{Q[i,k]} is \code{TRUE}.
 #' @name sgbp
 #' @export
 #' @param x object of class \code{sgbp}
 #' @param ... ignored
 #' @param n integer; maximum number of items to print
 #' @param max_nb integer; maximum number of neighbours to print for each item
-#' @details \code{sgbp} are sparse matrices, stored as a list with integer vectors holding the ordered \code{TRUE} indices of each row. This means that for a dense, \eqn{m \times n}{m x n} matrix \code{Q} and a list \code{L}, if \code{Q[i,j]} is \code{TRUE} then \eqn{j} is an element of \code{L[[i]]}. Reversed: when \eqn{k} is the value of \code{L[[i]][j]}, then \code{Q[i,k]} is \code{TRUE}.
 print.sgbp = function(x, ..., n = 10, max_nb = 10) {
 	n = min(length(x), n)
 	hd = paste0("Sparse geometry binary predicate list of length ", length(x), ", ",