ecological-agent-skills 3.1.0

package/skills/spatial-prioritization/resources/marxan-vs-prioritizr-comparison.md

@@ -0,0 +1,125 @@
+---
+resource_id: marxan-vs-prioritizr-comparison
+skill_id: spatial-prioritization
+---
+
+# Marxan vs prioritizr vs Zonation: Tool Comparison
+
+## Core Comparison
+
+| Feature | Marxan | prioritizr | Zonation |
+|---------|--------|-----------|---------|
+| **Algorithm** | Simulated annealing (heuristic) | Integer Linear Programming (exact) | Iterative removal (hierarchical) |
+| **Solution type** | Multiple near-optimal solutions | Single optimal (or near-optimal with gap) | Continuous priority rank surface |
+| **Objective** | Minimum set / maximum coverage | Minimum set / maximum coverage / others | Hierarchical feature retention |
+| **Targets** | Required | Required | Optional (uses curves) |
+| **Spatial compactness** | BLM penalty | BLM penalty | Integrated via edge weights |
+| **Speed on large problems** | Fast (heuristic) | Slower (exact, ILP overhead) | Fast (greedy removal) |
+| **Repeatability** | Stochastic (multiple runs) | Deterministic (exact) | Deterministic |
+| **R integration** | marxan R package | Native R (prioritizr) | ZonationR (wrapper) |
+| **License** | Free (registration) | Open source (MIT) | Free (registration) |
+| **Best for** | Exploratory planning, large PU counts | Exact solution, auditability | Landscape-wide ranking without targets |
+
+---
+
+## When to Use Each Tool
+
+### Use Marxan when:
+- Very large landscapes (> 100,000 planning units) where ILP is computationally infeasible
+- Exploring multiple near-optimal solutions to present to stakeholders
+- Legacy workflow compatibility required
+
+### Use prioritizr when:
+- Provably optimal or near-optimal solution required (legal/policy context)
+- Multiple constraints (locked in, locked out, budget constraints) must be handled exactly
+- Reproducibility and auditability are paramount
+- Gap to optimality must be certified (gap < 1%)
+
+### Use Zonation when:
+- No hard targets — want to rank all areas from most to least irreplaceable
+- Connectivity features (dispersal kernels, landscape complementarity) are central
+- Creating a continuous priority surface for broad-scale land-use planning
+
+---
+
+## Equivalence of Marxan BLM and prioritizr BLM
+
+Both tools use a Boundary Length Modifier to penalise fragmentation, but implementation differs:
+
+```r
+# prioritizr: BLM is applied as a penalty per unit of boundary
+p_prioritizr <- p %>%
+  add_boundary_penalties(penalty = 0.01, data = NULL)
+
+# Marxan BLM equivalent (approximate)
+# Marxan BLM ≈ prioritizr penalty × mean PU perimeter
+```
+
+**Calibration:** The same BLM value will produce different results in Marxan vs prioritizr because Marxan's objective function scaling differs. Calibrate each tool's BLM independently.
+
+---
+
+## Zonation Priority Surface in R (Concept)
+
+Zonation iteratively removes the planning unit with the least conservation value, preserving the most irreplaceable areas until all PUs are removed. The order of removal = priority rank (last removed = highest priority).
+
+```r
+# Simplified Zonation-like ranking in R (for conceptual illustration)
+# Full Zonation requires the standalone software
+zonation_rank <- function(features, weights = NULL) {
+  if (is.null(weights)) weights <- rep(1, nlyr(features))
+  feature_vals <- as.data.frame(features, xy = FALSE, na.rm = FALSE)
+  # Weighted rarity-normalised score per cell
+  totals <- colSums(feature_vals, na.rm = TRUE)
+  totals[totals == 0] <- 1
+  norm_vals <- sweep(feature_vals, 2, totals, "/")
+  cell_scores <- rowSums(norm_vals * rep(weights, each = nrow(norm_vals)),
+                          na.rm = TRUE)
+  # Rank cells: higher score = higher priority
+  rank(-cell_scores, ties.method = "first")
+}
+```
+
+---
+
+## Irreplaceability Comparison
+
+Both Marxan and prioritizr can compute irreplaceability scores:
+
+| Method | Implementation | Interpretation |
+|--------|---------------|----------------|
+| Marxan summed solution frequency | Run 100 solutions; irreplaceability = frequency of selection | 1.0 = selected in all solutions = irreplaceable |
+| prioritizr rarity-weighted richness | `eval_rare_richness_importance()` | Higher = rarer features concentrated in that PU |
+| Zonation rank | Priority rank from removal order | Rank 1 = last removed = most irreplaceable |
+
+```r
+# prioritizr irreplaceability
+irr_map <- eval_rare_richness_importance(p, s)
+
+# Marxan portfolio approach via prioritizr
+# Run 100 solutions with varying budgets/targets
+solutions <- lapply(1:100, function(i) {
+  solve(p %>% add_highs_solver(gap = 0.05))  # relaxed gap for diversity
+})
+# Frequency map
+freq_map <- Reduce("+", solutions) / 100
+```
+
+---
+
+## Output Format Comparison
+
+| Output | Marxan | prioritizr | Zonation |
+|--------|--------|-----------|---------|
+| Solution raster | `.dat` grid or spatial join | `SpatRaster` (binary) | `.rank.compressed.tif` |
+| Feature representation | `_mvbest.txt` | `eval_feature_representation_summary()` | `curves.txt` |
+| Cost summary | `_summary.txt` | `eval_cost_summary()` | — |
+| Boundary | `_boundcalc.txt` | `eval_boundary_summary()` | edge weight output |
+
+---
+
+## References
+
+- Ball, I.R., Possingham, H.P. & Watts, M.E. (2009). Marxan and relatives: software for spatial conservation prioritisation. In: *Spatial Conservation Prioritisation* (pp. 185–195). Oxford University Press.
+- 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
+- Moilanen, A. et al. (2022). Zonation spatial conservation planning framework, Version 5. University of Helsinki.

package/skills/spatial-prioritization/resources/prioritizr-formulation-guide.md

@@ -0,0 +1,188 @@
+---
+resource_id: prioritizr-formulation-guide
+skill_id: spatial-prioritization
+---
+
+# prioritizr Problem Formulation Guide
+
+## Problem Types
+
+| Problem type | Objective | When to use |
+|-------------|-----------|-------------|
+| **Minimum set** | Minimise total cost subject to meeting targets | Tight budgets; known targets (30×30) |
+| **Maximum coverage** | Maximise features protected subject to budget | Fixed budget; want to maximise benefit |
+| **Maximum utility** | Maximise weighted feature benefit | Prioritising high-value features |
+| **Phylogenetic diversity** | Maximise phylogenetic diversity protected | Biodiversity triage |
+
+---
+
+## Minimum Set Problem — Core Structure
+
+```r
+# Usage: source this block or call from run_prioritization.R
+suppressPackageStartupMessages(library(prioritizr))
+suppressPackageStartupMessages(library(terra))
+suppressPackageStartupMessages(library(sf))
+
+# Inputs:
+#   pu_raster     — SpatRaster, planning units (cell = one PU)
+#                   Values = cost; NA = excluded from analysis
+#   features      — SpatRaster, one layer per biodiversity feature
+#                   Values = amount of feature in each PU (0–1 suitability or area)
+#   targets       — numeric vector, length = n_features, proportion to protect
+#   locked_in     — SpatRaster, 1 = must be selected (existing PAs)
+#   locked_out    — SpatRaster, 1 = must not be selected (developed areas)
+
+build_problem <- function(pu_raster, features, targets,
+                           locked_in = NULL, locked_out = NULL,
+                           blm = 0) {
+  p <- problem(pu_raster, features) %>%
+    add_min_set_objective() %>%
+    add_relative_targets(targets) %>%
+    add_binary_decisions() %>%
+    add_default_solver(gap = 0.01, time_limit = 600, verbose = FALSE)
+
+  if (!is.null(locked_in)) {
+    p <- p %>% add_locked_in_constraints(locked_in)
+  }
+  if (!is.null(locked_out)) {
+    p <- p %>% add_locked_out_constraints(locked_out)
+  }
+  if (blm > 0) {
+    p <- p %>% add_boundary_penalties(penalty = blm, data = NULL)
+  }
+  p
+}
+```
+
+---
+
+## Setting Representation Targets
+
+| Target basis | Example value | Recommended for |
+|-------------|-------------|-----------------|
+| Fixed proportion | 0.30 (30% of range) | 30×30 policy, simple analyses |
+| IUCN-based rule | Declining spp → 0.50; stable → 0.25 | Threat-based targets |
+| Gap analysis | 1 − (current protected / total range) | Sites already partially protected |
+| Area-based | Minimum area to maintain MVP | Species with known minimum area |
+
+```r
+# IUCN-based target function
+set_iucn_targets <- function(species_df) {
+  # species_df: columns 'species', 'iucn_category', 'protected_fraction'
+  targets <- ifelse(species_df$iucn_category %in% c("CR", "EN"), 0.60,
+             ifelse(species_df$iucn_category == "VU",             0.50,
+             ifelse(species_df$iucn_category == "NT",             0.35,
+                                                                  0.25)))
+  # Reduce by already protected fraction (gap analysis)
+  gap_targets <- pmax(0, targets - species_df$protected_fraction)
+  gap_targets
+}
+```
+
+---
+
+## Boundary Length Modifier (BLM) Calibration
+
+BLM controls the compactness of the selected solution:
+- BLM = 0: ignores spatial compactness (fragmented solution)
+- Large BLM: highly compact, may sacrifice feature representation
+
+```r
+# BLM calibration: evaluate cost-compactness tradeoff
+blm_values <- c(0, 0.001, 0.01, 0.1, 1, 10)
+
+blm_results <- lapply(blm_values, function(blm) {
+  p <- build_problem(pu, features, targets, locked_in, blm = blm)
+  s <- solve(p)
+  list(
+    blm           = blm,
+    total_cost    = eval_cost_summary(p, s)$cost,
+    total_boundary = eval_boundary_summary(p, s)$boundary,
+    n_pu_selected  = sum(values(s), na.rm = TRUE)
+  )
+})
+
+blm_df <- dplyr::bind_rows(blm_results)
+# Plot: total cost vs boundary length — choose elbow point
+```
+
+**Rule:** Select BLM at the elbow of the cost–boundary tradeoff curve. Above the elbow, additional boundary reduction costs disproportionately more.
+
+---
+
+## Solvers
+
+| Solver | R package | License | Recommended for |
+|--------|----------|---------|----------------|
+| **HiGHS** | `highs` | MIT (free) | Default for new analyses |
+| Gurobi | `gurobi` | Commercial | Large problems, fastest |
+| CPLEX | — | Commercial | Enterprise use |
+| lpsymphony | `lpsymphony` | Free | Fallback if HiGHS unavailable |
+| Rsymphony | `Rsymphony` | Free | Small problems |
+
+```r
+# Use HiGHS (free, recommended)
+p <- p %>%
+  add_highs_solver(gap = 0.01, time_limit = 600, verbose = FALSE)
+```
+
+---
+
+## Evaluating Solution Performance
+
+```r
+# After solving
+s <- solve(p)
+
+# Feature representation
+rep_summary <- eval_feature_representation_summary(p, s)
+print(rep_summary)
+# Columns: feature, total_amount, absolute_held, relative_held
+
+# Targets met?
+targets_met <- rep_summary$relative_held >= targets
+cat(sprintf("Targets met: %d / %d features\n",
+            sum(targets_met), length(targets_met)))
+
+# Cost summary
+cost_df <- eval_cost_summary(p, s)
+cat(sprintf("Total cost: %g\n", cost_df$cost))
+
+# Number of PUs selected
+n_pu <- sum(values(s), na.rm = TRUE)
+cat(sprintf("PUs selected: %d / %d\n", n_pu, ncell(s[!is.na(s)])))
+```
+
+---
+
+## Irreplaceability (Rarity-Weighted Richness)
+
+```r
+# Compute portfolio irreplaceability via feature rarity weighting
+irr <- eval_rare_richness_importance(p, s)
+writeRaster(irr, "outputs/prioritization/irreplaceability.tif", overwrite = TRUE)
+
+# High-irreplaceability PUs not in solution = overlooked priorities
+high_irr <- irr >= quantile(values(irr), 0.80, na.rm = TRUE)
+high_irr_not_selected <- high_irr & (s == 0)
+```
+
+---
+
+## Pitfalls
+
+- **Feature layers with different spatial extents:** All feature and cost rasters must have identical extent, resolution, and CRS. Reproject and resample to a common grid before analysis.
+- **Targets set to 1.0 (100%):** A target of 1.0 requires protecting all PUs with any amount of the feature — often infeasible. Use 0.9 maximum unless justified.
+- **Ignoring existing PAs:** Not locking in existing protected areas means the solver may exclude them and replace with cheaper PUs. Always lock in existing PAs.
+- **Cost = area:** Equal-area PUs with cost = 1 creates minimum-set problems but maximises area, not biodiversity per cost unit. Use real cost data (land value, opportunity cost) where available.
+- **BLM = 0 in fragmented landscapes:** Without boundary penalty, solutions are often highly fragmented and impractical. Always test with at least one non-zero BLM value.
+- **Ignoring connectivity in feature layers:** Using species presence/absence rather than SDM suitability as features may overrepresent common, widespread species.
+
+---
+
+## 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
+- Marxan Conservation Solutions (2020). Marxan User Manual v2.43.
+- 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/resources/representation-targets-guide.md

@@ -0,0 +1,186 @@
+---
+resource_id: representation-targets-guide
+skill_id: spatial-prioritization
+---
+
+# Representation Targets Guide
+
+## What Are Representation Targets?
+
+Representation targets define the minimum amount of each biodiversity feature that must be included in the conservation solution. They operationalise policy commitments (30×30) and species-level conservation requirements into quantitative thresholds for ILP formulation.
+
+---
+
+## Target Types in prioritizr
+
+| Target type | Function | Input format | Example |
+|-------------|---------|--------------|---------|
+| Relative | `add_relative_targets()` | Proportion of total feature amount | 0.30 = protect 30% of each feature |
+| Absolute | `add_absolute_targets()` | Raw units (km², individuals, occurrences) | 500 km² of suitable habitat |
+| Loglinear | `add_loglinear_targets()` | Curve from lower to upper bound | Small-range spp → higher targets |
+
+---
+
+## 30×30 Target Implementation
+
+```r
+suppressPackageStartupMessages(library(prioritizr))
+
+# Simple: 30% of each feature
+p_30x30 <- p %>%
+  add_relative_targets(0.30)
+
+# Refined: 30% of terrestrial features, 30% of marine features
+# Apply different targets per feature group
+n_terrestrial <- 45
+n_marine      <- 20
+targets_vec   <- c(rep(0.30, n_terrestrial), rep(0.30, n_marine))
+p_30x30_v2    <- p %>%
+  add_relative_targets(targets_vec)
+```
+
+**Note:** 30×30 refers to 30% of area protected by 2030. The ILP target of 0.30 for each feature is not equivalent to 30% of area — the solution may protect more or less than 30% of area depending on feature distribution.
+
+---
+
+## IUCN-Based Targets (Gap Analysis)
+
+```r
+compute_iucn_targets <- function(species_df, features, existing_pa_raster) {
+  # species_df: columns species, iucn_category, total_range_km2
+  # features: SpatRaster with one layer per species
+  # existing_pa_raster: 1 = protected, 0 = not
+
+  n <- nrow(species_df)
+  targets <- numeric(n)
+
+  for (i in seq_len(n)) {
+    cat_i <- species_df$iucn_category[i]
+    # Raw targets by IUCN category (based on Jenkins et al. 2015)
+    raw_target <- switch(cat_i,
+      CR = 0.60,
+      EN = 0.50,
+      VU = 0.40,
+      NT = 0.30,
+           0.17  # LC default (Aichi Target 11)
+    )
+    # Gap analysis: subtract already protected fraction
+    feat_layer  <- features[[i]]
+    total_amt   <- global(feat_layer, "sum", na.rm = TRUE)[[1]]
+    pa_amt      <- global(feat_layer * existing_pa_raster, "sum", na.rm = TRUE)[[1]]
+    pct_protected <- pa_amt / max(total_amt, 1e-9)
+    gap_target  <- max(0, raw_target - pct_protected)
+    targets[i]  <- gap_target
+  }
+  targets
+}
+```
+
+---
+
+## Log-Linear Targets for Range-Size-Based Scaling
+
+Large-range species require smaller proportional targets than small-range species (Rodrigues et al. 2004):
+
+```r
+# Log-linear target function
+# Lower target for widespread, upper target for rare species
+loglinear_targets <- function(range_km2,
+                               lower_threshold_km2 = 1000,
+                               upper_threshold_km2  = 250000,
+                               lower_target = 0.10,
+                               upper_target = 1.00) {
+  targets <- ifelse(range_km2 < lower_threshold_km2,
+    upper_target,
+    ifelse(range_km2 > upper_threshold_km2,
+      lower_target,
+      upper_target + (lower_target - upper_target) *
+        (log(range_km2) - log(lower_threshold_km2)) /
+        (log(upper_threshold_km2) - log(lower_threshold_km2))
+    )
+  )
+  targets
+}
+
+# Example
+species_ranges <- c(100, 1000, 50000, 500000)  # km²
+targets <- loglinear_targets(species_ranges)
+cat(data.frame(range_km2 = species_ranges, target = round(targets, 2)))
+```
+
+| Range (km²) | Target |
+|-------------|--------|
+| 100 | 1.00 (100%) |
+| 1,000 | 1.00 (threshold) |
+| 50,000 | 0.62 |
+| 500,000 | 0.10 |
+
+---
+
+## Feature Weights (Prioritising Threatened Species)
+
+When not all features are equally important, apply weights:
+
+```r
+# Weight by IUCN category
+weights_vec <- case_when(
+  species_df$iucn_category == "CR" ~ 4,
+  species_df$iucn_category == "EN" ~ 3,
+  species_df$iucn_category == "VU" ~ 2,
+  species_df$iucn_category == "NT" ~ 1.5,
+  TRUE ~ 1
+)
+
+# Apply in maximum coverage problem
+p_weighted <- problem(pu, features) %>%
+  add_max_features_objective(budget = total_budget) %>%
+  add_absolute_targets(1e-6) %>%  # minimum feasibility
+  add_feature_weights(weights_vec) %>%
+  add_binary_decisions() %>%
+  add_highs_solver(gap = 0.01)
+```
+
+---
+
+## Target Shortfalls and Cost-Benefit Curves
+
+When targets cannot be fully met within budget:
+
+```r
+# Evaluate target shortfalls after solving
+rep_summary <- eval_feature_representation_summary(p, s)
+shortfall_df <- rep_summary %>%
+  mutate(target = targets_vec,
+         shortfall = pmax(0, target - relative_held),
+         pct_shortfall = shortfall / target * 100) %>%
+  arrange(desc(shortfall))
+
+# Cost-effectiveness curve: cost vs % of targets met
+budgets <- seq(0.2, 1.0, by = 0.1) * total_budget
+ce_results <- lapply(budgets, function(b) {
+  p_b <- p %>% add_max_features_objective(budget = b)
+  s_b <- solve(p_b)
+  rep_b <- eval_feature_representation_summary(p_b, s_b)
+  data.frame(budget = b,
+             pct_targets_met = mean(rep_b$relative_held >= targets_vec) * 100)
+})
+ce_df <- dplyr::bind_rows(ce_results)
+```
+
+---
+
+## Pitfalls
+
+- **Relative targets applied to features with zero total:** If a feature has total_amount = 0 (no occurrence in study area), any relative target is infeasible. Filter out zero-occurrence features before analysis.
+- **Targets exceeding currently achievable area:** If 80% of a species' range is already developed, a target of 0.60 may be infeasible. Check feasibility before optimisation.
+- **Equal targets for all species regardless of area or threat:** This treats a critically endangered microendemic the same as a common widespread species. Always use IUCN or range-based targets.
+- **Forgetting to account for feature detectability:** SDM-based features represent potential habitat, not confirmed presence. Over-targeting poorly surveyed species inflates solution cost without confirmed benefit.
+- **Targets ignore quality:** A target of 30% met by degraded habitat may not achieve conservation objectives. Consider weighting feature layers by habitat quality before setting targets.
+
+---
+
+## References
+
+- 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
+- Jenkins, C.N. et al. (2015). Global patterns of terrestrial vertebrate diversity and conservation. *PNAS*, 112(18), 5667–5672. DOI: 10.1073/pnas.1302251112
+- CBD (2022). *Kunming-Montreal Global Biodiversity Framework*. Convention on Biological Diversity, COP15.