ecological-agent-skills 3.1.0

package/skills/ecological-impact-assessment/scripts/power_analysis_baci.R

@@ -0,0 +1,274 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript power_analysis_baci.R <output_dir> [effect_size] [n_sites] [n_surveys] [alpha] [variance_estimate]
+# Compute statistical power for BACI designs and recommend minimum sample sizes.
+# Outputs: power_curves.png, power_summary.csv, minimum_n_recommendation.md
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "ecological-impact-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(ggplot2)
+  library(pwr)
+})
+
+# ── Arguments ─────────────────────────────────────────────────────────────────
+args              <- commandArgs(trailingOnly = TRUE)
+output_dir        <- if (length(args) >= 1) args[1] else "outputs/power_analysis"
+effect_size       <- if (length(args) >= 2) as.numeric(args[2]) else 0.5
+n_sites           <- if (length(args) >= 3) as.integer(args[3]) else 10
+n_surveys         <- if (length(args) >= 4) as.integer(args[4]) else 4
+alpha             <- if (length(args) >= 5) as.numeric(args[5]) else 0.05
+variance_estimate <- if (length(args) >= 6) as.numeric(args[6]) else 1.0
+
+log_decision("effect_size", effect_size,
+  "Cohen's d: 0.2=small, 0.5=medium, 0.8=large. Use 0.5 if no pilot data available.")
+log_decision("n_sites",   n_sites,
+  "Number of control + impact sites each side. Minimum recommended: 5 per group.")
+log_decision("n_surveys", n_surveys,
+  "Survey occasions before + after. Minimum recommended: 3 pre + 3 post = 6 total.")
+log_decision("alpha",     alpha,
+  "Type I error rate. Standard: 0.05. Use 0.10 for preliminary screening.")
+log_decision("variance_estimate", variance_estimate,
+  "Within-group variance from pilot data or literature. Affects Cohen's d calculation.")
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+# ── Helper: BACI power ────────────────────────────────────────────────────────
+# BACI interaction term is tested as a two-sample t-test on the difference-in-differences.
+# Effective n per group = n_sites * n_surveys (repeated measures increase precision).
+# Cohen's d adjusted for variance: d = effect_size / sqrt(variance_estimate)
+
+baci_power <- function(n_s, n_sv, eff, var_est, a) {
+  d_adj  <- eff / sqrt(var_est)
+  n_eff  <- n_s * n_sv          # effective replication per group (control or impact)
+  result <- tryCatch(
+    pwr.t.test(n = n_eff, d = d_adj, sig.level = a, type = "two.sample",
+               alternative = "two.sided"),
+    error = function(e) NULL
+  )
+  if (is.null(result)) return(NA_real_)
+  result$power
+}
+
+# ── Step 1: Curves — power × n_sites (n_surveys fixed) ───────────────────────
+log_step(1, "Computing power × n_sites curve")
+sites_range <- 2:30
+pow_vs_sites <- data.frame(
+  n_sites  = sites_range,
+  power    = sapply(sites_range, baci_power,
+                    n_sv = n_surveys, eff = effect_size,
+                    var_est = variance_estimate, a = alpha)
+)
+log_info("Power at n_sites=%d (n_surveys=%d fixed): %.3f",
+         n_sites, n_surveys, baci_power(n_sites, n_surveys, effect_size, variance_estimate, alpha))
+
+# ── Step 2: Curves — power × n_surveys (n_sites fixed) ───────────────────────
+log_step(2, "Computing power × n_surveys curve")
+surveys_range <- 1:20
+pow_vs_surveys <- data.frame(
+  n_surveys = surveys_range,
+  power     = sapply(surveys_range, function(sv)
+    baci_power(n_sites, sv, effect_size, variance_estimate, alpha))
+)
+
+# ── Step 3: Curves — power × effect_size ─────────────────────────────────────
+log_step(3, "Computing power × effect_size curve")
+eff_range <- seq(0.1, 1.5, by = 0.05)
+pow_vs_eff <- data.frame(
+  effect_size = eff_range,
+  power       = sapply(eff_range, baci_power,
+                       n_s = n_sites, n_sv = n_surveys,
+                       var_est = variance_estimate, a = alpha)
+)
+
+# ── Step 4: Minimum n calculations ────────────────────────────────────────────
+log_step(4, "Calculating minimum n for power = 0.80 and 0.90")
+
+find_min_n_sites <- function(target_power, n_sv, eff, var_est, a) {
+  for (ns in 2:200) {
+    if (!is.na(baci_power(ns, n_sv, eff, var_est, a)) &&
+        baci_power(ns, n_sv, eff, var_est, a) >= target_power) return(ns)
+  }
+  return(NA_integer_)
+}
+find_min_n_surveys <- function(target_power, ns, eff, var_est, a) {
+  for (nv in 1:100) {
+    if (!is.na(baci_power(ns, nv, eff, var_est, a)) &&
+        baci_power(ns, nv, eff, var_est, a) >= target_power) return(nv)
+  }
+  return(NA_integer_)
+}
+
+min_sites_80  <- find_min_n_sites(0.80, n_surveys, effect_size, variance_estimate, alpha)
+min_sites_90  <- find_min_n_sites(0.90, n_surveys, effect_size, variance_estimate, alpha)
+min_surveys_80<- find_min_n_surveys(0.80, n_sites, effect_size, variance_estimate, alpha)
+min_surveys_90<- find_min_n_surveys(0.90, n_sites, effect_size, variance_estimate, alpha)
+
+log_info("Min sites for power=0.80: %d | power=0.90: %d (surveys=%d fixed)",
+         min_sites_80, min_sites_90, n_surveys)
+log_info("Min surveys for power=0.80: %d | power=0.90: %d (sites=%d fixed)",
+         min_surveys_80, min_surveys_90, n_sites)
+
+if (is.na(min_sites_80)) {
+  log_warn("Power 0.80 not achievable with sites<=200. Increase effect_size or reduce variance_estimate.")
+}
+
+# ── Step 5: Power curves plot ─────────────────────────────────────────────────
+log_step(5, "Generating power curves plot")
+tryCatch({
+  p1 <- ggplot(pow_vs_sites, aes(n_sites, power)) +
+    geom_line(colour = "#2471a3", linewidth = 1) +
+    geom_hline(yintercept = c(0.80, 0.90), linetype = "dashed",
+               colour = c("#e74c3c","#27ae60")) +
+    geom_vline(xintercept = c(min_sites_80, min_sites_90), linetype = "dotted",
+               colour = c("#e74c3c","#27ae60")) +
+    annotate("text", x = min_sites_80 + 0.5, y = 0.05,
+             label = paste0("n=", min_sites_80, "\n(80%)"), hjust = 0, size = 3, colour = "#e74c3c") +
+    annotate("text", x = min_sites_90 + 0.5, y = 0.05,
+             label = paste0("n=", min_sites_90, "\n(90%)"), hjust = 0, size = 3, colour = "#27ae60") +
+    scale_y_continuous(limits = c(0, 1), labels = scales::percent) +
+    labs(title = paste0("BACI Power vs. Sites (n_surveys=", n_surveys, " fixed)"),
+         x = "Number of sites per group", y = "Statistical Power") +
+    theme_bw()
+
+  p2 <- ggplot(pow_vs_surveys, aes(n_surveys, power)) +
+    geom_line(colour = "#8e44ad", linewidth = 1) +
+    geom_hline(yintercept = c(0.80, 0.90), linetype = "dashed",
+               colour = c("#e74c3c","#27ae60")) +
+    scale_y_continuous(limits = c(0, 1), labels = scales::percent) +
+    labs(title = paste0("BACI Power vs. Surveys (n_sites=", n_sites, " fixed)"),
+         x = "Survey occasions (before + after)", y = "Statistical Power") +
+    theme_bw()
+
+  p3 <- ggplot(pow_vs_eff, aes(effect_size, power)) +
+    geom_line(colour = "#e67e22", linewidth = 1) +
+    geom_hline(yintercept = c(0.80, 0.90), linetype = "dashed",
+               colour = c("#e74c3c","#27ae60")) +
+    geom_vline(xintercept = effect_size, linetype = "dotted", colour = "grey40") +
+    scale_y_continuous(limits = c(0, 1), labels = scales::percent) +
+    labs(title = paste0("BACI Power vs. Effect Size (n=", n_sites, " sites, ",
+                        n_surveys, " surveys)"),
+         x = "Effect size (Cohen's d)", y = "Statistical Power") +
+    theme_bw()
+
+  suppressPackageStartupMessages(library(patchwork))
+  combined <- p1 / p2 / p3
+  plot_file <- file.path(output_dir, "power_curves.png")
+  ggsave(plot_file, combined, width = 8, height = 12, dpi = 150)
+  log_info("Power curves plot saved: %s", plot_file)
+}, error = function(e) {
+  log_warn("Plot generation failed: %s. Trying base graphics fallback.", conditionMessage(e))
+  tryCatch({
+    png(file.path(output_dir, "power_curves.png"), width = 800, height = 900)
+    par(mfrow = c(3, 1), mar = c(4, 4, 3, 1))
+    plot(pow_vs_sites$n_sites, pow_vs_sites$power, type = "l", col = "#2471a3", lwd = 2,
+         ylim = c(0,1), xlab = "Sites per group", ylab = "Power",
+         main = paste0("BACI Power vs Sites (surveys=", n_surveys, ")"))
+    abline(h = c(0.8, 0.9), lty = 2, col = c("red","darkgreen"))
+    plot(pow_vs_surveys$n_surveys, pow_vs_surveys$power, type = "l", col = "#8e44ad", lwd = 2,
+         ylim = c(0,1), xlab = "Survey occasions", ylab = "Power",
+         main = paste0("BACI Power vs Surveys (sites=", n_sites, ")"))
+    abline(h = c(0.8, 0.9), lty = 2, col = c("red","darkgreen"))
+    plot(pow_vs_eff$effect_size, pow_vs_eff$power, type = "l", col = "#e67e22", lwd = 2,
+         ylim = c(0,1), xlab = "Effect size (Cohen's d)", ylab = "Power",
+         main = "BACI Power vs Effect Size")
+    abline(h = c(0.8, 0.9), lty = 2, col = c("red","darkgreen"))
+    dev.off()
+    log_info("Base-graphics power curves saved.")
+  }, error = function(e2) {
+    log_error("Falha ao gerar grafico de poder: %s\nCausa provavel: pwr ou ggplot2 nao instalados.\nVerifique: install.packages(c('pwr','ggplot2','patchwork'))", conditionMessage(e2))
+  })
+})
+
+# ── Step 6: Power summary CSV ──────────────────────────────────────────────────
+log_step(6, "Saving power summary CSV")
+power_current <- baci_power(n_sites, n_surveys, effect_size, variance_estimate, alpha)
+
+summary_df <- data.frame(
+  parameter           = c("effect_size","n_sites","n_surveys","alpha","variance_estimate",
+                           "power_current","min_sites_power80","min_sites_power90",
+                           "min_surveys_power80","min_surveys_power90"),
+  value               = c(effect_size, n_sites, n_surveys, alpha, variance_estimate,
+                           round(power_current, 4),
+                           min_sites_80, min_sites_90,
+                           min_surveys_80, min_surveys_90),
+  stringsAsFactors    = FALSE
+)
+csv_file <- file.path(output_dir, "power_summary.csv")
+write.csv(summary_df, csv_file, row.names = FALSE)
+log_info("Power summary saved: %s", csv_file)
+
+# ── Step 7: Recommendation markdown ───────────────────────────────────────────
+log_step(7, "Writing minimum-n recommendation report")
+adequacy <- if (!is.na(power_current) && power_current >= 0.80) "ADEQUATE" else "INSUFFICIENT"
+rec_lines <- c(
+  "# BACI Power Analysis — Field Protocol Recommendation",
+  "",
+  paste0("Generated: ", Sys.time()),
+  "",
+  "## Input Parameters",
+  paste0("- **Effect size (Cohen's d):** ", effect_size),
+  paste0("- **Number of sites (per group):** ", n_sites),
+  paste0("- **Survey occasions (before + after):** ", n_surveys),
+  paste0("- **Significance level (α):** ", alpha),
+  paste0("- **Variance estimate:** ", variance_estimate),
+  "",
+  "## Current Design Power",
+  paste0("**Statistical power = ", round(power_current * 100, 1), "%** (", adequacy, ")"),
+  "",
+  ifelse(adequacy == "INADEQUATE",
+    "> ⚠️ **WARNING:** The current design has insufficient power to detect the target effect.",
+    "> ✅ The current design has adequate power to detect the target effect."),
+  "",
+  "## Minimum Sample Size Recommendations",
+  "",
+  paste0("### To achieve power = 80% (α = ", alpha, ")"),
+  paste0("- **Sites per group:** ≥ ",
+         ifelse(is.na(min_sites_80), "not achievable with ≤200 sites", min_sites_80),
+         " (with ", n_surveys, " survey occasions)"),
+  paste0("- **Survey occasions:** ≥ ",
+         ifelse(is.na(min_surveys_80), "not achievable", min_surveys_80),
+         " (with ", n_sites, " sites)"),
+  "",
+  paste0("### To achieve power = 90% (α = ", alpha, ")"),
+  paste0("- **Sites per group:** ≥ ",
+         ifelse(is.na(min_sites_90), "not achievable with ≤200 sites", min_sites_90),
+         " (with ", n_surveys, " survey occasions)"),
+  paste0("- **Survey occasions:** ≥ ",
+         ifelse(is.na(min_surveys_90), "not achievable", min_surveys_90),
+         " (with ", n_sites, " sites)"),
+  "",
+  "## Interpretation",
+  paste0("- A Cohen's d of **", effect_size, "** corresponds to detecting a ",
+         round(effect_size * sqrt(variance_estimate), 3),
+         " unit difference between impact and control sites, adjusting for σ² = ", variance_estimate, "."),
+  "- **Rule of thumb:** BACI studies should have ≥5 control and ≥5 impact sites,",
+  "  with ≥3 survey occasions before and ≥3 after the impact.",
+  "- If power is insufficient, prioritise adding **sites** (stronger than adding surveys)",
+  "  because spatial replication reduces pseudo-replication bias.",
+  "",
+  "## How to Obtain Variance Estimate",
+  "1. **From pilot data:** compute SD of the response variable across sites, then var = SD².",
+  "2. **From literature:** use SD values reported for the same metric and habitat type.",
+  "3. **Conservative default:** use variance_estimate = 1.0 (corresponds to Cohen's d units).",
+  "",
+  "## References",
+  "- Cohen, J. (1988). *Statistical Power Analysis for the Behavioral Sciences* (2nd ed.).",
+  "- Underwood, A.J. (1994). On beyond BACI. *Ecological Applications*, 4(1), 3–15.",
+  "- Stewart-Oaten, A. & Bence, J.R. (2001). Temporal and spatial variation in",
+  "  environmental impact assessment. *Ecological Monographs*, 71(2), 305–339."
+)
+md_file <- file.path(output_dir, "minimum_n_recommendation.md")
+writeLines(rec_lines, md_file)
+log_info("Recommendation report saved: %s", md_file)
+
+log_step(8, "Done — power analysis outputs in: %s", output_dir)

package/skills/ecosystem-services-assessment/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ecosystem-services-assessment
+description: "Maps and quantifies ecosystem services including carbon stocks, water yield, soil erosion, and habitat quality with trade-off analysis. Use this skill when the user mentions ecosystem services, InVEST models, ES mapping, carbon sequestration, water yield estimation, RUSLE erosion modeling, habitat quality, pollination services, trade-off analysis, PES (payments for ecosystem services), natural capital, or ES valuation."
+skill_version: 1.0.0
+---
+
+# Skill: ecosystem-services-assessment
+
+**Domain:** ES indicators · Provisioning · Regulating · Cultural · Trade-offs  
+**Phase:** 3 — Specialist  
+**Used by:** assess-ecosystem-services
+
+---
+
+## Purpose
+
+Guides the agent through the quantification and spatial representation of ecosystem services (ES): selecting appropriate indicators, computing biophysical ES estimates, mapping ES supply, and analysing trade-offs and synergies between services.
+
+---
+
+## When to Invoke
+
+- Quantifying ecosystem services across a landscape or watershed
+- Mapping ES supply and demand
+- Analysing trade-offs between conservation and production services
+- Supporting payments for ecosystem services (PES) design
+- Environmental impact assessments requiring ES valuation
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Land cover / land use map | GeoTIFF, SHP | Yes |
+| Biophysical data (rainfall, DEM, soil, biomass) | GeoTIFF, CSV | Yes |
+| Socioeconomic data (population, demand) | GeoTIFF, CSV | Optional |
+| Study area polygon | SHP, GPKG | Yes |
+
+---
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `es_indicator_maps/` | One raster per ES indicator |
+| `es_summary_table.csv` | ES value per land cover class |
+| `tradeoff_matrix.csv` | Pairwise ES correlation matrix |
+| `tradeoff_plot.png` | Scatter plots or heatmap of ES trade-offs |
+| `es_report.md` | Full ES assessment narrative |
+
+---
+
+## Steps
+
+### 1. Define the ES Portfolio
+Select relevant services for the context:
+
+| Category | Examples |
+|----------|---------|
+| Provisioning | Timber, water, food, fibre, genetic resources |
+| Regulating | Carbon sequestration, water regulation, erosion control, pollination |
+| Cultural | Recreation, aesthetic value, spiritual significance |
+| Supporting | Habitat, nutrient cycling (underlying processes) |
+
+### 2. Select Indicators and Methods per Service
+- **Carbon:** Above-ground biomass from REDD+ datasets or allometric models; soil carbon from SoilGrids
+- **Water regulation:** Curve number (CN) approach; InVEST Seasonal Water Yield
+- **Erosion control:** Revised Universal Soil Loss Equation (RUSLE); C-factor from land cover
+- **Pollination:** Distance-weighted bee habitat index from land cover
+- **Recreation:** Proximity index to natural areas weighted by accessibility
+
+### 3. Compute Biophysical ES Values
+- Apply selected method per service; store as raster layer
+- Validate against field measurements or published benchmarks where possible
+- Document all input parameters and data sources
+
+### 4. Aggregate by Land Cover Class
+- Zonal statistics: mean/total ES value per land cover polygon or raster class
+- Build summary table: rows = land cover classes, columns = ES indicators
+- Normalise to 0–1 for cross-service comparison
+
+### 5. Trade-off and Synergy Analysis
+- Compute pairwise Spearman correlations across pixels or land cover units
+- Positive correlations = synergies; negative = trade-offs
+- Visualise as correlation heatmap and scatter plots
+- Identify land cover classes that maximise multiple services simultaneously
+
+### 6. Beneficiary Mapping (optional)
+- Map ES demand using population density, agricultural areas, or water intake points
+- Overlay supply and demand to identify supply-demand gaps
+
+---
+
+## Key Decisions to Document
+
+- ES portfolio selection rationale
+- Method and data source per service
+- Normalisation method for cross-service comparison
+- Trade-off analysis unit (pixel, land cover class, watershed)
+
+---
+
+## Tools and Libraries
+
+**R:** `raster`, `terra`, `dplyr`, `ggplot2`, `corrplot`  
+**Python:** `rasterio`, `geopandas`, `seaborn`  
+**Dedicated:** InVEST (Stanford Natural Capital Project), ARIES, Co$ting Nature
+
+---
+
+## Resources
+
+- `resources/es-indicator-reference.md` — indicator definitions per service
+- `resources/invest-parameter-guide.md` — InVEST model configuration
+- `resources/rusle-coefficients.md` — RUSLE factor lookup tables
+- `examples/` — worked carbon + water regulation example
+
+---
+
+## Notes
+
+- ES assessment does not require monetary valuation; biophysical indicators are often sufficient and more defensible
+- InVEST is the most widely used open-source platform; use it unless a specific method is required
+- Always report uncertainty in ES estimates, especially for carbon stocks

package/skills/ecosystem-services-assessment/examples/example-prompts.md

@@ -0,0 +1,24 @@
+# Example Invocation Prompts — ecosystem-services-assessment
+
+## Multi-Service Assessment
+
+```
+Load skill: ecosystem-services-assessment
+Task: Assess three ecosystem services across the Mata Atlântica remnants in São Paulo state.
+
+Services: (1) carbon storage, (2) erosion control, (3) pollination habitat
+Inputs:
+  - data/landcover_sp_2022.tif (MapBiomas, 30m)
+  - data/biomass_mapbiomas.tif (above-ground biomass, MgC/ha)
+  - data/dem_sp.tif (SRTM 30m)
+  - data/rainfall_erosivity_sp.tif (R-factor, MJ·mm/ha/h/yr)
+  - data/sp_boundary.shp
+
+Steps:
+1. Carbon: extract biomass values per land cover class.
+2. Erosion control: compute RUSLE C-factor from land cover; compute avoided soil loss.
+3. Pollination: compute distance-weighted natural habitat index (1 km radius).
+4. Summarise ES per land cover class (zonal statistics).
+5. Trade-off analysis: pairwise Spearman correlations across pixels.
+Output: es_indicator_maps/, es_summary_table.csv, tradeoff_matrix.csv, es_report.md
+```

package/skills/ecosystem-services-assessment/resources/es-indicator-reference.md

@@ -0,0 +1,45 @@
+# Ecosystem Services Indicator Reference
+
+## Provisioning Services
+
+| Service | Indicator | Unit | Data source |
+|---------|-----------|------|-------------|
+| Above-ground carbon | Biomass carbon density | MgC/ha | REDD+ / GEDI / allometric |
+| Soil organic carbon | SOC stock | MgC/ha | SoilGrids 2.0 |
+| Timber | Volume/basal area | m³/ha | NFI data |
+| Water availability | Mean annual streamflow | mm/year | SWAT / InVEST |
+| Food production | Agricultural yield index | — | MapBiomas + FAO |
+
+## Regulating Services
+
+| Service | Indicator | Unit | Method |
+|---------|-----------|------|--------|
+| Carbon sequestration | Net ecosystem productivity | MgC/ha/year | MODIS MOD17 |
+| Water regulation | Baseflow index | — | InVEST Seasonal Water Yield |
+| Erosion control | Avoided soil loss | t/ha/year | RUSLE C-factor reduction |
+| Flood regulation | Curve number (CN) | — | USDA-NRCS method |
+| Pollination | Habitat suitability index | 0–1 | Distance from natural habitat |
+| Climate regulation | Evapotranspiration anomaly | mm/year | MOD16 |
+| Water purification | Nutrient retention | kg/ha/year | InVEST Nutrient Delivery Ratio |
+
+## Cultural Services
+
+| Service | Indicator | Unit | Method |
+|---------|-----------|------|--------|
+| Recreation | Accessibility-weighted natural area | ha (weighted) | Proximity index |
+| Aesthetic value | Viewshed from scenic areas | — | GIS viewshed |
+| Ecotourism potential | Biodiversity + accessibility index | — | Composite |
+| Spiritual | Indigenous territory presence | Binary | FUNAI / IBGE |
+
+## RUSLE C-factor by Land Cover (Brazil)
+
+| Land cover class | C-factor |
+|-----------------|---------|
+| Dense forest | 0.001 |
+| Secondary forest | 0.01 |
+| Savanna (Cerrado) | 0.05 |
+| Planted pasture | 0.15 |
+| Degraded pasture | 0.40 |
+| Annual cropland | 0.25–0.45 |
+| Bare soil | 1.00 |
+| Water body | 0 |

package/skills/ecosystem-services-assessment/resources/invest-parameter-guide.md

@@ -0,0 +1,86 @@
+# InVEST Model Configuration Guide
+
+InVEST (Integrated Valuation of Ecosystem Services and Tradeoffs) is the most widely used open-source platform for ES assessment. Developed by Stanford Natural Capital Project.
+
+## Available Models (most relevant for ecology)
+
+| Model | ES assessed | Key inputs |
+|-------|------------|-----------|
+| Carbon Storage and Sequestration | Carbon stocks | LULC map + carbon pools table |
+| Seasonal Water Yield | Water provisioning | LULC, DEM, soil, rainfall |
+| Nutrient Delivery Ratio (NDR) | Water quality (N, P) | LULC, DEM, soil, streams |
+| Sediment Delivery Ratio (SDR) | Erosion / sedimentation | LULC, DEM, soil, rainfall erosivity |
+| Habitat Quality | Biodiversity / habitat | LULC, threat sources, sensitivity table |
+| Pollination | Crop pollination | LULC, nesting habitat, floral resources |
+| Recreation | Ecotourism / recreation | LULC, access points, visitor data |
+| Coastal Blue Carbon | Mangrove/seagrass carbon | LULC (coastal), carbon pools |
+
+## Carbon Storage Model
+
+**Inputs:**
+- `lulc_current.tif` — Land use/land cover raster (integer class codes)
+- `carbon_pools.csv` — Carbon pool values per LULC class
+
+**Carbon pools table format:**
+
+| lucode | LULC_name | C_above | C_below | C_soil | C_dead |
+|--------|-----------|---------|---------|--------|--------|
+| 1 | Dense forest | 150 | 30 | 80 | 5 |
+| 2 | Secondary forest | 60 | 15 | 50 | 3 |
+| 3 | Cerrado | 30 | 20 | 40 | 2 |
+| 4 | Pasture | 5 | 3 | 20 | 0 |
+| 5 | Cropland | 3 | 1 | 15 | 0 |
+
+Units: Mg C / ha. Sources: IPCC Tier 1 default values; REDD+ national forest inventories; MapBiomas biomass layer.
+
+## Sediment Delivery Ratio (SDR) — Key Parameters
+
+| Parameter | Typical range | Notes |
+|-----------|--------------|-------|
+| Threshold flow accumulation | 1000–5000 cells | Higher = fewer streams |
+| k_param (USLE K) | 0.01–0.8 t·ha·h/ha/MJ/mm | Soil erodibility factor |
+| l_max | 122 m | Maximum USLE L factor slope length |
+| sdr_max | 0.8 | Maximum SDR value |
+
+## Habitat Quality Model
+
+**Threat sources table:**
+
+| threat | max_dist | weight | decay |
+|--------|---------|--------|-------|
+| roads | 5 | 0.8 | exponential |
+| agriculture | 8 | 0.6 | linear |
+| urban | 10 | 1.0 | exponential |
+
+**Sensitivity table** (access_weight per threat × LULC):
+
+| LULC | L_threat_roads | L_threat_agriculture | L_threat_urban |
+|------|---------------|---------------------|---------------|
+| Forest | 0.5 | 0.4 | 0.7 |
+| Savanna | 0.6 | 0.5 | 0.8 |
+| Wetland | 0.7 | 0.6 | 0.9 |
+| Pasture | 0.0 | 0.0 | 0.3 |
+
+## Running InVEST from Python
+
+```python
+import natcap.invest.carbon
+
+args = {
+    'workspace_dir': 'outputs/invest_carbon',
+    'lulc_cur_path': 'data/landcover_2022.tif',
+    'carbon_pools_path': 'data/carbon_pools.csv',
+    'calc_sequestration': False,
+    'do_redd': False,
+    'do_valuation': False,
+}
+natcap.invest.carbon.execute(args)
+```
+
+## Installation
+
+```bash
+pip install natcap.invest
+```
+
+Or via Conda: `conda install -c conda-forge natcap.invest`

package/skills/ecosystem-services-assessment/resources/rusle-coefficients.md

@@ -0,0 +1,88 @@
+# RUSLE Factor Reference
+
+The Revised Universal Soil Loss Equation estimates annual soil loss:
+
+**A = R × K × LS × C × P**
+
+where A = soil loss (t/ha/yr).
+
+## R Factor — Rainfall Erosivity (MJ·mm/ha/h/yr)
+
+| Region (Brazil) | Typical R range | Source |
+|----------------|----------------|--------|
+| Amazon (high rainfall) | 8,000–12,000 | Panagos et al. 2017 |
+| Cerrado | 5,000–9,000 | Oliveira et al. 2013 |
+| Atlantic Forest coast | 6,000–10,000 | |
+| Semi-arid Northeast | 1,000–3,000 | |
+| Southern Brazil | 5,000–8,000 | |
+
+Available layer: Global Rainfall Erosivity Database (ESDAC / Panagos et al. 2017)  
+DOI: 10.1016/j.scitotenv.2017.06.199
+
+## K Factor — Soil Erodibility (t·ha·h/ha/MJ/mm)
+
+| Soil texture | K range | Notes |
+|-------------|---------|-------|
+| Sandy / coarse | 0.01–0.10 | Low erodibility |
+| Loamy sand | 0.05–0.15 | |
+| Sandy loam | 0.10–0.25 | |
+| Loam | 0.15–0.35 | Moderate |
+| Silt loam | 0.25–0.45 | High |
+| Clay loam | 0.20–0.40 | |
+| Clay | 0.10–0.30 | Cohesive; lower K |
+| Organic / Latosol | 0.01–0.08 | Low despite fine texture |
+
+Source: SoilGrids 2.0 provides K factor globally at 250 m.
+
+## LS Factor — Slope Length × Steepness
+
+Computed from DEM using:
+
+```r
+library(terra)
+library(whitebox)
+dem <- rast("dem.tif")
+wbt_slope(input = "dem.tif", output = "slope.tif", units = "degrees")
+# LS factor: use standard RUSLE LS equations via saga or whitebox
+```
+
+Or use the pre-computed global LS factor from Panagos et al. 2015.
+
+## C Factor — Cover Management (key for ES assessment)
+
+The C factor represents the effect of land cover and management on soil erosion relative to bare fallow.
+
+| Land cover (MapBiomas) | C factor |
+|-----------------------|---------|
+| Dense Amazon forest | 0.0001 |
+| Open tropical forest | 0.001 |
+| Savanna (Cerrado) | 0.01–0.05 |
+| Secondary forest (old) | 0.005 |
+| Secondary forest (young) | 0.05 |
+| Planted pasture (good) | 0.01 |
+| Planted pasture (degraded) | 0.25–0.50 |
+| Annual crops (soy/corn) | 0.20–0.40 |
+| Sugarcane | 0.15 |
+| Natural wetland | 0.001 |
+| Mangrove | 0.00001 |
+| Bare soil / exposed rock | 1.00 |
+| Urban | 0.00 (no erosion model) |
+
+## P Factor — Support Practices
+
+| Practice | P factor |
+|---------|---------|
+| No practice (default) | 1.00 |
+| Contour farming | 0.50–0.75 |
+| Terracing | 0.10–0.50 |
+| Strip cropping | 0.35–0.70 |
+
+Default P = 1.0 for natural landscapes (no agricultural support practices).
+
+## Avoided Soil Loss (ES Indicator)
+
+Erosion control service = A_bare − A_vegetated
+
+where A_bare = soil loss if bare soil (C = 1, P = 1) and A_vegetated = actual soil loss.
+
+This difference represents the erosion that the current vegetation is preventing.