Spatial Species Accumulation Curves

Compute species accumulation curves using various spatial sampling methods with C++ backend for performance.

Usage

spacc(
  x,
  coords,
  n_seeds = 50L,
  method = c("knn", "kncn", "random", "radius", "gaussian", "cone", "collector"),
  distance = c("euclidean", "haversine"),
  backend = c("auto", "exact", "kdtree"),
  support = NULL,
  include_halo = TRUE,
  sigma = NULL,
  cone_width = pi/4,
  parallel = TRUE,
  n_cores = NULL,
  progress = TRUE,
  groups = NULL,
  time = NULL,
  w_space = 1,
  w_time = 1,
  seed = NULL
)

Arguments

x

A site-by-species matrix (rows = sites, cols = species) with presence/absence (0/1) or abundance data. Can also be a data.frame.

coords

Site coordinates. Can be:

A data.frame with columns x and y
An sf object with point geometries (CRS is preserved)
A spacc_dist object from distances()

n_seeds

Integer. Number of random starting points for uncertainty quantification. Default 50.

method

Character. Accumulation method:

"knn": k-Nearest Neighbor (always visit closest unvisited)
"kncn": k-Nearest Centroid Neighbor (visit closest to centroid)
"random": Random order (null model)
"radius": Expand by distance from seed
"gaussian": Probabilistic selection weighted by distance
"cone": Directional expansion within angular constraint
"collector": Sites in data order (no randomization, single curve)

distance

Character. Distance method: "euclidean" or "haversine".

backend

Character. Nearest-neighbor backend for knn and kncn:

"auto" (default): Uses exact (brute-force) for <=500 sites, spatial tree for >500 sites.
"exact": Always use brute-force with precomputed distance matrix.
"kdtree": Always use spatial tree. Uses k-d tree (nanoflann) for Euclidean distances and ball tree for haversine distances. Faster for large datasets, no distance matrix needed.

support

Optional. Spatial support for core/halo classification via areaOfEffect::aoe(). Can be:

"auto": Auto-detect countries and run per-country accumulation, returning a grouped spacc object with one curve per country
Country name or ISO code: "France", "FR", "FRA"
Vector of countries: c("France", "Germany")
An sf polygon object
An aoe_result object (pre-computed) When provided, seeds are sampled only from "core" sites (inside support), while accumulation can expand into "halo" sites (buffer zone).

include_halo

Logical. When support is provided, should halo sites be included in accumulation? Default TRUE (ecological boundary). Set to FALSE for political/hard boundary.

sigma

Numeric. Bandwidth for Gaussian method. Default auto-calculated.

cone_width

Numeric. Half-width in radians for cone method. Default pi/4.

parallel

Logical. Use parallel processing? Default TRUE.

n_cores

Integer. Number of cores. Default NULL uses detectCores() - 1.

progress

Logical. Show progress bar? Default TRUE.

groups

Optional. A factor, character, or integer vector of length ncol(x) assigning each species (column) to a group. When provided, separate accumulation curves are computed for each group using the same spatial site ordering, and a grouped spacc object is returned. Useful for comparing native vs alien species, families, or any categorical split. Default NULL (no grouping).

time

Optional. Numeric vector of length nrow(x) giving a temporal coordinate for each site. When provided, a combined spatiotemporal distance matrix is computed as w_space * d_spatial + w_time * d_temporal and used for accumulation. Forces exact (brute-force) backend since spatial trees cannot handle composite distances. Only supported for methods that use a distance matrix: "knn", "radius", "gaussian".

w_space

Numeric. Weight for spatial distance when time is provided. Default 1.

w_time

Numeric. Weight for temporal distance when time is provided. Default 1.

seed

Integer. Random seed for reproducibility. Default NULL.

Value

When groups = NULL, an object of class spacc containing:

curves: Matrix of cumulative species counts (n_seeds x n_sites)
coords: Original coordinates
n_seeds: Number of seeds used
method: Method used
n_species: Total species in dataset

References

Arrhenius, O. (1921). Species and area. Journal of Ecology, 9, 95-99.

Scheiner, S.M. (2003). Six types of species-area curves. Global Ecology and Biogeography, 12, 441-447.

Chiarucci, A., Bacaro, G., Scheiner, S.M. (2011). Old and new challenges in using species diversity for assessing biodiversity. Philosophical Transactions of the Royal Society B, 366, 2426-2437.

Examples

# \donttest{
coords <- data.frame(x = runif(50), y = runif(50))
species <- matrix(rbinom(50 * 30, 1, 0.3), nrow = 50)

# Basic usage
sac <- spacc(species, coords)
plot(sac)

# Different methods
sac_knn <- spacc(species, coords, method = "knn")
sac_rand <- spacc(species, coords, method = "random")
comp <- compare(sac_knn, sac_rand)
# }