ecological-agent-skills 3.1.0

package/skills/model-validation-and-uncertainty/resources/extrapolation-risk-guide.md

@@ -0,0 +1,236 @@
+# Extrapolation Risk Guide
+
+Assessing environmental novelty before interpreting model projections.
+
+---
+
+## 1. Interpolation vs Extrapolation in Environmental Space
+
+A species distribution model learns relationships between occurrence records and
+environmental predictors within the **calibration area** (M area). When a model
+is projected to a new region or time period, every prediction pixel falls into one
+of two categories:
+
+| Category | Definition | Risk |
+|---|---|---|
+| **Interpolation** | Pixel lies within the multivariate environmental range seen at calibration | Low — model is working within its learned space |
+| **Extrapolation (strict)** | Pixel has at least one predictor value outside the full range observed in calibration | High — model must extrapolate; response is undefined |
+| **Extrapolation (combinatorial)** | Pixel has individual values within calibration range, but their *combination* was not observed | Medium-High — subtler but still novel |
+
+**Key principle:** All three methods below (MOP, ExDet, MESS) detect different
+aspects of environmental novelty. None of them tells you *whether* the model will
+extrapolate correctly — only that it *is* extrapolating.
+
+---
+
+## 2. MOP — Mobility-Oriented Parity
+
+**Reference:** Owens et al. 2013. Constraints on interpretation of ecological niche
+models by limited environmental ranges on calibration areas.
+*Ecological Modelling* 263: 10–18.
+DOI: [10.1016/j.ecolmodel.2013.04.011](https://doi.org/10.1016/j.ecolmodel.2013.04.011)
+
+### What MOP measures
+
+MOP computes, for each projection pixel, the proportion of calibration points that
+fall *closer* (in multivariate Euclidean space) than the projection pixel itself.
+
+- **Scale:** 0 to 1
+- **MOP = 1:** pixel is well within calibration environmental range
+- **MOP = 0:** strict extrapolation — the pixel is more extreme than *all* calibration points in at least one predictor dimension
+- **MOP = 0.1:** only 10% of calibration points are environmentally similar
+
+### Interpretation
+
+| MOP value | Interpretation | Action |
+|---|---|---|
+| > 0.75 | Safe interpolation | Interpret predictions normally |
+| 0.50 – 0.75 | Moderate novelty | Report with caution |
+| 0.25 – 0.50 | High novelty | Flag in figure caption |
+| < 0.25 | Very high novelty | Strong caveat; consider masking |
+| = 0 | Strict extrapolation | Mask in publication figures |
+
+### R implementation (terra)
+
+```r
+# MOP function using terra (no Java required)
+calc_mop <- function(train_stack, proj_stack, prop = 0.1) {
+  suppressPackageStartupMessages(library(terra))
+
+  # Extract calibration values
+  cal_vals <- as.data.frame(train_stack, na.rm = TRUE)
+  proj_vals <- as.data.frame(proj_stack, na.rm = TRUE)
+  n_cal <- nrow(cal_vals)
+  n_vars <- ncol(cal_vals)
+
+  # For each projection pixel, compute proportion of calibration points
+  # that are "closer" (Euclidean distance in scaled predictor space)
+  cal_scaled <- scale(cal_vals)
+  center <- attr(cal_scaled, "scaled:center")
+  sdev   <- attr(cal_scaled, "scaled:scale")
+
+  proj_scaled <- sweep(sweep(proj_vals, 2, center, "-"), 2, sdev, "/")
+
+  mop_vals <- apply(proj_scaled, 1, function(px) {
+    if (any(is.na(px))) return(NA)
+    d_px_to_cal <- sqrt(rowSums(sweep(cal_scaled, 2, px, "-")^2))
+    d_cal_centroid <- sqrt(rowSums(cal_scaled^2))
+    # proportion of calibration points less extreme than projection pixel
+    sum(d_cal_centroid < quantile(d_px_to_cal, prop)) / n_cal
+  })
+
+  # Place back into raster
+  mop_rast <- proj_stack[[1]]
+  values(mop_rast) <- mop_vals
+  names(mop_rast) <- "MOP"
+  return(mop_rast)
+}
+```
+
+---
+
+## 3. ExDet — Extrapolation Detection
+
+**Reference:** Mesgaran et al. 2014. Here be dragons: a tool for quantifying novelty
+due to covariate range and collinearity extrapolation when predicting species
+distributions. *Diversity and Distributions* 20: 1147–1159.
+DOI: [10.1111/ddi.12209](https://doi.org/10.1111/ddi.12209)
+
+### What ExDet measures
+
+ExDet distinguishes two types of extrapolation:
+
+| Type | Code | Meaning |
+|---|---|---|
+| **NT1** (univariate) | Negative value | At least one predictor is outside its calibration min–max range |
+| **NT2** (combinatorial) | 0 to 1 | All predictors in range, but combination novel; value = Mahalanobis-based dissimilarity |
+| **Interpolation** | > 1 | Pixel well within calibration cloud |
+
+**NT1 extrapolation is the most dangerous** — the model is predicting beyond any
+observed value for that variable. NT2 is subtler but still represents novel
+environmental combinations that the model has not seen.
+
+### R code (manual ExDet)
+
+```r
+calc_exdet <- function(train_mat, proj_mat) {
+  # Standardize using calibration mean and sd
+  mu  <- colMeans(train_mat, na.rm = TRUE)
+  sig <- apply(train_mat, 2, sd, na.rm = TRUE)
+  S   <- cov(train_mat, use = "complete.obs")
+  S_inv <- solve(S)
+
+  apply(proj_mat, 1, function(px) {
+    if (any(is.na(px))) return(NA)
+    px_s <- (px - mu) / sig
+    tr_s <- sweep(train_mat, 2, mu, "-")
+    tr_s <- sweep(tr_s, 2, sig, "/")
+    # NT1: univariate extrapolation
+    below <- any(px < apply(train_mat, 2, min, na.rm = TRUE))
+    above <- any(px > apply(train_mat, 2, max, na.rm = TRUE))
+    if (below || above) {
+      # NT1 score: negative, proportional to extent of extrapolation
+      return(-1 * max(abs(px_s) - apply(abs(tr_s), 2, max)))
+    }
+    # NT2: Mahalanobis-based combinatorial novelty
+    mah_px  <- t(px - mu) %*% S_inv %*% (px - mu)
+    mah_ref <- median(apply(train_mat, 1, function(r) t(r - mu) %*% S_inv %*% (r - mu)))
+    return(as.numeric(mah_ref / mah_px))
+  })
+}
+```
+
+---
+
+## 4. MESS — Multivariate Environmental Similarity Surfaces
+
+**Package:** `dismo` (R)
+
+**Reference:** Elith et al. 2010. The art of modelling range-shifting species.
+*Methods in Ecology and Evolution* 1: 330–342.
+DOI: [10.1111/j.2041-210X.2010.00036.x](https://doi.org/10.1111/j.2041-210X.2010.00036.x)
+
+### What MESS measures
+
+MESS computes a similarity score for each projection pixel relative to the
+calibration reference set. Negative MESS values indicate novel environments.
+
+```r
+suppressPackageStartupMessages(library(dismo))
+suppressPackageStartupMessages(library(terra))
+
+# Reference points from calibration area
+ref_pts <- as.data.frame(train_stack, na.rm = TRUE)
+
+# MESS calculation
+mess_rast <- mess(proj_stack, ref_pts, full = FALSE)
+```
+
+- **MESS > 0:** similar to calibration set
+- **MESS = 0:** boundary of calibration range
+- **MESS < 0:** novel environment; magnitude indicates degree of novelty
+
+---
+
+## 5. Comparative Summary
+
+| Method | What it detects | Scale | Distinguishes NT1/NT2 | R package | Java needed |
+|---|---|---|---|---|---|
+| **MOP** | Overall proximity to calibration cloud | 0–1 (continuous) | No | `terra` (custom) | No |
+| **ExDet** | Univariate (NT1) and combinatorial (NT2) extrapolation | Continuous (negative=NT1, 0–1=NT2) | Yes | Custom / `ntbox` | No |
+| **MESS** | Multivariate similarity | Continuous (negative=novel) | No | `dismo` | No |
+
+**Recommendation for publication:**
+- **Minimum:** always compute MOP; mask MOP = 0 pixels in figures
+- **Recommended:** compute MESS alongside MOP for independent confirmation
+- **Full analysis:** use ExDet to distinguish NT1 from NT2 when many predictors exceed range
+
+---
+
+## 6. Practical Recommendations
+
+1. **Always run MOP before interpreting future projections.** Do not publish
+   suitability maps without showing MOP alongside them.
+2. **Mask MOP = 0 pixels in publication figures.** Use `terra::mask()` with the
+   MOP layer thresholded at 0.
+3. **Report the % of projection area with MOP < 0.25** in the methods section.
+4. If > 30% of the area has MOP < 0.25, add an explicit caveat in the abstract
+   or results section.
+5. For climate change projections, MOP to future periods tends to increase with
+   more extreme SSPs and longer time horizons — always report SSP-specific MOP.
+
+### Concern thresholds
+
+| % area with MOP < 0.25 | Recommended action |
+|---|---|
+| < 10% | Note in methods, no figure modification needed |
+| 10–30% | Report in results; add caption noting extrapolation zones |
+| 30–50% | Mask those pixels in primary figure; show MOP map in supplement |
+| > 50% | Strong caveat in abstract; consider restricting projection area |
+
+---
+
+## 7. Common Pitfalls
+
+- **Ignoring MOP entirely:** projecting to future SSP5-8.5 without any novelty
+  assessment is a major reviewer concern and methodological flaw.
+- **Confusing MESS negative values with unsuitable habitat:** MESS < 0 means
+  *novel environment*, not predicted *absence*. These are independent signals.
+- **Using only one method:** MOP and MESS are complementary; using both strengthens
+  the analysis.
+- **Not separating NT1 from NT2 when temperatures exceed calibration range:** for
+  climate change projections where temperature strictly exceeds historical range,
+  NT1 extrapolation is certain — ExDet makes this explicit.
+- **Masking too aggressively:** masking all MOP < 0.5 may remove large fractions
+  of a species' current range. Use MOP = 0 as the primary mask.
+
+---
+
+## 8. References
+
+| Citation | DOI |
+|---|---|
+| Owens et al. 2013. Ecol. Model. 263:10–18 | [10.1016/j.ecolmodel.2013.04.011](https://doi.org/10.1016/j.ecolmodel.2013.04.011) |
+| Mesgaran et al. 2014. Div. Dist. 20:1147–1159 | [10.1111/ddi.12209](https://doi.org/10.1111/ddi.12209) |
+| Elith et al. 2010. Meth. Ecol. Evol. 1:330–342 | [10.1111/j.2041-210X.2010.00036.x](https://doi.org/10.1111/j.2041-210X.2010.00036.x) |
+| Peterson et al. 2011. Ecological Niches and Geographic Distributions. Princeton UP | ISBN 978-0691136882 |

package/skills/model-validation-and-uncertainty/resources/metric-selection-guide.md

@@ -0,0 +1,52 @@
+# Model Performance Metric Selection Guide
+
+## Binary Classification (Presence/Absence, SDMs)
+
+| Metric | Range | Better | Notes |
+|--------|-------|--------|-------|
+| AUC-ROC | 0–1 | Higher | Threshold-independent. 0.7 = acceptable, 0.8 = good, 0.9 = excellent. Inflated for large bg samples. |
+| TSS (True Skill Statistic) | -1 to 1 | Higher | Threshold-dependent. TSS = Sensitivity + Specificity − 1. 0.4 = acceptable, 0.6 = good. |
+| Boyce Index | -1 to 1 | Higher → 1 | Presence-only metric. Preferred over AUC for presence-background models. |
+| Kappa | 0–1 | Higher | Prevalence-sensitive; avoid for imbalanced datasets. |
+| Brier Score | 0–1 | Lower | Mean squared error of predicted probabilities. Good calibration metric. |
+| Sensitivity (Recall) | 0–1 | Higher | True positive rate. Critical when false negatives are costly. |
+| Specificity | 0–1 | Higher | True negative rate. |
+| F1 Score | 0–1 | Higher | Harmonic mean of precision and recall. Good for imbalanced classes. |
+
+**Recommendation for SDMs:** Report AUC + TSS + Boyce index. Use Boyce as primary for presence-background.
+
+## Regression (Abundance, Biomass, NDVI)
+
+| Metric | Formula | Notes |
+|--------|---------|-------|
+| RMSE | √(mean((obs−pred)²)) | Same units as response. Lower is better. |
+| MAE | mean(|obs−pred|) | Robust to outliers. Lower is better. |
+| R² | 1 − SS_res/SS_tot | Proportion variance explained. Higher is better. |
+| Bias | mean(pred−obs) | Systematic over/underestimation. Should be ≈ 0. |
+| MAPE | mean(|obs−pred|/obs) × 100 | Percentage error. Problematic when obs ≈ 0. |
+
+## Count / Poisson Models
+
+| Metric | Notes |
+|--------|-------|
+| Pseudo-R² (McFadden) | 1 − (logL_model / logL_null). > 0.2 = good fit. |
+| Pearson dispersion | Sum(pearson²) / df. Should be ≈ 1 for well-fitted Poisson. |
+| DHARMa KS test | Uniformity of randomised quantile residuals. |
+
+## Occupancy Models
+
+| Metric | Notes |
+|--------|-------|
+| AUC (if binary) | Applied to site-level occupancy predictions |
+| MacKenzie-Bailey χ² | Goodness-of-fit via parametric bootstrap |
+| ĉ (c-hat) | Overdispersion factor. If > 1.5, use QAICc. |
+| WAIC | For Bayesian occupancy models |
+
+## Reporting Template
+
+Always report as: **metric (train / CV / test)**
+
+Example:
+> AUC = 0.91 (train) / 0.84 (spatial CV, 5-fold) / 0.82 (independent test)
+> TSS = 0.78 (train) / 0.67 (CV) / 0.65 (test)
+> Boyce Index = 0.93 (test)

package/skills/model-validation-and-uncertainty/resources/threshold-selection-guide.md

@@ -0,0 +1,64 @@
+# Threshold Selection Guide for Binary Predictions
+
+## Why Threshold Selection Matters
+
+SDMs and classifiers produce continuous suitability/probability values. A threshold converts these to binary predictions (suitable/not suitable, present/absent). The choice of threshold directly affects the area predicted suitable and the balance of errors.
+
+## Common Methods
+
+### 1. Maximum TSS (Youden's J) — **Recommended general default**
+- Threshold that maximises Sensitivity + Specificity − 1
+- Balanced between omission and commission errors
+- Not sensitive to prevalence
+
+```r
+library(PresenceAbsence)
+opt_thresh <- optimal.thresholds(
+  DATA = data.frame(plotID = 1:nrow(val), obs = val$observed, pred = val$predicted),
+  threshold = 101,
+  which.model = 1,
+  opt.methods = "MaxKappa"  # or "MaxTSS"
+)
+```
+
+### 2. Equal Sensitivity and Specificity
+- Threshold where Sensitivity = Specificity
+- Good when false positives and false negatives have equal cost
+
+### 3. Minimum Training Presence (MTP)
+- Threshold below which no training presence falls (0th percentile of training scores)
+- Very permissive (large suitable area); good for detecting all potential habitat
+- Use when false negatives are very costly (conservation planning)
+
+### 4. 10th Percentile Training Presence (P10)
+- Threshold below which 10% of training presences fall
+- Slightly more restrictive than MTP; removes poorly-surveyed sites
+- Standard in MaxEnt studies
+
+### 5. Fixed Prevalence Threshold
+- Set threshold to match the observed prevalence in the dataset
+- Appropriate when calibration data have known representative prevalence
+
+## Decision Guide
+
+```
+Primary goal is conservation planning (find all habitat)?
+  → Use MTP or P10 (low omission error)
+
+Primary goal is invasive species management (restrict false positives)?
+  → Use Maximum TSS or Equal Sensitivity/Specificity
+
+Publishing an SDM study (general)?
+  → Report results at both MaxTSS and P10 thresholds
+
+Comparing multiple species / scenarios?
+  → Use a consistent, a priori defined threshold for all
+```
+
+## Reporting Requirements
+
+Always report:
+- Threshold value used (e.g., 0.42)
+- Method used to select it
+- Resulting sensitivity, specificity, and TSS at that threshold
+- Area predicted suitable (km²) above threshold

package/skills/model-validation-and-uncertainty/scripts/extrapolation_risk.R

@@ -0,0 +1,315 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript extrapolation_risk.R <training_raster_stack.tif> <projection_raster_stack.tif> <output_dir>
+#
+# Arguments:
+#   training_raster_stack.tif   : Multi-band GeoTIFF used for model calibration
+#   projection_raster_stack.tif : Multi-band GeoTIFF for the projection area/period
+#   output_dir                  : Directory for outputs (created if absent)
+#
+# Outputs:
+#   mop_layer.tif              — MOP raster (0 = strict extrapolation, 1 = fully within range)
+#   mess_layer.tif             — MESS raster (negative = novel environment)
+#   extrapolation_summary.csv  — Summary statistics (% area per threshold)
+#   extrapolation_plots.png    — Side-by-side MOP and MESS maps
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "model-validation-and-uncertainty"
+.log_ts  <- function() format(Sys.time(), "[%Y-%m-%d %H:%M:%S]")
+log_info <- function(...) message(.log_ts(), " [INFO]  ", sprintf(...))
+log_warn <- function(...) message(.log_ts(), " [WARN]  ", sprintf(...))
+log_error<- function(...) message(.log_ts(), " [ERROR] ", sprintf(...))
+log_step <- function(n, d) log_info("-- STEP %d: %s", n, d)
+log_decision <- function(v, val, why) log_info("DECISION | %s = %s | %s", v, val, why)
+dir.create("logs", recursive=TRUE, showWarnings=FALSE)
+
+suppressPackageStartupMessages(library(terra))
+suppressPackageStartupMessages(library(dismo))
+suppressPackageStartupMessages(library(ggplot2))
+
+# ── 1. Parse arguments ──────────────────────────────────────────────────────
+log_step(1, "Parse arguments and validate inputs")
+args <- commandArgs(trailingOnly = TRUE)
+
+if (length(args) < 3) {
+  log_warn("Fewer than 3 arguments provided. Using default paths for testing.")
+  train_path  <- "data/predictors/env_train.tif"
+  proj_path   <- "data/predictors/env_proj.tif"
+  output_dir  <- "output/extrapolation"
+} else {
+  train_path  <- args[1]
+  proj_path   <- args[2]
+  output_dir  <- args[3]
+}
+
+log_decision("train_path", train_path, "raster stack used for model calibration")
+log_decision("proj_path",  proj_path,  "raster stack for the projection area/period")
+
+if (!file.exists(train_path)) {
+  log_error(
+    "Falha em validate inputs: raster de treinamento nao encontrado: %s\nCausa provavel: caminho incorreto ou arquivo GeoTIFF nao gerado\nVerifique: o argumento training_raster_stack.tif e o diretorio de trabalho\nSkill anterior: species-distribution-modelling",
+    train_path
+  )
+  stop("Training raster not found.")
+}
+if (!file.exists(proj_path)) {
+  log_error(
+    "Falha em validate inputs: raster de projecao nao encontrado: %s\nCausa provavel: caminho incorreto ou arquivo GeoTIFF nao gerado\nVerifique: o argumento projection_raster_stack.tif e o diretorio de trabalho\nSkill anterior: species-distribution-modelling",
+    proj_path
+  )
+  stop("Projection raster not found.")
+}
+
+# ── 2. Create output directory ───────────────────────────────────────────────
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+# ── 3. Load raster stacks ────────────────────────────────────────────────────
+log_step(2, "Load raster stacks")
+tryCatch({
+  log_info("Loading training stack: %s", train_path)
+  train_stack <- rast(train_path)
+
+  log_info("Loading projection stack: %s", proj_path)
+  proj_stack  <- rast(proj_path)
+}, error = function(e) {
+  log_error(
+    "Falha em load rasters: %s\nCausa provavel: arquivo GeoTIFF corrompido ou formato nao suportado\nVerifique: integridade dos arquivos TIF com gdalinfo\nSkill anterior: species-distribution-modelling",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# Validate that both stacks have the same layers
+if (!setequal(names(train_stack), names(proj_stack))) {
+  mismatched <- setdiff(names(train_stack), names(proj_stack))
+  log_error(
+    "Falha em validate layers: nomes de camadas divergem entre stacks de treinamento e projecao.\nCamadas ausentes na projecao: %s\nCausa provavel: stacks gerados com variaveis diferentes\nVerifique: que ambos os TIFs tem as mesmas bandas nomeadas\nSkill anterior: species-distribution-modelling",
+    paste(mismatched, collapse = ", ")
+  )
+  stop("Layer name mismatch between training and projection stacks.\n  Missing in projection: ",
+       paste(mismatched, collapse = ", "))
+}
+
+# Reorder projection layers to match training layer order
+proj_stack <- proj_stack[[names(train_stack)]]
+n_vars <- nlyr(train_stack)
+log_info("Variables (%d): %s", n_vars, paste(names(train_stack), collapse = ", "))
+
+# ── 4. Extract calibration reference values ──────────────────────────────────
+log_step(3, "Extract calibration reference values")
+tryCatch({
+  cal_vals <- as.data.frame(train_stack, na.rm = TRUE)
+  log_info("Calibration pixels extracted: %d", nrow(cal_vals))
+
+  if (nrow(cal_vals) < 100) {
+    log_warn("Only %d non-NA calibration pixels. MOP estimates may be unstable.", nrow(cal_vals))
+  }
+
+  # Scale calibration values for MOP distance computation
+  cal_center <- colMeans(cal_vals, na.rm = TRUE)
+  cal_sd     <- apply(cal_vals, 2, sd, na.rm = TRUE)
+
+  zero_sd_vars <- names(cal_sd)[cal_sd == 0]
+  if (length(zero_sd_vars) > 0) {
+    log_warn("Variables with zero variance (will be set to sd=1): %s", paste(zero_sd_vars, collapse = ", "))
+  }
+
+  # Replace zero sd with 1 to avoid division by zero
+  cal_sd[cal_sd == 0] <- 1
+
+  cal_scaled <- scale(cal_vals, center = cal_center, scale = cal_sd)
+  n_cal      <- nrow(cal_scaled)
+  log_decision("mop_scaling", "z-score using calibration mean/sd", "ensures all variables contribute equally to Euclidean distance")
+}, error = function(e) {
+  log_error(
+    "Falha em extract calibration values: %s\nCausa provavel: raster de treinamento com todos os pixels NA\nVerifique: mascara e extent do raster de treinamento\nSkill anterior: species-distribution-modelling",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 5. Compute MOP (Mobility-Oriented Parity) ────────────────────────────────
+# Reference: Owens et al. 2013. Ecol. Model. 263:10-18.
+# DOI: 10.1016/j.ecolmodel.2013.04.011
+#
+# For each projection pixel, MOP = proportion of calibration points that are
+# "closer" (in standardised Euclidean space) than the projection pixel.
+# MOP = 0 means the pixel is beyond ALL calibration points — strict extrapolation.
+
+log_step(4, "Compute MOP layer (Owens et al. 2013)")
+log_decision("mop_percentile", "10th percentile of pixel-to-calibration distances", "standard implementation following Owens et al. 2013")
+tryCatch({
+  log_info("Computing MOP layer (this may take a few minutes)...")
+
+  # Compute the centroid distance of each calibration point
+  cal_centroid_dist <- sqrt(rowSums(cal_scaled^2))
+
+  # Apply MOP computation pixel by pixel using terra::app
+  proj_vals <- as.data.frame(proj_stack, na.rm = FALSE, xy = TRUE)
+  xy_cols   <- c("x", "y")
+  env_cols  <- setdiff(names(proj_vals), xy_cols)
+
+  mop_compute <- function(px_env) {
+    if (any(is.na(px_env))) return(NA_real_)
+
+    # Scale projection pixel using calibration parameters
+    px_scaled <- (as.numeric(px_env) - cal_center) / cal_sd
+
+    # Euclidean distance from this pixel to every calibration point
+    d_px_to_cal <- sqrt(rowSums(sweep(cal_scaled, 2, px_scaled, "-")^2))
+
+    # MOP = proportion of calibration points whose centroid distance
+    # is less than the 10th percentile of distances from this pixel
+    ref_dist <- quantile(d_px_to_cal, 0.1)
+    sum(cal_centroid_dist < ref_dist) / n_cal
+  }
+
+  mop_vals <- apply(proj_vals[, env_cols], 1, mop_compute)
+
+  # Reconstruct as SpatRaster
+  mop_rast        <- rast(proj_stack[[1]])
+  values(mop_rast) <- NA
+  # Map back to all pixels (including those with NA that were skipped)
+  full_vals                                <- rep(NA_real_, ncell(mop_rast))
+  non_na_idx                               <- which(!is.na(values(proj_stack[[1]])))
+  full_vals[non_na_idx[seq_along(mop_vals)]] <- mop_vals
+  values(mop_rast) <- full_vals
+  names(mop_rast)  <- "MOP"
+
+  # Save MOP raster
+  mop_path <- file.path(output_dir, "mop_layer.tif")
+  writeRaster(mop_rast, mop_path, overwrite = TRUE)
+  log_info("Saved: %s", mop_path)
+}, error = function(e) {
+  log_error(
+    "Falha em MOP computation: %s\nCausa provavel: memoria insuficiente para rasters grandes ou valores NA inesperados\nVerifique: tamanho do raster de projecao e memoria disponivel\nSkill anterior: model-validation-and-uncertainty (calibration extraction)",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 6. Compute MESS (Multivariate Environmental Similarity Surfaces) ─────────
+# Reference: Elith et al. 2010. Meth. Ecol. Evol. 1:330-342.
+# DOI: 10.1111/j.2041-210X.2010.00036.x
+#
+# MESS < 0 indicates novel environment relative to calibration reference set.
+
+log_step(5, "Compute MESS layer (Elith et al. 2010)")
+tryCatch({
+  log_info("Computing MESS layer...")
+
+  # dismo::mess requires a RasterStack (terra → raster conversion for compatibility)
+  suppressPackageStartupMessages(library(raster))
+  proj_raster <- raster::stack(proj_stack)
+  train_df    <- cal_vals  # reference points
+
+  mess_result <- dismo::mess(proj_raster, train_df, full = FALSE)
+
+  # Convert back to terra SpatRaster
+  mess_rast  <- rast(mess_result)
+  names(mess_rast) <- "MESS"
+
+  # Save MESS raster
+  mess_path <- file.path(output_dir, "mess_layer.tif")
+  writeRaster(mess_rast, mess_path, overwrite = TRUE)
+  log_info("Saved: %s", mess_path)
+}, error = function(e) {
+  log_error(
+    "Falha em MESS computation: %s\nCausa provavel: incompatibilidade entre pacotes terra/raster ou raster sem CRS\nVerifique: versoes de terra e dismo, e que os rasters tem CRS definido\nSkill anterior: model-validation-and-uncertainty (calibration extraction)",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 7. Compute summary statistics ────────────────────────────────────────────
+log_step(6, "Compute extrapolation summary statistics")
+tryCatch({
+  mop_v  <- values(mop_rast,  na.rm = TRUE)
+  mess_v <- values(mess_rast, na.rm = TRUE)
+  n_proj <- length(mop_v)
+
+  pct_mop_zero <- round(100 * sum(mop_v == 0,     na.rm = TRUE) / n_proj, 2)
+  pct_mop_025  <- round(100 * sum(mop_v < 0.25,   na.rm = TRUE) / n_proj, 2)
+  pct_mop_050  <- round(100 * sum(mop_v < 0.50,   na.rm = TRUE) / n_proj, 2)
+  pct_mess_neg <- round(100 * sum(mess_v < 0,      na.rm = TRUE) / length(mess_v[!is.na(mess_v)]), 2)
+
+  summary_df <- data.frame(
+    metric = c("pct_area_MOP_zero",
+               "pct_area_MOP_lt_0.25",
+               "pct_area_MOP_lt_0.50",
+               "pct_area_MESS_negative"),
+    value  = c(pct_mop_zero, pct_mop_025, pct_mop_050, pct_mess_neg),
+    interpretation = c(
+      "Strict extrapolation (MOP = 0)",
+      "High novelty (MOP < 0.25)",
+      "Moderate-high novelty (MOP < 0.50)",
+      "Novel environment in MESS (MESS < 0)"
+    )
+  )
+
+  csv_path <- file.path(output_dir, "extrapolation_summary.csv")
+  write.csv(summary_df, csv_path, row.names = FALSE)
+  log_info("Saved: %s", csv_path)
+}, error = function(e) {
+  log_error(
+    "Falha em summary statistics: %s\nCausa provavel: rasters MOP ou MESS invalidos\nVerifique: etapas anteriores para mensagens de erro\nSkill anterior: model-validation-and-uncertainty (MOP/MESS computation)",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 8. Automatic warning if extrapolation is severe ──────────────────────────
+if (pct_mop_025 > 30) {
+  log_warn(
+    "EXTRAPOLATION WARNING: %.1f%% of the projection area has MOP < 0.25 (high novelty relative to calibration). Predictions in these areas should be treated with extreme caution. Recommendation: mask MOP < 0.25 pixels in publication figures and add explicit caveats in the methods section.",
+    pct_mop_025
+  )
+}
+
+if (pct_mop_zero > 10) {
+  log_warn(
+    "STRICT EXTRAPOLATION WARNING: %.1f%% of the projection area has MOP = 0 (model extrapolates beyond all calibration data). These pixels MUST be masked in publication figures.",
+    pct_mop_zero
+  )
+}
+
+# ── 9. Side-by-side diagnostic plots ─────────────────────────────────────────
+log_step(7, "Generate extrapolation diagnostic plots")
+tryCatch({
+  png(file.path(output_dir, "extrapolation_plots.png"),
+      width = 1600, height = 700, res = 150)
+  par(mfrow = c(1, 2), mar = c(4, 4, 3, 5))
+
+  # MOP map
+  plot(mop_rast, main = "MOP (0 = strict extrapolation)",
+       col = rev(terrain.colors(100)),
+       legend = TRUE, axes = FALSE)
+  mtext(paste0("MOP = 0: ", pct_mop_zero, "% | MOP < 0.25: ", pct_mop_025, "%"),
+        side = 1, cex = 0.8)
+
+  # MESS map (diverging palette: red = novel, blue = similar)
+  mess_cols <- colorRampPalette(c("red", "white", "steelblue"))(100)
+  plot(mess_rast, main = "MESS (negative = novel environment)",
+       col = mess_cols,
+       legend = TRUE, axes = FALSE)
+  mtext(paste0("MESS < 0: ", pct_mess_neg, "%"),
+        side = 1, cex = 0.8)
+
+  dev.off()
+  log_info("Saved: %s", file.path(output_dir, "extrapolation_plots.png"))
+}, error = function(e) {
+  log_error(
+    "Falha em diagnostic plots: %s\nCausa provavel: dispositivo grafico nao disponivel ou rasters invalidos\nVerifique: disponibilidade de X11/display e integridade dos rasters\nSkill anterior: model-validation-and-uncertainty (MOP/MESS computation)",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 10. Final summary ─────────────────────────────────────────────────────────
+log_info("========== EXTRAPOLATION SUMMARY ==========")
+log_info("%% area MOP = 0    (strict extrapolation): %.2f%%", pct_mop_zero)
+log_info("%% area MOP < 0.25 (high novelty)        : %.2f%%", pct_mop_025)
+log_info("%% area MOP < 0.50 (moderate novelty)    : %.2f%%", pct_mop_050)
+log_info("%% area MESS < 0   (novel environment)   : %.2f%%", pct_mess_neg)
+log_info("===========================================")