Fit climniche to terra raster data

Usage

fit_climniche_terra(
  current,
  future,
  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,
  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: terra SpatRaster of current climate layers.
future: terra SpatRaster of future climate layers with the same geometry and variables as current. Named layers are matched before fitting.
occupied: Optional one layer SpatRaster with binary or continuous occurrence, range, or SDM suitability values. Continuous values are retained on their supplied numerical scale.
occupied_threshold: Values at or below this threshold receive zero reference weight. Values above it keep their original value.
domain: Optional one layer SpatRaster limiting cells where exposure is analysed.
domain_threshold: Values greater than this threshold define the domain.
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

An object of class climniche_fit with SpatRaster outputs stored in x$rasters.

Details

fit_climniche_terra() is the SpatRaster workflow for users working with terra. It fits the current reference from finite current cells within domain, then evaluates cells with finite current and future values. Future missing values therefore do not alter the fitted current reference. Reported quantities are written back to SpatRaster outputs.