ecological-agent-skills 3.1.0

package/skills/spatial-prioritization/scripts/prioritization_sensitivity.R

@@ -0,0 +1,320 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript prioritization_sensitivity.R <pu_raster> <features_dir>
+#        <output_dir> [targets] [locked_in_raster] [locked_out_raster]
+#
+# Sensitivity analysis for conservation prioritization:
+#   1. BLM calibration (cost vs compactness tradeoff)
+#   2. Target sensitivity (50%, 75%, 100%, 125%, 150% of baseline targets)
+#   3. Cost scenario sensitivity (-30%, baseline, +30%)
+#   4. Portfolio irreplaceability (selection frequency across scenarios)
+#
+# Outputs:
+#   blm_calibration.csv            — Cost and boundary at each BLM value
+#   blm_calibration_plot.png       — Elbow plot for BLM selection
+#   target_sensitivity.csv         — Targets met and cost at each target scaling
+#   cost_scenario_sensitivity.csv  — Cost and PU selection under cost uncertainty
+#   portfolio_frequency.tif        — Selection frequency raster across all scenarios
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "spatial-prioritization"
+.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(prioritizr))
+suppressPackageStartupMessages(library(terra))
+suppressPackageStartupMessages(library(dplyr))
+suppressPackageStartupMessages(library(ggplot2))
+
+args <- commandArgs(trailingOnly = TRUE)
+if (length(args) < 3) {
+  cat("Usage: Rscript prioritization_sensitivity.R <pu_raster> <features_dir>",
+      "<output_dir> [targets] [locked_in] [locked_out]\n")
+  quit(status = 1)
+}
+
+pu_path      <- args[1]
+features_dir <- args[2]
+output_dir   <- args[3]
+targets_arg  <- if (length(args) >= 4 && args[4] != "NA") args[4] else "0.30"
+locked_in_p  <- if (length(args) >= 5 && args[5] != "NA") args[5] else NULL
+locked_out_p <- if (length(args) >= 6 && args[6] != "NA") args[6] else NULL
+
+# ── Input precondition checks ─────────────────────────────────────────────────
+if (!file.exists(pu_path)) {
+  log_error("Input nao encontrado: %s\nCausa provavel: passo anterior nao concluiu.\nVerifique: outputs do skill anterior.\nSkill anterior: spatial-prioritization (run_prioritization)", pu_path)
+  stop("Missing input: ", pu_path)
+}
+if (!dir.exists(features_dir)) {
+  log_error("Diretorio de features nao encontrado: %s\nCausa provavel: passo anterior nao concluiu ou caminho incorreto.\nVerifique: outputs do skill anterior.\nSkill anterior: spatial-prioritization (run_prioritization)", features_dir)
+  stop("Missing features directory: ", features_dir)
+}
+
+log_decision("targets_arg", targets_arg, "Baseline targets: single proportion applied to all features, or path to CSV with per-feature targets")
+log_decision("locked_in_p", ifelse(is.null(locked_in_p), "none", locked_in_p), "Locked-in raster constrains solver to always select these PUs")
+log_decision("locked_out_p", ifelse(is.null(locked_out_p), "none", locked_out_p), "Locked-out raster constrains solver to never select these PUs")
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+# ── Load data ─────────────────────────────────────────────────────────────────
+log_step(1, "Load planning unit raster and feature layers")
+tryCatch({
+  pu       <- rast(pu_path)
+  feat_files <- list.files(features_dir, pattern = "\\.tif$",
+                            full.names = TRUE, ignore.case = TRUE)
+  if (length(feat_files) == 0) {
+    log_error("Nenhum arquivo .tif encontrado em: %s\nCausa provavel: features_dir incorreto ou features nao geradas.\nVerifique: conteudo do diretorio de features.\nSkill anterior: spatial-prioritization (run_prioritization)", features_dir)
+    stop("No .tif feature files found in: ", features_dir)
+  }
+  features   <- rast(feat_files)
+  features   <- resample(features, pu, method = "bilinear")
+  names(features) <- tools::file_path_sans_ext(basename(feat_files))
+
+  # Remove zero-sum features
+  feat_sums <- global(features, "sum", na.rm = TRUE)[[1]]
+  zero_feats <- names(features)[feat_sums == 0]
+  if (length(zero_feats) > 0) {
+    log_warn("%d features com soma zero excluidas: %s", length(zero_feats), paste(zero_feats, collapse = ", "))
+  }
+  features  <- features[[feat_sums > 0]]
+  n_feats   <- nlyr(features)
+  log_info("Planning unit raster loaded: %d x %d cells.", nrow(pu), ncol(pu))
+  log_info("Feature layers loaded: %d (after removing zero-sum).", n_feats)
+
+  if (n_feats < 1) {
+    log_error("Nenhuma feature valida apos remocao de zero-sum.\nCausa provavel: todas as features tem distribuicao zero na area de estudo.\nVerifique: extensao espacial dos rasters de features.\nSkill anterior: spatial-prioritization (run_prioritization)")
+    stop("No valid feature layers remaining after zero-sum removal.")
+  }
+}, error = function(e) {
+  log_error("Falha em load_data: %s\nCausa provavel: rasters corrompidos, incompativeis ou caminho incorreto.\nVerifique: arquivos .tif e resolucao espacial.\nSkill anterior: spatial-prioritization (run_prioritization)", conditionMessage(e))
+  stop(e)
+})
+
+# Baseline targets
+log_step(2, "Set baseline targets")
+tryCatch({
+  if (file.exists(targets_arg)) {
+    target_df   <- read.csv(targets_arg)
+    targets_base <- target_df$target[match(names(features), target_df$feature_name)]
+    n_unmatched <- sum(is.na(targets_base))
+    targets_base[is.na(targets_base)] <- 0.30
+    if (n_unmatched > 0) {
+      log_warn("%d features sem alvo no CSV; usando padrao 0.30.", n_unmatched)
+    }
+    log_decision("targets_base", "from_csv", paste0("Per-feature targets loaded from ", targets_arg))
+  } else {
+    targets_base <- rep(as.numeric(targets_arg), n_feats)
+    log_decision("targets_base", targets_arg, "Single proportion applied uniformly to all features")
+  }
+  log_info("Baseline targets: min=%.2f, mean=%.2f, max=%.2f",
+           min(targets_base), mean(targets_base), max(targets_base))
+}, error = function(e) {
+  log_error("Falha em set_targets: %s\nCausa provavel: CSV de alvos malformado ou proporcao invalida.\nVerifique: formato do arquivo de alvos e nomes das features.\nSkill anterior: spatial-prioritization (run_prioritization)", conditionMessage(e))
+  stop(e)
+})
+
+# Helper: build and solve base problem with given cost and targets
+solve_scenario <- function(cost_r, targets_v, blm_val = 0, name = "scenario") {
+  p <- problem(cost_r, features) %>%
+    add_min_set_objective() %>%
+    add_relative_targets(pmin(targets_v, 0.999)) %>%
+    add_binary_decisions() %>%
+    add_highs_solver(gap = 0.05, time_limit = 300, verbose = FALSE)
+
+  if (!is.null(locked_in_p)) {
+    li <- resample(rast(locked_in_p), cost_r, method = "near")
+    p  <- p %>% add_locked_in_constraints(li)
+  }
+  if (!is.null(locked_out_p)) {
+    lo <- resample(rast(locked_out_p), cost_r, method = "near")
+    p  <- p %>% add_locked_out_constraints(lo)
+  }
+  if (blm_val > 0) {
+    p <- p %>% add_boundary_penalties(penalty = blm_val, data = NULL)
+  }
+
+  s <- tryCatch(solve(p), error = function(e) {
+    log_warn("Solver falhou para cenario '%s': %s. Retornando NULL.", name, conditionMessage(e))
+    return(NULL)
+  })
+  if (is.null(s)) return(NULL)
+
+  rep_s   <- eval_feature_representation_summary(p, s)
+  cost_s  <- eval_cost_summary(p, s)$cost
+  bound_s <- tryCatch(eval_boundary_summary(p, s)$boundary,
+                       error = function(e) NA_real_)
+
+  list(
+    solution       = s,
+    n_selected     = sum(values(s) == 1, na.rm = TRUE),
+    total_cost     = cost_s,
+    boundary       = bound_s,
+    targets_met    = sum(rep_s$relative_held >= targets_v, na.rm = TRUE),
+    mean_held      = mean(rep_s$relative_held, na.rm = TRUE)
+  )
+}
+
+# ── 1. BLM Calibration ────────────────────────────────────────────────────────
+log_step(3, "BLM calibration: cost vs compactness tradeoff")
+log_info("Running BLM calibration...")
+blm_values <- c(0, 0.001, 0.01, 0.05, 0.1, 0.5, 1.0)
+log_decision("blm_values", paste(blm_values, collapse = ", "),
+             "Standard BLM range spanning several orders of magnitude to identify elbow in cost-boundary tradeoff")
+
+tryCatch({
+  blm_results <- lapply(blm_values, function(blm) {
+    log_info("  BLM = %g", blm)
+    res <- solve_scenario(pu, targets_base, blm_val = blm,
+                          name = paste0("blm_", blm))
+    if (is.null(res)) {
+      log_warn("Cenario BLM=%g nao produziu solucao.", blm)
+      return(NULL)
+    }
+    data.frame(blm = blm, cost = res$total_cost,
+               boundary = res$boundary, n_selected = res$n_selected)
+  })
+  blm_df <- dplyr::bind_rows(Filter(Negate(is.null), blm_results))
+  write.csv(blm_df, file.path(output_dir, "blm_calibration.csv"), row.names = FALSE)
+  log_info("BLM calibration done. %d / %d scenarios solved successfully.", nrow(blm_df), length(blm_values))
+
+  if (nrow(blm_df) < 3) {
+    log_warn("Menos de 3 cenarios BLM resolvidos. Grafico de cotovelo pode ser insuficiente para selecao de BLM.")
+  }
+}, error = function(e) {
+  log_error("Falha em blm_calibration: %s\nCausa provavel: falha do solver HiGHS ou dados raster invalidos.\nVerifique: instalacao do HiGHS e integridade dos rasters.\nSkill anterior: spatial-prioritization (run_prioritization)", conditionMessage(e))
+  stop(e)
+})
+
+# BLM elbow plot
+log_step(4, "Generate BLM elbow plot")
+if (nrow(blm_df) > 2) {
+  tryCatch({
+    p_blm <- ggplot(blm_df, aes(x = boundary, y = cost, label = blm)) +
+      geom_path(colour = "steelblue") +
+      geom_point(size = 3, colour = "steelblue") +
+      ggrepel::geom_text_repel(size = 3) +
+      labs(x = "Total boundary length", y = "Total cost",
+           title = "BLM calibration: cost vs compactness tradeoff") +
+      theme_minimal(base_size = 10)
+    tryCatch(
+      ggsave(file.path(output_dir, "blm_calibration_plot.png"), p_blm,
+             width = 7, height = 5, dpi = 150),
+      error = function(e) log_warn("BLM plot falhou ao salvar: %s", conditionMessage(e))
+    )
+    log_info("BLM calibration plot saved.")
+  }, error = function(e) {
+    log_warn("Falha ao gerar grafico BLM: %s. Continuando sem o grafico.", conditionMessage(e))
+  })
+} else {
+  log_warn("Dados insuficientes para grafico BLM (menos de 3 pontos). Grafico nao gerado.")
+}
+
+# ── 2. Target Sensitivity ─────────────────────────────────────────────────────
+log_step(5, "Target sensitivity analysis")
+log_info("Running target sensitivity analysis...")
+target_scalings <- c(0.50, 0.75, 1.00, 1.25, 1.50)
+log_decision("target_scalings", paste(target_scalings, collapse = ", "),
+             "Scaling factors applied to baseline targets to assess sensitivity of solution cost and coverage")
+
+tryCatch({
+  target_results <- lapply(target_scalings, function(sc) {
+    log_info("  Target scaling = %.2fx", sc)
+    tgts <- pmin(targets_base * sc, 0.999)
+    res  <- solve_scenario(pu, tgts, name = paste0("target_", sc))
+    if (is.null(res)) {
+      log_warn("Cenario de alvo %.2fx nao produziu solucao.", sc)
+      return(NULL)
+    }
+    data.frame(target_scaling = sc,
+               mean_target    = mean(tgts),
+               cost           = res$total_cost,
+               targets_met    = res$targets_met,
+               n_selected     = res$n_selected)
+  })
+  target_df <- dplyr::bind_rows(Filter(Negate(is.null), target_results))
+  write.csv(target_df, file.path(output_dir, "target_sensitivity.csv"),
+            row.names = FALSE)
+  log_info("Target sensitivity done. %d / %d scenarios solved.", nrow(target_df), length(target_scalings))
+}, error = function(e) {
+  log_error("Falha em target_sensitivity: %s\nCausa provavel: falha do solver ou alvos fora do intervalo [0, 0.999].\nVerifique: valores de targets_base e instalacao do HiGHS.\nSkill anterior: spatial-prioritization (run_prioritization)", conditionMessage(e))
+  stop(e)
+})
+
+# ── 3. Cost Scenario Sensitivity ──────────────────────────────────────────────
+log_step(6, "Cost scenario sensitivity analysis")
+log_info("Running cost scenario sensitivity analysis...")
+log_decision("cost_scenarios", "low=-30%, baseline, high=+30%",
+             "Standard cost uncertainty range to assess robustness of prioritization to cost data errors")
+
+tryCatch({
+  cost_scenarios <- list(
+    low      = pu * 0.70,
+    baseline = pu,
+    high     = pu * 1.30
+  )
+
+  cost_results <- lapply(names(cost_scenarios), function(name) {
+    log_info("  Cost scenario: %s", name)
+    res <- solve_scenario(cost_scenarios[[name]], targets_base, name = name)
+    if (is.null(res)) {
+      log_warn("Cenario de custo '%s' nao produziu solucao.", name)
+      return(NULL)
+    }
+    data.frame(cost_scenario = name,
+               total_cost    = res$total_cost,
+               n_selected    = res$n_selected,
+               targets_met   = res$targets_met)
+  })
+  cost_df <- dplyr::bind_rows(Filter(Negate(is.null), cost_results))
+  write.csv(cost_df, file.path(output_dir, "cost_scenario_sensitivity.csv"),
+            row.names = FALSE)
+  log_info("Cost scenario sensitivity done. %d / %d scenarios solved.", nrow(cost_df), length(cost_scenarios))
+}, error = function(e) {
+  log_error("Falha em cost_scenario_sensitivity: %s\nCausa provavel: falha do solver ou raster de custo invalido.\nVerifique: valores do raster pu e instalacao do HiGHS.\nSkill anterior: spatial-prioritization (run_prioritization)", conditionMessage(e))
+  stop(e)
+})
+
+# ── 4. Portfolio Irreplaceability ─────────────────────────────────────────────
+log_step(7, "Build portfolio irreplaceability (selection frequency across all scenarios)")
+log_info("Building portfolio irreplaceability (selection frequency across scenarios)...")
+
+tryCatch({
+  # Collect all solutions computed above
+  all_solutions <- list()
+  for (blm in blm_values) {
+    res <- solve_scenario(pu, targets_base, blm_val = blm, name = paste0("blm_", blm))
+    if (!is.null(res)) all_solutions[[length(all_solutions) + 1]] <- res$solution
+  }
+  for (sc in target_scalings) {
+    tgts <- pmin(targets_base * sc, 0.999)
+    res  <- solve_scenario(pu, tgts, name = paste0("target_", sc))
+    if (!is.null(res)) all_solutions[[length(all_solutions) + 1]] <- res$solution
+  }
+
+  if (length(all_solutions) < 2) {
+    log_warn("Solucoes insuficientes para analise de portfolio (%d). Sao necessarias pelo menos 2.", length(all_solutions))
+  } else {
+    freq_raster <- Reduce("+", all_solutions) / length(all_solutions)
+    names(freq_raster) <- "selection_frequency"
+    writeRaster(freq_raster, file.path(output_dir, "portfolio_frequency.tif"),
+                overwrite = TRUE)
+    log_info("Portfolio frequency raster saved (%d scenarios).", length(all_solutions))
+  }
+}, error = function(e) {
+  log_error("Falha em portfolio_irreplaceability: %s\nCausa provavel: solucoes incompativeis (extensoes diferentes) ou falha na soma de rasters.\nVerifique: consistencia espacial das solucoes individuais.\nSkill anterior: spatial-prioritization (run_prioritization)", conditionMessage(e))
+  stop(e)
+})
+
+# ── Summary report ────────────────────────────────────────────────────────────
+log_step(8, "Print sensitivity analysis summary")
+log_info("=== Sensitivity Analysis Summary ===")
+log_info("BLM calibration:\n%s", paste(capture.output(print(blm_df)), collapse = "\n"))
+log_info("Target sensitivity:\n%s", paste(capture.output(print(target_df)), collapse = "\n"))
+log_info("Cost scenario sensitivity:\n%s", paste(capture.output(print(cost_df)), collapse = "\n"))
+log_info("Sensitivity analysis complete.")

package/skills/spatial-prioritization/scripts/run_prioritization.R

@@ -0,0 +1,336 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript run_prioritization.R <pu_raster> <features_dir> <output_dir>
+#        [targets] [locked_in_raster] [locked_out_raster] [blm] [budget]
+#
+# Runs systematic conservation prioritization using prioritizr (minimum-set
+# or maximum-coverage ILP problem solved with HiGHS solver).
+#
+# Arguments:
+#   pu_raster         — Planning unit cost raster (.tif); NA = excluded
+#   features_dir      — Directory of feature rasters (.tif, one per species/habitat)
+#   output_dir        — Directory for output files
+#   targets           — Single value (applied to all features) or path to CSV
+#                       with columns feature_name, target (default: 0.30)
+#   locked_in_raster  — Binary raster, 1 = must select (default: none)
+#   locked_out_raster — Binary raster, 1 = must exclude (default: none)
+#   blm               — Boundary length modifier (default: 0)
+#   budget            — For maximum coverage problem; if provided, switches
+#                       objective to max-features (default: NA = min-set)
+#
+# Outputs:
+#   solution.tif               — Binary raster: 1 = selected PU
+#   feature_representation.csv — Amount of each feature in solution
+#   cost_summary.csv           — Total cost and number of PUs selected
+#   irreplaceability.tif       — Rarity-weighted importance of each PU
+#   prioritization_map.png     — Visual output
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "spatial-prioritization"
+.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(prioritizr))
+suppressPackageStartupMessages(library(terra))
+suppressPackageStartupMessages(library(sf))
+suppressPackageStartupMessages(library(dplyr))
+suppressPackageStartupMessages(library(ggplot2))
+
+args <- commandArgs(trailingOnly = TRUE)
+if (length(args) < 3) {
+  cat("Usage: Rscript run_prioritization.R <pu_raster> <features_dir>",
+      "<output_dir> [targets] [locked_in] [locked_out] [blm] [budget]\n")
+  quit(status = 1)
+}
+
+pu_path       <- args[1]
+features_dir  <- args[2]
+output_dir    <- args[3]
+targets_arg   <- if (length(args) >= 4 && args[4] != "NA") args[4] else "0.30"
+locked_in_p   <- if (length(args) >= 5 && args[5] != "NA") args[5] else NULL
+locked_out_p  <- if (length(args) >= 6 && args[6] != "NA") args[6] else NULL
+blm           <- if (length(args) >= 7) as.numeric(args[7]) else 0
+budget        <- if (length(args) >= 8 && args[8] != "NA") as.numeric(args[8]) else NA_real_
+
+# ── Input precondition checks ─────────────────────────────────────────────────
+if (!file.exists(pu_path)) {
+  log_error("Input nao encontrado: %s\nCausa provavel: passo anterior nao concluiu.\nVerifique: outputs do skill anterior.\nSkill anterior: species-distribution-modeling", pu_path)
+  stop("Missing input: ", pu_path)
+}
+if (!dir.exists(features_dir)) {
+  log_error("Diretorio de features nao encontrado: %s\nCausa provavel: passo anterior nao concluiu ou caminho incorreto.\nVerifique: outputs do skill anterior.\nSkill anterior: species-distribution-modeling", features_dir)
+  stop("Missing features directory: ", features_dir)
+}
+
+log_decision("targets_arg", targets_arg, "Conservation targets: single proportion for all features or path to per-feature CSV")
+log_decision("blm", blm, "Boundary length modifier: 0 = no compactness penalty; increase to promote spatially compact solutions")
+log_decision("budget", ifelse(is.na(budget), "NA (min-set)", budget), "Budget for max-coverage objective; NA triggers minimum-set formulation")
+log_decision("locked_in_p", ifelse(is.null(locked_in_p), "none", locked_in_p), "Locked-in raster: PUs that must always be selected (e.g., existing protected areas)")
+log_decision("locked_out_p", ifelse(is.null(locked_out_p), "none", locked_out_p), "Locked-out raster: PUs that must never be selected (e.g., urban areas)")
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+# ── Load planning units ───────────────────────────────────────────────────────
+log_step(1, "Load planning unit raster")
+tryCatch({
+  pu <- rast(pu_path)
+  log_info("Planning units: %d x %d cells, CRS: %s",
+           nrow(pu), ncol(pu), crs(pu, describe = TRUE)$name)
+
+  n_pu_total <- sum(!is.na(values(pu)))
+  log_info("Valid planning units: %d", n_pu_total)
+
+  if (n_pu_total < 10) {
+    log_warn("Numero muito baixo de unidades de planejamento validas (%d). Verifique a mascara de NA no raster pu.", n_pu_total)
+  }
+}, error = function(e) {
+  log_error("Falha em load_planning_units: %s\nCausa provavel: raster corrompido, caminho incorreto ou CRS ausente.\nVerifique: arquivo pu_raster e sua integridade.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Load features ─────────────────────────────────────────────────────────────
+log_step(2, "Load feature rasters")
+tryCatch({
+  feat_files <- list.files(features_dir, pattern = "\\.tif$",
+                            full.names = TRUE, ignore.case = TRUE)
+  if (length(feat_files) == 0) {
+    log_error("Nenhum arquivo .tif encontrado em: %s\nCausa provavel: features nao geradas ou caminho incorreto.\nVerifique: conteudo do diretorio features_dir.\nSkill anterior: species-distribution-modeling", features_dir)
+    stop("No .tif feature files found in: ", features_dir)
+  }
+  log_info("Loading %d feature layers...", length(feat_files))
+
+  features <- rast(feat_files)
+  # Ensure same extent/resolution as planning units
+  features <- resample(features, pu, method = "bilinear")
+  names(features) <- tools::file_path_sans_ext(basename(feat_files))
+
+  # Check for zero-sum features
+  feat_sums <- global(features, "sum", na.rm = TRUE)[[1]]
+  zero_feats <- names(features)[feat_sums == 0]
+  if (length(zero_feats) > 0) {
+    log_warn("%d features com soma zero excluidas (nenhuma ocorrencia na area de estudo): %s",
+             length(zero_feats), paste(zero_feats, collapse = ", "))
+    features <- features[[!names(features) %in% zero_feats]]
+  }
+  n_feats <- nlyr(features)
+  log_info("Features loaded: %d (after removing zero-sum)", n_feats)
+
+  if (n_feats == 0) {
+    log_error("Nenhuma feature valida apos remocao de zero-sum.\nCausa provavel: features nao sobrepõem a area de planejamento.\nVerifique: extensao e CRS dos rasters de features vs pu_raster.\nSkill anterior: species-distribution-modeling")
+    stop("No valid features remaining after zero-sum removal.")
+  }
+}, error = function(e) {
+  log_error("Falha em load_features: %s\nCausa provavel: rasters corrompidos, incompativeis ou diretorio vazio.\nVerifique: arquivos .tif em features_dir e compatibilidade com pu_raster.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Set targets ────────────────────────────────────────────────────────────────
+log_step(3, "Set conservation targets")
+tryCatch({
+  if (file.exists(targets_arg)) {
+    target_df <- read.csv(targets_arg)
+    targets_vec <- target_df$target[match(names(features), target_df$feature_name)]
+    na_targets  <- is.na(targets_vec)
+    targets_vec[na_targets] <- 0.30  # default for unmatched features
+    if (any(na_targets)) {
+      log_warn("Alvo nao encontrado para %d features; usando padrao 0.30: %s",
+               sum(na_targets), paste(names(features)[na_targets], collapse = ", "))
+    }
+    log_decision("targets_vec", "from_csv", paste0("Per-feature targets loaded from ", targets_arg))
+  } else {
+    targets_vec <- rep(as.numeric(targets_arg), n_feats)
+    log_decision("targets_vec", targets_arg, "Uniform proportion target applied to all features")
+  }
+  log_info("Targets: min=%.2f, mean=%.2f, max=%.2f",
+           min(targets_vec), mean(targets_vec), max(targets_vec))
+
+  if (any(targets_vec > 0.90)) {
+    log_warn("%d features com alvo > 90%%. Alvos muito altos podem tornar o problema inviavel.", sum(targets_vec > 0.90))
+  }
+}, error = function(e) {
+  log_error("Falha em set_targets: %s\nCausa provavel: CSV de alvos malformado ou proporcao invalida fora de [0,1].\nVerifique: formato do arquivo de alvos e nomes das features.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Build problem ─────────────────────────────────────────────────────────────
+log_step(4, "Build prioritizr problem")
+tryCatch({
+  if (is.na(budget)) {
+    # Minimum set problem
+    p <- problem(pu, features) %>%
+      add_min_set_objective() %>%
+      add_relative_targets(targets_vec)
+    log_info("Objective: minimum cost (min-set)")
+    log_decision("objective", "min_set", "No budget specified; minimize cost while meeting all targets")
+  } else {
+    # Maximum coverage problem
+    p <- problem(pu, features) %>%
+      add_max_features_objective(budget = budget) %>%
+      add_absolute_targets(1e-6)  # minimum feasibility constraint
+    log_info("Objective: maximum coverage (budget = %g)", budget)
+    log_decision("objective", "max_features", paste0("Budget ", budget, " specified; maximize feature coverage within budget"))
+  }
+
+  p <- p %>%
+    add_binary_decisions()
+
+  # Locked-in
+  if (!is.null(locked_in_p)) {
+    li <- rast(locked_in_p)
+    li <- resample(li, pu, method = "near")
+    p  <- p %>% add_locked_in_constraints(li)
+    n_li <- sum(values(li) == 1, na.rm = TRUE)
+    log_info("Locked-in: %d PUs", n_li)
+    if (n_li == 0) {
+      log_warn("Raster locked-in fornecido mas nenhuma PU com valor 1 encontrada.")
+    }
+  }
+
+  # Locked-out
+  if (!is.null(locked_out_p)) {
+    lo <- rast(locked_out_p)
+    lo <- resample(lo, pu, method = "near")
+    p  <- p %>% add_locked_out_constraints(lo)
+    n_lo <- sum(values(lo) == 1, na.rm = TRUE)
+    log_info("Locked-out: %d PUs", n_lo)
+    if (n_lo == 0) {
+      log_warn("Raster locked-out fornecido mas nenhuma PU com valor 1 encontrada.")
+    }
+  }
+
+  # Boundary penalty
+  if (blm > 0) {
+    p <- p %>% add_boundary_penalties(penalty = blm, data = NULL)
+    log_info("Boundary length modifier applied: %g", blm)
+  }
+
+  # Solver (HiGHS preferred)
+  p <- p %>%
+    add_highs_solver(gap = 0.01, time_limit = 600, verbose = TRUE)
+
+  log_info("Problem built successfully.")
+}, error = function(e) {
+  log_error("Falha em build_problem: %s\nCausa provavel: incompatibilidade entre rasters, alvos invalidos ou pacote prioritizr desatualizado.\nVerifique: versoes de prioritizr e terra, e compatibilidade espacial dos rasters.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Solve ─────────────────────────────────────────────────────────────────────
+log_step(5, "Solve prioritization problem with HiGHS solver")
+log_info("Solving...")
+tryCatch({
+  s <- tryCatch(
+    solve(p),
+    error = function(e) {
+      log_warn("HiGHS falhou: %s. Tentando fallback para lpsymphony...", conditionMessage(e))
+      p2 <- p %>% add_lpsymphony_solver(gap = 0.05, time_limit = 600)
+      solve(p2)
+    }
+  )
+  log_info("Solver completed successfully.")
+}, error = function(e) {
+  log_error("Falha em solve_problem: %s\nCausa provavel: problema inviavel (alvos inalcancaveis), solver nao instalado, ou timeout.\nVerifique: alvos vs disponibilidade de features, e instalacao do HiGHS/lpsymphony.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Write solution raster ─────────────────────────────────────────────────────
+log_step(6, "Write solution raster and compute selection summary")
+tryCatch({
+  sol_path <- file.path(output_dir, "solution.tif")
+  writeRaster(s, sol_path, overwrite = TRUE)
+  n_selected <- sum(values(s) == 1, na.rm = TRUE)
+  log_info("Solution: %d PUs selected (%.1f%% of valid PUs)",
+           n_selected, n_selected / n_pu_total * 100)
+
+  if (n_selected == 0) {
+    log_warn("Nenhuma PU selecionada na solucao. Verifique viabilidade do problema e restricoes locked-out.")
+  }
+  if (n_selected / n_pu_total > 0.80) {
+    log_warn("Mais de 80%% das PUs selecionadas (%.1f%%). Alvos podem ser muito altos ou area de estudo muito restrita.", n_selected / n_pu_total * 100)
+  }
+}, error = function(e) {
+  log_error("Falha em write_solution: %s\nCausa provavel: permissoes de escrita ou solucao invalida.\nVerifique: output_dir e resultado do solver.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Feature representation ────────────────────────────────────────────────────
+log_step(7, "Evaluate feature representation in solution")
+tryCatch({
+  rep_df <- eval_feature_representation_summary(p, s)
+  rep_df$target <- targets_vec
+  rep_df$target_met <- rep_df$relative_held >= targets_vec
+
+  write.csv(rep_df, file.path(output_dir, "feature_representation.csv"),
+            row.names = FALSE)
+  n_targets_met <- sum(rep_df$target_met, na.rm = TRUE)
+  log_info("Targets met: %d / %d features", n_targets_met, n_feats)
+
+  if (n_targets_met < n_feats) {
+    log_warn("%d features nao atingiram seus alvos de representacao. Verifique viabilidade e restricoes.", n_feats - n_targets_met)
+  }
+}, error = function(e) {
+  log_error("Falha em feature_representation: %s\nCausa provavel: incompatibilidade entre problema e solucao, ou falha na avaliacao.\nVerifique: objetos p e s e versao do prioritizr.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Cost summary ──────────────────────────────────────────────────────────────
+log_step(8, "Compute and write cost summary")
+tryCatch({
+  cost_df <- data.frame(
+    metric = c("total_cost", "n_pu_selected", "n_pu_total",
+               "pct_pu_selected", "n_targets_met", "n_features"),
+    value  = c(eval_cost_summary(p, s)$cost,
+               n_selected, n_pu_total,
+               n_selected / n_pu_total * 100,
+               n_targets_met, n_feats)
+  )
+  write.csv(cost_df, file.path(output_dir, "cost_summary.csv"), row.names = FALSE)
+  log_info("Cost summary:\n%s", paste(capture.output(print(cost_df)), collapse = "\n"))
+}, error = function(e) {
+  log_error("Falha em cost_summary: %s\nCausa provavel: falha na avaliacao de custo ou permissoes de escrita.\nVerifique: objetos p e s e output_dir.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Irreplaceability ──────────────────────────────────────────────────────────
+log_step(9, "Compute irreplaceability (rarity-weighted richness)")
+tryCatch({
+  irr <- eval_rare_richness_importance(p, s)
+  writeRaster(irr, file.path(output_dir, "irreplaceability.tif"), overwrite = TRUE)
+  log_info("Irreplaceability map written.")
+}, error = function(e) {
+  log_error("Falha em irreplaceability: %s\nCausa provavel: falha na avaliacao de raridade ou permissoes de escrita.\nVerifique: objetos p e s e output_dir.\nSkill anterior: species-distribution-modeling", conditionMessage(e))
+  stop(e)
+})
+
+# ── Map visualisation ─────────────────────────────────────────────────────────
+log_step(10, "Generate prioritization map visualisation")
+tryCatch({
+  s_agg  <- aggregate(s, fact = max(1, floor(nrow(s) / 300)))
+  df_sol <- as.data.frame(s_agg, xy = TRUE)
+  names(df_sol)[3] <- "selected"
+  df_sol$selected <- factor(df_sol$selected, levels = c(0, 1),
+                             labels = c("Not selected", "Selected"))
+
+  p_map <- ggplot(df_sol, aes(x = x, y = y, fill = selected)) +
+    geom_raster() +
+    scale_fill_manual(values = c("Not selected" = "grey90", "Selected" = "#2166AC"),
+                      na.value = "white") +
+    coord_equal() +
+    labs(x = "Easting", y = "Northing", fill = "",
+         title = sprintf("Conservation solution — %d PUs selected, %d/%d targets met",
+                         n_selected, n_targets_met, n_feats)) +
+    theme_minimal(base_size = 10)
+
+  ggsave(file.path(output_dir, "prioritization_map.png"), p_map,
+         width = 9, height = 7, dpi = 150)
+  log_info("Prioritization map saved.")
+}, error = function(e) {
+  log_warn("Nao foi possivel gerar o mapa de priorizacao: %s. Continuando sem o grafico.", conditionMessage(e))
+})
+
+log_info("Prioritization complete.")