This example evaluates projected climate exposure for European anchovy (Engraulis encrasicolus) in the Mediterranean Sea. Current and SSP2-4.5 conditions use six Bio-ORACLE v3 surface variables. A continuous presence-background SDM supplies the current reference weights.
library(climniche)
case_path <- system.file("extdata/mediterranean_anchovy", package = "climniche")
case_cells <- read.csv(
file.path(case_path, "anchovy_climniche_input_sample.csv"),
check.names = FALSE
)
layer_manifest <- read.csv(
file.path(case_path, "anchovy_biooracle_layer_manifest.csv")
)
sdm_settings <- read.csv(
file.path(case_path, "anchovy_presence_background_sdm_settings.csv")
)
metric_weights <- read.csv(
file.path(case_path, "anchovy_climniche_sensitivity_weights.csv")
)Climatic data
The six retained variables describe temperature, salinity, pH and water movement. Current and future layers have identical variables, resolution and cell order.
variable_table <- subset(
layer_manifest,
retained_for_climniche,
c("variable", "label", "depth", "current_time", "future_time")
)
variable_table[["future_scenario"]] <- "SSP2-4.5"
variable_table
#> variable label depth
#> 1 temperature_mean Mean temperature surface (depthsurf)
#> 2 temperature_range Temperature range surface (depthsurf)
#> 3 salinity_range Salinity range surface (depthsurf)
#> 5 ph_mean Mean pH surface (depthsurf)
#> 6 sea_water_speed_mean Mean current speed surface (depthsurf)
#> 7 sea_water_speed_range Current speed range surface (depthsurf)
#> current_time future_time
#> 1 Bio-ORACLE v3 baseline time layers averaged 2050-01-01T00:00:00Z
#> 2 Bio-ORACLE v3 baseline time layers averaged 2050-01-01T00:00:00Z
#> 3 Bio-ORACLE v3 baseline time layers averaged 2050-01-01T00:00:00Z
#> 5 Bio-ORACLE v3 baseline time layers averaged 2050-01-01T00:00:00Z
#> 6 Bio-ORACLE v3 baseline time layers averaged 2050-01-01T00:00:00Z
#> 7 Bio-ORACLE v3 baseline time layers averaged 2050-01-01T00:00:00Z
#> future_scenario
#> 1 SSP2-4.5
#> 2 SSP2-4.5
#> 3 SSP2-4.5
#> 5 SSP2-4.5
#> 6 SSP2-4.5
#> 7 SSP2-4.5The diagonal climatic metric uses the ratio of current-domain variance to occurrence-cell variance, bounded to 0.25-4 and normalised to mean one. These weights define the relative distance scale for this case study; they are not physiological sensitivity estimates.
weight_table <- merge(
variable_table[c("variable", "label")],
metric_weights[c("variable", "sensitivity_weight")],
by = "variable",
sort = FALSE
)
names(weight_table) <- c(
"Variable", "Climate variable", "Climatic metric weight"
)
weight_table
#> Variable Climate variable Climatic metric weight
#> 1 temperature_mean Mean temperature 0.7709378
#> 2 temperature_range Temperature range 0.9848117
#> 3 salinity_range Salinity range 2.0457639
#> 4 ph_mean Mean pH 0.7755083
#> 5 sea_water_speed_mean Mean current speed 0.6458254
#> 6 sea_water_speed_range Current speed range 0.7771529The package contains a 2,000-cell extract of the prepared raster inputs so that the central calculation runs when this vignette is built. The maps later in the vignette come from the full Mediterranean raster analysis.
climate_variables <- variable_table[["variable"]]
current_columns <- paste0(climate_variables, "_current")
future_columns <- paste0(climate_variables, "_future")
current_climate <- as.matrix(case_cells[current_columns])
future_climate <- as.matrix(case_cells[future_columns])
colnames(current_climate) <- climate_variables
colnames(future_climate) <- climate_variables
weight_row <- sdm_settings[["setting"]] == "sdm_threshold"
sdm_threshold <- as.numeric(sdm_settings[weight_row, "value"])
climatic_weights <- setNames(
metric_weights[["sensitivity_weight"]],
metric_weights[["variable"]]
)Climate exposure relative to the current niche
Suitability values at or below the SDM threshold receive zero reference weight. Values above the threshold retain their continuous values.
anchovy_fit <- fit_climniche(
current = current_climate,
future = future_climate,
occupied = case_cells[["sdm_suitability"]],
occupied_threshold = sdm_threshold,
sensitivity = climatic_weights,
preprocess = FALSE
)
climniche_summary(anchovy_fit)
#> Scope Cells Reference weight sum Boundary quantile Boundary distance
#> current 1200 825.3044 0.95 5.241434
#>
#> Metric Mean Median 90th percentile
#> Climatic Displacement 3.519480 3.509524 3.7255453
#> Niche Distance Shift 2.184474 2.530491 2.9668506
#> Climatic Reconfiguration 2.553753 2.376605 3.4869382
#> Niche Boundary Exceedance 0.140777 0.000000 0.2373889Let current and future climatic conditions at cell \(i\) be \(c_i\) and \(f_i\), the centre of the current climatic niche reference be \(\mu\), and the fitted climatic distance be \(d_A\). The reported quantities are
\[ \begin{aligned} D_i &= d_A(f_i,c_i),\\ R_i &= d_A(f_i,\mu)-d_A(c_i,\mu),\\ C_i &= \sqrt{\max(0,D_i^2-R_i^2)},\\ E_i &= \max(0,d_A(f_i,\mu)-B_q). \end{aligned} \]
Climatic Displacement (\(D_i\)) and Niche Distance Shift (\(R_i\)) form the primary geometric pair. Climatic Reconfiguration (\(C_i\)) is derived from them as the non-radial component of Climatic Displacement; it is not an independently estimated process. Niche Boundary Exceedance (\(E_i\)) compares the future distance with the weighted empirical radial boundary \(B_q\).
The identity can be checked directly from the fitted object.
geometry_error <- with(
anchovy_fit,
climate_change_amount^2 -
niche_distance_change^2 -
climate_reconfiguration^2
)
max(abs(geometry_error))
#> [1] 3.552714e-15Niche Boundary Exceedance describes the future boundary-relative state. A positive value is an excess distance beyond \(B_q\); it does not by itself show that the cell crossed the boundary between current and future conditions.
Mediterranean maps
The full raster workflow uses the same climatic variables and reference weights.
spatial_fit <- fit_climniche_terra(
current = current_layers[[climate_variables]],
future = future_layers[[climate_variables]],
occupied = anchovy_suitability,
occupied_threshold = sdm_threshold,
domain = mediterranean_sea_mask,
sensitivity = climatic_weights,
preprocess = FALSE
)
metric_maps <- plot_climniche_maps(
spatial_fit,
occupied = anchovy_suitability,
occupied_only = TRUE,
occupied_threshold = sdm_threshold,
study_region = mediterranean_boundary,
degree_labels = "hemisphere",
legend_title = FALSE,
legend_position = "bottom"
)
metric_maps
Summary figure
Panel (a) shows the primary geometric pair. Panel (b) places the derived Climatic Reconfiguration term against the boundary-relative future state. Panel (c) gives each climatic variable’s mean absolute share of the change in squared niche distance. These are climatic distance contributions, not SDM variable importance. Panel (d) shows the weighted distributions of the reported quantities.
variable_labels <- setNames(
variable_table[["label"]],
variable_table[["variable"]]
)
summary_figure <- plot_climniche_summary_figure(
spatial_fit,
scope = "current",
top_variables = 6,
variable_labels = variable_labels,
title = NULL
)
summary_figure
The exposure through time example applies the same fixed current niche reference to four SSP2-4.5 projections. The spatial climatic contribution example maps the cell-level pattern summarized in panel (c).
Data sources
Bio-ORACLE v3 layers follow Assis et al. (2024), Global Ecology and Biogeography 33, e13813. Occurrence records were obtained from the Ocean Biodiversity Information System. The study region uses Marine Regions IHO Sea Areas version 3 (doi:10.14284/323).