Summarise Niche Boundary Exceedance across a study domain

Usage

climniche_range_summary(
  x,
  scope = c("current", "all"),
  aggregation_weight = NULL,
  area_weight = FALSE,
  boundary_exceedance_tolerance = NULL
)

Arguments

x: A climniche_fit or climniche_series object.
scope: "current" restricts the summary to positive reference weights. "all" uses every evaluated cell.
aggregation_weight: Optional non-negative cell weights used only for the range summary. Numeric vectors and, for spatial fits, matching RasterLayer or SpatRaster objects are accepted. These weights multiply the reference weights when scope = "current".
area_weight: If TRUE, multiply the summary weights by raster cell area. This option requires a spatial fit.
boundary_exceedance_tolerance: Optional non-negative tolerance used to identify positive Niche Boundary Exceedance. By default, the fitted descriptor tolerance is used.

Value

A data frame containing Weighted Niche Boundary Exceedance Fraction (exposed_fraction), Conditional Relative Niche Boundary Exceedance (conditional_relative_exceedance) and Range Mean Relative Niche Boundary Exceedance (range_wide_relative_exceedance). For a climniche_series, one row is returned for each time, model and scenario combination.

Details

Let a_i be the range summary weight, let $\tau$ be the boundary tolerance, and define $$\widetilde{E}_i = E_i I(E_i > \tau), \qquad e_i = \widetilde{E}_i / B_q.$$ The Weighted Niche Boundary Exceedance Fraction is $$F = \frac{\sum_i a_i I(e_i > 0)}{\sum_i a_i}.$$ Conditional Relative Niche Boundary Exceedance is $$S = \frac{\sum_i a_i e_i I(e_i > 0)} {\sum_i a_i I(e_i > 0)}.$$ Range Mean Relative Niche Boundary Exceedance is $$X = \frac{\sum_i a_i e_i I(e_i > 0)}{\sum_i a_i} = F S.$$ Here, $I(\cdot)$ is the indicator function. For scope = "current", a_i contains the reference weight. Optional aggregation and cell area weights multiply it. For scope = "all", the reference weight is omitted. These quantities summarise Niche Boundary Exceedance and do not add further cell-level exposure metrics.

Examples

sim <- simulate_climniche(n = 250, p = 6, seed = 8)
fit <- fit_climniche(
  sim$current,
  sim$future_away,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_range_summary(fit)