ecological-agent-skills 3.1.0

package/skills/environmental-time-series/scripts/trend_analysis.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+trend_analysis.py
+Mann-Kendall trend + Sen's slope + anomaly detection.
+Usage: python trend_analysis.py <timeseries_csv> <output_dir> [frequency]
+Requires: pandas, numpy, pymannkendall, matplotlib, scipy
+"""
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "environmental-time-series"
+_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 numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from scipy import stats
+
+try:
+    import pymannkendall as mk
+    HAS_MK = True
+except ImportError:
+    HAS_MK = False
+    logger.warning("pymannkendall not installed. Falling back to linear regression. pip install pymannkendall")
+
+
+def seasonal_decompose_simple(values, freq):
+    """Simple additive seasonal decomposition."""
+    n = len(values)
+    trend = pd.Series(values).rolling(window=freq, center=True, min_periods=1).mean().values
+    detrended = values - trend
+    seasonal = np.array([np.nanmean(detrended[i::freq]) for i in range(freq)])
+    seasonal_full = np.tile(seasonal, n // freq + 1)[:n]
+    remainder = values - trend - seasonal_full
+    return trend, seasonal_full, remainder
+
+def compute_anomalies(values, baseline_n):
+    mu = np.nanmean(values[:baseline_n])
+    sd = np.nanstd(values[:baseline_n])
+    return (values - mu) / (sd + 1e-10)
+
+def main():
+    ts_file    = sys.argv[1] if len(sys.argv) > 1 else "data/ndvi_series.csv"
+    output_dir = Path(sys.argv[2]) if len(sys.argv) > 2 else Path("outputs/timeseries")
+    freq       = int(sys.argv[3]) if len(sys.argv) > 3 else 12
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_decision("ts_file", ts_file, "Input time series CSV")
+    log_decision("freq", freq, "Expected seasonal frequency (12 = monthly annual cycle)")
+    log_decision("output_dir", str(output_dir), "Directory for trend analysis outputs")
+
+    if not Path(ts_file).exists():
+        logger.error(
+            "Input nao encontrado: %s\n"
+            "  Causa provavel: passo anterior nao concluiu.\n"
+            "  Skill anterior que deveria ter produzido este input: geoprocessing-for-ecology",
+            ts_file
+        )
+        sys.exit(1)
+
+    try:
+        log_step(1, "Loading time series data")
+        dat = pd.read_csv(ts_file)
+        val_col = "value" if "value" in dat.columns else dat.columns[-1]
+        values = dat[val_col].values.astype(float)
+        logger.info("Series length: %d | Frequency: %d", len(values), freq)
+
+        n_nan = int(np.sum(np.isnan(values)))
+        if n_nan > 0:
+            logger.warning(
+                "%d NaN values detected in series. These will be ignored in statistical tests.",
+                n_nan
+            )
+
+        log_step(2, "Running trend test (Mann-Kendall or linear regression)")
+        # Mann-Kendall
+        if HAS_MK:
+            res = mk.original_test(values)
+            logger.info(
+                "Mann-Kendall: tau = %.4f | p = %.4f | slope = %.6f/obs",
+                res.Tau, res.p, res.slope
+            )
+            log_decision("trend_method", "Mann-Kendall",
+                         "Preferred non-parametric test for monotonic trends in ecological series")
+            trend_df = pd.DataFrame({"tau": [res.Tau], "p_value": [res.p],
+                                      "sens_slope": [res.slope],
+                                      "trend": [res.trend]})
+            trend_df.to_csv(output_dir / "trend_results.csv", index=False)
+        else:
+            log_decision("trend_method", "linear regression",
+                         "Fallback — pymannkendall not available")
+            slope, intercept, r, p, se = stats.linregress(np.arange(len(values)), values)
+            logger.info(
+                "Linear regression (MK unavailable): slope = %.6f | p = %.4f", slope, p
+            )
+
+        log_step(3, "Seasonal decomposition")
+        # Decomposition
+        if len(values) >= 2 * freq:
+            trend_comp, seasonal_comp, remainder = seasonal_decompose_simple(values, freq)
+            fig, axes = plt.subplots(4, 1, figsize=(10, 10), sharex=True)
+            for ax, data, title in zip(axes, [values, trend_comp, seasonal_comp, remainder],
+                                       ["Observed", "Trend", "Seasonal", "Remainder"]):
+                ax.plot(data); ax.set_title(title); ax.grid(alpha=0.3)
+            plt.suptitle("Time Series Decomposition")
+            plt.tight_layout()
+            plt.savefig(output_dir / "decomposition_plot.png", dpi=150)
+            plt.close()
+            logger.info("Decomposition plot saved to: %s", output_dir / "decomposition_plot.png")
+        else:
+            logger.warning(
+                "Series length (%d) < 2 * freq (%d). Skipping seasonal decomposition.",
+                len(values), 2 * freq
+            )
+
+        log_step(4, "Computing anomaly Z-scores")
+        # Anomalies
+        baseline_n = min(freq * 10, len(values) // 2)
+        log_decision("baseline_n", baseline_n,
+                     "First N observations used as anomaly baseline (min of 10 cycles, half series)")
+        anomalies = compute_anomalies(values, baseline_n)
+        dat["anomaly_z"] = anomalies
+
+        n_extreme = int(np.sum(np.abs(anomalies) > 2))
+        if n_extreme > 0:
+            logger.warning(
+                "%d observations exceed ±2 SD anomaly threshold — review for data quality or ecological extremes.",
+                n_extreme
+            )
+
+        dat.to_csv(output_dir / "anomaly_series.csv", index=False)
+
+        log_step(5, "Generating anomaly bar plot")
+        fig, ax = plt.subplots(figsize=(10, 4))
+        ax.bar(range(len(anomalies)), anomalies,
+               color=np.where(anomalies < 0, "#d6604d", "#4393c3"), alpha=0.8)
+        ax.axhline(-1.5, color="orange", linestyle="--", label="±1.5σ")
+        ax.axhline(1.5, color="orange", linestyle="--")
+        ax.axhline(-2, color="red", linestyle="--", label="±2σ")
+        ax.axhline(2, color="red", linestyle="--")
+        ax.set_xlabel("Time step"); ax.set_ylabel("Standardised anomaly (z)")
+        ax.set_title(f"Anomalies (baseline = first {baseline_n} obs)")
+        ax.legend(); plt.tight_layout()
+        plt.savefig(output_dir / "anomaly_plot.png", dpi=150)
+        plt.close()
+        logger.info("Outputs written to: %s", output_dir)
+
+    except FileNotFoundError as e:
+        logger.error(
+            "Input file not found: %s\n"
+            "  Expected output from: geoprocessing-for-ecology\n"
+            "  Check that previous step completed.",
+            e
+        )
+        raise
+    except Exception as e:
+        logger.error("Unexpected error in trend analysis: %s", e)
+        raise
+
+if __name__ == "__main__":
+    main()

package/skills/geoprocessing-for-ecology/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: geoprocessing-for-ecology
+description: "Handles spatial data operations: reprojection, raster stacking, clipping, extraction, and environmental predictor downloads for ecological analyses. Use this skill when the user needs CRS reprojection, raster masking or cropping, spatial extraction, buffer creation, raster resampling, spatial joins, GeoTIFF processing, shapefile operations, WorldClim/CHELSA/ERA5 predictor downloads, GDAL operations, or predictor stack preparation."
+skill_version: 1.0.0
+---
+
+# Skill: geoprocessing-for-ecology
+
+**Domain:** Spatial analysis · CRS · Raster · Vector · Extraction  
+**Phase:** 1 — Foundation  
+**Used by:** run-sdm-study, assess-ecological-impact, build-fire-risk-map, analyze-environmental-change, assess-ecosystem-services
+
+---
+
+## Purpose
+
+Guides the agent through spatial data operations needed in quantitative ecology: coordinate reference system management, raster and vector processing, spatial masking, buffer creation, intersection, and extraction of environmental values at occurrence or sample points.
+
+---
+
+## When to Invoke
+
+- Reprojecting layers to a common CRS
+- Clipping rasters or shapefiles to a study area
+- Extracting environmental variables at point locations
+- Creating buffers around sites or features
+- Computing landscape metrics from a land cover layer
+- Stacking multi-band rasters for modeling
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Occurrence / sample points | CSV with lat/lon, SHP, GPKG | Yes |
+| Study area polygon | SHP, GPKG, GeoJSON | Yes |
+| Environmental rasters | GeoTIFF, NetCDF | Yes |
+| Land cover or habitat layer | GeoTIFF, SHP | Optional |
+
+---
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `layers_reprojected/` | All layers in common CRS |
+| `predictors_stack.tif` | Aligned, masked raster stack |
+| `points_with_env.csv` | Points with extracted environmental values |
+| `study_area_buffered.gpkg` | Study area with optional buffer |
+| `spatial_qa_report.md` | CRS audit and alignment report |
+
+---
+
+## Steps
+
+### 1. CRS Audit
+- Identify the CRS of each input layer
+- Define the project CRS (default: EPSG:4326 for global; UTM zone for regional)
+- Reproject all layers to the project CRS
+- Document the CRS choice and rationale
+
+### 2. Extent and Resolution Alignment
+- Define the study area extent from the provided polygon
+- Clip all rasters to the study area extent
+- Resample rasters to a common resolution (define target resolution explicitly)
+- Apply the study area mask to remove cells outside the polygon
+
+### 3. Vector Operations
+- Dissolve or simplify study area polygon if needed
+- Create buffers (specify distance and unit)
+- Perform intersection or spatial join between occurrence points and polygon layers
+- Check for topology errors (self-intersections, gaps)
+
+### 4. Environmental Extraction
+- Extract raster values at occurrence and background/pseudo-absence points
+- Handle NA values (edge cells, masked areas): document strategy
+- Check for spatial autocorrelation in extracted values if relevant
+
+### 5. Raster Stack QA
+- Verify all rasters share the same extent, resolution, CRS, and NA mask
+- Report NA cell counts per layer
+- Visualise layer histograms for anomaly detection
+
+### 6. Generate Outputs
+- Write reprojected layers to `layers_reprojected/`
+- Write stacked predictor raster to `predictors_stack.tif`
+- Write points with environmental values to `points_with_env.csv`
+- Write spatial QA report
+
+---
+
+## Key Decisions to Document
+
+- Project CRS (EPSG code)
+- Target raster resolution (and rationale)
+- Resampling method (nearest, bilinear, cubic)
+- NA handling strategy
+- Buffer distance (if used)
+
+---
+
+## Tools and Libraries
+
+**R:** `terra`, `sf`, `rgdal`, `raster`, `landscapemetrics`  
+**Python:** `rasterio`, `geopandas`, `pyproj`, `rasterstats`, `fiona`  
+**CLI:** `GDAL/OGR` (gdalwarp, ogr2ogr, gdal_calc)
+
+---
+
+## Resources
+
+- `resources/crs-reference.md` — common CRS codes for South American biomes
+- `resources/resampling-methods.md` — when to use each resampling method
+- `examples/` — example extraction workflows
+
+---
+
+## Notes
+
+- Always keep original layers intact; write outputs to separate directories
+- Document the GDAL version used for reproducibility
+- For very large rasters (>4 GB), use tiled/chunked processing

package/skills/geoprocessing-for-ecology/examples/example-prompts.md

@@ -0,0 +1,32 @@
+# Example Invocation Prompts — geoprocessing-for-ecology
+
+## Stack and Extract
+
+```
+Load skill: geoprocessing-for-ecology
+Task: I have 19 WorldClim v2.1 rasters (bio1–bio19) at 2.5 arcmin resolution
+and a set of jaguar occurrence points (occ_clean.csv).
+Study area: Amazon biome polygon (amazon_biome.shp).
+1. Reproject everything to EPSG:4326 (already geographic, just check).
+2. Clip rasters to Amazon extent + 1° buffer.
+3. Extract bioclim values at occurrence and 10,000 background points.
+4. Output: predictors_stack.tif, points_with_env.csv.
+```
+
+## Reprojection and Masking
+
+```
+Load skill: geoprocessing-for-ecology
+Task: Reproject landcover_mapbiomas_2022.tif from SIRGAS2000 (EPSG:4674)
+to WGS84 UTM 22S (EPSG:32722). Then mask to the study area polygon
+(cerrado_boundary.gpkg). Use nearest-neighbour resampling. Target resolution: 30m.
+```
+
+## Buffer and Intersection
+
+```
+Load skill: geoprocessing-for-ecology
+Task: Create a 5 km buffer around all hydroelectric dam points (dams.shp).
+Intersect with the Atlantic Forest remnant polygons (af_remnants.gpkg).
+Report: total forest area within 5 km of dams (ha), and number of dam-affected patches.
+```

package/skills/geoprocessing-for-ecology/resources/crs-reference.md

@@ -0,0 +1,62 @@
+# CRS Reference — South American Biomes
+
+## When to Use Each CRS
+
+| Use Case | Recommended CRS | EPSG |
+|----------|----------------|------|
+| Global or continental analysis | WGS 84 Geographic | 4326 |
+| Brazil national (planar, metres) | SIRGAS 2000 / UTM | varies by zone |
+| Area calculations, Amazon biome | SIRGAS 2000 UTM Zone 20S | 31980 |
+| Area calculations, Cerrado | SIRGAS 2000 UTM Zone 22S | 31982 |
+| Area calculations, Atlantic Forest | SIRGAS 2000 UTM Zone 23S | 31983 |
+| Area calculations, Pantanal | SIRGAS 2000 UTM Zone 21S | 31981 |
+| Equal-area, continental South America | South America Albers Equal Area | 102033 |
+| Distance calculations | WGS 84 / World Mercator | 3395 |
+| Remote sensing (MODIS native) | Sinusoidal | 6842 |
+| Landsat / Sentinel (Brazil) | WGS84 UTM zone (varies) | 32718–32724 |
+
+## UTM Zone Reference — Brazil
+
+| Zone | Longitude Range | States |
+|------|----------------|--------|
+| 18S (32718) | 72°W – 66°W | Far western Acre |
+| 19S (32719) | 66°W – 60°W | Acre, Amazonas W |
+| 20S (32720) | 60°W – 54°W | Amazonas, Pará W, Rondônia |
+| 21S (32721) | 54°W – 48°W | MT, MS, PA centre |
+| 22S (32722) | 48°W – 42°W | GO, TO, MG W |
+| 23S (32723) | 42°W – 36°W | SP, RJ, ES, MG E |
+| 24S (32724) | 36°W – 30°W | BA, SE, AL coast |
+| 25S (32725) | 30°W – 24°W | Fernando de Noronha |
+
+## Reprojection Commands
+
+### R (terra)
+```r
+library(terra)
+r <- rast("layer.tif")
+r_proj <- project(r, "EPSG:31982")   # Bilinear for continuous; near for categorical
+```
+
+### Python (rasterio + pyproj)
+```python
+import rasterio
+from rasterio.warp import reproject, Resampling, calculate_default_transform
+
+with rasterio.open("layer.tif") as src:
+    transform, width, height = calculate_default_transform(
+        src.crs, "EPSG:31982", src.width, src.height, *src.bounds)
+```
+
+### GDAL CLI
+```bash
+gdalwarp -t_srs EPSG:31982 -r bilinear input.tif output.tif
+```
+
+## Resampling Method Guide
+
+| Data Type | Method | Note |
+|-----------|--------|------|
+| Continuous (elevation, temperature) | Bilinear | Smooth interpolation |
+| Categorical (land cover, soil class) | Nearest neighbour | Preserves class values |
+| Count or integer | Nearest neighbour or mode | |
+| High-precision DEM | Cubic | Smoother gradients |