Summarise Niche Boundary Exceedance through time

Usage

climniche_departure(
  x,
  scope = c("current", "all"),
  persistence = 1L,
  boundary_exceedance_tolerance = NULL
)

Arguments

x: A climniche_series object.
scope: "current" for positive reference weights or "all" for every evaluated cell.
persistence: Minimum number of consecutive projections required to identify persistent Niche Boundary Exceedance. This setting affects persistence summaries, not the continuous exceedance values.
boundary_exceedance_tolerance: Optional non-negative boundary tolerance. The fitted value is used by default.

Value

A data frame with one row per cell, model and scenario. Primary temporal fields give the first sampled Niche Boundary Exceedance (first_boundary_exceedance) and the fraction of supplied projections beyond the boundary (boundary_exceedance_projection_fraction). Persistent onset and interval-weighted summaries are also returned.

Details

At projection time $t_k$, let $e_{ik}$ be Niche Boundary Exceedance for cell $i$, divided by the fitted niche boundary distance after the boundary tolerance is applied. Cumulative relative exceedance is $$J_i = \sum_{k=1}^{K-1} (t_{k+1}-t_k) \frac{e_{ik}+e_{i,k+1}}{2}.$$ Mean relative exceedance is $J_i/(t_K-t_1)$. The Time Weighted Niche Boundary Exceedance Fraction applies the same trapezoidal calculation to the binary exceedance indicator. Numeric, Date and POSIXct times may be irregularly spaced. Cumulative values use the reported time unit; mean values are dimensionless.

Persistent Niche Boundary Exceedance is a run of at least persistence sampled projections above the selected boundary tolerance. Its onset is the first sampled projection in that run, not an estimated crossing time between projections.

Examples

sim <- simulate_climniche(n = 160, p = 6, seed = 2)
future <- lapply(c(0.2, 0.5, 0.8, 1), function(fraction) {
  sim$current + fraction * (sim$future_away - sim$current)
})
series <- fit_climniche_series(
  sim$current,
  future,
  time = c(2030, 2050, 2070, 2090),
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
head(climniche_departure(series))