---
title: "Ecological screening of climate exposure"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Ecological screening of climate exposure}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.align = "center")
```

An ecological criterion can be screened against different components of
climate exposure. `climniche_priority()` keeps the two objectives visible and
returns their Pareto fronts.

## Pareto screening

Each screen pairs one climniche quantity with one ecological criterion. A cell
has Pareto rank 1 when no other retained cell is at least as preferred on both
objectives and strictly preferred on one. Successive fronts describe
increasing Pareto depth. The Pareto depth score rescales these fronts from zero
to one, with one assigned to the non-dominated front.

The two objectives remain visible throughout the analysis. The result is a set
of non-dominated alternatives rather than a weighted sum or a complete
conservation ranking.

## Mediterranean anchovy

The spatial fit is taken from the
[European anchovy example](climniche-examples.html). Current SDM suitability
provides the second criterion for both screens. Because this suitability
surface also defines the fitted reference niche, the result is a
within-reference spatial screening, not an independent conservation priority.

**Positive Niche Distance Shift screen** combines high current suitability with
a larger positive Niche Distance Shift. Positive values represent movement
away from the current niche centre.

```{r positive-shift-code, eval = FALSE}
positive_shift <- climniche_priority(
  spatial_fit,
  exposure = "niche_distance_change",
  criterion_name = "Current SDM suitability",
  scope = "current",
  positive_only = TRUE,
  exposure_direction = "maximize"
)
```

**Low Climatic Displacement screen** combines high current suitability with
lower Climatic Displacement. It identifies cells where higher suitability
coincides with comparatively less local climatic change.

```{r low-displacement-code, eval = FALSE}
low_displacement <- climniche_priority(
  spatial_fit,
  exposure = "climate_change_amount",
  criterion_name = "Current SDM suitability",
  scope = "current",
  positive_only = FALSE,
  exposure_direction = "minimize"
)
```

```{r screening-summary, echo = FALSE}
library(climniche)

case_path <- system.file("extdata/mediterranean_anchovy", package = "climniche")
screening_summary <- read.csv(
  file.path(case_path, "anchovy_climniche_priority_summary.csv")
)
screening_table <- data.frame(
  Profile = screening_summary[["profile"]],
  Exposure = screening_summary[["exposure"]],
  Direction = screening_summary[["exposure_direction"]],
  `Ranked cells` = format(
    screening_summary[["ranked_cells"]],
    big.mark = ","
  ),
  `Pareto fronts` = screening_summary[["pareto_fronts"]],
  `First front` = screening_summary[["first_front_cells"]],
  check.names = FALSE
)
knitr::kable(screening_table, row.names = FALSE)
```

## Decision planes and maps

```{r screening-figure-code, eval = FALSE}
positive_shift_figure <- plot_climniche_priority(
  positive_shift,
  type = "both",
  map_value = "pareto_depth_score",
  study_region = mediterranean_boundary,
  degree_labels = "hemisphere"
)

low_displacement_figure <- plot_climniche_priority(
  low_displacement,
  type = "both",
  map_value = "pareto_depth_score",
  study_region = mediterranean_boundary,
  degree_labels = "hemisphere"
)
```

```{r screening-figure-output, echo = FALSE, out.width = "100%"}
knitr::include_graphics("figures/anchovy-climniche-priority.png")
```

Panels (a) and (c) retain the two objectives and outline the first Pareto
front. Panels (b) and (d) map the depth of each retained cell relative to its
own screen. Pareto depth scores are therefore interpreted within a screen, not
compared between the two maps.

An independent abundance, habitat-condition, irreplaceability, restoration or
management-cost layer can instead be supplied through `criterion`, with the
preferred direction set by `criterion_direction`.

The Pareto procedure follows the spatial multi-criteria application of
[Tracey et al. (2018)](https://doi.org/10.1371/journal.pone.0200203). Lower
Climatic Displacement indicates relative climatic stability in the fitted
climatic space; it is not evidence of species persistence or a climate
refugium.