Examples
This vignette analyses European anchovy (Engraulis encrasicolus) in the Mediterranean Sea using Bio-ORACLE v3 surface layers, OBIS occurrences and a continuous suitability surface fitted with presence-background data.
library(climniche)
case_path <- system.file("extdata/mediterranean_anchovy", package = "climniche")
# Prepared tables stored with the package.
metric_summary <- read.csv(
file.path(case_path, "anchovy_climniche_metric_summary.csv")
)
variable_contributions <- read.csv(
file.path(case_path, "anchovy_climniche_variable_contributions.csv")
)
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")
)
fit_settings <- read.csv(
file.path(case_path, "anchovy_climniche_fit_settings.csv")
)
sensitivity_weights <- read.csv(
file.path(case_path, "anchovy_climniche_sensitivity_weights.csv")
)
predictor_screen <- read.csv(
file.path(case_path, "anchovy_predictor_correlation_vif_screen.csv")
)Prepared inputs
The environmental data are Bio-ORACLE v3 surface layers. Baseline time layers were averaged for current conditions; future rasters use the same variables under SSP2-4.5 at the 2050 time coordinate.
# Use readable scenario labels in the printed table.
layer_table <- layer_manifest
layer_table[["future_scenario"]] <- "SSP2-4.5"
unique(layer_table[, c(
"depth", "current_time", "future_scenario", "future_time"
)])
#> depth current_time
#> 1 surface (depthsurf) Bio-ORACLE v3 baseline time layers averaged
#> future_scenario future_time
#> 1 SSP2-4.5 2050-01-01T00:00:00Z
subset(layer_table, retained_for_climniche, c(
"label", "depth", "current_time", "future_scenario", "future_time"
))
#> label depth
#> 1 Mean temperature surface (depthsurf)
#> 2 Temperature range surface (depthsurf)
#> 3 Salinity range surface (depthsurf)
#> 5 Mean pH surface (depthsurf)
#> 6 Mean current speed surface (depthsurf)
#> 7 Current speed range surface (depthsurf)
#> current_time future_scenario
#> 1 Bio-ORACLE v3 baseline time layers averaged SSP2-4.5
#> 2 Bio-ORACLE v3 baseline time layers averaged SSP2-4.5
#> 3 Bio-ORACLE v3 baseline time layers averaged SSP2-4.5
#> 5 Bio-ORACLE v3 baseline time layers averaged SSP2-4.5
#> 6 Bio-ORACLE v3 baseline time layers averaged SSP2-4.5
#> 7 Bio-ORACLE v3 baseline time layers averaged SSP2-4.5
#> future_time
#> 1 2050-01-01T00:00:00Z
#> 2 2050-01-01T00:00:00Z
#> 3 2050-01-01T00:00:00Z
#> 5 2050-01-01T00:00:00Z
#> 6 2050-01-01T00:00:00Z
#> 7 2050-01-01T00:00:00ZThe current reference layer is a continuous suitability raster from a presence-background SDM. Background cells are sampled Mediterranean cells outside occurrence cells; they are not confirmed absences. The maximum TSS threshold removes low suitability cells from the reference set. Suitability values above the threshold remain continuous weights.
subset(
sdm_settings,
setting == "presence_cell_count" |
setting == "background_cell_count" |
setting == "background_to_presence_ratio" |
setting == "sdm_test_auc" |
setting == "sdm_test_tss" |
setting == "sdm_threshold"
)
#> setting value
#> 5 presence_cell_count 462
#> 7 background_cell_count 462
#> 8 background_to_presence_ratio 1.00
#> 17 sdm_threshold 0.6047
#> 18 sdm_test_auc 0.854
#> 19 sdm_test_tss 0.572Predictor screening was completed before the climniche
fit. The retained variables are:
climniche_predictors <- subset(
predictor_screen,
role == "climniche exposure calculation" & retained
)
subset(climniche_predictors, retained, c("label", "vif_after_screening"))
#> label vif_after_screening
#> 8 Mean temperature 1.479452
#> 9 Temperature range 1.485345
#> 10 Salinity range 1.441306
#> 12 Mean pH 1.719198
#> 13 Mean current speed 1.704366
#> 14 Current speed range 1.679131Fit the exposure model
The prepared Bio-ORACLE layers are terra rasters. The suitability raster enters the fit as a continuous reference layer; the maximum TSS cutoff removes low suitability values without converting the retained values to one.
The diagonal metric for this case study uses the ratio of current-domain variance to occurrence-cell variance, bounded between 0.25 and 4 and rescaled to mean one.
sensitivity_weights
#> variable label sensitivity_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.7771529# Use the maximum TSS threshold to remove low suitability cells.
threshold_row <- subset(sdm_settings, setting == "sdm_threshold")
sdm_threshold <- as.numeric(threshold_row[["value"]])
# Keep the Bio-ORACLE variables retained after predictor screening.
climniche_predictors <- subset(
predictor_screen,
role == "climniche exposure calculation" & retained
)
selected_predictors <- climniche_predictors[["variable"]]
predictor_labels <- setNames(
climniche_predictors[["label"]],
selected_predictors
)
predictor_sensitivity <- setNames(
sensitivity_weights[["sensitivity_weight"]],
sensitivity_weights[["variable"]]
)
# The suitability raster supplies continuous reference weights.
fit <- fit_climniche_terra(
current = current_layers[[selected_predictors]],
future = future_layers[[selected_predictors]],
occupied = anchovy_suitability,
occupied_threshold = sdm_threshold,
domain = mediterranean_sea_mask,
sensitivity = predictor_sensitivity
)
climniche_summary(fit)Niche-relative decomposition
The fit returns four quantities. Climatic Displacement is the distance from current to future conditions under the fitted climatic metric. Niche Distance Shift is the signed change in distance from the current realised niche centre. Climatic Reconfiguration is the remaining non radial component, calculated from the identity \(D_i^2 = R_i^2 + C_i^2\). Niche Boundary Exceedance is the positive excess of future niche distance beyond the empirical radial boundary of the current realised climatic niche.
If \(r_{0i}\) and \(r_{1i}\) are the current and future distances from the niche centre and \(\theta_i\) is the angle between their centred climatic vectors, then
\[ C_i^2 = 2r_{0i}r_{1i}\left[1 - \cos(\theta_i)\right]. \]
Climatic Reconfiguration therefore combines angular change with current and future distances from the niche centre. It is calculated from Climatic Displacement and Niche Distance Shift rather than fitted independently.
subset(
fit_settings,
setting == "boundary_quantile" |
setting == "tolerance" |
setting == "boundary_exceedance_tolerance"
)
#> setting value
#> 22 boundary_quantile 0.95
#> 23 tolerance 1.02733139047166
#> 25 boundary_exceedance_tolerance 0
metric_summary[, c(
"n", "reference_weight_sum", "boundary_quantile",
"mean_climate_change_amount", "mean_niche_distance_change",
"prop_beyond_niche_boundary", "mean_niche_boundary_exceedance"
)]
#> n reference_weight_sum boundary_quantile mean_climate_change_amount
#> 1 13584 9350.182 0.95 4.074289
#> mean_niche_distance_change prop_beyond_niche_boundary
#> 1 2.513135 0.09296699
#> mean_niche_boundary_exceedance
#> 1 0.1528591The variable contributions sum to future minus current squared niche distance. They are not SDM variable importance or causal effects.
variable_contributions
#> variable mean_absolute_share mean_signed_contribution
#> 1 ph_mean 0.68265941 13.2333040
#> 2 temperature_range 0.13090297 2.1475081
#> 3 salinity_range 0.10653320 1.2680182
#> 4 temperature_mean 0.04147293 0.5022907
#> 5 sea_water_speed_range 0.02926721 0.3970779
#> dominant_weight_fraction mean_contribution abs_mean_contribution
#> 1 0.826981390 13.2333040 13.2333040
#> 2 0.071284480 2.1475081 2.1475081
#> 3 0.099758279 1.2680182 1.2680182
#> 4 0.000000000 0.5022907 0.5022907
#> 5 0.001975851 0.3970779 0.3970779
#> interpretation
#> 1 positive mean contribution
#> 2 positive mean contribution
#> 3 positive mean contribution
#> 4 positive mean contribution
#> 5 positive mean contributionMediterranean maps
The map figure shows the four continuous reported quantities within the current SDM suitable area.
metric_maps <- plot_climniche_maps(
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
The summary figure uses one weighted plane for Climatic Displacement and Niche Distance Shift and a second for Climatic Reconfiguration and Niche Boundary Exceedance. Panel (c) shows each climatic variable’s mean absolute contribution share to the squared-distance change underlying Niche Distance Shift. Panel (d) shows weighted distributions of the four reported quantities. The spatial climatic contribution example maps the cell-level pattern underlying panel (c).
summary_figure <- plot_climniche_summary_figure(
fit,
scope = "current",
top_variables = 6,
variable_labels = predictor_labels,
title = NULL
)
summary_figure
The exposure through time example extends this fit to four SSP2-4.5 projection years while retaining the same current niche reference.