ecological-agent-skills 3.1.0

package/skills/species-distribution-modeling/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: species-distribution-modeling
+description: "Runs the complete species distribution modeling (SDM/ENM) pipeline: occurrence preparation, model fitting (MaxEnt, ensemble), thresholding, projection under climate scenarios, and interpretation. Use this skill when the user mentions habitat suitability, niche modeling, MaxEnt, biomod2, potential distribution, range maps, suitable area mapping, climate projections, invasion risk, range shift analysis, suitability mapping, ENM, ecological niche model, or calibration area definition."
+skill_version: 1.0.0
+---
+
+# Skill: species-distribution-modeling
+
+**Domain:** SDM · ENM · MaxEnt · Ensemble · Projection  
+**Phase:** 2 — Modeling  
+**Used by:** run-sdm-study
+
+---
+
+## Purpose
+
+Guides the agent through the complete species distribution / ecological niche modeling pipeline: from occurrence and predictor preparation to model fitting, ensemble building, thresholding, projection, and interpretation.
+
+---
+
+## When to Invoke
+
+- Modeling the potential or realised distribution of one or more species
+- Projecting distributions under climate or land-use scenarios
+- Comparing niche overlap between taxa or time periods
+- Assessing invasion risk or connectivity
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Occurrence records (cleaned) | CSV with lat/lon | Yes |
+| Environmental predictor stack | GeoTIFF (multiband or stack) | Yes |
+| Study area / calibration area | SHP, GPKG | Yes |
+| Future/alternative scenario rasters | GeoTIFF | Optional |
+| Background / pseudo-absence points | CSV | Optional |
+
+---
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `suitability_current.tif` | Continuous suitability map (current) |
+| `suitability_binary.tif` | Thresholded binary map |
+| `suitability_scenarios/` | Projected maps per scenario |
+| `ensemble_sd.tif` | Uncertainty (SD across algorithms) |
+| `variable_importance.csv` | Predictor contributions |
+| `response_curves.png` | Marginal response per predictor |
+| `sdm_report.md` | Full methodological narrative |
+
+---
+
+## Steps
+
+### 1. Occurrence Curation
+- Apply spatial thinning to reduce sampling bias (minimum distance = target resolution)
+- Split into calibration and evaluation partitions using spatial blocks
+- Report final occurrence count after thinning
+
+### 2. Background / Pseudo-absence Sampling
+- Sample background within the calibration area (or a bias-corrected version)
+- Ratio: 1:1 to 1:10 (occurrences : background); document choice
+- For pseudo-absence methods: apply geographic or environmental constraints
+
+### 3. Predictor Selection
+- Apply `predictive-modeling-best-practices` skill for collinearity reduction
+- Prefer ecologically justified predictor subsets over data-driven selection alone
+- Document final predictor set and sources
+
+### 4. Algorithm Selection
+- Run minimum 3 algorithms for ensemble:
+  - MaxEnt (presence-background)
+  - BRT / GBM (presence-absence or presence-background)
+  - Random Forest
+  - GLM (baseline)
+- Additional: SVM, ANN, GAM as needed
+
+### 5. Model Fitting and Tuning
+- Tune regularisation/complexity per algorithm using spatial CV
+- Store all tuned model objects and parameters
+
+### 6. Ensemble Building
+- Combine algorithms using weighted average (weights = TSS or AUC per algorithm)
+- Report ensemble weights
+- Compute ensemble SD as uncertainty layer
+
+### 7. Thresholding
+- Apply chosen threshold to produce binary map
+- Report area predicted suitable (km²) above threshold
+
+### 8. Projection
+- Project ensemble to future/alternative scenarios
+- Mask extrapolation areas (MESS or ExDet) to flag novel environments
+- Report change in suitable area between current and projected
+
+### 9. Interpretation
+- Identify the 3 most important predictors
+- Describe response curve shapes in ecological terms
+- Flag any ecologically implausible responses
+- Discuss model limitations and transferability
+
+---
+
+## Key Decisions to Document
+
+- Spatial thinning distance
+- Calibration area definition method
+- Background sampling strategy
+- Algorithm set and tuning ranges
+- Ensemble weighting method
+- Threshold selection method
+- MESS/ExDet extrapolation masking
+
+---
+
+## Tools and Libraries
+
+**R:** `biomod2`, `ENMeval`, `dismo`, `maxnet`, `sdm`, `kuenm`  
+**Python:** `elapid`, `pysdm`, `sklearn`
+
+---
+
+## Resources
+
+- `resources/sdm-checklist.md` — SDM reporting checklist (based on ODMAP protocol)
+- `resources/calibration-area-guide.md` — M area selection methods
+- `resources/algorithm-comparison.md` — algorithm strengths and limitations
+- `examples/sdm/` — full worked example
+
+---
+
+## Notes
+
+- Follow the ODMAP (Overview of Data and Methods in Presence-Absence Modeling) reporting standard
+- Always mask predictions to the calibration area unless explicitly projecting to novel regions
+- Climate projections should use multiple GCMs and report uncertainty across models

package/skills/species-distribution-modeling/examples/example-prompts.md

@@ -0,0 +1,36 @@
+# Example Invocation Prompts — species-distribution-modeling
+
+## Full SDM Pipeline
+
+```
+Load skill: species-distribution-modeling
+Task: Build a habitat suitability model for Panthera onca in the Amazon biome.
+
+Inputs:
+  - Occurrences: data/processed/data_clean.csv (n = 523 after cleaning)
+  - Predictors: data/predictors_stack.tif (bio1, bio4, bio12, bio15, NDVI, slope — 6 vars, collinearity checked)
+  - Calibration area: data/spatial/amazon_buffered.shp
+  - Background: 10,000 points sampled within calibration area
+
+Steps:
+  1. Spatial thinning: 10 km minimum distance
+  2. Spatial CV: 5 blocks (blockCV, block size = 300 km)
+  3. Algorithms: MaxEnt (maxnet), BRT (gbm), Random Forest
+  4. Ensemble: weighted average by TSS score per algorithm
+  5. Threshold: MaxTSS and P10
+  6. Uncertainty: SD across algorithms
+
+Output: suitability_current.tif, suitability_binary.tif, variable_importance.csv, response_curves.png, sdm_report.md
+```
+
+## Projection to 2050
+
+```
+Load skill: species-distribution-modeling
+Task: Project the fitted jaguar SDM to 2050 conditions.
+Scenario rasters: data/predictors_2050_ssp245/ (same variable names as current stack)
+Calibration area: data/spatial/amazon_buffered.shp
+Apply MESS mask to flag areas outside training range.
+Compute change in suitable area (km²) between current and 2050.
+Output: suitability_2050_ssp245.tif, mess_mask.tif, change_summary.csv
+```

package/skills/species-distribution-modeling/resources/algorithm-comparison.md

@@ -0,0 +1,25 @@
+# SDM Algorithm Comparison
+
+| Algorithm | Type | Presence data | Absence needed | Overfitting risk | Extrapolation | Interpretability |
+|-----------|------|--------------|----------------|-----------------|---------------|-----------------|
+| MaxEnt | ML (max entropy) | Presence-background | No | Moderate | Poor (clamping) | Moderate |
+| BRT/GBM | Ensemble tree | PA or PB | Recommended | High if untuned | Poor | Moderate |
+| Random Forest | Ensemble tree | PA or PB | Recommended | Low–moderate | Poor | Low |
+| GLM | Statistical | PA | Yes | Low | Good | High |
+| GAM | Statistical | PA | Yes | Moderate | Good | High |
+| BIOCLIM | Envelope | Presence only | No | Low | Poor | High |
+| Mahalanobis | Distance | Presence only | No | Low | Moderate | High |
+| SVM | ML | PA or PB | Recommended | Moderate | Moderate | Low |
+| ANN / MLP | Deep learning | PA | Recommended | Very high | Poor | Very low |
+
+## Recommendations by Context
+
+| Context | Recommended algorithms |
+|---------|----------------------|
+| Presence-only data only | MaxEnt + BIOCLIM (ensemble) |
+| < 50 occurrences | MaxEnt + GLM (regularised) |
+| 50–200 occurrences | MaxEnt + BRT + GLM |
+| > 200 occurrences | BRT + RF + GLM + MaxEnt (full ensemble) |
+| Need for projection to novel climates | GLM + GAM (better extrapolation) |
+| Regulatory / conservation decision | Minimum 3 algorithms in ensemble |
+| Publication | Ensemble ≥ 3 algorithms + uncertainty map |

package/skills/species-distribution-modeling/resources/calibration-area-guide.md

@@ -0,0 +1,71 @@
+# Calibration Area (M Area) Selection Guide
+
+The calibration area (M, accessible area, or training region) defines the geographic extent from which background or pseudo-absence points are sampled and within which the model is calibrated. It is one of the most consequential decisions in SDM.
+
+## Why M Matters
+
+- Background points sampled outside M misrepresent the environmental conditions available to the species
+- An M that is too large includes environments never accessible to the species → inflated model performance, incorrect niche characterisation
+- An M that is too small may omit accessible habitats → truncated niche, poor transferability
+
+## Common Delimitation Methods
+
+### 1. Biotic Region / Biome
+Use biogeographic boundaries (biome, ecoregion) that match the species' known biogeographic history.
+- **Best for:** Continental or regional studies with well-known biogeographic context
+- **R:** IBGE biome polygons, WWF Ecoregions (rnaturalearth)
+
+### 2. Minimum Convex Hull (MCP) + Buffer
+Convex hull around all occurrence points, expanded by a fixed buffer distance (e.g., 200–500 km).
+- **Best for:** Species with limited occurrence data; simple implementation
+- **Caution:** Can include barriers (oceans, mountain ranges) that limit dispersal
+
+```r
+library(sf)
+occ_sf <- st_as_sf(occ, coords = c("decimalLongitude","decimalLatitude"), crs = 4326)
+hull   <- st_convex_hull(st_union(occ_sf))
+M_area <- st_buffer(hull, dist = 200000)  # 200 km buffer
+```
+
+### 3. Dispersal Simulation (Circuitscape / BioModelos)
+Model the area reachable by the species over a defined time period given dispersal rate and landscape permeability.
+- **Best for:** Species with known dispersal capacity; connectivity studies
+
+### 4. Watershed / Drainage Basin (aquatic species)
+- **Best for:** Freshwater fish, invertebrates, plants with hydrological dispersal
+
+### 5. Political / Administrative Unit
+Use only when the species is genuinely limited to that unit (e.g., island endemics).
+- **Avoid for:** Most terrestrial species with cross-border ranges
+
+## Recommended Workflow
+
+1. Start with the known biome or ecoregion containing all occurrences
+2. Expand by one adjacent ecoregion or 200–500 km buffer to include accessible but unsampled habitats
+3. Clip to ecologically meaningful barriers (e.g., remove ocean from terrestrial species M)
+4. Verify that the background environment within M spans the full range of occurrence conditions (convex hull check in environmental space)
+
+## Environmental Space Check
+
+```r
+library(terra)
+env_bg   <- extract(predictor_stack, bg_points)
+env_occ  <- extract(predictor_stack, occ_points)
+
+# Check: are all occurrence environmental conditions within the background range?
+for (v in names(env_bg)) {
+  occ_range <- range(env_occ[[v]], na.rm = TRUE)
+  bg_range  <- range(env_bg[[v]], na.rm = TRUE)
+  cat(v, "| occ:", round(occ_range, 2),
+      "| bg:", round(bg_range, 2), "\n")
+}
+# If occ range exceeds bg range → M is too small for that variable
+```
+
+## Reporting
+
+Always report:
+- M delimitation method and rationale
+- Area of M in km²
+- Proportion of occurrences inside M (should be 100%)
+- Environmental coverage (does bg span all occurrence conditions?)

package/skills/species-distribution-modeling/resources/climate-scenario-preparation.md

@@ -0,0 +1,170 @@
+# Climate Scenario Preparation Guide
+
+Preparing future climate layers for SDM projection: sources, SSPs, time horizons, and pipeline.
+
+---
+
+## 1. Sources of Future Climate Data
+
+| Source | Resolution | SSPs available | Temporal coverage | Recommended for |
+|---|---|---|---|---|
+| **CHELSA-Future** | ~1 km (30 arc-sec) | SSP1-2.6, SSP3-7.0, SSP5-8.5 | 2041–2060, 2061–2080 | **Primary recommendation** — high resolution, bias-corrected |
+| **WorldClim v2.1 future** | ~18 km (10 arc-min) | SSP1-2.6, SSP2-4.5, SSP3-7.0, SSP5-8.5 | 2021–2040, 2041–2060, 2061–2080, 2081–2100 | Regional studies where 10-min resolution is acceptable |
+| **CMIP6 raw** | ~100 km (1°) | All SSPs from each GCM | Monthly, 1850–2100 | Research requiring specific GCM; requires statistical downscaling |
+| **TerraClimate** | ~4 km | N/A (historical only) | 1958–present | Historical baseline calibration |
+
+**Key reference:** Karger et al. 2017 (CHELSA v1). DOI: [10.1038/sdata.2017.122](https://doi.org/10.1038/sdata.2017.122)
+
+**Download portals:**
+- CHELSA: https://chelsa-climate.org/downloads/
+- WorldClim: https://worldclim.org/data/cmip6/cmip6climate.html
+
+---
+
+## 2. SSPs — Shared Socioeconomic Pathways
+
+| SSP | Common name | Radiative forcing (2100) | Temperature anomaly (°C, 2100) | When to use |
+|---|---|---|---|---|
+| **SSP1-2.6** | Optimistic / sustainability | 2.6 W/m² | ~1.8°C | Show "best case" scenario |
+| **SSP2-4.5** | Intermediate | 4.5 W/m² | ~2.7°C | **Always include** — most likely trajectory |
+| **SSP3-7.0** | Regional rivalry | 7.0 W/m² | ~3.6°C | Regional fragmentation scenarios |
+| **SSP5-8.5** | High emissions / fossil fuel | 8.5 W/m² | ~4.4°C | **Always include** — worst-case bound |
+
+**Minimum reporting standard:** Always include at least **SSP2-4.5** and **SSP5-8.5** to capture intermediate and worst-case trajectories. Including SSP1-2.6 (optimistic) is recommended to illustrate the conservation value of mitigation.
+
+---
+
+## 3. Standard Time Horizons
+
+| Label | Period | Commonly called |
+|---|---|---|
+| Near future | 2021–2040 | "2030" |
+| Mid-century | 2041–2060 | **"2050"** (most used) |
+| Late-century | 2061–2080 | **"2070"** (most used) |
+| End-of-century | 2081–2100 | "2100" |
+
+**Recommendation:** Report at minimum **2050** and **2070** for each SSP. This yields 4 projection scenarios minimum (SSP2-4.5 × 2050, SSP2-4.5 × 2070, SSP5-8.5 × 2050, SSP5-8.5 × 2070).
+
+---
+
+## 4. Mandatory Preparation Pipeline
+
+Follow these steps in order before passing any future layer to a model:
+
+### Step 1 — Download future layers
+Download the same set of bioclimatic/environmental variables that were selected
+during calibration. **Never add or remove variables between current and future.**
+
+```r
+# Example: listing CHELSA-Future files for a specific SSP and GCM
+# Files follow naming convention: CHELSA_{var}_2041-2060_{ssp}_{gcm}_V.2.1.tif
+chelsa_files <- list.files("data/chelsa_future/ssp585_2050/", pattern = "\\.tif$",
+                            full.names = TRUE)
+```
+
+### Step 2 — Reproject to calibration CRS
+
+```r
+suppressPackageStartupMessages(library(terra))
+
+# Load reference (calibration) stack
+ref_stack    <- rast("data/predictors/env_train.tif")
+future_stack <- rast(chelsa_files)
+
+# Reproject to match calibration CRS
+future_stack <- project(future_stack, crs(ref_stack), method = "bilinear")
+```
+
+### Step 3 — Clip and mask to projection area (G area)
+
+The projection area (G area) is typically the full study continent or biome.
+It must be the same for all SSPs and time periods.
+
+```r
+study_area <- vect("data/study_area/g_area.shp")
+future_stack <- crop(future_stack,   study_area)
+future_stack <- mask(future_stack,   study_area)
+```
+
+### Step 4 — Verify identical geometry with terra::compareGeom()
+
+This is **critical** — silent geometry mismatches cause wrong predictions.
+
+```r
+# compareGeom returns TRUE if extent, resolution, CRS all match
+if (!compareGeom(ref_stack, future_stack, stopOnError = FALSE)) {
+  # Resample to exactly match reference grid
+  future_stack <- resample(future_stack, ref_stack, method = "bilinear")
+
+  # Verify again
+  if (!compareGeom(ref_stack, future_stack, stopOnError = FALSE)) {
+    stop("Geometry mismatch persists after resampling. Check CRS and extent.")
+  }
+}
+message("Geometry check passed.")
+```
+
+### Step 5 — Verify layer names match calibration stack
+
+Layer name matching is **critical for maxnet and biomod2** — the model uses
+names to match predictors. A mismatch causes silent wrong variable assignment.
+
+```r
+# Check names
+ref_names    <- names(ref_stack)
+future_names <- names(future_stack)
+
+missing_in_future <- setdiff(ref_names, future_names)
+extra_in_future   <- setdiff(future_names, ref_names)
+
+if (length(missing_in_future) > 0) {
+  stop("Future stack is missing layers present in calibration: ",
+       paste(missing_in_future, collapse = ", "))
+}
+
+if (length(extra_in_future) > 0) {
+  message("Extra layers in future stack (will be dropped): ",
+          paste(extra_in_future, collapse = ", "))
+  future_stack <- future_stack[[ref_names]]  # subset to calibration variables
+}
+
+# Reorder to match calibration
+future_stack <- future_stack[[ref_names]]
+message("Layer names verified and ordered.")
+```
+
+---
+
+## 5. Quick-Reference Checklist
+
+| Step | Check | Status |
+|---|---|---|
+| Same variables as calibration | All bioclim variables identical | ☐ |
+| CRS matches calibration stack | `crs(future) == crs(train)` | ☐ |
+| Resolution matches | `res(future) == res(train)` | ☐ |
+| Extent matches after crop | `compareGeom()` returns TRUE | ☐ |
+| Layer names identical and in same order | `names(future) == names(train)` | ☐ |
+| Masked to G area polygon | `mask()` applied | ☐ |
+| Output file saved with SSP+year label | `future_stack_ssp585_2050.tif` | ☐ |
+
+---
+
+## 6. Common Errors
+
+- **Using different variables between current and future:** e.g., using bio1–bio5 for calibration but bio1–bio3 for future. This is an automatic error in maxnet.
+- **Not clipping to G area:** projecting to a wider area than intended inflates apparent suitable area and may increase extrapolation.
+- **Silent CRS incompatibilities:** `terra::project()` will reproject, but if you skip this step and the CRS differs by even the datum, predictions will be geographically offset.
+- **Using a different GCM for each SSP:** GCMs have different temperature sensitivities; using different GCMs per SSP conflates SSP and GCM effects. Use the same GCM(s) across all SSPs.
+- **Layer name mismatch after renaming:** CHELSA uses long names like `CHELSA_bio1_2041-2060_ssp585_MPI-ESM1-2-HR_V.2.1`; rename layers to match short names (`bio1`, `bio2`, …) immediately after loading.
+
+---
+
+## 7. References
+
+| Citation | DOI |
+|---|---|
+| Karger et al. 2017. Sci. Data 4:170122 (CHELSA) | [10.1038/sdata.2017.122](https://doi.org/10.1038/sdata.2017.122) |
+| Fick & Hijmans 2017. Int. J. Climatol. (WorldClim 2) | [10.1002/joc.5086](https://doi.org/10.1002/joc.5086) |
+| Eyring et al. 2016. Geosci. Model Dev. (CMIP6) | [10.5194/gmd-9-1937-2016](https://doi.org/10.5194/gmd-9-1937-2016) |
+| O'Neill et al. 2016. Geosci. Model Dev. (SSPs) | [10.5194/gmd-9-3461-2016](https://doi.org/10.5194/gmd-9-3461-2016) |
+| Zurell et al. 2020. Ecography (ODMAP) | [10.1111/ecog.04960](https://doi.org/10.1111/ecog.04960) |

package/skills/species-distribution-modeling/resources/maxent-calibration-guide.md

@@ -0,0 +1,211 @@
+# MaxEnt Calibration Guide
+
+Regularization, feature classes, model selection, and calibration grid for maxnet/ENMeval.
+
+---
+
+## 1. Regularization Multiplier (RM) and Feature Classes (FC)
+
+MaxEnt (and its R equivalent **maxnet**) controls model complexity through two parameters:
+
+### Regularization Multiplier (RM)
+
+RM penalises model complexity. Think of it as a smoothing parameter:
+
+| RM value | Effect |
+|---|---|
+| < 1 | Under-regularised — risk of **overfitting** (model memorises noise in occurrence data) |
+| 1 (default) | Often appropriate for large, clean datasets |
+| 1.5 – 2 | Recommended starting point for typical GBIF datasets |
+| 3 – 6 | High smoothing — appropriate for very small n, noisy data, or wide-ranging species |
+
+### Feature Classes (FC)
+
+FC determines which response curve shapes are available to the model:
+
+| FC code | Name | Response shape allowed | Risk |
+|---|---|---|---|
+| **L** | Linear | Monotonic linear relationship | Very simple; may underfit |
+| **Q** | Quadratic | Unimodal response (bell curve) | Good default for most ecological variables |
+| **H** | Hinge | Piecewise linear with breakpoint | Flexible; needs more data to fit reliably |
+| **P** | Product | Interactions between pairs of predictors | Can model synergies; risk of overfitting |
+| **T** | Threshold | Step function | Extreme flexibility; high overfitting risk |
+
+Combinations are additive: `LQ` allows both linear and quadratic features; `LQHPT` allows all five.
+
+**Typical recommendation:** Start with `LQ` or `LQH`; add `P` and `T` only with > 100 clean occurrences and only if AICc improves substantially.
+
+---
+
+## 2. Model Selection Criteria
+
+### Why AUC alone is insufficient
+
+AUC measures discrimination (can the model rank presences above absences?) but does **not**
+detect overfitting to the calibration area. A highly over-fitted model can have AUC = 0.99
+in calibration but fail completely in independent validation.
+
+### Recommended criteria (in priority order)
+
+| Criterion | What it measures | Threshold / rule |
+|---|---|---|
+| **OR10** (Omission Rate at 10%) | Whether the model omits 10% of training points at the selected threshold | Must be ≤ expected omission rate (0.10); lower is better |
+| **AICc** | Model complexity-penalised fit (Akaike Information Criterion, corrected) | Select model(s) with lowest AICc; models within delta_AICc < 2 are equivalent |
+| **Partial ROC** | AUC computed only over the biologically relevant part of the ROC curve | Ratio > 1 (compared to random); higher is better |
+| **AUC (train)** | Training set AUC | Supplementary only — not a selection criterion |
+
+**Peterson et al. 2008** showed that omission rate is a more ecologically meaningful
+criterion than AUC for evaluating niche model performance.
+DOI: [10.1016/j.ecolmodel.2007.11.008](https://doi.org/10.1016/j.ecolmodel.2007.11.008)
+
+**Warren & Seifert 2011** introduced the OR_AICc approach: select models with low
+omission rate AND low AICc to balance predictive accuracy and parsimony.
+DOI: [10.1890/10-1171.1](https://doi.org/10.1890/10-1171.1)
+
+### OR_AICc selection rule (recommended)
+
+1. Filter all models where `OR10 <= 0.10 + tolerance` (tolerance = 0.05 recommended)
+2. Among passing models, select those with `delta_AICc < 2`
+3. If multiple models pass, report ensemble or select the most parsimonious (fewest parameters)
+
+---
+
+## 3. Recommended Calibration Grid
+
+Use this 35-model grid as the default for `tune_maxnet.R`:
+
+```
+RM  = c(0.5, 1, 1.5, 2, 3, 4, 6)
+FC  = c("L", "LQ", "LQH", "LQHP", "LQHPT")
+```
+
+Total combinations: 7 × 5 = **35 models**
+
+For species with n_clean < 50, restrict to:
+```
+RM = c(1, 2, 3, 4, 6)
+FC = c("L", "LQ", "LQH")
+```
+
+---
+
+## 4. kuenm vs ENMeval + maxnet
+
+| Feature | kuenm (maxent.jar) | ENMeval + maxnet |
+|---|---|---|
+| Engine | MaxEnt Java `.jar` | maxnet (R-native, no Java) |
+| Java required | **Yes** | **No** |
+| CRAN installable | No (manual download) | **Yes** |
+| Calibration parallelism | Yes (via Java threads) | Yes (via `parallel` package) |
+| Output metrics | OR, AUC, AICc, pROC | OR, AUC, AICc |
+| Partial ROC | Built-in | Separate `ENMeval::eval.stats()` |
+| Reproducibility | Depends on MaxEnt version | Fully reproducible in R |
+| Recommended for this repo | No | **Yes** |
+
+**Why ENMeval in this repo:**
+- No Java dependency → simpler CI, reproducible environments
+- `maxnet` produces identical predictions to MaxEnt (Phillips et al. 2017)
+- `ENMeval >= 2.0` provides a standardised, tidy interface
+- Easily integrated with `terra` and `sf` pipelines
+
+---
+
+## 5. Interpreting Calibration Results
+
+### delta_AICc table
+
+```
+delta_AICc < 2     → Model is equivalent to best model; all are candidates
+delta_AICc 2–7     → Some support for this model; use with caution
+delta_AICc > 7     → Little to no support; exclude from ensemble
+```
+
+### Omission rate × AUC plot
+
+```
+Good model: low OR10 (y-axis) + high AUC (x-axis) → lower-right quadrant
+Overfitted: very low OR10 (memorised training data) + moderate validation AUC
+Underfitted: OR10 > 0.15 (misses known occurrences)
+```
+
+When reading the plot: **prioritise OR10 first, then AUC**. A model with OR10 = 0.08
+and AUC = 0.82 is better than OR10 = 0.02 and AUC = 0.91 (the latter is likely overfitted).
+
+### Quick-reference checklist
+
+| Check | Pass condition |
+|---|---|
+| OR10 ≤ 0.15 | Model does not severely omit known occurrences |
+| delta_AICc < 2 for selected model | Model is parsimonious |
+| Training AUC > 0.70 | Model performs above random |
+| No single FC dominates (e.g., all T features) | Model not over-complex |
+| Selected RM in middle of grid (not 0.5 or 6) | RM not at boundary — extend grid if needed |
+
+---
+
+## 6. R Code Example
+
+```r
+suppressPackageStartupMessages(library(ENMeval))
+suppressPackageStartupMessages(library(terra))
+
+# Load data
+occ  <- read.csv("tests/data/points_with_env.csv")
+env  <- rast("data/predictors/env_stack.tif")
+
+occ_pts  <- occ[, c("decimalLongitude", "decimalLatitude")]
+env_vals <- as.data.frame(extract(env, occ_pts))
+
+# Background points (10,000 random within study area)
+bg <- spatSample(env, size = 10000, method = "random",
+                 na.rm = TRUE, as.df = TRUE, xy = TRUE)
+bg_pts <- bg[, c("x", "y")]
+
+# Calibration grid
+eval_out <- ENMevaluate(
+  occs      = occ_pts,
+  envs      = env,
+  bg        = bg_pts,
+  algorithm = "maxnet",
+  partitions = "block",          # spatial cross-validation
+  tune.args  = list(
+    rm = c(0.5, 1, 1.5, 2, 3, 4, 6),
+    fc = c("L", "LQ", "LQH", "LQHP", "LQHPT")
+  )
+)
+
+# View results table
+res <- eval.results(eval_out)
+head(res[order(res$AICc), ])
+
+# Select best model by OR_AICc criterion
+best <- res[res$or.10p.avg <= 0.15 & res$delta.AICc < 2, ]
+```
+
+---
+
+## 7. Common Pitfalls
+
+- **RM too low (e.g., 0.5):** model memorises training localities; performs poorly in
+  independent validation. Symptom: very jagged, patchy suitability map.
+- **RM too high (e.g., 6):** model is overly smooth and may miss real habitat patches.
+  Symptom: very broad, featureless map regardless of species ecology.
+- **Using AUC as the sole selection criterion:** rewards discrimination but not calibration.
+  Always pair with OR10.
+- **Not running spatial CV:** random k-fold CV inflates AUC due to spatial autocorrelation.
+  Always use `partitions="block"` or `"checkerboard"` in ENMeval.
+- **Grid boundary effects:** if best RM is 0.5 or 6 (grid edges), extend the grid and re-run.
+- **Not checking layer names:** maxnet uses column names from the training data to match
+  projection layers. Mismatch causes silent errors or wrong predictions.
+
+---
+
+## 8. References
+
+| Citation | DOI |
+|---|---|
+| Peterson et al. 2008. Ecol. Model. 213: 63–72 | [10.1016/j.ecolmodel.2007.11.008](https://doi.org/10.1016/j.ecolmodel.2007.11.008) |
+| Warren & Seifert 2011. Ecol. Apps. 21: 335–342 | [10.1890/10-1171.1](https://doi.org/10.1890/10-1171.1) |
+| Phillips et al. 2017. Ecography 40: 913–922 (maxnet) | [10.1111/ecog.03049](https://doi.org/10.1111/ecog.03049) |
+| Muscarella et al. 2014. Meth. Ecol. Evol. (ENMeval v1) | [10.1111/2041-210X.12261](https://doi.org/10.1111/2041-210X.12261) |
+| Kass et al. 2021. Meth. Ecol. Evol. (ENMeval v2) | [10.1111/2041-210X.13628](https://doi.org/10.1111/2041-210X.13628) |