Fit niche relative climate exposure from matrices

Usage

fit_climniche(
  current,
  future,
  occupied = NULL,
  occupied_threshold = NULL,
  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: Numeric matrix or data frame of current climate values. Rows are cells, sites, or samples. Columns are climate variables.
future: Numeric matrix or data frame of future climate values with the same rows and columns as current.
occupied: Reference information used to estimate the current realised niche. Use NULL to give every row weight 1, a logical vector to mark reference rows, a numeric vector of length nrow(current) for continuous reference weights, or positive integer row indices for 0/1 reference cells.
occupied_threshold: Optional cutoff for numeric reference weights. Values at or below the cutoff are set to 0. Values above it keep their original continuous value.
cnfa: Optional CENFA cnfa object. Its marginality and sensitivity slots are used when center, sensitivity, or A are not supplied.
center: Optional realised niche centre in the climate space used by the fit. If omitted, the centre is the weighted mean of current reference rows.
sensitivity: Optional non-negative variable weights. Used to build a diagonal metric when A is not supplied.
A: Optional square metric matrix. When supplied, it overrides sensitivity, cnfa, and metric for distance calculations.
metric: Method used to build A when A is missing. "diag" uses variable-level sensitivity weights. "factor" uses the factor metric available from a compatible CENFA object.
boundary: Quantile used to define the empirical boundary of the current realised niche. Must be between 0 and 1.
scale: Logical. If TRUE, current and future values are centred and scaled with the current-layer mean and standard deviation before distances are calculated.
preprocess: Logical. If TRUE, remove near-zero variance variables and highly correlated variables before metric fitting.
preprocess_correlation: Maximum absolute pairwise correlation retained among current climate variables during preprocessing.
preprocess_min_sd: Minimum current-climate standard deviation retained during preprocessing.
global_mean: Optional means used for centering. If omitted, column means of current are used.
global_sd: Optional standard deviations used for scaling. If omitted, column standard deviations of current are used.
tolerance: Optional tolerance around zero for Niche Distance Shift. If NULL, the fitted object uses tolerance_quantile.
tolerance_quantile: Quantile of absolute Niche Distance Shift used to set tolerance when tolerance = NULL.
boundary_exceedance_tolerance: Tolerance used to label whether Niche Boundary Exceedance is greater than zero for descriptor summaries.

Value

An object of class climniche_fit.

Details

Let current and future climatic conditions at cell $i$ be $c_i$ and $f_i$. Let $\mu$ be the centre of the current realised climatic niche, and let $d_A(x, y)$ be the sensitivity weighted distance under weighting matrix $A$. The four metrics are:

$$D_i = d_A(f_i, c_i)$$ $$R_i = d_A(f_i, \mu) - d_A(c_i, \mu)$$ $$C_i = \sqrt{\max(0, D_i^2 - R_i^2)}$$ $$E_i = \max(0, d_A(f_i, \mu) - B_q)$$

where $B_q$ is the $q$-th weighted quantile of current reference-cell distances from the realised niche centre.

Metric fields

The primary fitted fields are climate_change_amount, niche_distance_change, climate_reconfiguration, and niche_boundary_exceedance. The legacy names composition_change and outside_niche_exceedance are retained as aliases for old code.

User-settable thresholds

boundary controls the empirical niche boundary. tolerance controls the zero band for Niche Distance Shift. boundary_exceedance_tolerance controls the boundary descriptor. The fitted values are stored in descriptor_settings.

Scaling and preprocessing

scale centres and scales retained variables. preprocess screens the variable set before fitting. The two steps are independent and are enabled by default.

Choosing a fit function

Use fit_climniche() when current and future climate values have already been extracted to matrices or data frames. Use fit_climniche_raster() for objects from the raster package. Use fit_climniche_terra() for terra::SpatRaster objects. The three functions calculate the same metrics; the raster and terra methods add spatial masking and return map layers in x$rasters.