# Examples

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).

    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.

    summary_tab[, c(
      "n", "boundary_quantile", "mean_climate_change_amount",
      "mean_niche_distance_change", "prop_niche_divergence",
      "prop_niche_exceedance", "prop_niche_convergence"
    )]
    #>       n boundary_quantile mean_climate_change_amount mean_niche_distance_change
    #> 1 22633              0.95                   2.447509                   1.067926
    #>   prop_niche_divergence prop_niche_exceedance prop_niche_convergence
    #> 1             0.6161799             0.1643618              0.1203111

    head(class_tab)
    #>                                   class proportion count
    #> 1            farther from current niche 0.61617991 13946
    #> 2        outside current niche boundary 0.16436177  3720
    #> 3               closer to current niche 0.12031105  2723
    #> 4 changed composition, similar distance 0.06662837  1508
    #> 5           little climate niche change 0.03251889   736
    head(variable_tab)
    #>   variable mean_contribution abs_mean_contribution
    #> 1  sst_min         2.4199989             2.4199989
    #> 2  sst_max         1.1530620             1.1530620
    #> 3 sst_mean         0.7985194             0.7985194
    #>                  interpretation
    #> 1 less similar to current niche
    #> 2 less similar to current niche
    #> 3 less similar to current niche
    nrow(records)
    #> [1] 1480

## 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.

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.

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.

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.

    class_tab[, c("class", "proportion")]
    #>                                   class proportion
    #> 1            farther from current niche 0.61617991
    #> 2        outside current niche boundary 0.16436177
    #> 3               closer to current niche 0.12031105
    #> 4 changed composition, similar distance 0.06662837
    #> 5           little climate niche change 0.03251889
    variable_tab[, c("variable", "mean_contribution", "interpretation")]
    #>   variable mean_contribution                interpretation
    #> 1  sst_min         2.4199989 less similar to current niche
    #> 2  sst_max         1.1530620 less similar to current niche
    #> 3 sst_mean         0.7985194 less similar to current niche

## 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.

    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.

    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
    )