Skip to contents

Constructs geographic range polygons from species occurrence records using spatial clustering followed by buffered concave hulls. Occurrence records are first grouped into spatial clusters based on pairwise geographic distances. A concave hull is then generated for each cluster and spatially restricted using a user-defined `sf` object.

Usage

lets.range(
  occs,
  n_max = 1000,
  eps_m = 1e+06,
  min_pts = 1,
  ratio = 0.5,
  buf = 50000,
  crop_shp,
  round_par = 3,
  plot_map = TRUE,
  intersection = TRUE
)

Arguments

occs

A data frame containing species occurrence records. It must include the columns `scientificName`, `decimalLongitude`, and `decimalLatitude`.

n_max

Integer. Maximum number of occurrence records retained for each species. Species with more records are randomly subsampled. Default is `1000`.

eps_m

Numeric. Maximum distance, in meters, used by DBSCAN to define spatial clusters. Default is `1000000` meters (1000 km).

min_pts

Integer. Minimum number of points required to form a DBSCAN cluster. Default is `1`.

ratio

Numeric between 0 and 1 controlling the concavity of the hull. A value of `1` produces a convex hull, whereas values approaching `0` produce increasingly concave hulls. Default is `0.5`.

buf

Numeric. Buffer distance, in meters, applied before and after construction of the concave hull. Default is `50000`.

crop_shp

An `sf` object defining the spatial feature used to restrict the estimated range polygons. Its effect depends on `intersection`. When `intersection = TRUE`, only the portion of the estimated range overlapping `crop_shp` is retained. When `intersection = FALSE`, the portion overlapping `crop_shp` is removed.

round_par

Integer. Number of decimal places used to round geographic coordinates before removing duplicated records. Default is `3`.

plot_map

Logical. If `TRUE`, plots `crop_shp`, the resulting range polygons, and the occurrence records for each species. Default is `TRUE`.

intersection

Logical. Determines how `crop_shp` is applied to the estimated range polygons. If `TRUE`, [sf::st_intersection()] is used and only areas overlapping `crop_shp` are retained. If `FALSE`, [sf::st_difference()] is used and areas overlapping `crop_shp` are removed. Default is `TRUE`.

Value

An `sf` object containing the estimated geographic range polygons for all species in EPSG:4326, with `binomial` and integer `cluster` columns. Each surviving cluster occupies one MULTIPOLYGON row. When no polygons survive, an empty `sf` with the same columns and CRS is returned.

Details

For each species, coordinates are rounded according to `round_par` and duplicated records are removed. If the number of unique occurrence records exceeds `n_max`, a random subset of records is retained.

Pairwise geographic distances among occurrence records are calculated using [lets.distmat()]. Records are then grouped into spatial clusters using [dbscan::dbscan()]. A buffered concave hull is constructed independently for each cluster using [sf::st_concave_hull()]. DBSCAN noise (label 0) is omitted. Buffers before and after the hull are computed in a local azimuthal equidistant projection centered using the circular mean longitude. This is a regional range estimator; metric distortion increases for clusters extending far from their center. With the default `min_pts = 1` and positive `buf`, even one unique occurrence produces a buffered polygon (approximately `2 * buf` radius before masking). Two-point and collinear clusters are also supported. Repeated records at one location count as one occurrence after rounding. Higher `min_pts` still applies: isolated points classified as noise are omitted, and a mask can remove the entire buffered range. With `buf = 0`, clusters with no polygonal area are omitted.

Ranges and masks are split at the antimeridian before Cartesian overlays on their longitude/latitude coordinates. These overlays follow the mapped edges of the mask, rather than interpreting them as S2 great-circle arcs. No distance or buffer is calculated in degrees, and the caller's S2 setting is unchanged. Missing species and invalid coordinates are dropped with a warning; `crop_shp` must have a known CRS.

The resulting polygons are subsequently combined with `crop_shp`. When `intersection = TRUE`, only the portion overlapping `crop_shp` is retained. This can be used, for example, to restrict terrestrial species ranges to land areas. When `intersection = FALSE`, the portion overlapping `crop_shp` is removed. This can be used to remove land polygons from the ranges of marine species.

The choice of `eps_m`, `ratio`, and `buf` can substantially influence the resulting range geometry and should reflect the spatial scale, sampling properties, and biological characteristics of the study system.

Note that the function requires sf >= 1.0-11 and GEOS >= 3.11.0 for concave hull construction.

See also

[lets.distmat()], [dbscan::dbscan()], [sf::st_concave_hull()], [sf::st_intersection()], [sf::st_difference()]

Examples

if (FALSE) { # \dontrun{
library(sf)
library(rnaturalearth)

# Example occurrence records for a marine species
occs <- data.frame(
  scientificName = "Example_brasiliensis",
  decimalLongitude = c(-38.2, -37.8, -36.8, -35.5, -34.8) + 1,
  decimalLatitude = c(-23, -22, -10.5, -8.5, -7)
)

# Land polygons used to remove terrestrial areas
land <- ne_countries(
  scale = "medium",
  returnclass = "sf"
)

# Estimate a marine range by removing land from the range polygons
ranges <- lets.range(
  occs,
  crop_shp = land,
  intersection = FALSE,
  buf = 100000,
  eps_m = 1000000, 
  ratio = 1
)
} # }