ecological-agent-skills 3.1.0

package/skills/spatial-prioritization/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: spatial-prioritization
+description: "Solves systematic conservation planning problems using integer linear programming (prioritizr), Marxan, or Zonation for protected area design. Use this skill when the user mentions conservation planning, 30x30 targets, Marxan, Zonation, prioritizr, irreplaceability, boundary length modifier (BLM), minimum set problems, representation targets, systematic conservation, or protected area network design."
+skill_version: 1.0.0
+---
+
+# Skill: spatial-prioritization
+
+**Domain:** Conservation planning · prioritizr · Marxan · Zonation · Reserve design · 30×30
+
+---
+
+## Purpose
+
+Guides the agent through systematic conservation planning to identify priority areas that efficiently represent biodiversity targets under cost constraints. Covers problem formulation (minimum-set, maximum-coverage), planning unit design, target definition, cost surface selection, connectivity penalties, and solving with integer linear programming. Produces priority maps, irreplaceability surfaces, and cost-effectiveness curves for decision-makers.
+
+---
+
+## When to Invoke
+
+Invoke this skill when:
+
+- The user requests conservation area prioritisation, gap analysis, or reserve design
+- Systematic conservation planning (Marxan, Zonation, prioritizr) is needed
+- Protected area network adequacy must be evaluated against biodiversity targets
+- A 30×30 or other area-based conservation target must be spatially allocated
+- Trade-offs between cost and biodiversity representation must be quantified
+
+**trigger_keywords:** `conservation planning`, `protected areas`, `Marxan`, `Zonation`, `prioritizr`, `reserve design`, `systematic conservation`, `30x30`, `biodiversity target`, `irreplaceability`, `complementarity`, `gap analysis`, `cost-effectiveness`, `planning unit`, `boundary length modifier`
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|---|---|---|
+| Species suitability or distribution stack | GeoTIFF (multiband) | Required |
+| Cost surface raster | GeoTIFF | Required |
+| Study area polygon | SHP or GPKG | Required |
+| Conservation targets per species (%) | CSV | Recommended |
+| Locked-in areas (existing protected areas) | SHP or GPKG | Optional |
+| Locked-out areas (exclusion zones) | SHP or GPKG | Optional |
+| Connectivity layer (habitat patches or resistance surface) | GeoTIFF or GPKG | Optional |
+
+---
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `priority_solution.tif` | Binary raster: 1 = selected planning unit, 0 = not selected |
+| `irreplaceability.tif` | Selection frequency across portfolio of near-optimal solutions |
+| `targets_achieved.csv` | % of target met per species/feature in the solution |
+| `cost_effectiveness_curve.png` | Total cost vs. % targets achieved across budget levels |
+| `solution_summary.md` | Narrative: total area, cost, targets met, connectivity score |
+| `sensitivity_results.csv` | Solution metrics across BLM and target combinations |
+
+---
+
+## Steps
+
+1. **Define planning units**
+   Use the study area raster cells as planning units (pixel-based) or create a hexagonal
+   grid at the appropriate resolution. Confirm CRS matches all input layers.
+   Record planning unit size and type in `decision_log.md`.
+
+2. **Prepare features (biodiversity layers)**
+   Load species suitability stack from `species-distribution-modeling` skill.
+   Optionally include ecosystem service layers from `ecosystem-services-assessment`.
+   Normalise all feature layers to [0, 1] if combining different units.
+
+3. **Define targets**
+   Default: 30% of each species' total distribution within the study area.
+   If IUCN threat status data are available, apply higher targets for threatened species
+   (CR: 50%, EN: 40%, VU: 30%).
+   Save target table as `params/targets.csv`.
+
+4. **Build and solve the prioritisation problem** *(invoke `run_prioritization.R`)*
+   Create problem with `prioritizr::problem()`, add targets, cost, and penalties.
+   Set locked-in (existing protected areas) and locked-out (excluded) zones.
+   Add connectivity penalty using `add_boundary_penalties(penalty = BLM)`.
+   Solve with `highs` solver (default) or `symphony` (fallback).
+
+5. **Evaluate solution**
+   Check `targets_achieved.csv`: all features must reach ≥ 80% of target.
+   If any feature < 80%: budget is insufficient; run `prioritization_sensitivity.R`.
+   Calculate irreplaceability as selection frequency across 100 near-optimal solutions.
+
+6. **Generate cost-effectiveness curve** *(invoke `prioritization_sensitivity.R`)*
+   Solve at 5 budget levels (50%, 75%, 100%, 125%, 150% of selected solution cost).
+   Plot cumulative targets achieved vs. total cost.
+   Present to decision-maker as trade-off summary.
+
+7. **Validate and document**
+   Verify `priority_solution.tif` covers the expected % of study area.
+   Record solver used, BLM value, target definitions, and any infeasible scenarios
+   in `decision_log.md`.
+
+---
+
+## Decision Points
+
+| Condition | Diagnosis | Recommended Action |
+|---|---|---|
+| No feasible solution found in 1000 iterations | Budget too restrictive or targets unachievable | Relax targets (reduce by 5% increments) or increase budget; document trade-off |
+| < 80% of targets achieved in solution | Budget insufficient for full representation | Present cost-effectiveness curve; let decision-maker choose acceptable representation level |
+| Irreplaceability > 0.8 for a deforested area | Critical irreplaceable area is already lost | Escalate to restoration analysis; include in gap analysis narrative |
+| BLM = 0 gives highly fragmented solution | Connectivity not enforced | Calibrate BLM: increase until solution compactness is acceptable without losing > 10% of targets |
+| Existing protected areas already meet targets | No additional areas needed | Perform gap analysis only; report which species remain under-represented |
+
+---
+
+## Key Decisions to Document
+
+Record the following in `decision_log.md` after running this skill:
+
+- Planning unit type (pixel vs. hexagon), size, and CRS used
+- Target percentages per feature and their justification (30×30, IUCN status, etc.)
+- Cost surface used (area proxy, economic value, opportunity cost) and its source
+- BLM value applied and how it was calibrated
+- Solver used (highs, symphony, gurobi) and whether any scenarios were infeasible
+
+---
+
+## Tools and Libraries
+
+**R**
+```r
+suppressPackageStartupMessages(library(prioritizr))   # conservation planning problem
+suppressPackageStartupMessages(library(highs))        # HiGHS solver (recommended, free)
+suppressPackageStartupMessages(library(terra))        # raster handling
+suppressPackageStartupMessages(library(sf))           # vector handling
+suppressPackageStartupMessages(library(dplyr))        # data manipulation
+suppressPackageStartupMessages(library(ggplot2))      # cost-effectiveness plots
+```
+
+**Python** *(support layer only — core analysis in R)*
+```python
+import geopandas as gpd     # spatial data inspection
+import rasterio             # raster inspection
+import numpy as np          # array operations
+from pathlib import Path    # file system
+```
+
+---
+
+## Resources
+
+- [`skills/spatial-prioritization/resources/prioritizr-formulation-guide.md`](resources/prioritizr-formulation-guide.md) — Problem types, planning units, targets, costs, BLM, solvers, and locked zones
+- [`skills/spatial-prioritization/resources/marxan-vs-prioritizr-comparison.md`](resources/marxan-vs-prioritizr-comparison.md) — Comparison of Marxan, Zonation, prioritizr, and OPT; migration guide
+- [`skills/spatial-prioritization/resources/cost-surface-reference.md`](resources/cost-surface-reference.md) — Cost proxy options, global data sources, normalisation, and sensitivity to cost
+- [`skills/spatial-prioritization/resources/representation-targets-guide.md`](resources/representation-targets-guide.md) — 10%/17%/30% targets, species-level targets, fine-filter vs. coarse-filter approaches
+
+---
+
+## Notes
+
+- **prioritizr requires a solver:** The `highs` package provides a free, high-performance solver sufficient for most problems. `gurobi` is faster for very large problems but requires an academic licence. Do not attempt to solve without an explicit solver; `prioritizr` will error.
+- **Boundary length modifier (BLM) requires calibration:** BLM = 0 produces the cheapest but most fragmented solution. Too high a BLM increases cost dramatically. Calibrate by plotting cost vs. total boundary length across BLM values (built into `prioritization_sensitivity.R`).
+- **Irreplaceability ≠ priority:** A planning unit with irreplaceability = 1.0 is selected in every near-optimal solution but may be inexpensive. A unit with irreplaceability = 0.3 is selected only in some solutions. Report both the solution map and irreplaceability map.
+- **Planning unit size affects resolution and computation time:** 1 km² pixels for a country-scale analysis may produce millions of planning units, making ILP very slow. Aggregate to 10 km² for national-scale problems; use 1 km² only for regional scales.
+- **Locked-in areas must be in the same CRS as planning units:** CRS mismatch between existing protected areas and planning units is a common error that causes protected areas to be ignored in the solution.

package/skills/spatial-prioritization/examples/biodiversity_hotspot_prioritization_example.md

@@ -0,0 +1,289 @@
+---
+skill_id: spatial-prioritization
+example_type: full_walkthrough
+taxon: Multi-species (Atlantic Forest endemic vertebrates)
+region: Southern Bahia, Brazil — Atlantic Forest hotspot
+---
+
+# Atlantic Forest Biodiversity Hotspot Prioritization — Full Walkthrough
+
+## Study Context
+
+**Location:** Southern Bahia, Brazil — one of the world's most biodiverse (and threatened) Atlantic Forest remnants
+**Objective:** Design a minimum-cost protected area expansion to meet 30% representation targets for 85 endemic vertebrate species while maximising compactness (coridor potential)
+**Planning units:** 5×5 km grid cells, n = 3,240 valid PUs
+**Features:** 85 species SDM suitability layers (MaxEnt, continuous 0–1)
+**Cost:** Opportunity cost surface based on agricultural land value (R$/ha/yr)
+**Existing PAs:** 12 federal and state reserves (already locked in, covering ~8% of area)
+
+---
+
+## Step 1 — Data Preparation
+
+### Planning unit cost surface
+
+```r
+suppressPackageStartupMessages(library(terra))
+suppressPackageStartupMessages(library(sf))
+
+# Agricultural opportunity cost: sugarcane + cattle + timber
+sugarcane <- rast("data/sugarcane_revenue_reais_ha.tif")
+cattle    <- rast("data/cattle_TLU_ha.tif") * 180  # R$/TLU/yr
+timber    <- rast("data/timber_potential_reais_ha.tif")
+opp_cost  <- max(sugarcane, cattle, timber, na.rm = TRUE)
+opp_cost  <- aggregate(opp_cost, fact = 5, fun = "mean")  # resample to 5km
+
+# Minimum floor
+opp_cost[opp_cost < 1] <- 1
+writeRaster(opp_cost, "data/pu_cost_5km.tif", overwrite = TRUE)
+cat(sprintf("Cost range: %.0f – %.0f R$/ha/yr\n",
+            global(opp_cost, "min")[[1]], global(opp_cost, "max")[[1]]))
+```
+
+**Cost statistics:**
+
+| Statistic | Value (R$/ha/yr) |
+|-----------|-----------------|
+| Min | 1.0 |
+| Median | 845 |
+| Mean | 1,240 |
+| Q95 | 3,890 |
+| Max | 8,750 |
+
+**Decision:** Log-transform cost for analysis to reduce influence of 5 outlier PUs with costs > 7,000 R$/ha/yr. Decision logged with rationale.
+
+### Feature layers preparation
+
+```r
+feat_files <- list.files("data/sdm_continuous/", pattern = ".tif$", full.names = TRUE)
+features   <- rast(feat_files)
+features   <- resample(features, rast("data/pu_cost_5km.tif"), method = "bilinear")
+
+# Check feature distribution: remove features with < 5 PUs with suitability > 0.3
+feat_sums  <- global(features > 0.3, "sum", na.rm = TRUE)
+low_feat   <- names(features)[feat_sums[[1]] < 5]
+cat(sprintf("Removing %d features with very restricted range.\n", length(low_feat)))
+features   <- features[[!names(features) %in% low_feat]]
+```
+
+**Result:** 3 species removed (range < 5 PUs); 82 features retained.
+
+---
+
+## Step 2 — Baseline Prioritization (Minimum Set, 30% Targets)
+
+### Target computation (IUCN-based)
+
+```r
+species_meta <- read.csv("data/species_iucn_status.csv")
+# Columns: species, iucn_category, current_protected_fraction
+
+set_iucn_targets <- function(species_df) {
+  raw <- dplyr::case_when(
+    species_df$iucn_category == "CR" ~ 0.60,
+    species_df$iucn_category == "EN" ~ 0.50,
+    species_df$iucn_category == "VU" ~ 0.40,
+    species_df$iucn_category == "NT" ~ 0.30,
+    TRUE ~ 0.17
+  )
+  pmax(0, raw - species_df$current_protected_fraction)
+}
+
+targets_df <- set_iucn_targets(species_meta)
+# Distribution: CR: 0.42 median (gap after 18% already protected)
+#               EN: 0.35; VU: 0.28; NT: 0.22
+write.csv(data.frame(feature_name = names(features), target = targets_df),
+          "data/iucn_targets.csv", row.names = FALSE)
+```
+
+### Run baseline prioritization
+
+```bash
+Rscript run_prioritization.R \
+  data/pu_cost_5km.tif \
+  data/sdm_continuous/ \
+  outputs/baseline/ \
+  data/iucn_targets.csv \
+  data/existing_PAs_5km.tif \
+  data/excluded_urban_water.tif \
+  0 \
+  NA
+```
+
+**Baseline results:**
+
+| Metric | Value |
+|--------|-------|
+| PUs selected | 487 / 3,240 (15.0%) |
+| Total cost | R$ 234M/yr opportunity cost |
+| Features with targets met | 79 / 82 (96.3%) |
+| 3 features below target | *Diclidurus ingens* (CR, 0.41 vs 0.42 target), 2 VU bats |
+
+**Action:** The 3 shortfall species have extremely restricted ranges. Manual inspection shows their key PUs are in a locked-out urban buffer. Decision: remove urban buffer restriction for those 3 PUs (no development plans confirmed) → re-run.
+
+---
+
+## Step 3 — Sensitivity Analysis
+
+```bash
+Rscript prioritization_sensitivity.R \
+  data/pu_cost_5km.tif \
+  data/sdm_continuous/ \
+  outputs/sensitivity/ \
+  data/iucn_targets.csv \
+  data/existing_PAs_5km.tif \
+  data/excluded_urban_water.tif
+```
+
+### BLM calibration
+
+| BLM | Cost (R$M/yr) | Boundary length | PUs selected |
+|-----|--------------|-----------------|-------------|
+| 0 | 234 | 18,240 | 487 |
+| 0.001 | 238 | 15,120 | 492 |
+| 0.01 | 251 | 11,880 | 508 |
+| 0.05 | 279 | 8,640 | 531 |
+| 0.1 | 312 | 7,200 | 565 |
+
+**Decision:** BLM = 0.01 selected (elbow point — 7% cost increase reduces boundary by 35%). This creates significantly more compact, corridor-compatible solutions.
+
+### Target sensitivity
+
+| Target scaling | Mean target | Cost (R$M/yr) | Features met |
+|---------------|-------------|--------------|-------------|
+| 50% | 0.17 | 98 | 82/82 |
+| 75% | 0.26 | 167 | 82/82 |
+| 100% (baseline) | 0.35 | 251 | 82/82 |
+| 125% | 0.44 | 389 | 80/82 |
+| 150% | 0.52 | 521 | 76/82 |
+
+**Finding:** Cost increases 3× from 50% to 150% target scaling. Targets above ~130% become infeasible for 2+ species given locked-out area constraints.
+
+---
+
+## Step 4 — Final Solution (BLM = 0.01)
+
+```bash
+Rscript run_prioritization.R \
+  data/pu_cost_5km.tif \
+  data/sdm_continuous/ \
+  outputs/final/ \
+  data/iucn_targets.csv \
+  data/existing_PAs_5km.tif \
+  data/excluded_urban_water.tif \
+  0.01 \
+  NA
+```
+
+**Final solution results:**
+
+| Metric | Value |
+|--------|-------|
+| PUs selected | 508 (15.7%) |
+| Total opportunity cost | R$ 251M/yr |
+| Area selected | ~12,700 km² |
+| Combined with existing PAs | ~14,600 km² (20.8% of study area) |
+| Features with targets met | 82 / 82 (100%) |
+| Gap to optimality (HiGHS) | 0.8% |
+
+**Irreplaceability analysis:**
+
+```r
+irr <- rast("outputs/final/irreplaceability.tif")
+# High-priority areas (top 10% irreplaceability, not yet in PA system)
+high_irr_unprotected <- (irr >= quantile(values(irr), 0.90, na.rm = TRUE)) &
+                         (rast("data/existing_PAs_5km.tif") == 0)
+n_high_irr_unprotected <- sum(values(high_irr_unprotected) == 1, na.rm = TRUE)
+cat(sprintf("High-irreplaceability, unprotected PUs: %d (%.0f km²)\n",
+            n_high_irr_unprotected, n_high_irr_unprotected * 25))
+```
+
+**Result:** 47 PUs (1,175 km²) have irreplaceability > 0.90 and are not currently protected. These are the highest-priority acquisition targets.
+
+---
+
+## Step 5 — Portfolio Irreplaceability Map
+
+```r
+freq <- rast("outputs/sensitivity/portfolio_frequency.tif")
+# Areas selected in > 75% of scenarios = robust priorities
+robust_areas <- freq >= 0.75
+robust_area_km2 <- sum(values(robust_areas) == 1, na.rm = TRUE) * 25
+cat(sprintf("Robust priority areas (selected in >75%% scenarios): %.0f km²\n",
+            robust_area_km2))
+```
+
+**Result:** 8,450 km² selected in > 75% of all scenarios. These areas are recommended as the highest-priority acquisition regardless of cost or target assumptions.
+
+---
+
+## Step 6 — Final Outputs
+
+```
+outputs/
+├── baseline/
+│   ├── solution.tif                    # 487 PUs selected
+│   ├── feature_representation.csv      # 82 species, 79 met targets
+│   ├── cost_summary.csv
+│   └── irreplaceability.tif
+├── final/                              # BLM = 0.01
+│   ├── solution.tif                    # 508 PUs, all 82 targets met
+│   ├── feature_representation.csv
+│   ├── irreplaceability.tif
+│   └── prioritization_map.png
+└── sensitivity/
+    ├── blm_calibration.csv
+    ├── blm_calibration_plot.png
+    ├── target_sensitivity.csv
+    ├── cost_scenario_sensitivity.csv
+    └── portfolio_frequency.tif         # robust priorities (75% threshold)
+```
+
+---
+
+## Summary Table
+
+| Metric | Value |
+|--------|-------|
+| Planning units | 3,240 (5×5 km) |
+| Features analysed | 82 Atlantic Forest endemics |
+| Existing PA coverage | 8.0% (locked in) |
+| Solution area | 15.7% (+ existing = 20.8%) |
+| All targets met | Yes (82/82) |
+| Opportunity cost | R$ 251M/yr |
+| Gap to optimality | 0.8% |
+| Robust priority area (>75% freq) | 8,450 km² |
+| Irreplaceable unprotected area | 1,175 km² (47 PUs) |
+
+---
+
+## Decision Log
+
+```yaml
+- date: 2026-02-01
+  skill_id: spatial-prioritization
+  decision: "Log-transform cost; outlier PUs capped at 95th percentile"
+  rationale: "5 PUs with cost > 7000 R$/ha dominated solution; log-transform standard practice"
+  outputs: ["data/pu_cost_5km.tif"]
+
+- date: 2026-02-02
+  skill_id: spatial-prioritization
+  decision: "BLM = 0.01 selected for final solution"
+  rationale: "Elbow of cost-compactness curve; 7% cost increase for 35% boundary reduction"
+  outputs: ["outputs/sensitivity/blm_calibration.csv"]
+
+- date: 2026-02-03
+  skill_id: spatial-prioritization
+  decision: "Urban buffer exception for 3 CR bat species PUs"
+  rationale: "No confirmed development plans in those PUs; verified with municipal zoning"
+  outputs: ["outputs/final/solution.tif"]
+```
+
+---
+
+## References
+
+- Hanson, J.O. et al. (2024). prioritizr: Systematic conservation prioritization in R. *Methods in Ecology and Evolution*, 15(8), 1337–1344. DOI: 10.1111/2041-210X.14376
+- CBD (2022). *Kunming-Montreal Global Biodiversity Framework*, Target 3. COP15.
+- Rodrigues, A.S.L. et al. (2004). Effectiveness of the global protected area network in representing species diversity. *Nature*, 428, 640–643. DOI: 10.1038/nature02422
+- Wilson, K.A. et al. (2009). Conserving biodiversity efficiently: what to do, where, and when. *PLOS Biology*, 7(9), e1000175. DOI: 10.1371/journal.pbio.1000175

package/skills/spatial-prioritization/examples/example-prompts.md

@@ -0,0 +1,93 @@
+---
+skill_id: spatial-prioritization
+example_count: 5
+---
+
+# Spatial Prioritization — Example Prompts
+
+## Scenario 1: 30×30 Target Achievement — Tropical Country
+
+**Context:** A tropical nation needs to expand its protected area network from current 14% coverage to 30% by 2030 (Kunming-Montreal GBF Target 3).
+
+**Prompt:**
+> "I have SDM suitability layers for 120 species and an opportunity cost surface for a tropical country. Design a minimum-cost protected area network that achieves 30% representation for all species AND covers at least 30% of total land area. Lock in existing PAs."
+
+**Expected workflow:**
+1. Build feature layers (120 species SDM suitability rasters)
+2. Set targets = 0.30 for all features; add area constraint via `add_min_set_objective`
+3. Lock in WDPA existing PAs via `locked_in_raster`
+4. `run_prioritization.R pu_cost.tif features/ outputs/ 0.30 wdpa.tif`
+5. Check `feature_representation.csv` — verify all 120 features ≥ 30%
+6. Map solution; compute % land area covered
+
+**Key decision points:**
+- If any species < 30% → check if its range is fully within locked-out areas
+- If solution selects > 40% of land → check if some targets can be relaxed for LC species
+
+---
+
+## Scenario 2: Fixed Budget Conservation Planning
+
+**Context:** NGO has USD 10M to acquire land in a biodiversity hotspot. Maximise conservation benefit within this budget.
+
+**Prompt:**
+> "With a budget of USD 10M, select the set of land parcels (planning units) that maximises the number of threatened species (IUCN CR, EN, VU) whose representation targets are met. Use IUCN-based targets (CR=60%, EN=50%, VU=40%)."
+
+**Expected workflow:**
+1. Compute IUCN targets via `set_iucn_targets()` from resource guide
+2. Switch to `add_max_features_objective(budget = 10e6)`
+3. `run_prioritization.R pu_cost.tif features/ outputs/ targets_iucn.csv NA NA 0 10000000`
+4. Load `feature_representation.csv` → count species above/below target
+5. Report cost-effectiveness: threatened species-targets met per million USD
+
+---
+
+## Scenario 3: Corridor Design Between Two National Parks
+
+**Context:** Two national parks need to be connected by a wildlife corridor. Identify the minimum-cost land parcels connecting them while protecting 40% of corridor species.
+
+**Prompt:**
+> "Design a wildlife corridor connecting Park A and Park B. Select planning units that form a connected corridor while meeting 40% representation targets for 25 focal species. Lock in both parks; exclude urban areas."
+
+**Expected workflow:**
+1. Lock in both parks as locked_in_raster
+2. Lock out urban + water as locked_out_raster
+3. Set BLM = 0.05 to encourage compact, connected solution
+4. `run_prioritization.R pu.tif features/ outputs/ 0.40 parks.tif urban_water.tif 0.05`
+5. Verify solution forms a connected path (use igraph on solution raster)
+6. Report total corridor length and width at narrowest point
+
+---
+
+## Scenario 4: Sensitivity Analysis for Policy Decision
+
+**Context:** Government needs to defend a new protected area design to stakeholders. Show how the solution is robust to cost uncertainty and target choice.
+
+**Prompt:**
+> "Run a sensitivity analysis on the conservation solution: (1) BLM calibration to find the optimal compactness, (2) test target scalings from 50% to 150% of the baseline 30% target, (3) test cost uncertainty ±30%. Produce a portfolio irreplaceability map."
+
+**Expected workflow:**
+1. `prioritization_sensitivity.R pu.tif features/ outputs/ 0.30 locked_in.tif locked_out.tif`
+2. Load `blm_calibration.csv` → plot cost-compactness tradeoff → select elbow BLM
+3. Load `target_sensitivity.csv` → show cost doubles going from 50% to 150% scaling
+4. Load `portfolio_frequency.tif` → map areas selected in > 75% of scenarios = robust priorities
+
+---
+
+## Scenario 5: Marine Protected Area Network
+
+**Context:** Marine spatial planning for a coastal nation. Design an MPA network covering 30% of territorial waters while protecting key fish spawning areas and coral reefs.
+
+**Prompt:**
+> "I have marine biodiversity feature layers (fish spawning areas, coral, seagrass, endemic species SDMs) and a planning unit grid representing fishing revenue as opportunity cost. Design an MPA network meeting 30% targets for all features while minimising cost to fishers."
+
+**Expected workflow:**
+1. Planning units: 1 km² grid cells covering territorial waters; cost = annual fishing revenue
+2. Features: spawning aggregations, coral cover, seagrass, endemic species suitability
+3. Locked-out: shipping lanes (navigational requirement), oil/gas concessions
+4. `run_prioritization.R marine_pu.tif marine_features/ outputs/ 0.30 NA shipping.tif 0.01`
+5. Report: total fishing revenue lost in solution vs % marine area protected
+
+**Key decision points:**
+- If fishing revenue cost unavailable → use inverse of fishing effort as proxy
+- If no-take zones are mandatory in PA regulations → add no-take constraint as binary feature layer

package/skills/spatial-prioritization/resources/cost-surface-reference.md

@@ -0,0 +1,130 @@
+---
+resource_id: cost-surface-reference
+skill_id: spatial-prioritization
+---
+
+# Cost Surface Reference for Conservation Planning
+
+## Types of Conservation Cost
+
+| Cost type | Definition | Data source | Bias risk |
+|-----------|-----------|-------------|-----------|
+| **Land acquisition** | Market value of land | Cadastral databases, government assessments | Overvalues urban-adjacent land |
+| **Opportunity cost** | Foregone income if land is protected | Crop productivity + livestock density | Ignores non-market values |
+| **Management cost** | Annual monitoring, enforcement, restoration | Government agency budgets | Variable by governance context |
+| **Transaction cost** | Legal, administrative negotiation costs | Expert estimate | Often ignored; can dominate |
+| **Area (proxy)** | Equal cost per PU (1 per cell) | Always available | No economic information |
+
+**Recommended hierarchy:** Opportunity cost > land acquisition cost > area proxy. Use area proxy only when no cost data is available.
+
+---
+
+## Opportunity Cost Construction
+
+```r
+suppressPackageStartupMessages(library(terra))
+
+# Components of agricultural opportunity cost
+crop_value     <- rast("data/crop_net_revenue_usd_ha.tif")   # $/ha/yr
+livestock_value <- rast("data/livestock_density_TLU_ha.tif")  # TLU/ha → $/ha/yr
+timber_value   <- rast("data/timber_potential_usd_ha.tif")    # $/ha
+
+# Weight livestock by price per TLU (e.g., 200 USD/TLU/yr)
+livestock_opp <- livestock_value * 200
+
+# Total opportunity cost = max of competing land uses
+opp_cost <- max(crop_value, livestock_opp, timber_value, na.rm = TRUE)
+
+# Replace NA with low cost (not zero — zero cost attracts solver spuriously)
+opp_cost[is.na(opp_cost)] <- 1
+writeRaster(opp_cost, "data/opportunity_cost.tif", overwrite = TRUE)
+```
+
+---
+
+## Cost Normalisation
+
+```r
+# Option 1: Standardise to 0–1 (useful for comparing solutions across regions)
+cost_norm <- (opp_cost - global(opp_cost, "min", na.rm = TRUE)[[1]]) /
+             (global(opp_cost, "max", na.rm = TRUE)[[1]] -
+              global(opp_cost, "min", na.rm = TRUE)[[1]])
+
+# Option 2: Log-transform (reduces influence of outlier high-cost cells)
+cost_log <- log1p(opp_cost)
+
+# Option 3: Percentile cap (cap at 95th percentile to remove outliers)
+q95 <- quantile(values(opp_cost), 0.95, na.rm = TRUE)
+cost_capped <- min(opp_cost, q95)
+```
+
+**Choose normalisation based on cost distribution.** If cost is approximately log-normal (common for land values), log-transform avoids a few high-cost cells dominating the solution.
+
+---
+
+## Cost Surface Uncertainty
+
+Cost data often has high uncertainty. Test prioritisation robustness:
+
+```r
+# Run prioritization under 3 cost scenarios
+cost_low  <- cost * 0.7   # -30% uncertainty
+cost_base <- cost
+cost_high <- cost * 1.3   # +30% uncertainty
+
+run_scenario <- function(cost_raster, name) {
+  p <- problem(cost_raster, features) %>%
+    add_min_set_objective() %>%
+    add_relative_targets(targets) %>%
+    add_highs_solver(gap = 0.01) %>%
+    add_binary_decisions()
+  s <- solve(p)
+  data.frame(scenario = name,
+             cost = eval_cost_summary(p, s)$cost,
+             n_pu = sum(values(s), na.rm = TRUE))
+}
+
+scenarios <- lapply(list(cost_low, cost_base, cost_high),
+                    list("low", "base", "high"),
+                    function(c, n) run_scenario(c, n))
+```
+
+---
+
+## Locked-In and Locked-Out Planning Units
+
+| Category | Definition | R implementation |
+|----------|-----------|-----------------|
+| **Locked-in** | Must be selected (existing PAs, community reserves) | `add_locked_in_constraints(locked_in_raster)` |
+| **Locked-out** | Cannot be selected (developed areas, water bodies, military) | `add_locked_out_constraints(locked_out_raster)` |
+| **Semi-locked** | Selected only if budget allows | Remove from locked constraints; let solver decide |
+
+```r
+# Build locked-in raster from protected area shapefile
+pas <- st_read("data/wdpa_protected_areas.shp", quiet = TRUE)
+locked_in <- rasterize(vect(pas), cost, field = 1, background = 0)
+locked_in[is.na(cost)] <- NA  # match planning unit extent
+
+# Build locked-out from urban and water polygons
+excluded <- st_read("data/urban_water_excluded.shp", quiet = TRUE)
+locked_out <- rasterize(vect(excluded), cost, field = 1, background = 0)
+locked_out[is.na(cost)] <- NA
+```
+
+---
+
+## Pitfalls
+
+- **Zero-cost cells attracting all PUs:** If cost = 0 for some PUs, the solver trivially selects them. Use a minimum cost floor (e.g., 1) for all non-excluded PUs.
+- **Cost misalignment with features:** If cost raster is at 10-km resolution but features at 1-km, resampling introduces spatial mismatch. Always build cost at the same resolution as the analysis.
+- **Ignoring non-market values:** Pure opportunity cost undervalues inaccessible, culturally important, or wilderness areas. Consider supplementing with ecosystem service values.
+- **Using area as cost when land access is the real constraint:** In many developing-country contexts, political access (community agreements, government willingness) is the real cost, not land value. Document which cost metric was used and why.
+- **Static cost surface:** Land values change over time. For 30-year planning horizons, consider projected future opportunity cost (discounted NPV of land use revenues).
+
+---
+
+## References
+
+- Naidoo, R. & Iwamura, T. (2007). Global-scale mapping of economic benefits from agricultural lands. *Biological Conservation*, 140(1–2), 40–49. DOI: 10.1016/j.biocon.2007.07.025
+- Polasky, S. et al. (2008). Where to put things? Spatial land management to sustain biodiversity and economic returns. *Biological Conservation*, 141(6), 1505–1524. DOI: 10.1016/j.biocon.2008.03.022
+- Ferraro, P.J. (2003). Asymmetric information and contract design for payments for environmental services. *Ecological Economics*, 65(4), 810–821. DOI: 10.1016/j.ecolecon.2007.07.029