ecological-agent-skills 3.1.0

package/skills/ecological-impact-assessment/resources/pressure-index-template.md

@@ -0,0 +1,78 @@
+# Anthropogenic Pressure Index — Template and Data Sources
+
+## Concept
+
+A composite pressure index aggregates multiple threatening processes into a single spatial layer representing cumulative human impact on biodiversity. Each pressure layer is normalised (0–1) and combined as a weighted sum.
+
+## Standard Pressure Layers
+
+| Pressure | Proxy variable | Resolution | Source |
+|---------|---------------|-----------|--------|
+| Land conversion | % natural habitat remaining | 30 m | MapBiomas / ESA CCI |
+| Road proximity | Distance to paved roads (inverted) | 100 m | OpenStreetMap / DNIT |
+| Human density | Population density | 100 m | WorldPop |
+| Agricultural intensity | Cropland + pasture density | 30 m | MapBiomas |
+| Fire frequency | Fire count per year (MODIS/VIIRS) | 500 m | INPE BDQueimadas |
+| Deforestation rate | Annual forest loss | 30 m | PRODES / Hansen GFC |
+| Human footprint | Composite human impact | 1 km | Wildlife Conservation Society (2022) |
+| Night-time lights | Light pollution (VIIRS DNB) | 500 m | NASA Black Marble |
+| Fragmentation | 1 − MESH (normalised) | Derived | landscapemetrics |
+
+## Normalisation Method
+
+For each pressure layer P_i:
+
+P_norm = (P_i − P_min) / (P_max − P_min)
+
+where P_min and P_max are the 1st and 99th percentiles of values within the study area (use percentiles to reduce outlier influence).
+
+For distance-based layers (e.g., distance to roads), invert after normalisation:
+P_norm = 1 − [(dist − dist_min) / (dist_max − dist_min)]
+
+## Weighted Combination
+
+```
+Pressure_Index = Σ(w_i × P_norm_i) / Σ(w_i)
+```
+
+Default equal weights: w_i = 1 for all layers.
+
+Justify custom weights with literature or expert elicitation. Document all weights in `params.yaml`.
+
+## Classification Thresholds (default)
+
+| Pressure class | Pressure_Index range |
+|---------------|---------------------|
+| Low | 0.00 – 0.25 |
+| Moderate | 0.25 – 0.50 |
+| High | 0.50 – 0.75 |
+| Critical | 0.75 – 1.00 |
+
+## R Code Template
+
+```r
+library(terra)
+
+# Load normalised pressure layers (all same extent, CRS, resolution)
+layers <- rast(c("road_proximity_norm.tif",
+                 "pop_density_norm.tif",
+                 "fire_frequency_norm.tif",
+                 "deforestation_norm.tif",
+                 "habitat_loss_norm.tif"))
+
+# Equal weights
+weights <- rep(1, nlyr(layers))
+pressure_index <- weighted.mean(layers, w = weights)
+
+# Classify
+m <- matrix(c(0, 0.25, 1,
+              0.25, 0.50, 2,
+              0.50, 0.75, 3,
+              0.75, 1.00, 4), ncol = 3, byrow = TRUE)
+pressure_class <- classify(pressure_index, m)
+levels(pressure_class) <- data.frame(id = 1:4,
+  class = c("Low", "Moderate", "High", "Critical"))
+
+writeRaster(pressure_index, "outputs/pressure_index.tif", overwrite = TRUE)
+writeRaster(pressure_class, "outputs/pressure_class.tif", overwrite = TRUE)
+```

package/skills/ecological-impact-assessment/resources/study-design-guide.md

@@ -0,0 +1,168 @@
+# BACI Study Design Guide
+
+## Overview
+
+A well-designed BACI (Before-After Control-Impact) study requires careful decisions about site selection, survey timing, and sample size before fieldwork begins. Underpowered studies cannot detect real impacts; overdesigned studies waste resources. This guide provides evidence-based recommendations for each decision.
+
+---
+
+## 1. How Many Sites? Control vs. Impact
+
+### Recommendation: ≥ 5 control + ≥ 5 impact sites
+
+| Sites per group | Approx. power (d=0.5, 4 surveys, α=0.05) | Notes |
+|----------------|------------------------------------------|-------|
+| 3               | ~0.29                                    | Severely underpowered; only detect large effects |
+| 5               | ~0.46                                    | Minimum acceptable for preliminary screening |
+| 10              | ~0.74                                    | Adequate for medium-large effects |
+| 15              | ~0.89                                    | Recommended for publication |
+| 20+             | ~0.95+                                   | Required for small effects (d < 0.3) |
+
+**Why spatial replication matters more than temporal:** Adding sites reduces pseudo-replication and provides genuine spatial independence. Multiple survey occasions at the same site are not independent — they increase precision within a site but cannot substitute for spatial replication.
+
+**Equal vs. unequal allocation:** Balance (equal n control and impact) is optimal when variance is homogeneous. If one group is more variable, allocate more sites there (proportional to σ ratio).
+
+---
+
+## 2. How Many Surveys? Before and After
+
+### Recommendation: ≥ 3 pre-impact + ≥ 3 post-impact occasions
+
+| Survey design | Notes |
+|--------------|-------|
+| 1 before + 1 after | Inadequate — cannot estimate background variance |
+| 2 before + 2 after | Marginal — acceptable only with many sites (n ≥ 15) |
+| **3 before + 3 after** | **Minimum recommended** |
+| 4 before + 4 after | Preferred for publication; allows seasonal coverage |
+| 6+ before + 6+ after | Required for detecting gradual, delayed, or cyclical impacts |
+
+**Asymmetric designs:** More pre-impact surveys are better than symmetric if baseline variance is unknown (collect baseline data opportunistically while awaiting impact).
+
+**Temporal extent:** Surveys should span at least one full seasonal cycle (12 months) to avoid confounding phenological variation with impact effects.
+
+---
+
+## 3. How to Select Control Sites (Matching Criteria)
+
+Control sites must be ecologically equivalent to impact sites in every way **except** exposure to the stressor. Failure here is the most common source of BACI bias.
+
+### Matching criteria checklist
+
+| Criterion | Description | How to verify |
+|-----------|-------------|---------------|
+| **Habitat type** | Same vegetation class, canopy cover, soil type | Remote sensing / field survey |
+| **Disturbance history** | No recent land-use change within ≥ 10 years | Historical imagery / land records |
+| **Hydrology** | Similar drainage, upstream catchment area | GIS topographic analysis |
+| **Human access** | Similar road density, hunting/gathering pressure | Map + community consultation |
+| **Spatial isolation** | ≥ minimum dispersal distance from impact site | Species-specific dispersal data |
+| **Environmental gradients** | Similar elevation, aspect, slope | DEM analysis |
+| **Connectivity** | No shared corridor that allows spill-over | Landscape connectivity analysis |
+
+### Matching algorithm (propensity score matching)
+```r
+# Using MatchIt package
+library(MatchIt)
+match_obj <- matchit(treated ~ habitat + elevation + slope + dist_road,
+                     data      = site_covariates,
+                     method    = "nearest",
+                     distance  = "logit",
+                     ratio     = 1)  # 1:1 matching
+summary(match_obj)
+# Check standardised mean differences < 0.1 for all covariates
+```
+
+---
+
+## 4. Survey Interval (Closure Period)
+
+The time between consecutive survey occasions must balance:
+
+| Concern | Recommendation |
+|---------|---------------|
+| **Independence** | Interval ≥ 2 × animal home-range crossing time |
+| **Seasonal coverage** | Cover wet + dry season (or all 4 seasons) within a year |
+| **Biological response time** | Post-impact surveys should begin after sufficient time for response (e.g., 6 months for vegetation recovery; 1–2 breeding seasons for birds) |
+| **Minimum interval** | Never < 2 weeks for mobile species (risk of individual recapture) |
+
+**Typical intervals by taxon:**
+
+| Taxon | Minimum interval | Rationale |
+|-------|----------------|-----------|
+| Large mammals | 4–6 weeks | Home range traversal time |
+| Birds (point counts) | 2–3 weeks | Territory turnover between surveys |
+| Amphibians | 2–4 weeks | Breeding pond drying/filling cycles |
+| Fish (electrofishing) | 4–8 weeks | Habitat recovery after survey disturbance |
+| Plants | 3–12 months | Phenological completeness |
+| Invertebrates | 2–4 weeks | Generation time consideration |
+
+---
+
+## 5. How to Estimate Variance for Power Analysis
+
+A variance estimate (σ²) is required to convert effect size to Cohen's d. Three approaches:
+
+### Option A: From pilot data (preferred)
+```r
+# Compute pooled within-site, within-period variance from at least 5 sites × 2 occasions
+pilot_data <- read.csv("pilot_sites.csv")   # columns: site, period, y (response)
+# Mixed model to extract residual variance
+library(lme4)
+mod    <- lmer(y ~ (1 | site) + (1 | period), data = pilot_data)
+sigma2 <- sigma(mod)^2   # residual (within-site) variance
+cat("Variance estimate:", sigma2, "\n")
+```
+
+### Option B: From literature
+Search for studies with the same response variable (e.g., bird abundance, fish CPUE) and same habitat type. Extract reported SD and use σ² = SD².
+
+| Common ecological responses | Typical CV | Approx. σ² (if mean = 10) |
+|----------------------------|-----------|--------------------------|
+| Bird point count abundance | 0.4–0.8   | 16–64 |
+| Camera-trap RAI | 0.6–1.2 | 36–144 |
+| Tree basal area (m²/ha) | 0.1–0.3 | 1–9 |
+| Fish CPUE | 0.8–2.0 | 64–400 |
+| Macroinvertebrate richness | 0.2–0.4 | 4–16 |
+
+### Option C: Conservative default
+Use σ² = 1.0, which means the effect_size argument to `power_analysis_baci.R` is directly Cohen's d (fully standardised).
+
+---
+
+## 6. Ecologically Relevant Effect Sizes by Impact Type
+
+Use these as starting points when no pilot data are available. Cohen's d values are for the BACI interaction term (difference-in-differences).
+
+| Impact type | Typical detectable effect (d) | Response variable | Source |
+|------------|------------------------------|-------------------|--------|
+| **Road construction** | 0.4–0.8 | Bird/mammal abundance within 500 m | Trombulak & Frissell (2000) |
+| **Dam / reservoir** | 0.6–1.2 | Fish species richness, benthic community | Poff et al. (2007) |
+| **Deforestation (partial)** | 0.5–0.9 | Bird richness, amphibian abundance | Barlow et al. (2007) |
+| **Mining (artisanal)** | 0.8–1.5 | Benthic invertebrate richness | Dudgeon et al. (2006) |
+| **Invasive species introduction** | 0.3–0.7 | Native species richness | Blackburn et al. (2014) |
+| **Agricultural expansion** | 0.5–1.0 | Pollinator abundance, bird richness | Benton et al. (2003) |
+| **Protected area establishment** | 0.2–0.5 | Large mammal density (10–15 yr lag) | Craigie et al. (2010) |
+| **Ecological restoration** | 0.3–0.6 | Vegetation cover, bird diversity | Benayas et al. (2009) |
+
+**Note:** Larger Cohen's d values require fewer sites to detect; smaller values (d < 0.3) may require n > 20 sites per group and render BACI impractical without landscape-scale monitoring programs.
+
+---
+
+## 7. Pitfalls and Common Mistakes
+
+| Pitfall | Consequence | Prevention |
+|---------|-------------|------------|
+| Control sites too close to impact | Spillover contamination | Distance ≥ max dispersal distance |
+| Surveys only in impact-accessible season | Seasonal confounding | Stratified survey schedule |
+| Single impact site | No spatial replication — can't compute error | Always ≥ 3 impact sites |
+| Starting surveys after impact begins | No before data | Anticipate impacts; survey pre-emptively |
+| Ignoring spatial autocorrelation | Inflated degrees of freedom | Use spatial mixed models (glmmTMB) |
+| Unbalanced loss of sites | Post-hoc unbalanced design | Monitor site accessibility; have spare sites |
+
+---
+
+## References
+
+- Underwood, A.J. (1994). On beyond BACI. *Ecological Applications*, 4(1), 3–15. [https://doi.org/10.2307/1942083](https://doi.org/10.2307/1942083)
+- Stewart-Oaten, A. & Bence, J.R. (2001). Temporal and spatial variation. *Ecological Monographs*, 71(2), 305–339. [https://doi.org/10.1890/0012-9615(2001)071[0305:TASVI]2.0.CO;2](https://doi.org/10.1890/0012-9615(2001)071[0305:TASVI]2.0.CO;2)
+- Rosenbaum, P.R. & Rubin, D.B. (1983). The central role of the propensity score. *Biometrika*, 70(1), 41–55. [https://doi.org/10.1093/biomet/70.1.41](https://doi.org/10.1093/biomet/70.1.41)
+- Cohen, J. (1988). *Statistical Power Analysis for the Behavioral Sciences* (2nd ed.). Lawrence Erlbaum Associates.

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

@@ -0,0 +1,161 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript baci_analysis.R <baci_data.csv> <output_dir> [response_col] [random_effects]
+# BACI mixed-effects model for ecological impact assessment
+# Usage: Rscript baci_analysis.R <data_csv> <response_var> <output_dir>
+# Requires: glmmTMB, emmeans, ggplot2, dplyr
+
+# ── 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(glmmTMB)
+  library(emmeans)
+  library(ggplot2)
+  library(dplyr)
+})
+
+args         <- commandArgs(trailingOnly = TRUE)
+data_file    <- ifelse(length(args) >= 1, args[1], "data/baci_data.csv")
+response_var <- ifelse(length(args) >= 2, args[2], "abundance")
+output_dir   <- ifelse(length(args) >= 3, args[3], "outputs/baci")
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_info("Skill: %s | data_file=%s | response_var=%s | output_dir=%s",
+         SKILL_NAME, data_file, response_var, output_dir)
+
+# ── Input precondition check ──────────────────────────────────────────────────
+if (!file.exists(data_file)) {
+  log_error(
+    "Input nao encontrado: %s\nCausa provavel: caminho errado ou arquivo nao gerado pelo passo anterior.\nVerifique: se o arquivo CSV existe e o nome esta correto.\nSkill anterior: ecological-sampling-design ou coleta de campo.",
+    data_file
+  )
+  stop("Missing: ", data_file)
+}
+
+log_step(1, "Carregar e validar dados BACI")
+dat <- tryCatch({
+  read.csv(data_file)
+}, error = function(e) {
+  log_error(
+    "Falha ao ler CSV: %s\nCausa provavel: arquivo corrompido ou encoding incorreto.\nVerifique: abra o arquivo em editor de texto e confira separadores.\nSkill anterior: ecological-sampling-design.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+required_cols <- c("site", "period", "treatment", response_var)
+missing_cols  <- setdiff(required_cols, names(dat))
+if (length(missing_cols) > 0) {
+  log_error(
+    "Colunas obrigatorias ausentes: %s\nCausa provavel: CSV nao segue o esquema BACI esperado.\nVerifique: o arquivo deve ter colunas site, period, treatment e a variavel resposta.\nSkill anterior: ecological-sampling-design.",
+    paste(missing_cols, collapse = ", ")
+  )
+  stop("Missing columns: ", paste(missing_cols, collapse = ", "))
+}
+
+n_na <- sum(is.na(dat[[response_var]]))
+if (n_na > 0) {
+  log_warn("Coluna '%s' contem %d valores NA — podem ser excluidos pela funcao de modelo.", response_var, n_na)
+}
+
+dat$period    <- factor(dat$period,    levels = c("before", "after"))
+dat$treatment <- factor(dat$treatment, levels = c("control", "impact"))
+
+n_sites  <- n_distinct(dat$site)
+n_before <- sum(dat$period == "before")
+n_after  <- sum(dat$period == "after")
+log_info("Sites: %d | Before: %d | After: %d", n_sites, n_before, n_after)
+log_decision("response_var", response_var, "variavel resposta fornecida pelo usuario ou padrao 'abundance'")
+log_decision("family", "nbinom2", "distribuicao binomial negativa adequada para contagens de abundancia com superdispersao")
+
+if (n_sites < 3) {
+  log_warn("Apenas %d site(s) detectado(s) — efeitos aleatorios podem nao ser estimaveis.", n_sites)
+}
+
+# ── Fit BACI model ────────────────────────────────────────────────────────────
+log_step(2, "Ajustar modelo misto BACI (glmmTMB, nbinom2)")
+formula_str <- paste(response_var, "~ period * treatment + (1|site)")
+log_info("Formula: %s", formula_str)
+
+m <- tryCatch({
+  glmmTMB(as.formula(formula_str), data = dat, family = nbinom2())
+}, error = function(e) {
+  log_error(
+    "Falha ao ajustar modelo glmmTMB: %s\nCausa provavel: dados insuficientes, colunas mal codificadas ou singularidade no modelo.\nVerifique: numero de niveis por site/periodo e presenca de zeros excessivos.\nSkill anterior: ecological-sampling-design.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Modelo ajustado com sucesso.")
+print(summary(m))
+
+# ── Extract BACI interaction ───────────────────────────────────────────────────
+log_step(3, "Extrair interacao BACI e calcular efeito na escala original")
+coef_table <- tryCatch({
+  as.data.frame(coef(summary(m))$cond)
+}, error = function(e) {
+  log_error(
+    "Falha ao extrair coeficientes do modelo: %s\nCausa provavel: modelo nao convergiu ou estrutura inesperada.\nVerifique: inspecione summary(m) manualmente.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+baci_row <- grep("period.*treatment|treatment.*period", rownames(coef_table))
+
+if (length(baci_row) > 0) {
+  baci_est <- coef_table[baci_row, ]
+  log_info("=== Interacao BACI ===")
+  print(baci_est)
+  effect_multiplicative <- round(exp(baci_est[, "Estimate"]), 3)
+  log_info("Efeito na escala original (multiplicativo): %s", paste(effect_multiplicative, collapse = ", "))
+  tryCatch({
+    write.csv(baci_est, file.path(output_dir, "baci_results.csv"))
+    log_info("baci_results.csv salvo em: %s", output_dir)
+  }, error = function(e) {
+    log_error(
+      "Falha ao salvar baci_results.csv: %s\nCausa provavel: permissao negada ou disco cheio.\nVerifique: permissoes do diretorio de saida.\nSkill anterior: nenhuma.",
+      conditionMessage(e)
+    )
+    stop(e)
+  })
+} else {
+  log_warn("Termo de interacao BACI (period:treatment) nao encontrado na tabela de coeficientes.")
+}
+
+# ── Before/After plot ──────────────────────────────────────────────────────────
+log_step(4, "Gerar grafico BACI (controle vs impacto, antes vs depois)")
+tryCatch({
+  p_baci <- dat |>
+    group_by(period, treatment) |>
+    summarise(mean_y = mean(.data[[response_var]], na.rm = TRUE),
+              se_y   = sd(.data[[response_var]], na.rm = TRUE) / sqrt(n()),
+              .groups = "drop") |>
+    ggplot(aes(x = period, y = mean_y, colour = treatment, group = treatment)) +
+    geom_line(linewidth = 1) +
+    geom_point(size = 3) +
+    geom_errorbar(aes(ymin = mean_y - se_y, ymax = mean_y + se_y), width = 0.1) +
+    scale_colour_manual(values = c(control = "#2166ac", impact = "#d6604d")) +
+    labs(y = response_var, title = "BACI: Control vs Impact") +
+    theme_bw()
+  ggsave(file.path(output_dir, "baci_plot.png"), p_baci, width = 6, height = 5, dpi = 150)
+  log_info("baci_plot.png salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao gerar ou salvar grafico BACI: %s\nCausa provavel: dados insuficientes para sumarizacao ou diretorio sem permissao de escrita.\nVerifique: presenca de pelo menos um registro por combinacao period/treatment.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Analise BACI concluida. Saidas em: %s", output_dir)

package/skills/ecological-impact-assessment/scripts/fragmentation_analysis.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+fragmentation_analysis.py
+Compute landscape fragmentation metrics from a land cover raster.
+Usage: python fragmentation_analysis.py <landcover_tif> <habitat_class> <output_dir>
+Requires: rasterio, numpy, pandas, scipy, skimage
+"""
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "ecological-impact-assessment"
+_LOG_DIR   = Path("logs")
+_LOG_DIR.mkdir(parents=True, exist_ok=True)
+_log_file  = _LOG_DIR / f"skill_{SKILL_NAME}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s] [%(levelname)s] [" + SKILL_NAME + "] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[
+        logging.StreamHandler(sys.stdout),
+        logging.FileHandler(_log_file, encoding="utf-8"),
+    ],
+)
+logger = logging.getLogger(SKILL_NAME)
+
+def log_step(n: int, desc: str) -> None:
+    logger.info("-- STEP %d: %s", n, desc)
+
+def log_decision(var: str, val, why: str) -> None:
+    logger.info("DECISION | %s = %s | %s", var, val, why)
+
+import numpy as np
+import pandas as pd
+import rasterio
+from scipy import ndimage
+
+
+def load_habitat_mask(tif_path: str, habitat_class: int) -> tuple:
+    with rasterio.open(tif_path) as src:
+        lc = src.read(1).astype(float)
+        res = src.res  # (x_res, y_res) in map units
+        crs_is_projected = src.crs.is_projected if src.crs else False
+    mask = (lc == habitat_class).astype(int)
+    return mask, res, crs_is_projected
+
+def label_patches(mask: np.ndarray):
+    struct = ndimage.generate_binary_structure(2, 2)  # 8-connectivity
+    labeled, n_patches = ndimage.label(mask, structure=struct)
+    return labeled, n_patches
+
+def compute_metrics(mask: np.ndarray, labeled: np.ndarray, n_patches: int,
+                    cell_area_ha: float) -> pd.Series:
+    total_cells = mask.sum()
+    total_area_ha = total_cells * cell_area_ha
+    patch_sizes = ndimage.sum(mask, labeled, range(1, n_patches + 1))
+    patch_areas_ha = np.array(patch_sizes) * cell_area_ha
+    landscape_area_ha = mask.size * cell_area_ha
+
+    largest_patch_ha = patch_areas_ha.max() if len(patch_areas_ha) > 0 else 0
+    lpi = (largest_patch_ha / landscape_area_ha) * 100
+
+    # Effective mesh size: MESH = Σ(Ai²) / A_landscape
+    mesh = np.sum(patch_areas_ha ** 2) / landscape_area_ha
+
+    return pd.Series({
+        "total_habitat_ha":     round(total_area_ha, 2),
+        "landscape_area_ha":    round(landscape_area_ha, 2),
+        "habitat_cover_pct":    round(100 * total_area_ha / landscape_area_ha, 2),
+        "n_patches":            int(n_patches),
+        "mean_patch_size_ha":   round(float(patch_areas_ha.mean()), 2) if len(patch_areas_ha) > 0 else 0,
+        "median_patch_size_ha": round(float(np.median(patch_areas_ha)), 2) if len(patch_areas_ha) > 0 else 0,
+        "largest_patch_ha":     round(float(largest_patch_ha), 2),
+        "lpi_pct":              round(float(lpi), 3),
+        "mesh_ha":              round(float(mesh), 2),
+    })
+
+def main():
+    tif_file      = sys.argv[1] if len(sys.argv) > 1 else "data/landcover.tif"
+    habitat_class = int(sys.argv[2]) if len(sys.argv) > 2 else 3
+    output_dir    = Path(sys.argv[3]) if len(sys.argv) > 3 else Path("outputs/fragmentation")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_decision("tif_file", tif_file, "Input land cover raster path")
+    log_decision("habitat_class", habitat_class, "Target habitat class code to extract")
+    log_decision("output_dir", str(output_dir), "Directory for fragmentation metric outputs")
+
+    if not Path(tif_file).exists():
+        logger.error(
+            "Input nao encontrado: %s\n"
+            "  Causa provavel: passo anterior nao concluiu.\n"
+            "  Skill anterior que deveria ter produzido este input: geoprocessing-for-ecology",
+            tif_file
+        )
+        sys.exit(1)
+
+    try:
+        log_step(1, "Loading habitat mask from raster")
+        logger.info("Loading: %s | Habitat class: %s", tif_file, habitat_class)
+        mask, (xres, yres), projected = load_habitat_mask(tif_file, habitat_class)
+        cell_area_ha = abs(xres * yres) / 10000  # m² → ha (assumes projected CRS)
+        log_decision("cell_area_ha", round(cell_area_ha, 6), "Derived from pixel resolution; assumes projected CRS")
+        if not projected:
+            logger.warning(
+                "Raster appears to be in geographic CRS. Area estimates will be approximate."
+            )
+
+        log_step(2, "Labeling habitat patches with 8-connectivity")
+        labeled, n_patches = label_patches(mask)
+        logger.info("Patches found: %d", n_patches)
+        if n_patches == 0:
+            logger.warning("No patches found for habitat class %d. Check class code.", habitat_class)
+
+        log_step(3, "Computing fragmentation metrics")
+        metrics = compute_metrics(mask, labeled, n_patches, cell_area_ha)
+        logger.info("Fragmentation Metrics:\n%s", metrics.to_string())
+
+        log_step(4, "Writing outputs")
+        metrics_df = metrics.to_frame(name="value").reset_index().rename(columns={"index": "metric"})
+        out_csv = output_dir / "fragmentation_metrics.csv"
+        metrics_df.to_csv(out_csv, index=False)
+        logger.info("Saved to: %s", out_csv)
+
+    except FileNotFoundError as e:
+        logger.error(
+            "Input file not found: %s\n"
+            "  Expected output from: geoprocessing-for-ecology\n"
+            "  Check that previous step completed.",
+            e
+        )
+        raise
+    except Exception as e:
+        logger.error("Unexpected error in fragmentation analysis: %s", e)
+        raise
+
+if __name__ == "__main__":
+    main()