Fit climate exposure through time relative to a fixed climatic niche

Fits one current climatic niche reference and evaluates an ordered set of future projections. Projections may represent time periods, climate models, scenarios, or their combinations.

Usage

fit_climniche_series(
  current,
  future,
  time,
  model = NULL,
  scenario = NULL,
  occupied = NULL,
  occupied_threshold = NULL,
  domain = NULL,
  domain_threshold = 0,
  cnfa = NULL,
  center = NULL,
  sensitivity = NULL,
  A = NULL,
  metric = c("diag", "factor"),
  boundary = 0.95,
  scale = TRUE,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  global_mean = NULL,
  global_sd = NULL,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

current: Current climatic conditions supplied as a numeric matrix, data frame, RasterLayer, RasterStack, RasterBrick or SpatRaster.
future: A list of future objects matching current. A three-dimensional numeric array may also be supplied, with cells, variables and projections in its three dimensions.
time: Numeric, Date or POSIXct projection times, one per future object.
model: Optional climate model identifiers, one per future object or a single value recycled across projections.
scenario: Optional scenario identifiers, one per future object or a single value recycled across projections.
occupied: Current reference rows, weights or a matching one-layer raster.
occupied_threshold: Optional cutoff for continuous reference weights.
domain: Optional one-layer raster limiting a spatial analysis.
domain_threshold: Threshold used when domain is supplied.
cnfa: Optional compatible CENFA object.
center: Optional current niche centre in the fitted climatic space.
sensitivity: Optional non-negative climatic metric weights.
A: Optional climatic weighting matrix.
metric: Method used to build A when it is not supplied.
boundary: Weighted quantile defining the empirical radial boundary.
scale: If TRUE, standardise retained variables using current climate.
preprocess: If TRUE, screen near-zero variance and highly correlated current-climate variables.
preprocess_correlation: Maximum absolute correlation retained during preprocessing.
preprocess_min_sd: Minimum current-climate standard deviation as a fraction of the largest finite current standard deviation.
global_mean, global_sd: Optional centring and scaling values.
tolerance: Optional tolerance around zero for Niche Distance Shift.
tolerance_quantile: Quantile used when tolerance = NULL.
boundary_exceedance_tolerance: Tolerance used by the empirical boundary descriptor and dynamic summaries.

Value

A climniche_series object containing one compatible climniche_fit per projection.

Details

The current niche centre, climatic weighting matrix, standardisation and empirical radial boundary are held fixed. For spatial inputs, this reference is estimated from finite current cells within domain, independently of missing values in future projections. Future comparisons use the common set of finite cells across all projections. All projections also use one Niche Distance Shift tolerance. When tolerance = NULL, it is the requested quantile of pooled absolute Niche Distance Shift values across the fitted series.

Examples

sim <- simulate_climniche(n = 180, p = 6, seed = 12)
future <- lapply(c(0.25, 0.50, 0.75, 1), function(fraction) {
  sim$current + fraction * (sim$future_away - sim$current)
})
series <- fit_climniche_series(
  current = sim$current,
  future = future,
  time = c(2030, 2050, 2070, 2090),
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
climniche_range_summary(series)