Fit climate exposure relative to a climatic niche from matrices

Estimates projected climatic change at each site relative to a fitted current niche reference.

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: Reference information used to estimate the current 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 metric weights. These define relative contributions to distance and are not physiological sensitivity estimates unless supplied from an independent analysis.
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 current reference 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.
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

Let current and future climatic conditions at cell $i$ be $c_i$ and $f_i$. Let $\mu$ be the centre of the current climatic niche reference, and let $d_A(x, y)$ be the climatic distance under weighting matrix $A$. Climatic Displacement and Niche Distance Shift form the primary geometric pair:

Climatic Displacement: $$D_i = d_A(f_i, c_i)$$

Niche Distance Shift: $$R_i = d_A(f_i, \mu) - d_A(c_i, \mu)$$

Climatic Reconfiguration: $$C_i = \sqrt{\max(0, D_i^2 - R_i^2)}$$

Niche Boundary Exceedance: $$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 reference centre. Climatic Reconfiguration is derived from Climatic Displacement and Niche Distance Shift. Niche Boundary Exceedance is a separate comparison with the fitted radial boundary.

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)