ecological-agent-skills 3.1.0

package/skills/community-ecology-ordination/examples/example-prompts.md

@@ -0,0 +1,35 @@
+# Example Invocation Prompts — community-ecology-ordination
+
+## Full Community Analysis
+
+```
+Load skill: community-ecology-ordination
+Task: Analyse bird community structure across three land use types
+(old-growth forest, secondary forest, pasture) in the Atlantic Forest.
+
+Files:
+  - data/bird_abundance_matrix.csv   (100 sites × 87 species, count data)
+  - data/site_metadata.csv           (land_use, elevation, canopy_cover, edge_distance)
+
+Steps:
+1. Rarefaction curves to assess sampling adequacy.
+2. Alpha diversity (richness, Shannon, Simpson) per land use; compare with Kruskal-Wallis.
+3. NMDS (Bray-Curtis, k=2). Report stress.
+4. PERMANOVA: community ~ land_use. Test assumption with PERMDISP.
+5. SIMPER: top 10 species driving differences between land use pairs.
+6. Indicator species (IndVal) per land use type.
+7. Hierarchical clustering (Ward.D2) of sites.
+
+Output: ordination_plot.png, diversity_metrics.csv, permanova_results.txt, community_report.md
+```
+
+## Beta Diversity Partitioning
+
+```
+Load skill: community-ecology-ordination
+Task: Partition beta diversity into turnover and nestedness components
+for amphibian communities across an elevation gradient (1000–3500 m, 25 sites).
+Data: data/amphibian_pa_matrix.csv (presence/absence)
+Use betapart package. Report total beta, turnover fraction, and nestedness fraction.
+Plot beta diversity components against elevation.
+```

package/skills/community-ecology-ordination/resources/dissimilarity-metric-guide.md

@@ -0,0 +1,53 @@
+# Dissimilarity Metric Selection Guide
+
+## Bray-Curtis (Sørensen quantitative)
+- **Data:** Abundance (count or biomass)
+- **Properties:** Asymmetric (treats double-zeros correctly); ranges 0–1
+- **When:** Most ecological abundance data; default for NMDS of communities
+- **R:** `vegan::vegdist(x, method = "bray")`
+
+## Jaccard
+- **Data:** Presence/absence
+- **Properties:** Symmetric; ranges 0–1
+- **When:** Presence-only data; when all species are equally important
+- **R:** `vegan::vegdist(x, method = "jaccard")`
+
+## Sørensen (Dice)
+- **Data:** Presence/absence
+- **Properties:** Emphasises co-occurrences more than Jaccard
+- **When:** Similar to Jaccard; slightly more weight to shared species
+- **R:** `vegan::vegdist(x, method = "bray")` on 0/1 matrix (equivalent)
+
+## Chao
+- **Data:** Abundance (accounts for unobserved species)
+- **Properties:** Estimates true dissimilarity adjusting for sampling effort
+- **When:** Datasets with very different sampling intensities; rare species important
+- **R:** `vegan::vegdist(x, method = "chao")`
+
+## Euclidean
+- **Data:** Continuous environmental variables
+- **Properties:** Symmetric; sensitive to magnitude; double-zero problem
+- **When:** Environmental (not species) data in PCA / RDA
+- **Avoid for:** Raw species abundances (use Hellinger transform first)
+
+## Hellinger Distance
+- **Data:** Abundance (after Hellinger transformation)
+- **Properties:** Avoids double-zero problem; linear methods applicable
+- **When:** PCA or RDA on species data; good compromise
+- **R:** `vegan::decostand(x, "hellinger")` then Euclidean distance
+
+## Aitchison Distance
+- **Data:** Compositional / proportional abundance
+- **Properties:** Log-ratio based; appropriate for compositional data
+- **When:** Microbiome, pollen, compositional assemblage data
+- **R:** `compositions::dist.acomp()` or `zCompositions` + Euclidean
+
+## Decision Summary
+
+```
+Data type: Abundance?
+  YES → Bray-Curtis (default) | Chao (unequal effort) | Hellinger (for PCA/RDA)
+  NO  → Presence/absence?
+          YES → Jaccard | Sørensen
+          NO  → Continuous (env) → Euclidean | Gower (mixed types)
+```

package/skills/community-ecology-ordination/resources/nmds-interpretation-guide.md

@@ -0,0 +1,104 @@
+# NMDS Interpretation Guide
+
+## What is NMDS?
+
+Non-Metric Multidimensional Scaling (NMDS) is an ordination technique that represents the rank-order dissimilarity between samples in a low-dimensional space. Unlike PCA, it makes no assumptions about the data distribution and works with any dissimilarity matrix.
+
+## Stress Value — Quality of Fit
+
+| Stress | Fit quality | Action |
+|--------|-------------|--------|
+| < 0.05 | Excellent | Report and proceed |
+| 0.05–0.10 | Good | Report and proceed |
+| 0.10–0.15 | Acceptable | Report; note limitation |
+| 0.15–0.20 | Poor | Consider k=3 dimensions |
+| > 0.20 | Unacceptable | Do not use 2D representation |
+
+**Always report stress in the plot caption or legend.**
+
+## How to Run Properly
+
+```r
+library(vegan)
+set.seed(42)  # for reproducibility
+
+nmds <- metaMDS(
+  comm    = species_matrix,
+  distance = "bray",    # Bray-Curtis for abundance; jaccard for PA
+  k       = 2,          # start with 2; try 3 if stress > 0.15
+  trymax  = 50,         # run 50 random starts; keep best
+  autotransform = FALSE # don't auto-transform; apply Hellinger manually if needed
+)
+
+cat("Stress:", nmds$stress, "\n")
+cat("Converged:", nmds$converged, "\n")
+
+# Run multiple k values to choose
+for (k in 2:4) {
+  tmp <- metaMDS(species_matrix, distance="bray", k=k, trymax=20, trace=0)
+  cat("k =", k, "| stress =", round(tmp$stress, 4), "\n")
+}
+```
+
+## Reading an NMDS Plot
+
+### Site scores (samples)
+- **Nearby points** → similar species composition
+- **Distant points** → dissimilar composition
+- **Clusters** → groups with consistently similar assemblages
+
+### Species scores (if added)
+- Arrow/point direction → gradient of increasing species abundance/occurrence
+- Arrow length → strength of association with NMDS axes
+
+### Environmental vectors (envfit)
+- Added post-hoc to correlate environmental variables with ordination axes
+- Arrow direction and length indicate direction and strength of environmental gradient
+
+```r
+# Add environmental vectors
+env_fit <- envfit(nmds, env_matrix, permutations = 999)
+print(env_fit)  # shows r² and p-value for each variable
+
+# Plot
+plot(nmds, display = "sites")
+plot(env_fit, p.max = 0.05)  # only significant vectors
+```
+
+## Producing a Publication-Quality Plot
+
+```r
+library(ggplot2)
+
+scores_df <- as.data.frame(scores(nmds, display = "sites"))
+scores_df$group <- metadata$land_use  # your grouping variable
+
+ggplot(scores_df, aes(x = NMDS1, y = NMDS2, colour = group, shape = group)) +
+  geom_point(size = 3, alpha = 0.8) +
+  stat_ellipse(level = 0.95, linetype = "dashed") +  # 95% confidence ellipses
+  annotate("text", x = Inf, y = Inf,
+           label = paste("Stress =", round(nmds$stress, 3)),
+           hjust = 1.1, vjust = 1.5, size = 3.5) +
+  scale_colour_brewer(palette = "Set2") +
+  labs(title = "NMDS (Bray-Curtis)", colour = "Land use", shape = "Land use") +
+  theme_bw() +
+  theme(legend.position = "right")
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Only running 1 random start | Set `trymax = 50` |
+| Reporting stress > 0.20 as acceptable | Use k=3 or a different ordination |
+| Not setting seed | Always `set.seed()` before metaMDS |
+| Using autotransform=TRUE without checking | Turn off; apply transformation explicitly |
+| Not checking convergence | Check `nmds$converged` |
+| Interpreting axes as principal components | NMDS axes are arbitrary; only relative distances matter |
+
+## When to Use PCA Instead
+
+- Data are continuous environmental variables (not species composition)
+- Linear relationships are expected
+- You need to explain specific % variance per axis
+- For species data: apply Hellinger transformation first (PCA on Hellinger = RDA with no constraints)

package/skills/community-ecology-ordination/scripts/community_analysis.R

@@ -0,0 +1,143 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript community_analysis.R <species_site_matrix.csv> <metadata.csv> <output_dir> [method]
+# NMDS ordination, diversity metrics, PERMANOVA
+# Usage: Rscript community_analysis.R <species_matrix_csv> <metadata_csv> <output_dir>
+# Requires: vegan, ggplot2, dplyr
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "community-ecology-ordination"
+.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(vegan)
+  library(ggplot2)
+  library(dplyr)
+})
+
+args       <- commandArgs(trailingOnly = TRUE)
+sp_file    <- ifelse(length(args) >= 1, args[1], "data/species_matrix.csv")
+meta_file  <- ifelse(length(args) >= 2, args[2], "data/site_metadata.csv")
+output_dir <- ifelse(length(args) >= 3, args[3], "outputs/community")
+
+log_step(1, "Validate inputs")
+if (!file.exists(sp_file)) {
+  log_error(
+    "Falha em validate inputs: arquivo de matriz de especies nao encontrado: %s\nCausa provavel: caminho incorreto ou arquivo nao gerado\nVerifique: o argumento species_matrix_csv e o diretorio de trabalho\nSkill anterior: data-cleaning",
+    sp_file
+  )
+  stop("Species matrix file not found.")
+}
+if (!file.exists(meta_file)) {
+  log_error(
+    "Falha em validate inputs: arquivo de metadados nao encontrado: %s\nCausa provavel: caminho incorreto ou arquivo nao gerado\nVerifique: o argumento metadata_csv e o diretorio de trabalho\nSkill anterior: data-cleaning",
+    meta_file
+  )
+  stop("Metadata file not found.")
+}
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+set.seed(42)
+log_decision("random_seed", 42, "ensures reproducibility of NMDS and permutation tests")
+
+log_step(2, "Load species matrix and metadata")
+tryCatch({
+  sp   <- read.csv(sp_file, row.names = 1)
+  meta <- read.csv(meta_file, row.names = 1)
+}, error = function(e) {
+  log_error(
+    "Falha em load data: %s\nCausa provavel: CSV malformado ou sem coluna de rownames\nVerifique: estrutura dos arquivos (primeira coluna deve ser site ID)\nSkill anterior: data-cleaning",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Sites: %d | Species: %d", nrow(sp), ncol(sp))
+
+if (any(sp < 0, na.rm = TRUE)) {
+  log_warn("Species matrix contains negative values. Abundances must be >= 0. Check your input data.")
+}
+if (anyNA(sp)) {
+  log_warn("Species matrix contains %d NA values. These will be treated as zero by vegan.", sum(is.na(sp)))
+}
+
+log_step(3, "Compute alpha diversity metrics")
+tryCatch({
+  div <- data.frame(
+    site    = rownames(sp),
+    richness = specnumber(sp),
+    shannon  = diversity(sp, index = "shannon"),
+    simpson  = diversity(sp, index = "simpson")
+  )
+  write.csv(div, file.path(output_dir, "diversity_metrics.csv"), row.names = FALSE)
+  log_info("Alpha diversity computed. Mean richness: %.1f | Mean Shannon: %.2f",
+           mean(div$richness), mean(div$shannon))
+}, error = function(e) {
+  log_error(
+    "Falha em alpha diversity: %s\nCausa provavel: matriz de especies vazia ou nao numerica\nVerifique: estrutura do CSV de especies\nSkill anterior: data-cleaning",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_step(4, "Run NMDS ordination (Bray-Curtis, k=2)")
+log_decision("distance_metric", "bray", "Bray-Curtis is standard for community composition data")
+log_decision("nmds_k", 2, "2 dimensions for interpretable 2D ordination plot")
+tryCatch({
+  nmds <- metaMDS(sp, distance = "bray", k = 2, trymax = 50, trace = 0)
+  log_info("NMDS stress: %.4f", nmds$stress)
+  if (nmds$stress > 0.2) {
+    log_warn("NMDS stress = %.4f exceeds 0.20. Ordination may be unreliable; consider k=3 or data transformation.", nmds$stress)
+  }
+
+  scores_df <- as.data.frame(scores(nmds, display = "sites")) |>
+    mutate(site = rownames(sp)) |>
+    left_join(meta |> mutate(site = rownames(meta)), by = "site")
+
+  p_ord <- ggplot(scores_df, aes(x = NMDS1, y = NMDS2)) +
+    geom_point(size = 3) +
+    annotate("text", x = Inf, y = -Inf, label = paste("Stress =", round(nmds$stress, 3)),
+             hjust = 1.1, vjust = -0.5, size = 3.5) +
+    theme_bw() + labs(title = "NMDS Ordination (Bray-Curtis)")
+  ggsave(file.path(output_dir, "ordination_plot.png"), p_ord, width = 7, height = 6, dpi = 150)
+  log_info("Ordination plot saved.")
+}, error = function(e) {
+  log_error(
+    "Falha em NMDS: %s\nCausa provavel: matriz com sites/especies insuficientes ou todos zeros\nVerifique: numero de sites (>= 3) e que a matriz nao seja toda zeros\nSkill anterior: data-cleaning",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_step(5, "PERMANOVA and PERMDISP (if 'group' column present)")
+if ("group" %in% names(meta)) {
+  log_decision("permanova_permutations", 999, "standard number for robust p-value estimation")
+  tryCatch({
+    dist_mat  <- vegdist(sp, method = "bray")
+    perm      <- adonis2(dist_mat ~ meta$group, permutations = 999)
+    disp      <- betadisper(dist_mat, meta$group)
+    disp_test <- permutest(disp, permutations = 999)
+    log_info("PERMANOVA:\n%s", paste(capture.output(perm), collapse = "\n"))
+    log_info("PERMDISP:\n%s", paste(capture.output(disp_test), collapse = "\n"))
+    capture.output(perm, disp_test) |>
+      writeLines(file.path(output_dir, "permanova_results.txt"))
+    log_info("PERMANOVA results saved.")
+  }, error = function(e) {
+    log_error(
+      "Falha em PERMANOVA/PERMDISP: %s\nCausa provavel: grupo com apenas um nivel ou sites insuficientes por grupo\nVerifique: coluna 'group' nos metadados e balanceamento\nSkill anterior: data-cleaning",
+      conditionMessage(e)
+    )
+    stop(e)
+  })
+} else {
+  log_warn("Column 'group' not found in metadata. PERMANOVA and PERMDISP skipped.")
+}
+
+log_info("Done. Outputs in: %s", output_dir)

package/skills/community-ecology-ordination/scripts/community_analysis.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+community_analysis.py
+Beta diversity, ordination (PCoA), and group comparison (PERMANOVA via skbio).
+Usage: python community_analysis.py <species_matrix_csv> <metadata_csv> <output_dir>
+Requires: pandas, numpy, scipy, skbio, matplotlib
+"""
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "community-ecology-ordination"
+_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 matplotlib.pyplot as plt
+from scipy.spatial.distance import braycurtis
+from scipy.cluster.hierarchy import dendrogram, linkage, copshenetic
+from scipy.spatial.distance import squareform
+
+try:
+    from skbio.diversity import beta_diversity
+    from skbio.stats.ordination import pcoa
+    from skbio.stats.distance import permanova, DistanceMatrix
+    HAS_SKBIO = True
+except ImportError:
+    HAS_SKBIO = False
+    logger.warning("scikit-bio not installed. PCoA and PERMANOVA will be skipped. pip install scikit-bio")
+
+
+def bray_curtis_matrix(sp: pd.DataFrame) -> np.ndarray:
+    n = len(sp)
+    dm = np.zeros((n, n))
+    vals = sp.values.astype(float)
+    for i in range(n):
+        for j in range(i+1, n):
+            d = braycurtis(vals[i], vals[j])
+            dm[i, j] = dm[j, i] = d
+    return dm
+
+def alpha_diversity(sp: pd.DataFrame) -> pd.DataFrame:
+    richness = (sp > 0).sum(axis=1)
+    def shannon(row):
+        p = row[row > 0] / row.sum()
+        return -np.sum(p * np.log(p))
+    def simpson(row):
+        p = row[row > 0] / row.sum()
+        return 1 - np.sum(p**2)
+    return pd.DataFrame({
+        "site":     sp.index,
+        "richness": richness.values,
+        "shannon":  sp.apply(shannon, axis=1).values,
+        "simpson":  sp.apply(simpson, axis=1).values,
+    })
+
+def main():
+    sp_file    = sys.argv[1] if len(sys.argv) > 1 else "data/species_matrix.csv"
+    meta_file  = sys.argv[2] if len(sys.argv) > 2 else "data/site_metadata.csv"
+    output_dir = Path(sys.argv[3]) if len(sys.argv) > 3 else Path("outputs/community")
+
+    log_step(1, "Validate inputs")
+    if not Path(sp_file).exists():
+        logger.error(
+            "Species matrix file not found: %s\n"
+            "Causa provavel: caminho incorreto ou arquivo nao gerado\n"
+            "Verifique: o argumento species_matrix_csv e o diretorio de trabalho\n"
+            "Skill anterior: data-cleaning",
+            sp_file
+        )
+        sys.exit(1)
+    if not Path(meta_file).exists():
+        logger.error(
+            "Metadata file not found: %s\n"
+            "Causa provavel: caminho incorreto ou arquivo nao gerado\n"
+            "Verifique: o argumento metadata_csv e o diretorio de trabalho\n"
+            "Skill anterior: data-cleaning",
+            meta_file
+        )
+        sys.exit(1)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_step(2, "Load species matrix and metadata")
+    try:
+        sp   = pd.read_csv(sp_file, index_col=0)
+        meta = pd.read_csv(meta_file, index_col=0)
+    except Exception as e:
+        logger.error(
+            "Unexpected error in load data: %s\n"
+            "Causa provavel: CSV malformado ou sem coluna de rownames\n"
+            "Verifique: estrutura dos arquivos (primeira coluna deve ser site ID)\n"
+            "Skill anterior: data-cleaning",
+            e
+        )
+        raise
+
+    logger.info("Sites: %d | Species: %d", len(sp), len(sp.columns))
+
+    if (sp < 0).any().any():
+        logger.warning("Species matrix contains negative values. Abundances must be >= 0. Check your input data.")
+    if sp.isna().any().any():
+        logger.warning("Species matrix contains %d NA values. These will affect distance calculations.", sp.isna().sum().sum())
+
+    log_step(3, "Compute alpha diversity metrics")
+    try:
+        div = alpha_diversity(sp)
+        div.to_csv(output_dir / "diversity_metrics.csv", index=False)
+        logger.info("Mean richness: %.1f | Shannon: %.2f", div['richness'].mean(), div['shannon'].mean())
+    except Exception as e:
+        logger.error(
+            "Unexpected error in alpha diversity: %s\n"
+            "Causa provavel: matriz de especies vazia ou nao numerica\n"
+            "Verifique: estrutura do CSV de especies\n"
+            "Skill anterior: data-cleaning",
+            e
+        )
+        raise
+
+    log_step(4, "Compute Bray-Curtis distance matrix")
+    log_decision("distance_metric", "bray-curtis", "standard for community composition; handles double-zeros correctly")
+    try:
+        dm = bray_curtis_matrix(sp)
+        pd.DataFrame(dm, index=sp.index, columns=sp.index).to_csv(output_dir / "bray_curtis_matrix.csv")
+        logger.info("Bray-Curtis matrix computed (%d x %d).", len(sp), len(sp))
+    except Exception as e:
+        logger.error(
+            "Unexpected error in Bray-Curtis matrix: %s\n"
+            "Causa provavel: dados nao numericos na matriz de especies\n"
+            "Verifique: tipos de dados no CSV de especies\n"
+            "Skill anterior: data-cleaning",
+            e
+        )
+        raise
+
+    log_step(5, "PCoA ordination and PERMANOVA")
+    if HAS_SKBIO:
+        log_decision("permanova_permutations", 999, "standard number for robust p-value estimation")
+        try:
+            dist_mat = DistanceMatrix(dm, ids=list(sp.index))
+            pc = pcoa(dist_mat)
+            scores = pc.samples[["PC1", "PC2"]].copy()
+            scores["site"] = scores.index
+            if "group" in meta.columns:
+                scores["group"] = meta["group"].reindex(scores.index).values
+                groups_for_perm = meta["group"].reindex(sp.index).values
+                perm_result = permanova(dist_mat, groups_for_perm, permutations=999)
+                logger.info(
+                    "PERMANOVA: F = %.3f | p = %.4f",
+                    perm_result['test statistic'], perm_result['p-value']
+                )
+                perm_df = pd.DataFrame({"statistic": [perm_result["test statistic"]],
+                                        "p_value":   [perm_result["p-value"]]})
+                perm_df.to_csv(output_dir / "permanova_results.csv", index=False)
+                # Plot coloured by group
+                fig, ax = plt.subplots(figsize=(7, 6))
+                for grp in scores["group"].unique():
+                    sub = scores[scores["group"] == grp]
+                    ax.scatter(sub["PC1"], sub["PC2"], label=grp, s=50, alpha=0.8)
+                ax.set_xlabel(f"PC1 ({pc.proportion_explained[0]*100:.1f}%)")
+                ax.set_ylabel(f"PC2 ({pc.proportion_explained[1]*100:.1f}%)")
+                ax.set_title("PCoA (Bray-Curtis)")
+                ax.legend(); plt.tight_layout()
+                plt.savefig(output_dir / "pcoa_plot.png", dpi=150)
+                plt.close()
+                logger.info("PCoA plot saved.")
+            else:
+                logger.warning("Column 'group' not found in metadata. PERMANOVA skipped.")
+        except Exception as e:
+            logger.error(
+                "Unexpected error in PCoA/PERMANOVA: %s\n"
+                "Causa provavel: grupo com apenas um nivel ou sites insuficientes\n"
+                "Verifique: coluna 'group' nos metadados e balanceamento\n"
+                "Skill anterior: data-cleaning",
+                e
+            )
+            raise
+    else:
+        logger.warning("scikit-bio unavailable. PCoA and PERMANOVA steps skipped.")
+
+    log_step(6, "Hierarchical clustering")
+    try:
+        Z = linkage(squareform(dm), method="ward")
+        c, _ = copshenetic(Z, squareform(dm))
+        log_decision("linkage_method", "ward", "minimises total within-cluster variance; standard for ecology")
+        logger.info("Cophenetic correlation (Ward): %.3f", c)
+        if c < 0.7:
+            logger.warning("Cophenetic correlation = %.3f < 0.70. Dendrogram may poorly represent distances.", c)
+        fig, ax = plt.subplots(figsize=(max(8, len(sp)//2), 5))
+        dendrogram(Z, labels=list(sp.index), ax=ax, leaf_rotation=90, leaf_font_size=8)
+        ax.set_title(f"Hierarchical Clustering (Ward.D2) | Cophenetic r = {c:.3f}")
+        plt.tight_layout()
+        plt.savefig(output_dir / "cluster_dendrogram.png", dpi=150)
+        plt.close()
+        logger.info("Cluster dendrogram saved.")
+    except Exception as e:
+        logger.error(
+            "Unexpected error in hierarchical clustering: %s\n"
+            "Causa provavel: matriz de distancias com NaN ou apenas um site\n"
+            "Verifique: integridade da matriz Bray-Curtis\n"
+            "Skill anterior: community-ecology-ordination (distance matrix)",
+            e
+        )
+        raise
+
+    logger.info("Outputs written to: %s", output_dir)
+
+if __name__ == "__main__":
+    main()