Screen ecological criteria against climate exposure

Usage

climniche_priority(
  x,
  exposure = c("niche_distance_change", "niche_boundary_exceedance",
    "climate_reconfiguration", "climate_change_amount", "outside_niche_exceedance",
    "composition_change"),
  criterion = NULL,
  criterion_name = NULL,
  criterion_direction = c("maximize", "minimize"),
  scope = c("current", "all"),
  positive_only = NULL,
  exposure_direction = c("maximize", "minimize")
)

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

Arguments

x: A fitted climniche_fit object.
exposure: Climatic quantity used as the exposure objective. Available choices are "niche_distance_change", "niche_boundary_exceedance", "climate_reconfiguration", and "climate_change_amount". Legacy metric aliases are accepted.
criterion: Optional second decision criterion. A numeric vector may contain one value per evaluated row or, for a spatial fit, one value per raster cell. A matching one-layer RasterLayer or SpatRaster is also accepted. When omitted, current reference weights are used.
criterion_name: Display name for criterion.
criterion_direction: Whether larger or smaller criterion values are preferred.
scope: "current" ranks cells with positive current reference weight; "all" ranks every evaluated cell with finite criteria.
positive_only: If TRUE, only cells with a positive value of the selected exposure quantity are ranked. The default, NULL, uses TRUE when exposure is maximised and FALSE when it is minimised.
exposure_direction: Whether larger or smaller exposure values are preferred in the Pareto comparison. Use "maximize" to screen for greater exposure and "minimize" to screen for lower exposure.
object: A climniche_priority object.
...: Unused.

Value

A climniche_priority object containing the two decision criteria, Pareto ranks, Pareto depth score (pareto_depth_score) and, for spatial fits, map layers. relative_priority is retained as a compatibility alias for pareto_depth_score.

summary() returns a summary.climniche_priority object with the fitted settings and Pareto diagnostics.

Details

The function ranks cells on two objectives: the selected climatic exposure quantity and one reference or decision criterion. Cell \(i\) dominates cell \(k\) when it is at least as preferred on both objectives and strictly preferred on one. Non-dominated cells form Pareto rank 1. Removing that front and repeating the comparison produces ranks 2, 3, and subsequent fronts.

If an analysis contains \(K\) Pareto fronts, pareto_depth_score is \((K-r_i)/(K-1)\) for the rank \(r_i\) of cell \(i\); it is 1 when all cells occupy one front. The score does not order cells within a front and is not comparable among separate analyses. Pareto dominance is invariant to monotonic rescaling, so the two criteria are not combined with fitted weights.

When current reference weights are constant, the default second criterion does not distinguish cells and ranking is determined by exposure alone. When the weights vary, the default is a within-reference screening rather than a comparison with independent ecological evidence. Supply criterion for the latter use.

Only one exposure quantity is used at a time. This avoids counting Climatic Displacement, Niche Distance Shift and Climatic Reconfiguration as independent objectives even though their values satisfy the fitted geometric identity. When the second criterion represents ecological value, maximising a positive Niche Distance Shift identifies cells where high ecological value coincides with movement away from the current niche centre. Minimising Climatic Displacement identifies cells where high ecological value coincides with less local climatic change. The two directions answer different screening questions; neither is a complete conservation ranking.

summary() reports the first-front fraction and the Spearman correlation between the preference-oriented forms of the two objectives. These describe how strongly the objectives separate the ranked cells; they are not inferential tests.

References

Tracey JA, Rochester CJ, Hathaway SA, et al. (2018). Prioritizing conserved areas threatened by wildfire and fragmentation for monitoring and management. PLOS ONE, 13, e0200203. doi:10.1371/journal.pone.0200203

Sacre E, Bode M, Weeks R, Pressey RL (2019). The context dependence of frontier versus wilderness conservation priorities. Conservation Letters, 12, e12632. doi:10.1111/conl.12632

Examples

sim <- simulate_climniche(n = 500, p = 6, seed = 18)
fit <- fit_climniche(
  sim[["current"]],
  sim[["future_away"]],
  occupied = sim[["occupied"]],
  sensitivity = sim[["sensitivity"]]
)
priority <- climniche_priority(fit)
priority
priority_table <- priority[["table"]]
head(priority_table[priority_table[["included"]], ])
summary(priority)