Project climatic conditions onto a fitted niche reference

Usage

project_climniche(
  reference,
  future,
  current = NULL,
  occupied = NULL,
  occupied_threshold = NULL,
  tolerance = NULL,
  tolerance_quantile = 0.1,
  boundary_exceedance_tolerance = 0
)

Arguments

reference: A climniche_reference object.
future: Numeric matrix or data frame of projected climatic conditions.
current: Optional current climatic conditions for the projected rows. If omitted, the current rows stored in reference are used.
occupied: Optional reference weights for summaries of the projected rows. When current is omitted, the fitted reference weights are reused. With a supplied current, named rows are matched to the reference; otherwise projected rows receive equal weight.
occupied_threshold: Optional cutoff for numeric occupied weights.
tolerance: Optional tolerance around zero for Niche Distance Shift.
tolerance_quantile: Quantile of absolute Niche Distance Shift used when tolerance = NULL.
boundary_exceedance_tolerance: Non-negative tolerance used by the boundary status descriptor.

Value

A climniche_fit object using the fixed reference.

Details

Let $A$ be the fitted weighting matrix and let $\mu$ be the realised niche centre. In the transformed climatic space, write the current and future centred vectors as $z_0$ and $z_1$, with lengths $r_0$ and $r_1$. When both lengths are positive, let $\theta$ be the angle between those vectors. Climatic Reconfiguration satisfies $$C_i^2 = 2 r_{0i} r_{1i} (1 - \cos(\theta_i)).$$ It therefore depends on angular change and current and future niche distances. It is derived from Climatic Displacement and Niche Distance Shift, not fitted as an independent process.

Examples

sim <- simulate_climniche(n = 200, p = 6, seed = 4)
reference <- fit_climniche_reference(
  sim$current,
  occupied = sim$occupied,
  sensitivity = sim$sensitivity
)
fit <- project_climniche(reference, sim$future_away)
climniche_summary(fit)