Summarise dominant climatic contributions by cell — climniche_dominant

Identifies the climate variable with the largest absolute contribution to future minus current squared niche distance at each evaluated cell.

Usage

climniche_dominant_contribution(x, scope = c("current", "all"))

# S3 method for class 'climniche_contribution'
summary(object, ...)

Arguments

x: A fitted climniche_fit object.
scope: "current" retains cells with positive current reference weight; "all" retains every evaluated cell.
object: A climniche_contribution object.
...: Additional arguments passed to methods.

Value

A climniche_contribution object. table contains the dominant variable, signed contribution and dominance share for each cell. summary contains mean contribution shares and signed contributions by variable, together with the fraction of non-zero analysis weight for which each variable is uniquely dominant. squared_niche_distance_change is the row sum of the signed variable contributions. The legacy field niche_potential_change is retained as an exact alias. Spatial fits also return raster layers.

Details

Let $V_{ij}$ be the contribution returned by variable_contribution() for cell $i$ and variable $j$. The dominant variable has the largest $|V_{ij}|$. Its dominance share is $$H_i = \frac{\max_j |V_{ij}|}{\sum_j |V_{ij}|}.$$ The share is undefined when every contribution is zero. Equal largest absolute contributions are reported as "Tied" rather than being assigned according to column order.

Contributions sum exactly to future minus current squared niche distance. This total is also $(r_{1i} - r_{0i})(r_{1i} + r_{0i})$. The terms therefore attribute the squared-distance change underlying Niche Distance Shift. For a non-diagonal metric matrix, each variable term includes its part of the cross-variable terms in the chosen climatic basis. They are not SDM variable importance or causal effects. Current-scope summaries use the fitted reference weights; all-scope summaries give each evaluated cell equal weight.

Examples

sim <- simulate_climniche(n = 300, p = 6, seed = 31)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
contribution <- climniche_dominant_contribution(fit)
summary(contribution)
head(contribution[["table"]])