ecological-agent-skills 3.1.0

package/skills/ecosystem-services-assessment/scripts/compute_es.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+compute_es.py
+Compute basic ecosystem service indicators from land cover + biophysical data.
+Usage: python compute_es.py <landcover_tif> <carbon_pools_csv> <output_dir>
+Services: carbon storage, erosion control (RUSLE C-factor), pollination habitat index
+Requires: rasterio, numpy, pandas, geopandas
+"""
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "ecosystem-services-assessment"
+_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 rasterio
+from rasterio.transform import rowcol
+
+
+def load_raster(path: str) -> tuple:
+    with rasterio.open(path) as src:
+        data = src.read(1).astype(float)
+        meta = src.meta.copy()
+    return data, meta
+
+def zonal_summary(lc: np.ndarray, es_layer: np.ndarray,
+                  class_codes: list, class_names: dict) -> pd.DataFrame:
+    rows = []
+    for code in class_codes:
+        mask = lc == code
+        if mask.sum() > 0:
+            rows.append({"lulc_code": code,
+                         "lulc_name": class_names.get(code, str(code)),
+                         "n_pixels":  int(mask.sum()),
+                         "mean_es":   round(float(np.nanmean(es_layer[mask])), 4),
+                         "total_es":  round(float(np.nansum(es_layer[mask])), 2)})
+    return pd.DataFrame(rows).sort_values("lulc_code")
+
+def main():
+    lc_file      = sys.argv[1] if len(sys.argv) > 1 else "data/landcover.tif"
+    carbon_file  = sys.argv[2] if len(sys.argv) > 2 else "data/carbon_pools.csv"
+    output_dir   = Path(sys.argv[3]) if len(sys.argv) > 3 else Path("outputs/ecosystem_services")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_decision("lc_file", lc_file, "Input land cover raster")
+    log_decision("carbon_file", carbon_file, "Carbon pools lookup CSV")
+    log_decision("output_dir", str(output_dir), "Directory for ecosystem service outputs")
+
+    if not Path(lc_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",
+            lc_file
+        )
+        sys.exit(1)
+
+    if not Path(carbon_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",
+            carbon_file
+        )
+        sys.exit(1)
+
+    try:
+        log_step(1, "Loading land cover raster")
+        lc, meta = load_raster(lc_file)
+        n_classes = len(np.unique(lc[~np.isnan(lc)]))
+        logger.info("Land cover raster: %s | Classes: %d", lc.shape, n_classes)
+
+        log_step(2, "Loading and validating carbon pools CSV")
+        carbon_df = pd.read_csv(carbon_file)
+        required_cols = ["lucode", "C_above", "C_below", "C_soil", "C_dead"]
+        missing = [c for c in required_cols if c not in carbon_df.columns]
+        if missing:
+            logger.warning(
+                "Carbon pools CSV missing columns: %s. Using zeros for missing fields.", missing
+            )
+            for c in missing:
+                carbon_df[c] = 0
+
+        # ── 1. Carbon storage ──────────────────────────────────────────────────
+        log_step(3, "Computing carbon storage layer")
+        carbon_map = np.full(lc.shape, np.nan)
+        class_names = {}
+        for _, row in carbon_df.iterrows():
+            mask = lc == row["lucode"]
+            total_c = row["C_above"] + row["C_below"] + row["C_soil"] + row["C_dead"]
+            carbon_map[mask] = total_c
+            if "LULC_name" in carbon_df.columns:
+                class_names[int(row["lucode"])] = row["LULC_name"]
+
+        carbon_out = output_dir / "carbon_storage_MgCha.tif"
+        with rasterio.open(carbon_out, "w", **meta) as dst:
+            dst.write(carbon_map.astype(np.float32), 1)
+        logger.info("Carbon: mean = %.1f MgC/ha | Output: %s", np.nanmean(carbon_map), carbon_out)
+
+        # ── 2. RUSLE C-factor (erosion control proxy) ─────────────────────────
+        log_step(4, "Computing RUSLE C-factor erosion control layer")
+        # Default C-factors (add your own mapping)
+        c_factor_defaults = {1: 0.001, 2: 0.005, 3: 0.01, 4: 0.15, 5: 0.30, 6: 1.0}
+        log_decision("c_factor_defaults", c_factor_defaults,
+                     "Default RUSLE C-factors per LULC class; replace with site-specific values")
+        c_map = np.full(lc.shape, np.nan)
+        for code, c_val in c_factor_defaults.items():
+            c_map[lc == code] = c_val
+        # Erosion control ES = avoided erosion = (1 - C_factor); higher = better service
+        erosion_control = 1.0 - c_map
+        unmapped = np.sum(np.isnan(c_map) & ~np.isnan(lc))
+        if unmapped > 0:
+            logger.warning(
+                "%d pixels have no C-factor mapping (not in c_factor_defaults). "
+                "Erosion control will be NaN for those pixels.",
+                unmapped
+            )
+        erosion_out = output_dir / "erosion_control_index.tif"
+        with rasterio.open(erosion_out, "w", **meta) as dst:
+            dst.write(erosion_control.astype(np.float32), 1)
+        logger.info("Erosion control layer written: %s", erosion_out)
+
+        # ── 3. Pollination habitat index ─────────────────────────────────────
+        log_step(5, "Computing pollination habitat index layer")
+        # Natural / semi-natural = high value (1); crops = partial (0.5); urban/bare = 0
+        pollination_suitability = {1: 1.0, 2: 0.8, 3: 0.7, 4: 0.3, 5: 0.1, 6: 0.0}
+        log_decision("pollination_suitability", pollination_suitability,
+                     "Expert-based pollination suitability scores per LULC class")
+        poll_map = np.full(lc.shape, np.nan)
+        for code, val in pollination_suitability.items():
+            poll_map[lc == code] = val
+        poll_out = output_dir / "pollination_habitat.tif"
+        with rasterio.open(poll_out, "w", **meta) as dst:
+            dst.write(poll_map.astype(np.float32), 1)
+        logger.info("Pollination habitat layer written: %s", poll_out)
+
+        # ── Summary table ─────────────────────────────────────────────────────
+        log_step(6, "Building zonal summary table")
+        class_codes = [int(c) for c in np.unique(lc[~np.isnan(lc)])]
+        summary = zonal_summary(lc, carbon_map, class_codes, class_names)
+        summary["erosion_control_mean"] = [
+            round(float(np.nanmean(erosion_control[lc == c])), 4)
+            if np.any(lc == c) else np.nan for c in class_codes]
+        summary["pollination_mean"] = [
+            round(float(np.nanmean(poll_map[lc == c])), 4)
+            if np.any(lc == c) else np.nan for c in class_codes]
+        summary_out = output_dir / "es_summary_table.csv"
+        summary.to_csv(summary_out, index=False)
+        logger.info("ES summary:\n%s", summary.to_string(index=False))
+        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 ecosystem services assessment: %s", e)
+        raise
+
+if __name__ == "__main__":
+    main()

package/skills/ecosystem-services-assessment/scripts/tradeoff_analysis.R

@@ -0,0 +1,161 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript tradeoff_analysis.R <es_summary_table.csv> <output_dir>
+# ES trade-off and synergy analysis across pixels or land cover units
+# Usage: Rscript tradeoff_analysis.R <es_summary_csv> <output_dir>
+# Requires: dplyr, ggplot2, corrplot, tidyr
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "ecosystem-services-assessment"
+.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(dplyr)
+  library(ggplot2)
+  library(corrplot)
+  library(tidyr)
+})
+
+args       <- commandArgs(trailingOnly = TRUE)
+es_file    <- ifelse(length(args) >= 1, args[1], "outputs/ecosystem_services/es_summary_table.csv")
+output_dir <- ifelse(length(args) >= 2, args[2], "outputs/ecosystem_services")
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_info("Skill: %s | es_file=%s | output_dir=%s", SKILL_NAME, es_file, output_dir)
+
+# ── Input precondition check ──────────────────────────────────────────────────
+if (!file.exists(es_file)) {
+  log_error(
+    "Input nao encontrado: %s\nCausa provavel: o script de quantificacao de servicos ecossistemicos nao foi executado ou o caminho esta errado.\nVerifique: execute primeiro o script de mapeamento/quantificacao de ES.\nSkill anterior: ecosystem-services-assessment (quantification step).",
+    es_file
+  )
+  stop("Missing: ", es_file)
+}
+
+log_step(1, "Carregar tabela de servicos ecossistemicos")
+es <- tryCatch({
+  read.csv(es_file)
+}, error = function(e) {
+  log_error(
+    "Falha ao ler CSV de servicos ecossistemicos: %s\nCausa provavel: arquivo corrompido ou com separador incorreto.\nVerifique: abra o arquivo em editor de texto e confira o formato.\nSkill anterior: ecosystem-services-assessment (quantification step).",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Tabela de ES carregada: %d classes de uso do solo", nrow(es))
+
+n_na_total <- sum(is.na(es))
+if (n_na_total > 0) {
+  log_warn("Tabela de ES contem %d valores NA no total — correlacoes serao calculadas com 'complete.obs'.", n_na_total)
+}
+
+# ── Identify numeric ES columns ───────────────────────────────────────────────
+log_step(2, "Identificar colunas de indicadores de ES e normalizar 0-1")
+es_cols <- names(es)[sapply(es, is.numeric) & !names(es) %in% c("lulc_code", "n_pixels")]
+log_info("Indicadores de ES: %s", paste(es_cols, collapse = ", "))
+log_decision("es_cols", paste(es_cols, collapse = ", "),
+             "colunas numericas excluindo lulc_code e n_pixels sao tratadas como indicadores de ES")
+
+if (length(es_cols) < 2) {
+  log_warn("Menos de 2 indicadores de ES encontrados — analise de trade-off nao e possivel com apenas %d coluna(s).", length(es_cols))
+  log_info("Encerrando sem erro. Adicione mais indicadores ao CSV de entrada.")
+  quit(status = 0)
+}
+
+# ── Normalise to 0-1 ──────────────────────────────────────────────────────────
+es_norm <- tryCatch({
+  es |>
+    mutate(across(all_of(es_cols),
+                  ~ (. - min(., na.rm=TRUE)) / (max(., na.rm=TRUE) - min(., na.rm=TRUE) + 1e-10)))
+}, error = function(e) {
+  log_error(
+    "Falha na normalizacao 0-1 dos indicadores: %s\nCausa provavel: colunas nao numericas identificadas incorretamente.\nVerifique: os tipos de coluna no CSV de entrada.\nSkill anterior: ecosystem-services-assessment (quantification step).",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_decision("normalization", "min-max [0,1] com epsilon 1e-10",
+             "evita divisao por zero quando todos os valores de um indicador sao iguais")
+
+# ── Correlation matrix (Spearman) ─────────────────────────────────────────────
+log_step(3, "Calcular matriz de correlacao de Spearman entre indicadores de ES")
+cor_mat <- tryCatch({
+  cor(es_norm[es_cols], method = "spearman", use = "complete.obs")
+}, error = function(e) {
+  log_error(
+    "Falha ao calcular matriz de correlacao: %s\nCausa provavel: todos os valores de alguma coluna sao NA apos normalizacao.\nVerifique: presenca de variacao nos indicadores de ES.\nSkill anterior: ecosystem-services-assessment (quantification step).",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_decision("correlation_method", "Spearman",
+             "metodo nao-parametrico robusto a distribuicoes assimetricas comuns em dados de ES")
+
+tryCatch({
+  write.csv(as.data.frame(cor_mat), file.path(output_dir, "tradeoff_matrix.csv"))
+  log_info("tradeoff_matrix.csv salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao salvar tradeoff_matrix.csv: %s\nCausa provavel: permissao negada ou disco cheio.\nVerifique: permissoes do diretorio de saida.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── Correlation heatmap ────────────────────────────────────────────────────────
+log_step(4, "Gerar heatmap de trade-offs (corrplot)")
+tryCatch({
+  png(file.path(output_dir, "tradeoff_heatmap.png"), width = 800, height = 700, res = 150)
+  corrplot(cor_mat, method = "color", type = "upper", tl.cex = 0.8,
+           addCoef.col = "black", number.cex = 0.7, cl.cex = 0.7,
+           title = "ES Trade-offs (Spearman r)", mar = c(0, 0, 2, 0))
+  dev.off()
+  log_info("tradeoff_heatmap.png salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao gerar heatmap de trade-offs: %s\nCausa provavel: corrplot nao instalado ou matriz de correlacao invalida.\nVerifique: se o pacote corrplot esta disponivel e a matriz tem pelo menos 2 variaveis.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── Scatter plots for top pairs ───────────────────────────────────────────────
+log_step(5, "Gerar graficos de dispersao para pares de indicadores de ES")
+pair_combos <- combn(es_cols, 2, simplify = FALSE)
+n_pairs     <- min(6, length(pair_combos))
+log_info("Gerando %d graficos de dispersao (de %d pares possiveis)", n_pairs, length(pair_combos))
+log_decision("max_scatter_plots", as.character(n_pairs),
+             "limitado a 6 pares para evitar geracao excessiva de arquivos")
+
+for (pr in pair_combos[seq_len(n_pairs)]) {
+  tryCatch({
+    p <- ggplot(es |> mutate(label = lulc_code),
+                aes(x = .data[[pr[1]]], y = .data[[pr[2]]], label = label)) +
+      geom_point(size = 3, colour = "#2166ac") +
+      ggrepel::geom_text_repel(size = 2.5, max.overlaps = 10) +
+      labs(x = pr[1], y = pr[2],
+           title = paste("Trade-off:", pr[1], "vs", pr[2])) +
+      theme_bw()
+    fname <- paste0("scatter_", pr[1], "_vs_", pr[2], ".png")
+    ggsave(file.path(output_dir, fname), p, width = 5, height = 4, dpi = 150)
+    log_info("Salvo: %s", fname)
+  }, error = function(e) {
+    log_error(
+      "Falha ao gerar grafico de dispersao para par %s vs %s: %s\nCausa provavel: coluna ausente apos filtragem ou problema com ggrepel.\nVerifique: se as colunas '%s' e '%s' existem e possuem dados validos.\nSkill anterior: nenhuma.",
+      pr[1], pr[2], conditionMessage(e), pr[1], pr[2]
+    )
+    stop(e)
+  })
+}
+
+log_info("Analise de trade-off concluida. Saidas em: %s", output_dir)

package/skills/environmental-time-series/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: environmental-time-series
+description: "Detects trends, breakpoints, and recovery trajectories in environmental time series data from remote sensing or field measurements. Use this skill when the user mentions time series analysis, NDVI/EVI/LST trends, Mann-Kendall tests, Sen slope, BFAST breakpoints, structural change detection, seasonal decomposition (STL), anomaly detection, recovery trajectories, regime shifts, or pixel-wise trend analysis."
+skill_version: 1.0.0
+---
+
+# Skill: environmental-time-series
+
+**Domain:** Trend · Seasonality · Breakpoints · Anomalies · Recovery  
+**Phase:** 2 — Modeling  
+**Used by:** build-fire-risk-map, analyze-environmental-change
+
+---
+
+## Purpose
+
+Guides the agent through the analysis of environmental and ecological time series: trend detection, seasonal decomposition, structural breakpoint identification, anomaly detection, and post-disturbance recovery trajectory estimation.
+
+---
+
+## When to Invoke
+
+- Analysing NDVI, EVI, LST, rainfall, or any environmental time series
+- Detecting trend direction and magnitude in ecological indicators
+- Identifying regime shifts or abrupt changes in a time series
+- Characterising anomalies relative to historical baseline
+- Estimating recovery time after a disturbance event
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Time-indexed environmental variable | CSV or GeoTIFF time stack | Yes |
+| Time series frequency (daily, monthly, annual) | Text | Yes |
+| Disturbance event date (for recovery) | Date | Conditional |
+| Historical baseline period | Date range | Recommended |
+
+---
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `trend_results.csv` | Trend slope, magnitude, p-value per pixel or site |
+| `seasonal_decomposition.png` | STL decomposition plot |
+| `breakpoints.csv` | Detected breakpoint dates with confidence intervals |
+| `anomaly_series.csv` | Standardised anomaly per time step |
+| `recovery_metrics.csv` | Recovery rate and 80/100% recovery date |
+| `timeseries_report.md` | Analysis narrative |
+
+---
+
+## Steps
+
+### 1. Inspect and Clean the Series
+- Plot raw series; identify obvious outliers, data gaps, sensor artifacts
+- Interpolate short gaps (≤ 3 steps) if justified; document method
+- Report temporal extent, frequency, and missing value rate
+
+### 2. Trend Detection
+- Mann-Kendall test for monotonic trend (non-parametric, handles non-normality)
+- Sen's slope estimator for trend magnitude
+- For raster: pixel-wise MK + Sen's slope
+- Report τ (Kendall's tau), p-value, and slope in original units/year
+
+### 3. Seasonal Decomposition
+- STL decomposition (Seasonal-Trend decomposition using LOESS): robust to outliers
+- Report seasonal amplitude, trend component, and remainder
+- For annual data with no seasonality, skip this step
+
+### 4. Breakpoint Detection
+- BFAST (Breaks For Additive Season and Trend): simultaneous trend and breakpoint
+- `strucchange` (R) for structural change tests
+- Report: number of breakpoints, dates, 95% CIs
+- Verify detected breakpoints against known events (fire, drought, deforestation)
+
+### 5. Anomaly Detection
+- Compute historical baseline (mean ± SD or percentiles) from reference period
+- Standardised anomaly: z = (x − μ) / σ
+- Flag values beyond ±2σ as anomalous
+- For rainfall: SPI (Standardised Precipitation Index)
+- For vegetation: VCI (Vegetation Condition Index) or zNDVI
+
+### 6. Recovery Trajectory (post-disturbance)
+- Define pre-disturbance baseline from N years before event
+- Fit recovery curve: linear, exponential, or logistic
+- Estimate: time to 80% recovery, time to full recovery
+- Compute Recovery Indicator (RI) = (post − min) / (pre − min)
+
+---
+
+## Key Decisions to Document
+
+- Baseline period definition
+- Gap interpolation method
+- Seasonal decomposition method and parameters
+- Breakpoint detection method and significance level
+- Anomaly threshold (z-score cutoff)
+- Recovery model type
+
+---
+
+## Tools and Libraries
+
+**R:** `bfast`, `strucchange`, `trend`, `zoo`, `terra`, `ggplot2`  
+**Python:** `pymannkendall`, `ruptures`, `statsmodels.tsa`, `xarray`  
+**Remote sensing:** Google Earth Engine (pixel-wise BFAST, trend)
+
+---
+
+## Resources
+
+- `resources/bfast-parameter-guide.md` — how to set h, season, and type in BFAST
+- `resources/anomaly-indices-reference.md` — SPI, VCI, zNDVI definitions
+- `examples/` — worked BFAST and recovery analysis example
+
+---
+
+## Notes
+
+- Autocorrelation in time series violates independence assumptions of standard tests; use MK which handles it
+- BFAST requires at least 3 full seasonal cycles to be reliable
+- For raster time series > 10 years monthly, consider GEE for computational efficiency

package/skills/environmental-time-series/examples/example-prompts.md

@@ -0,0 +1,33 @@
+# Example Invocation Prompts — environmental-time-series
+
+## NDVI Trend and Breakpoint Analysis
+
+```
+Load skill: environmental-time-series
+Task: Analyse long-term NDVI trends in the Cerrado (2001–2023) from MODIS MOD13A3.
+
+Input: data/ndvi_monthly_cerrado.csv
+  Columns: date (YYYY-MM-DD), pixel_id, ndvi (0–1 scaled)
+
+Steps:
+1. STL decomposition (period = 12 months).
+2. Mann-Kendall trend test + Sen's slope per pixel (or aggregated if single site).
+3. BFAST breakpoint detection (h = 0.15, season = "harmonic").
+4. Standardised anomaly relative to 2001–2010 baseline.
+5. Report: trend slope (NDVI/year), breakpoint dates, anomaly time series.
+Output: trend_results.csv, breakpoints.csv, decomposition_plot.png, anomaly_series.csv
+```
+
+## Post-Fire Recovery
+
+```
+Load skill: environmental-time-series
+Task: Estimate vegetation recovery trajectory after the 2020 fires in the Pantanal.
+Fire event date: 2020-07-01.
+Pre-fire baseline: 2015-01-01 to 2020-06-30.
+Data: data/ndvi_pantanal_recovery.csv (monthly NDVI per burned polygon, 2015–2023)
+
+Fit recovery curve (logistic or exponential).
+Compute: Recovery Indicator (RI) per year, estimated time to 80% and 100% recovery.
+Output: recovery_metrics.csv, recovery_curves.png
+```

package/skills/environmental-time-series/resources/anomaly-indices-reference.md

@@ -0,0 +1,88 @@
+# Environmental Anomaly Indices Reference
+
+## Standardised Precipitation Index (SPI)
+
+Measures rainfall deficit/surplus relative to a long-term distribution, at multiple time scales.
+
+| SPI value | Category |
+|-----------|---------|
+| > 2.0 | Extremely wet |
+| 1.5 to 2.0 | Very wet |
+| 1.0 to 1.5 | Moderately wet |
+| -1.0 to 1.0 | Near normal |
+| -1.5 to -1.0 | Moderately dry |
+| -2.0 to -1.5 | Severely dry |
+| < -2.0 | Extremely dry |
+
+Time scales: SPI-1 (monthly), SPI-3 (seasonal), SPI-6, SPI-12 (annual drought).
+
+```r
+library(SPEI)
+data(wichita)  # example dataset
+spi_3 <- spi(wichita$PRCP, scale = 3)
+plot(spi_3)
+```
+
+## Standardised Precipitation Evapotranspiration Index (SPEI)
+
+Like SPI but accounts for evapotranspiration (temperature effect). Better for drought assessment under warming climate.
+
+```r
+spei_12 <- spei(wichita$PRCP - wichita$PET, scale = 12)
+```
+
+## Vegetation Condition Index (VCI)
+
+Normalises NDVI relative to historical minimum and maximum for the same period of year.
+
+VCI = 100 × (NDVI − NDVI_min) / (NDVI_max − NDVI_min)
+
+| VCI | Vegetation condition |
+|-----|---------------------|
+| 0–10 | Extreme stress |
+| 10–20 | Severe stress |
+| 20–40 | Moderate stress |
+| 40–60 | Good condition |
+| 60–80 | Very good |
+| 80–100 | Excellent |
+
+```python
+import numpy as np
+# NDVI time stack (time × lat × lon)
+vci = 100 * (ndvi - ndvi.min(axis=0)) / (ndvi.max(axis=0) - ndvi.min(axis=0) + 1e-6)
+```
+
+## Standardised NDVI Anomaly (zNDVI)
+
+zNDVI = (NDVI_i − μ_NDVI) / σ_NDVI
+
+where μ and σ are computed per pixel over the baseline period (same calendar period).
+
+Interpretation: zNDVI < -1.5 indicates vegetation stress; zNDVI < -2.0 indicates severe anomaly.
+
+## Temperature Anomaly
+
+T_anomaly = T_i − T_climatological_mean (for the same month/season)
+
+## Recovery Indicator (RI)
+
+Post-disturbance vegetation recovery relative to pre-disturbance baseline:
+
+RI_t = (NDVI_t − NDVI_min) / (NDVI_pre − NDVI_min)
+
+- RI = 0: at the lowest post-disturbance value
+- RI = 1: full recovery to pre-disturbance level
+- RI < 0: further decline after disturbance
+- RI > 1: exceeds pre-disturbance level (e.g., fire-stimulated flush)
+
+## Reference Datasets
+
+| Variable | Product | Resolution | Source |
+|----------|---------|-----------|--------|
+| NDVI (8-day) | MODIS MOD13Q1 | 250 m | NASA LP DAAC |
+| NDVI (monthly) | MODIS MOD13A3 | 1 km | NASA LP DAAC |
+| NDVI (daily, 10 m) | Sentinel-2 (Harmonized) | 10 m | Copernicus / GEE |
+| Rainfall | CHIRPS v2.0 | 5 km | UCSB Climate Hazards Group |
+| Rainfall | ERA5-Land | 9 km | ECMWF |
+| LST | MODIS MOD11A2 | 1 km | NASA LP DAAC |
+| SPI | Global SPEI Database | 0.5° | CSIC Spain |

package/skills/environmental-time-series/resources/bfast-parameter-guide.md

@@ -0,0 +1,69 @@
+# BFAST Parameter Guide
+
+BFAST (Breaks For Additive Season and Trend) detects breakpoints in both the seasonal and trend components of a time series simultaneously.
+
+## Key Parameters
+
+### `h` — Minimum Segment Size
+Minimum proportion of observations between two consecutive breakpoints.
+- Default: `h = 0.15` (15% of n observations)
+- Example: for n = 120 monthly observations, h = 0.15 means ≥ 18 observations per segment (≥ 1.5 years)
+- **Set smaller** if breakpoints may occur close together
+- **Set larger** to avoid detecting noise as breakpoints
+
+### `season` — Seasonal Model
+- `"harmonic"`: Fourier terms (sine + cosine); recommended for MODIS NDVI, temperature
+- `"dummy"`: Dummy variables for each period; less flexible
+- `"none"`: No seasonal component; for annual time series
+
+### `max.iter` — Maximum Iterations
+- Default: `max.iter = 10`
+- Increase to 20–50 for complex time series that do not converge quickly
+
+### `breaks` — Maximum Number of Breakpoints
+- Default: `NULL` (auto-select by BIC)
+- Set `breaks = 1` to force detection of at most 1 breakpoint
+- Set `breaks = 5` for long series with multiple expected events
+
+### `type` — Type of Breakpoint Test
+- `"OLS-MOSUM"` (default): Fast; appropriate for most cases
+- `"OLS-CUSUM"`: More sensitive to gradual changes
+- `"DYNP"`: Dynamic programming; exact but slow for large n
+
+## Typical MODIS NDVI Configuration
+
+```r
+library(bfast)
+
+# Monthly NDVI time series (16-day composites aggregated to monthly)
+ts_ndvi <- ts(ndvi_vector, start = c(2000, 1), frequency = 12)
+
+fit <- bfast(ts_ndvi,
+             h        = 0.15,
+             season   = "harmonic",
+             max.iter = 20,
+             breaks   = NULL)
+
+# Extract results
+if (fit$output[[1]]$Tt.bp > 0) {  # breakpoints detected
+  bp_dates <- fit$output[[1]]$bp.Vt$breakpoints
+  cat("Breakpoints at observations:", bp_dates, "\n")
+}
+
+plot(fit)
+```
+
+## Interpreting Outputs
+
+| Component | Meaning |
+|-----------|---------|
+| `Tt` | Trend component with breakpoints |
+| `St` | Seasonal component with breakpoints |
+| `Nt` | Remainder (noise) |
+| `bp.Vt` | Trend breakpoints (indices) |
+| `bp.Wt` | Seasonal breakpoints (indices) |
+
+## Minimum Series Length
+- At least **3 full seasonal cycles** are required
+- For monthly data: ≥ 36 observations (3 years)
+- For 16-day MODIS: ≥ 69 observations (≥ 3 years)