ecological-agent-skills 3.1.0

package/skills/geoprocessing-for-ecology/scripts/stack_and_extract.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+stack_and_extract.py
+Clip rasters to study area and extract values at points.
+Usage: python stack_and_extract.py <raster_dir> <points_csv> <studyarea_shp> <output_dir>
+Requires: rasterio, geopandas, rasterstats, numpy, pandas
+"""
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "geoprocessing-for-ecology"
+_LOG_DIR   = Path("logs")
+_LOG_DIR.mkdir(parents=True, exist_ok=True)
+_log_file  = _LOG_DIR / f"skill_{SKILL_NAME}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s] [%(levelname)s] [" + SKILL_NAME + "] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[
+        logging.StreamHandler(sys.stdout),
+        logging.FileHandler(_log_file, encoding="utf-8"),
+    ],
+)
+logger = logging.getLogger(SKILL_NAME)
+
+def log_step(n: int, desc: str) -> None:
+    logger.info("-- STEP %d: %s", n, desc)
+
+def log_decision(var: str, val, why: str) -> None:
+    logger.info("DECISION | %s = %s | %s", var, val, why)
+
+import os
+import numpy as np
+import pandas as pd
+import geopandas as gpd
+import rasterio
+from rasterio.mask import mask as rio_mask
+from rasterio.warp import reproject, Resampling, calculate_default_transform
+from shapely.geometry import mapping
+
+
+def reproject_raster(src_path, dst_path, dst_crs):
+    with rasterio.open(src_path) as src:
+        transform, width, height = calculate_default_transform(
+            src.crs, dst_crs, src.width, src.height, *src.bounds)
+        kwargs = src.meta.copy()
+        kwargs.update({"crs": dst_crs, "transform": transform, "width": width, "height": height})
+        with rasterio.open(dst_path, "w", **kwargs) as dst:
+            for i in range(1, src.count + 1):
+                reproject(source=rasterio.band(src, i), destination=rasterio.band(dst, i),
+                          src_transform=src.transform, src_crs=src.crs,
+                          dst_transform=transform, dst_crs=dst_crs,
+                          resampling=Resampling.bilinear)
+
+def clip_to_area(raster_path, area_geom, out_path):
+    with rasterio.open(raster_path) as src:
+        out_image, out_transform = rio_mask(src, [mapping(area_geom)], crop=True)
+        out_meta = src.meta.copy()
+        out_meta.update({"transform": out_transform, "width": out_image.shape[2],
+                         "height": out_image.shape[1]})
+        with rasterio.open(out_path, "w", **out_meta) as dst:
+            dst.write(out_image)
+
+def extract_values(raster_paths, points_df, lon_col="decimalLongitude", lat_col="decimalLatitude"):
+    from rasterstats import point_query
+    result_df = points_df.copy()
+    coords = list(zip(points_df[lon_col], points_df[lat_col]))
+    for rpath in raster_paths:
+        varname = Path(rpath).stem
+        vals = point_query(coords, rpath, interpolate="bilinear")
+        result_df[varname] = vals
+    return result_df
+
+def main():
+    raster_dir  = sys.argv[1] if len(sys.argv) > 1 else "data/predictors/raw"
+    points_file = sys.argv[2] if len(sys.argv) > 2 else "data/processed/data_clean.csv"
+    area_file   = sys.argv[3] if len(sys.argv) > 3 else "data/spatial/study_area.shp"
+    output_dir  = Path(sys.argv[4]) if len(sys.argv) > 4 else Path("data/processed")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_decision("raster_dir", raster_dir, "Directory containing raw predictor GeoTIFFs")
+    log_decision("points_file", points_file, "CSV of occurrence/sample points with coordinates")
+    log_decision("area_file", area_file, "Shapefile defining the study area extent for clipping")
+    log_decision("output_dir", str(output_dir), "Directory for clipped rasters and extracted values")
+
+    if not Path(raster_dir).exists():
+        logger.error(
+            "Input nao encontrado: %s\n"
+            "  Causa provavel: passo anterior nao concluiu.\n"
+            "  Skill anterior que deveria ter produzido este input: reproducible-ecology-pipeline",
+            raster_dir
+        )
+        sys.exit(1)
+
+    if not Path(points_file).exists():
+        logger.error(
+            "Input nao encontrado: %s\n"
+            "  Causa provavel: passo anterior nao concluiu.\n"
+            "  Skill anterior que deveria ter produzido este input: reproducible-ecology-pipeline",
+            points_file
+        )
+        sys.exit(1)
+
+    if not Path(area_file).exists():
+        logger.error(
+            "Input nao encontrado: %s\n"
+            "  Causa provavel: passo anterior nao concluiu.\n"
+            "  Skill anterior que deveria ter produzido este input: reproducible-ecology-pipeline",
+            area_file
+        )
+        sys.exit(1)
+
+    try:
+        log_step(1, "Discovering raster files in raster directory")
+        tif_files = sorted(Path(raster_dir).glob("*.tif"))
+        logger.info("Rasters found: %d", len(tif_files))
+        if len(tif_files) == 0:
+            logger.warning(
+                "No .tif files found in %s. Check raster_dir path or file extension.", raster_dir
+            )
+
+        log_step(2, "Loading study area geometry")
+        area = gpd.read_file(area_file)
+        area_geom = area.geometry.unary_union
+
+        log_step(3, "Clipping rasters to study area extent")
+        clipped_dir = output_dir / "predictors_clipped"
+        clipped_dir.mkdir(exist_ok=True)
+        clipped_paths = []
+        for tif in tif_files:
+            out_path = clipped_dir / tif.name
+            clip_to_area(str(tif), area_geom, str(out_path))
+            clipped_paths.append(str(out_path))
+            logger.info("  Clipped: %s", tif.name)
+
+        log_step(4, "Loading point data and extracting raster values")
+        pts = pd.read_csv(points_file)
+        logger.info("Points loaded: %d", len(pts))
+        pts_env = extract_values(clipped_paths, pts)
+        pts_env.to_csv(output_dir / "points_with_env.csv", index=False)
+
+        complete = pts_env.dropna().shape[0]
+        incomplete = len(pts) - complete
+        logger.info(
+            "Points with complete env data: %d/%d", complete, len(pts)
+        )
+        if incomplete > 0:
+            logger.warning(
+                "%d points have missing values after extraction — likely fall outside raster extent.",
+                incomplete
+            )
+        logger.info("Output written to: %s", output_dir / "points_with_env.csv")
+
+    except FileNotFoundError as e:
+        logger.error(
+            "Input file not found: %s\n"
+            "  Expected output from: reproducible-ecology-pipeline\n"
+            "  Check that previous step completed.",
+            e
+        )
+        raise
+    except Exception as e:
+        logger.error("Unexpected error in stack and extract: %s", e)
+        raise
+
+if __name__ == "__main__":
+    main()

package/skills/landscape-connectivity/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: landscape-connectivity
+description: "Analyzes landscape connectivity using graph theory, resistance surfaces, and corridor identification for conservation planning. Use this skill when the user mentions habitat connectivity, wildlife corridors, Circuitscape, least-cost paths, resistance surfaces, IIC/dPC connectivity metrics, stepping stones, patch importance ranking, betweenness centrality, fragmentation analysis, landscape graphs, or pinchpoint identification."
+skill_version: 1.0.0
+---
+
+# Skill: landscape-connectivity
+
+**Domain:** Landscape connectivity · Graph theory · Circuitscape · Corridor · Resistance surface
+
+---
+
+## Purpose
+
+Guides the agent through quantifying structural and functional landscape connectivity, identifying wildlife corridors, and calculating the contribution of individual habitat patches to overall network connectivity. Covers resistance surface construction, graph-based connectivity indices (IIC, PC, dPC), Circuitscape current mapping, and least-cost path analysis for corridor delineation.
+
+---
+
+## When to Invoke
+
+Invoke this skill when:
+
+- The user asks about habitat connectivity, wildlife corridors, or dispersal pathways
+- Patches of habitat must be ranked by their importance to overall connectivity
+- A resistance surface is needed for Circuitscape or least-cost path modelling
+- The impact of habitat loss or fragmentation on connectivity must be quantified
+- Gene flow, dispersal barriers, or landscape permeability are the focus
+
+**trigger_keywords:** `habitat connectivity`, `wildlife corridor`, `dispersal`, `gene flow`, `landscape graph`, `resistance surface`, `least-cost path`, `circuit theory`, `Circuitscape`, `IIC`, `PC`, `dPC`, `corridor width`, `patch importance`, `landscape permeability`
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|---|---|---|
+| Habitat/land cover raster | GeoTIFF | Required |
+| Study area polygon | SHP or GPKG | Required |
+| Dispersal distance or dispersal kernel parameters | CSV or text | Required |
+| Resistance value table (land cover class → resistance) | CSV | Recommended |
+| Existing protected areas or focal nodes | SHP or GPKG | Optional |
+| Habitat class codes | Integer codes or CSV lookup | Optional |
+
+---
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `patch_metrics.csv` | Area, perimeter, IIC, PC, dIIC, dPC per patch |
+| `connectivity_summary.csv` | Global IIC, PC, and top-10 patches by dPC |
+| `top_patches_map.tif` | Raster with dPC value per patch |
+| `connectivity_graph.png` | Habitat patch network diagram |
+| `resistance_surface.tif` | Resistance surface for Circuitscape input |
+| `patch_betweenness.csv` | Betweenness centrality per patch (graph metric) |
+| `least_cost_paths.gpkg` | Least-cost path lines between patch pairs |
+
+---
+
+## Steps
+
+1. **Prepare habitat patches**
+   Load land cover raster and mask to study area using `geoprocessing-for-ecology`.
+   Reclassify to binary habitat/non-habitat. Extract discrete habitat patches
+   with `terra::patches()` or `landscapemetrics::get_patches()`.
+   Filter patches below minimum area threshold (document threshold in `decision_log.md`).
+
+2. **Build resistance surface** *(invoke `resistance_surface.R`)*
+   Reclassify land cover using the resistance table.
+   Apply optional focal smoothing to avoid hard edges.
+   Validate: all land cover classes must have an assigned resistance value.
+   Output: `resistance_surface.tif`.
+
+3. **Calculate distance matrix between patches**
+   Compute pairwise Euclidean or least-cost distances between patch centroids.
+   If dispersal distance threshold is unknown, use 3 values for sensitivity analysis:
+   conservative (25th percentile), medium (median), optimistic (75th percentile).
+
+4. **Compute connectivity indices** *(invoke `connectivity_metrics.R`)*
+   Calculate IIC and PC for each dispersal distance scenario.
+   Compute dIIC and dPC (patch removal importance) for all patches.
+   Rank patches by dPC to identify conservation priorities.
+
+5. **Run Circuitscape for corridor mapping** *(optional, requires Circuitscape installed)*
+   Export focal nodes (top-N patches by dPC) and resistance surface.
+   Run in `all-to-one` mode to produce cumulative current density map.
+   Interpret high-current corridors as priority dispersal pathways.
+
+6. **Delineate least-cost paths** *(invoke `connectivity_analysis.py`)*
+   Use `scikit-image.graph.route_through_array()` for least-cost paths.
+   Output vector lines between top-priority patch pairs.
+
+7. **Validate outputs and record decisions**
+   Check dPC values sum approximately to the global PC.
+   Record dispersal distance scenario, resistance table source, and minimum patch area
+   in `decision_log.md`.
+
+---
+
+## Decision Points
+
+| Condition | Diagnosis | Recommended Action |
+|---|---|---|
+| Dispersal distance unknown | Sensitivity of results to this parameter is high | Run analysis at 3 distances (conservative, medium, optimistic); report range of outcomes |
+| Landscape < 10 patches | Graph metrics statistically unstable | Use fragmentation metrics from ecological-impact-assessment skill instead |
+| IIC or PC < 0.01 | Extremely low connectivity | Prioritise restoration before corridor analysis; identify bottleneck patches |
+| dPC > 0.8 for a patch already deforested | High-priority patch lost | Escalate to restoration planning; include in gap analysis |
+| All patches isolated (no edges at chosen distance) | Threshold too restrictive | Increase dispersal distance or use resistance-based (cost) distance threshold |
+
+---
+
+## Key Decisions to Document
+
+Record the following in `decision_log.md` after running this skill:
+
+- Dispersal distance(s) used and their biological justification
+- Source of resistance values (literature, telemetry, expert opinion)
+- Minimum patch area threshold applied and rationale
+- Whether Circuitscape was run; mode used (pairwise, all-to-one, one-to-all)
+- Top-N patches selected for focal node analysis
+
+---
+
+## Tools and Libraries
+
+**R**
+```r
+suppressPackageStartupMessages(library(terra))              # raster operations
+suppressPackageStartupMessages(library(sf))                 # vector operations
+suppressPackageStartupMessages(library(landscapemetrics))   # patch extraction and metrics
+suppressPackageStartupMessages(library(igraph))             # graph theory (IIC, PC, betweenness)
+suppressPackageStartupMessages(library(dplyr))              # data manipulation
+suppressPackageStartupMessages(library(ggplot2))            # plotting
+```
+
+**Python**
+```python
+import networkx as nx           # graph metrics (betweenness centrality)
+from skimage.graph import route_through_array  # least-cost path
+import geopandas as gpd         # vector operations
+import rasterio                 # raster reading
+import numpy as np              # numerical operations
+from pathlib import Path        # file system
+```
+
+**CLI**
+```bash
+# Circuitscape (optional, must be installed)
+circuitscape_4_0 <config_file.ini>
+# or Julia-based CS4
+julia -e "using Circuitscape; compute(<config_file.ini>)"
+```
+
+---
+
+## Resources
+
+- [`skills/landscape-connectivity/resources/graph-theory-for-ecology.md`](resources/graph-theory-for-ecology.md) — IIC, PC, dPC formulas, interpretation, and dispersal threshold definition
+- [`skills/landscape-connectivity/resources/resistance-surface-guide.md`](resources/resistance-surface-guide.md) — Resistance value assignment by taxon, calibration methods, and Circuitscape export
+- [`skills/landscape-connectivity/resources/circuitscape-parameter-guide.md`](resources/circuitscape-parameter-guide.md) — Circuitscape modes, focal nodes, solver selection, and output interpretation
+
+---
+
+## Notes
+
+- **IIC and PC are scale-dependent:** Both indices depend on the total landscape area (`A`). Always report the landscape extent used in calculation to enable comparison across studies.
+- **Euclidean distance ≠ functional connectivity:** Distance-based IIC/PC ignores landscape resistance. Use cost-distance for species sensitive to habitat matrix quality (e.g., forest-dependent species crossing agricultural land).
+- **Circuitscape can be slow for large landscapes:** For rasters > 10 million cells, use the Julia implementation (Circuitscape.jl) which is 10–50× faster than the Python version.
+- **Betweenness centrality is a proxy, not a measure of flow:** High betweenness patches are on many shortest paths but may not have high actual dispersal if resistance is high elsewhere.
+- **Patch size confounds dPC:** Large patches tend to have high dPC because their removal drastically reduces total habitat area. Always report patch area alongside dPC to distinguish area effect from connectivity effect.

package/skills/landscape-connectivity/examples/example-prompts.md

@@ -0,0 +1,96 @@
+---
+skill_id: landscape-connectivity
+example_count: 5
+---
+
+# Landscape Connectivity — Example Prompts
+
+## Scenario 1: Forest Fragment Connectivity Assessment
+
+**Context:** Atlantic Forest remnants, southeastern Brazil. 85 patches of varying size in a 10,000 km² landscape dominated by pasture and sugarcane.
+
+**Prompt:**
+> "I have a shapefile of 85 Atlantic Forest patches in southeastern Brazil. Compute IIC and PC for the landscape at dispersal distances of 500 m, 1 km, and 2 km (to cover uncertainty about ocelot dispersal). Rank patches by dPC and identify the top 10 most important patches for connectivity."
+
+**Expected workflow:**
+1. `connectivity_metrics.R patches.shp outputs/ 1000` (repeat for 500, 2000)
+2. Compare IIC and PC across three dmax values — check robustness
+3. Rank by `dPC_pct` descending; report top 10 patches with area and dPC
+4. Flag patches with dPC > 5% as high-priority conservation targets
+
+**Key decision points:**
+- If IIC changes > 50% between dmax = 500 and 2000 m → conduct formal sensitivity analysis before interpreting
+- If top patches overlap with unprotected private land → identify restoration opportunity
+
+---
+
+## Scenario 2: Corridor Identification with Circuitscape
+
+**Context:** Two forest blocks separated by 15 km of agricultural land. Identify the most likely movement corridors for pumas and test which land cover types are least permeable.
+
+**Prompt:**
+> "I have a resistance surface for pumas based on land cover type. Two forest blocks are the source and destination patches. Run Circuitscape in pairwise mode, identify pinch points in the current map, and test how corridor connectivity changes if the highway between the blocks is removed."
+
+**Expected workflow:**
+1. `resistance_surface.R landcover.tif resistance_table.csv outputs/ dem.tif roads.shp`
+2. Run Circuitscape via `run_circuitscape()` function (pairwise, 2 nodes)
+3. Load `*_cum_curmap.asc`; extract top 5% current cells as pinch points
+4. Remove highway from resistance surface → re-run Circuitscape → compare effective resistance
+
+**Expected findings:**
+- Pinch points likely at river crossings and road underpasses
+- Removing highway typically reduces effective resistance by 30–60%
+
+---
+
+## Scenario 3: Stepping Stone Prioritisation for Rewilding
+
+**Context:** Degraded agricultural landscape. 12 existing forest patches; 30 candidate restoration sites. Identify which restoration sites most increase connectivity (dPC gain).
+
+**Prompt:**
+> "I have 12 existing forest patches and 30 candidate restoration polygons. For each candidate site, calculate how much it would increase PC if restored. Rank candidates by connectivity gain and identify the top 5 restoration priorities."
+
+**Expected workflow:**
+1. Compute PC for existing 12 patches
+2. For each candidate: add it to patch set → recompute PC → ΔPC = PC_new − PC_baseline
+3. Rank candidates by ΔPC descending
+4. Report top 5 candidates with area, cost estimate, and ΔPC
+5. Map showing candidate sites coloured by ΔPC gain
+
+**Key decision points:**
+- If multiple candidates have similar ΔPC → add cost layer and rank by ΔPC/ha
+- If candidate overlaps with existing connectivity graph → betweenness centrality gain is secondary metric
+
+---
+
+## Scenario 4: Genetic Isolation by Resistance Test
+
+**Context:** 8 populations of a montane amphibian sampled for genetic markers. Test whether resistance distance (based on land cover) predicts genetic differentiation better than Euclidean distance.
+
+**Prompt:**
+> "I have FST values for 8 amphibian populations and a resistance surface based on elevation and land cover. Compute pairwise resistance distances using Circuitscape, then compare IBR (isolation by resistance) vs IBD (isolation by distance) models using a partial Mantel test."
+
+**Expected workflow:**
+1. `resistance_surface.R` → combined resistance for amphibians
+2. Circuitscape pairwise for 8 population locations → effective resistance matrix
+3. Partial Mantel test: `FST ~ resistance | Euclidean` using `vegan::mantel.partial()`
+4. Report: if resistance explains more variance than distance → resistance model supported
+
+---
+
+## Scenario 5: Connectivity Change Before and After Deforestation
+
+**Context:** Long-term forest loss monitoring. Compute connectivity for years 2000, 2010, 2020 to quantify fragmentation over time.
+
+**Prompt:**
+> "I have three land cover maps (2000, 2010, 2020) for a deforestation frontier in Amazonia. Compute IIC and PC for each year at dmax = 2 km. Quantify patch loss, connectivity loss, and identify which patches were permanently deforested."
+
+**Expected workflow:**
+1. `connectivity_metrics.R` for each year → `landscape_summary.csv` per year
+2. Join summaries; compute annual % change in IIC, PC, n_patches, mean_area
+3. Identify patches present in 2000 but absent in 2020 → permanent deforestation
+4. Plot IIC/PC trend over time with error bars from dmax sensitivity (500–5000 m)
+
+**Expected findings:**
+- Typical Amazonian deforestation frontier: IIC losses of 15–40% per decade
+- PC declines faster than IIC at early stages (many small patches lose probabilistic connections before binary connectivity is severed)