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.626122                   1.084759
#>   prop_niche_divergence prop_niche_exceedance prop_niche_convergence
#> 1             0.5896415              0.164444              0.1317674

head(class_tab)
#>                                                        class  proportion count
#> 1                                 Farther from current niche 0.589641541 14342
#> 2                             Outside current niche boundary 0.164444021  4030
#> 3                                    Closer to current niche 0.131767385  2032
#> 4 Climatic Reconfiguration with limited Niche Distance Shift 0.109244037  2070
#> 5                               Limited climate niche change 0.004903016   159
head(variable_tab)
#>   variable mean_contribution abs_mean_contribution
#> 1  sst_min         2.6826576             2.6826576
#> 2  sst_max         1.1279729             1.1279729
#> 3 sst_mean         0.8217001             0.8217001
#>                          interpretation
#> 1 positive niche potential contribution
#> 2 positive niche potential contribution
#> 3 positive niche potential contribution
nrow(records)
#> [1] 1480

Mediterranean maps

The map panel shows the data structure used for interpretation: current suitability, Climatic Displacement, Niche Distance Shift, Climatic Reconfiguration, Niche Boundary Exceedance, change alignment, and exposure class. The four metrics are continuous quantities. The exposure classes are derived after fitting by applying the classification thresholds to those metrics; they are not a one-to-one set of four metric categories.

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. Continuous suitability values are used as reference weights in the fitted niche centre, empirical niche boundary and current-scope summaries.

Summary figure

plot_climniche_showcase() combines the binned exposure plane, exposure class proportions, variable contributions, and distributions of the four metrics.

The Mediterranean case identifies sea-surface temperature minima, maxima, and mean conditions as the variables with the largest positive contributions to niche potential change. The class table gives the exposure classes numerically.

class_tab[, c("class", "proportion")]
#>                                                        class  proportion
#> 1                                 Farther from current niche 0.589641541
#> 2                             Outside current niche boundary 0.164444021
#> 3                                    Closer to current niche 0.131767385
#> 4 Climatic Reconfiguration with limited Niche Distance Shift 0.109244037
#> 5                               Limited climate niche change 0.004903016
variable_tab[, c("variable", "mean_contribution", "interpretation")]
#>   variable mean_contribution                        interpretation
#> 1  sst_min         2.6826576 positive niche potential contribution
#> 2  sst_max         1.1279729 positive niche potential contribution
#> 3 sst_mean         0.8217001 positive niche potential contribution

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, occupied_threshold removes low suitability values. Values above the threshold remain continuous reference weights.

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,
  tolerance_quantile = 0.10,
  stable_quantile = 0.25,
  stable_reconfiguration_quantile = 0.25,
  boundary_exceedance_tolerance = 0,
  conflict_ratio = 0.25
)

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_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 a 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
)