---
title: "Examples"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Examples}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This page uses the Mediterranean anchovy case study from the package data. The
case study is based on a Mediterranean analysis domain, current and projected
sea-surface temperature variables, and an SDM-derived current reference area for
European anchovy (*Engraulis encrasicolus*).

```{r}
library(climniche)

case_path <- system.file("extdata/mediterranean_anchovy", package = "climniche")
summary_tab <- read.csv(file.path(case_path, "anchovy_climniche_summary.csv"))
class_tab <- read.csv(file.path(case_path, "anchovy_climniche_classes.csv"))
variable_tab <- read.csv(file.path(case_path, "anchovy_climniche_top_variables.csv"))
records <- read.csv(file.path(case_path, "anchovy_clean_obis_records.csv"))
```

The included tables keep the vignette small while recording the fitted case.
The full raster workflow used the same package functions shown below.

```{r}
summary_tab[, c(
  "n", "boundary_quantile", "mean_climate_change_amount",
  "mean_niche_distance_change", "prop_niche_divergence",
  "prop_niche_exceedance", "prop_niche_convergence"
)]

head(class_tab)
head(variable_tab)
nrow(records)
```

## Mediterranean maps

The map panel shows the data structure used for interpretation: current
suitability, climate change amount, niche distance change, composition change,
niche boundary exceedance, change alignment, and exposure class.

```{r, echo = FALSE, out.width = "100%"}
knitr::include_graphics("figures/anchovy-mediterranean-maps.png")
```

The map is limited to the Mediterranean analysis domain. The current reference
cells are taken from the SDM suitability layer; exposure is evaluated at those
cells and interpreted against the realised niche estimated from the same
reference set.

## Niche climate diagram

The same result can be shown in climate space. The filled polygon is the current
realised niche envelope, the boundary line is the empirical niche boundary, and
arrows show the mean movement of exposure classes.

```{r, echo = FALSE, out.width = "80%"}
knitr::include_graphics("figures/anchovy-climniche-diagram.png")
```

This diagram is useful when a map alone is ambiguous. It separates cells that
experience large climate change from cells whose future climate is specifically
farther from, closer to, or outside the current realised niche.

## Summary figure

`plot_climniche_showcase()` combines the binned exposure plane, exposure class
proportions, variable contributions, and metric distributions.

```{r, echo = FALSE, out.width = "95%"}
knitr::include_graphics("figures/anchovy-climniche-showcase.png")
```

The Mediterranean case identifies sea-surface temperature minima, maxima, and
mean conditions as the variables contributing most to the increase in niche
distance. The class table gives the same result numerically.

```{r}
class_tab[, c("class", "proportion")]
variable_tab[, c("variable", "mean_contribution", "interpretation")]
```

## Fitting the same data structure

For a raster workflow, current and future environmental layers must have the
same geometry. The occupied layer can be binary or continuous. With a continuous
SDM layer, cells above `occupied_threshold` define the current reference niche.

```r
fit <- fit_climniche_raster(
  current = current_sst_stack,
  future = future_sst_stack,
  occupied = anchovy_sdm_suitability,
  occupied_threshold = 0.40,
  domain = mediterranean_domain,
  sensitivity = c(sst_min = 1, sst_mean = 1, sst_max = 1),
  boundary = 0.95
)

climniche_summary(fit)
plot_climniche_map(fit, metric = "niche_distance_change",
                   occupied = anchovy_sdm_suitability,
                   occupied_only = TRUE,
                   occupied_threshold = 0.40)
plot_climniche_classes(fit, occupied = anchovy_sdm_suitability,
                       occupied_only = TRUE,
                       occupied_threshold = 0.40)
plot_climniche_diagram(fit)
plot_climniche_showcase(fit)
```

For a matrix workflow, extract current and future environmental values first and
pass the current reference cells as a logical vector, row indices, or continuous
suitability vector.

```r
fit <- fit_climniche(
  current = current_values,
  future = future_values,
  occupied = sdm_suitability,
  occupied_threshold = 0.40,
  sensitivity = c(sst_min = 1, sst_mean = 1, sst_max = 1),
  boundary = 0.95
)
```