ecological-agent-skills 3.1.0 → 3.2.0

package/AGENT_CONTEXT.md

@@ -47,10 +47,17 @@ Each workflow lives at `workflows/<workflow-id>/WORKFLOW.md`.
 | **Environmental time series** | ecological-data-foundation | environmental-time-series | biostatistics-workbench | reproducible-ecology-pipeline | — |
 | **Ecosystem services** | ecological-data-foundation | geoprocessing-for-ecology | ecosystem-services-assessment | model-validation-and-uncertainty | reproducible-ecology-pipeline |
 | **Multispecies screening** | ecological-data-foundation | geoprocessing-for-ecology | species-distribution-modeling (loop) | model-validation-and-uncertainty | reproducible-ecology-pipeline |
+| **Acoustic monitoring** | ecological-data-foundation | acoustic-monitoring | biostatistics-workbench | model-validation-and-uncertainty | reproducible-ecology-pipeline |
+| **Camera trap occupancy** | ecological-data-foundation | camera-trap-processing | occupancy-and-detection | model-validation-and-uncertainty | reproducible-ecology-pipeline |
+| **Landscape connectivity** | ecological-data-foundation | geoprocessing-for-ecology | landscape-connectivity | model-validation-and-uncertainty | reproducible-ecology-pipeline |
+| **Population viability** | ecological-data-foundation | biostatistics-workbench | population-viability-analysis | model-validation-and-uncertainty | reproducible-ecology-pipeline |
+| **Conservation prioritization** | ecological-data-foundation | geoprocessing-for-ecology | species-distribution-modeling | spatial-prioritization | reproducible-ecology-pipeline |
 
 For multispecies projects always read `workflows/run-multispecies-screening/WORKFLOW.md`
 before starting. It contains the priority classification logic.
 
+Available workflows (14): `run-sdm-study`, `run-multispecies-screening`, `run-occupancy-analysis`, `run-camera-trap-occupancy`, `run-acoustic-monitoring`, `run-population-viability`, `run-conservation-prioritization`, `assess-ecological-impact`, `assess-ecosystem-services`, `assess-landscape-connectivity`, `analyze-community-structure`, `analyze-environmental-change`, `build-fire-risk-map`, `produce-technical-report`.
+
 ---
 
 ## 3. Disambiguation Rules for Overlapping Skills
@@ -153,7 +160,53 @@ Apply the appropriate routing based on project complexity:
 
 ---
 
-## 7. File Conventions of This Repository
+## 7. Environmental Data Sources
+
+### Default source: CHELSA v2.1
+
+The default environmental predictor source for all SDM and geoprocessing workflows is **CHELSA v2.1**
+(Climatologies at High resolution for the Earth's Land Surface Areas).
+
+- Resolution: ~1 km (30 arcsec)
+- Variables: BIO1-BIO19 (1981-2010 climatology)
+- Download URL pattern: `https://os.zhdk.cloud.switch.ch/chelsav2/GLOBAL/climatologies/1981-2010/bio/CHELSA_bio{N}_1981-2010_V.2.1.tif`
+- No authentication required
+- License: CC BY 4.0
+
+**WorldClim v2.1** is the automatic fallback if CHELSA downloads fail.
+The `download_predictors.py` script handles this transparently — no user action required.
+
+Do not default to WorldClim unless the user explicitly requests it or CHELSA is unavailable.
+
+### Python version compatibility
+
+| Python | Status for this repository |
+|--------|---------------------------|
+| 3.11 | Recommended — all packages build correctly |
+| 3.12 | Supported — most packages available |
+| 3.13 | Untested |
+| 3.14 | Not recommended — `elapid` (MaxEnt) fails to build; `pygbif` has API bugs |
+
+If `elapid` is unavailable (Python 3.12+), `sdm_pipeline.py` automatically falls back to an
+RF + BRT ensemble without MaxEnt. This is logged as a DECISION entry.
+
+If `pygbif` raises a `TypeError` on `Session.request()` (Python 3.14), `download_from_gbif.py`
+automatically falls back to direct HTTP calls to the GBIF REST API.
+
+### Spatial thinning
+
+`clean_occurrences.py` accepts an optional third argument `thin_deg` (decimal degrees).
+When provided, one record is retained per `thin_deg × thin_deg` grid cell to reduce
+spatial autocorrelation before SDM fitting. Recommended values: 0.1 (~11 km) to 0.5 (~55 km).
+
+Example:
+```bash
+python clean_occurrences.py data/raw/occurrences.csv data/processed 0.1
+```
+
+---
+
+## 8. File Conventions of This Repository
 
 ### Where to put input data
 - Place raw input files in `data/raw/` (create if absent).

package/CATALOG.md

@@ -152,7 +152,7 @@ A quick-reference index for all 17 skills. Each row summarises the skill's domai
 **When to use:** When processing audio recordings from AudioMoth, SM4, or similar recorders to compute soundscape indices or detect species via BirdNET or similar classifiers.
 **Inputs:** Audio directory (WAV/FLAC), recording metadata, species list (optional), location coordinates
 **Outputs:** Acoustic indices time series (CSV), detection list with confidence scores, species accumulation curve, soundscape heatmap
-**Used by workflows:** (standalone; pairs with environmental-time-series)
+**Used by workflows:** run-acoustic-monitoring; pairs with environmental-time-series
 
 ---
 
@@ -191,15 +191,16 @@ A quick-reference index for all 17 skills. Each row summarises the skill's domai
 | assess-ecological-impact | ✓ | ✓ | ✓ | | ✓ | | | | ✓ | | | ✓ | | | | | |
 | analyze-community-structure | ✓ | | ✓ | | ✓ | | | ✓ | | | | ✓ | | | | | |
 | build-fire-risk-map | ✓ | ✓ | | ✓ | ✓ | | | | ✓ | ✓ | | | | | | | |
-| run-occupancy-analysis | ✓ | | ✓ | | ✓ | | ✓ | | | | | ✓ | ✓ | | | | |
-| analyze-environmental-change | ✓ | ✓ | | | | | | | ✓ | ✓ | | ✓ | | ✓ | | | |
-| assess-ecosystem-services | ✓ | ✓ | ✓ | | | | | | | | ✓ | ✓ | | | | | ✓ |
-| produce-technical-report | | | | | | | | | | | | ✓ | | | | | |
+| run-occupancy-analysis | ✓ | | ✓ | | ✓ | | ✓ | | | | | ✓ | | | | | |
+| analyze-environmental-change | ✓ | ✓ | | | | | | | ✓ | ✓ | | ✓ | | | | | |
+| assess-ecosystem-services | ✓ | ✓ | ✓ | | | | | | | | ✓ | ✓ | | | | | |
+| produce-technical-report | | | ✓ | | | | | | | | | ✓ | | | | | |
 | run-multispecies-screening | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | | | | | | | | |
 | run-camera-trap-occupancy | ✓ | | | | ✓ | | ✓ | | | | | ✓ | ✓ | | | | |
 | assess-landscape-connectivity | ✓ | ✓ | | | ✓ | | | | | | | ✓ | | | ✓ | | |
 | run-population-viability | ✓ | | ✓ | | ✓ | | | | | | | ✓ | | | | ✓ | |
 | run-conservation-prioritization | ✓ | ✓ | | | | ✓ | | | | | | ✓ | | | | | ✓ |
+| run-acoustic-monitoring | ✓ | | ✓ | | ✓ | | | | | | | ✓ | | ✓ | | | |
 
 ---
 

package/README.md

@@ -2,9 +2,13 @@
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
-A curated, agent-agnostic skill library for **quantitative ecology** workflows, designed for use with any AI coding agent.
+Teach your AI agent to do rigorous ecology.
 
-**17 modular skills** | **13 multi-step workflows** | **58 R/Python scripts** | **14 worked examples across 6 continents**
+**ecological-agent-skills** is a structured instruction library that turns any AI coding agent into a quantitative ecology assistant — capable of cleaning occurrence data, fitting species distribution models, estimating occupancy, assessing landscape connectivity, running population viability analyses, and designing reserve networks, all with built-in decision logic, reproducibility tracking, and validated R/Python scripts.
+
+Works with Claude Code, Gemini CLI, Cursor, GitHub Copilot, and any agent that reads Markdown.
+
+**17 modular skills** | **14 multi-step workflows** | **58 R/Python scripts** | **14 worked examples across 6 continents**
 
 ---
 
@@ -14,7 +18,7 @@ A curated, agent-agnostic skill library for **quantitative ecology** workflows,
 - [Installation](#installation)
 - [Core Concepts](#core-concepts)
 - [Skills (17)](#skills-17)
-- [Workflows (13)](#workflows-13)
+- [Workflows (14)](#workflows-14)
 - [How to Use Skills](#how-to-use-skills)
 - [For AI Agents](#for-ai-agents)
 - [Examples (14)](#examples-14)
@@ -190,7 +194,7 @@ See [CATALOG.md](CATALOG.md) for full metadata, inputs, outputs, and workflow li
 
 ---
 
-## Workflows (13)
+## Workflows (14)
 
 | Workflow | Skills Used | Purpose |
 |----------|-------------|---------|
@@ -207,6 +211,7 @@ See [CATALOG.md](CATALOG.md) for full metadata, inputs, outputs, and workflow li
 | `assess-landscape-connectivity` | 1 → 2 → 15 → 5 → 12 | Corridor and patch importance |
 | `run-population-viability` | 1 → 3 → 16 → 5 → 12 | PVA and extinction risk |
 | `run-conservation-prioritization` | 1 → 2 → 6 → 17 → 12 | Reserve network design |
+| `run-acoustic-monitoring` | 1 → 14 → 3 → 5 → 12 | Soundscape indices and species detection |
 
 ---
 
@@ -305,7 +310,7 @@ ecological-agent-skills/
 │       ├── resources/            ← checklists, glossaries, templates
 │       ├── examples/             ← usage prompt examples
 │       └── scripts/              ← R/Python helpers
-├── workflows/                    ← 13 multi-step playbooks
+├── workflows/                    ← 14 multi-step playbooks
 │   └── <workflow-name>/
 │       └── WORKFLOW.md
 ├── templates/                    ← reusable prompts, reports, checklists

package/docs/DECISION_TREE.md

@@ -0,0 +1,218 @@
+# Skill Selection Decision Tree
+
+Use this guide to identify which skill (or sequence of skills) to invoke based on your data type and analytical goal. Start at the top and follow the branches that match your situation.
+
+---
+
+## Quick Reference Table
+
+| If your data is... | And your goal is... | Start with skill |
+|--------------------|---------------------|------------------|
+| Occurrence records (species coordinates) | Download, clean, validate | ecological-data-foundation |
+| Occurrence records + environmental layers | Model species distribution | ecological-data-foundation → geoprocessing-for-ecology → predictive-modeling-best-practices → species-distribution-modeling |
+| Raster / vector layers only | Reproject, clip, stack, extract values | geoprocessing-for-ecology |
+| Tabular ecological data (1 response, N predictors) | Statistical test or regression | biostatistics-workbench |
+| Species × site matrix | Community composition / ordination | ecological-data-foundation → community-ecology-ordination |
+| Replicated detection/non-detection surveys | Occupancy and detection probability | ecological-data-foundation → occupancy-and-detection |
+| Before/after, control/impact data | Quantify disturbance effect (BACI) | ecological-data-foundation → ecological-impact-assessment |
+| Time-indexed environmental variable | Trend, breakpoint, anomaly | ecological-data-foundation → environmental-time-series |
+| Land cover + biophysical layers | Ecosystem services mapping | ecological-data-foundation → geoprocessing-for-ecology → ecosystem-services-assessment |
+| Camera trap image records | Detection events, diel activity | camera-trap-processing (→ occupancy-and-detection) |
+| Audio recordings (WAV/FLAC) | Soundscape indices, species detection | acoustic-monitoring (→ environmental-time-series) |
+| Habitat patches + land cover raster | Landscape connectivity, corridors | geoprocessing-for-ecology → landscape-connectivity |
+| Vital rates (survival, fecundity by stage) | Population viability, IUCN Criterion E | biostatistics-workbench → population-viability-analysis |
+| Suitability maps + planning units | Reserve design, prioritization | species-distribution-modeling → spatial-prioritization |
+| Any fitted model | Evaluate performance, quantify uncertainty | model-validation-and-uncertainty |
+| Any completed analysis | Audit trail, reproducibility checklist | reproducible-ecology-pipeline |
+
+---
+
+## Decision Tree — Detailed
+
+### Step 1: What type of data do you have?
+
+```
+Root
+ ├── A. Occurrence records (species lat/lon)        → go to Branch A
+ ├── B. Spatial rasters or vectors only             → go to Branch B
+ ├── C. Tabular survey data (sites × variables)     → go to Branch C
+ ├── D. Time series data                            → go to Branch D
+ ├── E. Multimedia data (images / audio)            → go to Branch E
+ └── F. Model outputs (predictions, suitability)   → go to Branch F
+```
+
+---
+
+### Branch A — Occurrence Records
+
+```
+A. Occurrence records
+ ├── A1. Raw / uncleaned records?
+ │    └── ALWAYS start with: ecological-data-foundation
+ │         (cleaning, QA, deduplication, coordinate flags)
+ │
+ ├── A2. Goal: map species distribution / suitability?
+ │    └── ecological-data-foundation
+ │         → geoprocessing-for-ecology       (extract env. values)
+ │         → predictive-modeling-best-practices  (predictor selection, CV design)
+ │         → species-distribution-modeling   (MaxEnt / RF / BRT / ensemble)
+ │         → model-validation-and-uncertainty (AUC, TSS, uncertainty maps)
+ │         → reproducible-ecology-pipeline
+ │
+ ├── A3. Goal: occupancy and detection probability?
+ │    → Replicated visit data required (detection history matrix)
+ │    └── ecological-data-foundation
+ │         → occupancy-and-detection
+ │         → biostatistics-workbench
+ │         → reproducible-ecology-pipeline
+ │
+ └── A4. Multiple species simultaneously?
+      └── Follow workflow: run-multispecies-screening
+           (ecological-data-foundation → geoprocessing-for-ecology
+            → species-distribution-modeling (loop) → model-validation-and-uncertainty)
+```
+
+---
+
+### Branch B — Spatial Rasters or Vectors
+
+```
+B. Spatial rasters or vectors
+ ├── B1. Need to reproject, clip, resample, stack layers?
+ │    └── geoprocessing-for-ecology (standalone)
+ │
+ ├── B2. Need to extract environmental values at occurrence points?
+ │    └── geoprocessing-for-ecology (stack_and_extract.py)
+ │         → then continue with predictive-modeling-best-practices
+ │
+ ├── B3. Land cover raster + biophysical data → ecosystem services?
+ │    └── ecological-data-foundation → geoprocessing-for-ecology
+ │         → ecosystem-services-assessment → reproducible-ecology-pipeline
+ │
+ └── B4. Habitat patches + dispersal distance → connectivity?
+      └── geoprocessing-for-ecology → landscape-connectivity
+```
+
+---
+
+### Branch C — Tabular Survey Data
+
+```
+C. Tabular survey data
+ ├── C1. Single response variable (abundance, richness, biomass)?
+ │    └── ecological-data-foundation → biostatistics-workbench
+ │         (GLM/GLMM, hypothesis testing, model selection)
+ │
+ ├── C2. Species × site matrix (multiple species, multiple sites)?
+ │    └── ecological-data-foundation → community-ecology-ordination
+ │         (NMDS, PCA, PCoA, diversity indices, PERMANOVA)
+ │
+ ├── C3. Before/after, control/impact sites (BACI)?
+ │    └── ecological-data-foundation → ecological-impact-assessment
+ │         → biostatistics-workbench → model-validation-and-uncertainty
+ │
+ ├── C4. Vital rates by age/stage class?
+ │    └── biostatistics-workbench → population-viability-analysis
+ │         (lambda, elasticity, stochastic PVA, IUCN Criterion E)
+ │
+ └── C5. Planning units + species features?
+      └── species-distribution-modeling → spatial-prioritization
+           (prioritizr/Marxan, representation targets, reserve design)
+```
+
+---
+
+### Branch D — Time Series Data
+
+```
+D. Time series data
+ ├── D1. Environmental signal (NDVI, temperature, rainfall)?
+ │    └── ecological-data-foundation → environmental-time-series
+ │         (Mann-Kendall trend, BFAST breakpoint, anomaly detection)
+ │
+ ├── D2. Biodiversity metric over time (species index, acoustic)?
+ │    └── ecological-data-foundation → environmental-time-series
+ │         → biostatistics-workbench (if inferential comparison needed)
+ │
+ └── D3. Fire risk or land cover change?
+      └── Follow workflow: build-fire-risk-map or analyze-environmental-change
+           (ecological-data-foundation → geoprocessing-for-ecology
+            → ecological-impact-assessment → environmental-time-series)
+```
+
+---
+
+### Branch E — Multimedia Data
+
+```
+E. Multimedia data
+ ├── E1. Camera trap images?
+ │    └── camera-trap-processing
+ │         (detection events, diel activity, trap effort table)
+ │         → occupancy-and-detection  (if occupancy estimation needed)
+ │
+ └── E2. Audio recordings (WAV/FLAC)?
+      └── acoustic-monitoring
+           (ACI/NDSI/ADI soundscape indices, BirdNET species detection)
+           → environmental-time-series  (if temporal trend analysis needed)
+```
+
+---
+
+### Branch F — Model Outputs
+
+```
+F. Model outputs
+ ├── F1. Model fitted; need performance metrics?
+ │    └── model-validation-and-uncertainty
+ │         (AUC, TSS, RMSE, calibration, sensitivity, uncertainty maps)
+ │
+ ├── F2. Suitability maps; need conservation priorities?
+ │    └── spatial-prioritization
+ │         (planning units, targets, BLM, prioritizr/Marxan)
+ │
+ └── F3. Any outputs; need reproducibility checklist?
+      └── reproducible-ecology-pipeline
+           (parameter manifest, decision log, audit trail)
+```
+
+---
+
+## Disambiguation Rules
+
+Apply exactly one rule when two skills seem applicable.
+
+### ecological-data-foundation vs. geoprocessing-for-ecology
+- **ecological-data-foundation**: cleaning, deduplication, column validation, coordinate QA.
+- **geoprocessing-for-ecology**: spatial operations on rasters/vectors (reproject, mask, stack, extract).
+- If the task involves occurrence records AND spatial operations, run **ecological-data-foundation first**.
+
+### predictive-modeling-best-practices vs. model-validation-and-uncertainty
+- **predictive-modeling-best-practices**: BEFORE fitting — predictor selection, collinearity, CV design.
+- **model-validation-and-uncertainty**: AFTER fitting — metrics, calibration, uncertainty quantification.
+- Never reverse this order.
+
+### species-distribution-modeling vs. occupancy-and-detection
+- **species-distribution-modeling**: suitability surface from presence/absence + environmental predictors.
+- **occupancy-and-detection**: occupancy probability (psi) + detection (p) from replicated visit data.
+
+### ecological-impact-assessment vs. biostatistics-workbench
+- **ecological-impact-assessment**: data with explicit before/after + control/impact structure (BACI), or landscape fragmentation metrics.
+- **biostatistics-workbench**: statistical comparisons without BACI design.
+
+### biostatistics-workbench vs. community-ecology-ordination
+- **biostatistics-workbench**: one response variable, one or more predictors.
+- **community-ecology-ordination**: species × site matrix as primary input (multivariate assemblage data).
+
+---
+
+## Minimum Records Quick Reference
+
+| Analysis | Do NOT proceed below | Recommended |
+|----------|----------------------|-------------|
+| SDM (any algorithm) | 10 occurrences | >= 30 |
+| Occupancy model | 15 sites | >= 30 sites, >= 3 visits |
+| BACI mixed model | 5 control + 5 impact sites | >= 10 per group |
+| Community ordination | 5 sites | >= 10 sites |
+| GLM (single predictor) | 20 observations | >= 50 |
+| Stochastic PVA | 5 years of count data | >= 10 years |

package/docs/GBIF_SETUP.md

@@ -0,0 +1,88 @@
+# GBIF Credentials Setup
+
+GBIF credentials are **optional** but enable async downloads with a citable DOI,
+which is required for reproducible publications and for datasets > 100,000 records.
+
+Without credentials, `download_from_gbif.py` falls back to `occ.search`
+(no DOI, max ~100,000 records, still functional for most studies).
+
+---
+
+## Step 1 — Create a free GBIF account
+
+1. Go to https://www.gbif.org
+2. Click **Login** > **Register**
+3. Fill in username, email, and password
+4. Confirm your email address
+
+---
+
+## Step 2 — Set environment variables
+
+Set these three variables in your shell before running any skill:
+
+```bash
+# Linux / macOS — add to ~/.bashrc or ~/.zshrc
+export GBIF_USER="your_gbif_username"
+export GBIF_PWD="your_gbif_password"
+export GBIF_EMAIL="your_email@example.com"
+```
+
+```powershell
+# Windows — PowerShell (current session only)
+$env:GBIF_USER  = "your_gbif_username"
+$env:GBIF_PWD   = "your_gbif_password"
+$env:GBIF_EMAIL = "your_email@example.com"
+```
+
+```powershell
+# Windows — PowerShell (permanent, per user)
+[System.Environment]::SetEnvironmentVariable("GBIF_USER",  "your_gbif_username", "User")
+[System.Environment]::SetEnvironmentVariable("GBIF_PWD",   "your_gbif_password", "User")
+[System.Environment]::SetEnvironmentVariable("GBIF_EMAIL", "your_email@example.com", "User")
+```
+
+If using conda, you can also add them to `environment.yaml` under `variables:`
+(not recommended for shared/committed files — use a `.env` file instead).
+
+---
+
+## Step 3 — Verify
+
+```bash
+python -c "import os; print(os.getenv('GBIF_USER'))"
+```
+
+Should print your GBIF username.
+
+---
+
+## When credentials are used vs. not used
+
+| Scenario | Method used | DOI | Max records |
+|----------|-------------|-----|-------------|
+| Credentials set + dataset > 100k records | Async download | Yes | Unlimited |
+| Credentials set + dataset <= 100k records | `occ.search` | No | ~100k |
+| No credentials | `occ.search` fallback | No | ~100k |
+
+---
+
+## Citing GBIF downloads
+
+When credentials are set and an async download completes, the script saves a
+`download_metadata_*.txt` file containing the DOI. Cite it in publications as:
+
+> GBIF.org (YYYY) GBIF Occurrence Download https://doi.org/10.15468/dl.XXXXXX
+
+---
+
+## Troubleshooting
+
+**"GBIF async download requires env vars"** — credentials not set; see Step 2 above.
+
+**"occ.count returned 400"** — `hasCoordinate` is not supported by the count endpoint;
+this is a known GBIF API limitation. The script handles this silently.
+
+**pygbif TypeError on Python 3.14** — `pygbif` has an API incompatibility with
+Python 3.14's `requests` session. The script automatically falls back to direct
+HTTP calls to the GBIF REST API. No action needed.