Fit climniche to raster data

Usage

fit_climniche_raster(
  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: RasterLayer, RasterStack or RasterBrick object of current climate layers.
future: Matching RasterLayer, RasterStack or RasterBrick object of future climate layers with the same geometry and variables as current. Named layers are matched before fitting.
occupied: Optional RasterLayer 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 RasterLayer 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 RasterLayer outputs stored in x$rasters.

Details

fit_climniche_raster() is the spatial workflow for users working with the raster package. 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 RasterLayer outputs.