Fit climate exposure relative to a climatic niche from matrices

Compares the amount of climatic change at each location with movement towards or away from the current reference centre and distance beyond its estimated climatic range.

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,
  global_mean = NULL,
  global_sd = NULL,
  preprocess = TRUE,
  preprocess_correlation = 0.95,
  preprocess_min_sd = 1e-08,
  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 variables as current. Complete row and variable names are matched before fitting.
occupied: Location weights used to estimate the empirical climatic niche reference. 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. Complete names are matched to the row names of current. With NULL, the reference is the climatic distribution of all current analysis rows.
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 compatible CENFA object. Its mf and sf components can supply the niche centre and diagonal metric weights; metric = "factor" requires co and eig. The object and climatic inputs must use the same variables and standardisation.
center: Optional current niche centre on the scale used for distance calculations. With scale = TRUE, supply a centre in the standardised climatic space. If omitted, the centre is the weighted mean of current reference rows.
sensitivity: Optional non-negative climatic variable weights defining relative contributions to distance. Retained variables receive equal weights by default. These are separate from the location weights in occupied.
A: Optional square metric matrix defined for the fitted climatic space. 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 climatic metric weights. "factor" constructs a weighted metric from the co and eig components of a compatible CENFA object.
boundary: Weighted quantile used to define the empirical radial boundary of the empirical climatic niche reference. 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.
global_mean: Optional means used for centering when scale = TRUE. If omitted, column means of current are used.
global_sd: Optional standard deviations used for scaling. If scale = TRUE and this argument is omitted, column standard deviations of current are used.
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 as a fraction of the largest finite current standard deviation. Variables at or below this value are removed during preprocessing.
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 Niche Boundary Exceedance in descriptor summaries.

Value

A climniche_fit object containing the reported quantities, reference weights, fitted niche centre, metric matrix and effective settings.

Details

The empirical climatic niche reference summarises the current distribution of climatic conditions by a weighted centre and radial boundary. It is a proxy for the species' current climatic niche. With occupied = NULL, it instead describes the study region.

Let $c_i$ and $f_i$ be current and future climatic conditions at location $i$ in the fitted climatic space, $\mu$ the reference centre, and $d_A(x, y)$ the distance under climatic weighting matrix $A$. The four quantities are:

Climatic Displacement, the amount of local climatic change: $$D_i = d_A(f_i, c_i)$$

Niche Distance Shift, the signed change in distance from the centre: $$R_i = d_A(f_i, \mu) - d_A(c_i, \mu)$$

Climatic Reconfiguration, the displacement not expressed as a distance shift: $$C_i = \sqrt{\max(0, D_i^2 - R_i^2)}$$

Niche Boundary Exceedance, the distance beyond the fitted boundary: $$E_i = \max(0, d_A(f_i, \mu) - B_q)$$

Here $B_q$ is the $q$-th location-weighted quantile of current distances from the centre. Negative Niche Distance Shift indicates movement towards the centre; positive values indicate movement away. When current and future distances are equal, Niche Distance Shift is zero and Climatic Reconfiguration equals Climatic Displacement. Niche Boundary Exceedance is zero at or within the boundary and positive beyond it.

Reported fields

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 radial 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.

Boundary scale

boundary_distance and boundary_radius store the fitted boundary in distance units. boundary_potential stores its squared value and is the quantity accepted by boundary_exceedance(). boundary_value is retained as a legacy alias of boundary_distance.

Scaling and preprocessing

preprocess selects retained variables. scale then converts those variables to z scores using current-climate means and standard deviations. Both are enabled by default. When fitted CENFA components are used, preprocessing must be disabled because the component dimensions are fixed. Inputs must either already use the CENFA standardisation with scale = FALSE or provide its exact means and standard deviations through global_mean and global_sd. climniche reads the required components from the supplied object and does not call CENFA package functions.

Choosing a fit function

Use fit_climniche() for matrices or data frames, fit_climniche_raster() for RasterLayer, RasterStack or RasterBrick objects, and fit_climniche_terra() for SpatRaster objects. All three functions calculate the same quantities. The spatial functions add domain masking and return map layers in x$rasters. Use fit_climniche_series() for ordered projections.

Examples

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