ecological-agent-skills 3.1.0

package/skills/camera-trap-processing/scripts/estimate_activity.R

@@ -0,0 +1,169 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript estimate_activity.R <record_table_csv> <species_name> <output_dir> [group_column]
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "camera-trap-processing"
+.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(overlap))
+suppressPackageStartupMessages(library(circular))
+suppressPackageStartupMessages(library(dplyr))
+suppressPackageStartupMessages(library(ggplot2))
+suppressPackageStartupMessages(library(lubridate))
+
+args <- commandArgs(trailingOnly = TRUE)
+if (length(args) < 3) {
+  log_error("Argumentos insuficientes. Uso: Rscript estimate_activity.R <record_table_csv> <species_name> <output_dir> [group_column]")
+  cat("Usage: Rscript estimate_activity.R <record_table_csv> <species_name> <output_dir> [group_column]\n")
+  cat("  group_column: optional column for comparing two groups (e.g., 'season')\n")
+  quit(status = 1)
+}
+
+record_csv   <- args[1]
+species_name <- args[2]
+output_dir   <- args[3]
+group_col    <- ifelse(length(args) >= 4, args[4], NULL)
+
+# ── Input precondition checks ────────────────────────────────────────────────
+if (!file.exists(record_csv)) {
+  log_error("Input nao encontrado: %s\nCausa provavel: process_camtrap_data.R nao foi executado ou falhou\nVerifique: se record_table.csv existe no diretorio de saida\nSkill anterior: camera-trap-processing (process_camtrap_data.R)", record_csv)
+  stop("Missing record_csv: ", record_csv)
+}
+
+log_decision("species_name", species_name,
+             "especie alvo para estimativa de atividade diaria")
+log_decision("group_col", ifelse(is.null(group_col), "NULL", group_col),
+             "coluna de grupo para comparacao de sobreposicao; NULL = sem comparacao")
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_step(1, "Carregando e filtrando registros para a especie alvo")
+records <- tryCatch({
+  read.csv(record_csv, stringsAsFactors = FALSE)
+}, error = function(e) {
+  log_error("Falha ao ler record_table CSV: %s\nCausa provavel: arquivo corrompido ou formato invalido\nVerifique: saida de process_camtrap_data.R\nSkill anterior: camera-trap-processing", conditionMessage(e))
+  stop(e)
+})
+
+records$DateTimeOriginal <- as.POSIXct(records$DateTimeOriginal,
+                                        format = "%Y-%m-%d %H:%M:%S")
+
+sp_data <- records[records$Species == species_name, ]
+log_info("Registros para '%s': %d eventos", species_name, nrow(sp_data))
+
+if (nrow(sp_data) < 10) {
+  log_error("n_eventos_independentes < 10 para '%s' (%d encontrados)\nCausa provavel: especie rara ou limiar de independencia muito alto\nVerifique: especies disponiveis na tabela de registros\nSkill anterior: camera-trap-processing (process_camtrap_data.R)", species_name, nrow(sp_data))
+  stop("n_independent_events < 10 for '", species_name,
+       "'. Report RAI only; do not estimate activity overlap.")
+}
+
+log_step(2, "Convertendo horarios para radianos e estimando densidade de atividade")
+# Convert to radians
+to_rad <- function(dt) {
+  (hour(dt) + minute(dt) / 60) * (2 * pi / 24)
+}
+sp_data$time_rad <- to_rad(sp_data$DateTimeOriginal)
+
+# Overall activity density plot
+tryCatch({
+  png(file.path(output_dir, "activity_plot.png"), width = 900, height = 600, res = 120)
+  overlapPlot(sp_data$time_rad, rug = TRUE,
+              main = paste("Diel Activity —", gsub("_", " ", species_name)),
+              xlab = "Time of day", col.main = "black")
+  dev.off()
+  log_info("Grafico de atividade salvo: activity_plot.png")
+}, error = function(e) {
+  log_error("Falha ao gerar grafico de atividade: %s\nCausa provavel: biblioteca overlap com problema\nVerifique: instalacao do pacote overlap\nSkill anterior: [nenhuma]", conditionMessage(e))
+  stop(e)
+})
+
+log_step(3, "Calculando estatisticas circulares")
+# Circular statistics
+time_circ  <- circular(sp_data$time_rad, units = "radians", template = "clock24")
+mean_rad   <- mean.circular(time_circ)
+mean_hour  <- as.numeric(mean_rad) * 24 / (2 * pi)
+kappa_est  <- tryCatch(mle.vonmises(time_circ)$kappa, error = function(e) {
+  log_warn("mle.vonmises() falhou (kappa = NA): %s", conditionMessage(e))
+  NA_real_
+})
+rayleigh_p <- rayleigh.test(time_circ)$p.value
+
+log_decision("rayleigh_p", round(rayleigh_p, 4),
+             "p < 0.05 indica distribuicao nao-uniforme (atividade diaria concentrada)")
+if (rayleigh_p >= 0.05) {
+  log_warn("Rayleigh p = %.4f >= 0.05: atividade diaria nao difere de uniforme para '%s'",
+           rayleigh_p, species_name)
+}
+
+circ_stats <- data.frame(
+  species         = species_name,
+  n_events        = nrow(sp_data),
+  mean_activity_hour = round(mean_hour %% 24, 2),
+  kappa           = round(kappa_est, 3),
+  rayleigh_p      = round(rayleigh_p, 4),
+  non_uniform     = rayleigh_p < 0.05
+)
+write.csv(circ_stats, file.path(output_dir, "circular_stats.csv"), row.names = FALSE)
+log_info("Estatisticas circulares salvas: hora media = %.1f h, kappa = %.3f",
+         mean_hour %% 24, ifelse(is.na(kappa_est), 0, kappa_est))
+
+log_step(4, "Calculando sobreposicao de atividade entre grupos (se aplicavel)")
+# Diel overlap between two groups (if group_col provided)
+overlap_result <- data.frame()
+if (!is.null(group_col) && group_col %in% names(sp_data)) {
+  groups <- unique(sp_data[[group_col]])
+  if (length(groups) == 2) {
+    groupA <- sp_data$time_rad[sp_data[[group_col]] == groups[1]]
+    groupB <- sp_data$time_rad[sp_data[[group_col]] == groups[2]]
+
+    if (length(groupA) >= 10 && length(groupB) >= 10) {
+      log_info("Estimando sobreposicao Dhat4 entre '%s' (n=%d) e '%s' (n=%d)",
+               groups[1], length(groupA), groups[2], length(groupB))
+      boot_out  <- bootEst(groupA, groupB, nb = 1000, type = "Dhat4")
+      delta4    <- boot_out["Dhat4"]
+      ci_lower  <- boot_out["lwr"]
+      ci_upper  <- boot_out["upr"]
+
+      overlap_result <- data.frame(
+        groupA  = groups[1],
+        groupB  = groups[2],
+        n_A     = length(groupA),
+        n_B     = length(groupB),
+        Dhat4   = round(delta4, 3),
+        ci_lower = round(ci_lower, 3),
+        ci_upper = round(ci_upper, 3)
+      )
+
+      png(file.path(output_dir, "activity_overlap.png"), width = 900, height = 600, res = 120)
+      overlapPlot(groupA, groupB, rug = TRUE,
+                  main = paste("Diel Overlap — Δ4 =", round(delta4, 2)),
+                  linecol = c("blue", "red"))
+      legend("topright", legend = groups, col = c("blue", "red"), lty = 1)
+      dev.off()
+      log_info("Sobreposicao Dhat4 = %.3f [%.3f, %.3f]",
+               delta4, ci_lower, ci_upper)
+    } else {
+      log_warn("Um ou ambos os grupos tem < 10 eventos; sobreposicao nao calculada (n_A=%d, n_B=%d)",
+               length(groupA), length(groupB))
+    }
+  } else {
+    log_warn("group_col '%s' tem %d valores unicos; exatamente 2 necessarios para sobreposicao",
+             group_col, length(groups))
+  }
+} else if (!is.null(group_col)) {
+  log_warn("Coluna de grupo '%s' nao encontrada nos dados da especie", group_col)
+}
+write.csv(overlap_result, file.path(output_dir, "activity_overlap.csv"), row.names = FALSE)
+
+log_info("Concluido. Saidas gravadas em: %s", output_dir)
+log_info("  n eventos: %d", nrow(sp_data))
+log_info("  Hora media de atividade: %.1f h", mean_hour %% 24)
+log_info("  Rayleigh p: %.4f", round(rayleigh_p, 4))

package/skills/camera-trap-processing/scripts/process_camtrap_data.R

@@ -0,0 +1,179 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript process_camtrap_data.R <image_dir> <camera_metadata_csv> <output_dir> [indep_threshold_min]
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "camera-trap-processing"
+.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(camtrapR))
+suppressPackageStartupMessages(library(dplyr))
+suppressPackageStartupMessages(library(lubridate))
+
+args <- commandArgs(trailingOnly = TRUE)
+if (length(args) < 3) {
+  log_error("Uso: Rscript process_camtrap_data.R <image_dir> <camera_metadata_csv> <output_dir> [indep_threshold_min]")
+  cat("Usage: Rscript process_camtrap_data.R <image_dir> <camera_metadata_csv> <output_dir> [indep_threshold_min]\n")
+  cat("  indep_threshold_min: independence threshold in minutes (default: 30)\n")
+  quit(status = 1)
+}
+
+image_dir    <- args[1]
+metadata_csv <- args[2]
+output_dir   <- args[3]
+thresh_min   <- ifelse(length(args) >= 4, as.integer(args[4]), 30L)
+
+# ── Input precondition checks ────────────────────────────────────────────────
+if (!dir.exists(image_dir)) {
+  log_error("Input nao encontrado: %s\nCausa provavel: caminho errado ou diretorio nao montado\nVerifique: se o diretorio de imagens existe e tem permissao de leitura\nSkill anterior: [nenhuma — etapa inicial]", image_dir)
+  stop("Missing image_dir: ", image_dir)
+}
+if (!file.exists(metadata_csv)) {
+  log_error("Input nao encontrado: %s\nCausa provavel: arquivo CSV de metadados nao gerado ou nome incorreto\nVerifique: se o arquivo existe e o caminho esta correto\nSkill anterior: [nenhuma — etapa inicial]", metadata_csv)
+  stop("Missing metadata_csv: ", metadata_csv)
+}
+
+log_decision("indep_threshold_min", thresh_min,
+             "limiar padrao de 30 min para independencia de registros; ajuste por especie se necessario")
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_step(1, "Carregando metadados das cameras")
+cam_meta <- tryCatch({
+  read.csv(metadata_csv, stringsAsFactors = FALSE)
+}, error = function(e) {
+  log_error("Falha ao ler metadata CSV: %s\nCausa provavel: arquivo corrompido ou formato incorreto\nVerifique: estrutura do CSV\nSkill anterior: [nenhuma]", conditionMessage(e))
+  stop(e)
+})
+log_info("Metadados carregados: %d estacoes", nrow(cam_meta))
+
+required_cols <- c("Station", "Setup_date", "Retrieval_date")
+missing <- setdiff(required_cols, names(cam_meta))
+if (length(missing) > 0) {
+  log_error("Colunas obrigatorias ausentes no CSV de metadados: %s\nCausa provavel: formato de planilha incorreto\nVerifique: se o CSV contem Station, Setup_date, Retrieval_date", paste(missing, collapse = ", "))
+  stop("Camera metadata missing required columns: ", paste(missing, collapse = ", "))
+}
+
+log_step(2, "Construindo matriz de operacao das cameras")
+has_problems <- all(c("Problem1_from", "Problem1_to") %in% names(cam_meta))
+log_decision("has_problems", has_problems,
+             "indica se ha colunas de problemas tecnicas nas cameras no CSV")
+
+cam_op <- tryCatch({
+  cameraOperation(
+    CTtable      = cam_meta,
+    stationCol   = "Station",
+    setupCol     = "Setup_date",
+    retrievalCol = "Retrieval_date",
+    hasProblems  = has_problems,
+    dateFormat   = "yyyy-mm-dd"
+  )
+}, error = function(e) {
+  log_error("Falha em cameraOperation(): %s\nCausa provavel: datas em formato errado ou estacoes duplicadas\nVerifique: formato yyyy-mm-dd nas colunas de data\nSkill anterior: [nenhuma]", conditionMessage(e))
+  stop(e)
+})
+
+# Trap effort per station
+trap_effort <- data.frame(
+  Station    = rownames(cam_op),
+  trap_nights = apply(cam_op, 1, sum, na.rm = TRUE)
+)
+low_effort <- trap_effort$Station[trap_effort$trap_nights < 100]
+if (length(low_effort) > 0) {
+  log_warn("Estacoes com < 100 armadilhas-noite (dados insuficientes para ocupancia): %s",
+           paste(low_effort, collapse = ", "))
+}
+
+log_step(3, "Construindo tabela de registros a partir das imagens")
+log_info("Limiar de independencia: %d min", thresh_min)
+record_table <- tryCatch({
+  recordTable(
+    inDir               = image_dir,
+    IDfrom              = "directory",
+    minDeltaTime        = thresh_min,
+    deltaTimeComparedTo = "lastIndependentRecord",
+    timeZone            = Sys.timezone(),
+    removeDuplicateRecords = TRUE
+  )
+}, error = function(e) {
+  log_error("Falha em recordTable(): %s\nCausa provavel: estrutura de diretorios incorreta\nVerifique: se imagens seguem <Estacao>/<Especie>/<imagens>\nSkill anterior: [nenhuma]", conditionMessage(e))
+  stop("recordTable() failed: ", conditionMessage(e),
+       "\nCheck that image directory follows <Station>/<Species>/<images> structure.")
+})
+log_info("Tabela de registros construida: %d eventos independentes", nrow(record_table))
+
+log_step(4, "Calculando resumo de registros por especie")
+# Records per species summary
+records_per_species <- record_table %>%
+  group_by(Species) %>%
+  summarise(
+    n_events       = n(),
+    n_stations     = n_distinct(Station),
+    first_detection = min(DateTimeOriginal),
+    last_detection  = max(DateTimeOriginal),
+    .groups = "drop"
+  )
+
+low_detections <- records_per_species$Species[records_per_species$n_events < 10]
+if (length(low_detections) > 0) {
+  log_warn("Especies com < 10 eventos independentes (apenas RAI; sem ocupancia): %s",
+           paste(low_detections, collapse = ", "))
+}
+
+log_step(5, "Gerando historicos de deteccao por especie")
+# Generate detection history for all species with >= 10 events
+det_hist_list <- list()
+for (sp in records_per_species$Species[records_per_species$n_events >= 10]) {
+  sp_clean <- gsub(" ", "_", sp)
+  dh <- tryCatch(
+    detectionHistory(
+      recordTable       = record_table,
+      camOp             = cam_op,
+      stationCol        = "Station",
+      speciesCol        = "Species",
+      recordDateTimeCol = "DateTimeOriginal",
+      species           = sp,
+      occasionLength    = 7,
+      day1              = "station",
+      output            = "binary"
+    ),
+    error = function(e) {
+      log_warn("detectionHistory() falhou para especie '%s': %s", sp, conditionMessage(e))
+      NULL
+    }
+  )
+  if (!is.null(dh)) det_hist_list[[sp_clean]] <- dh$detection_history
+}
+log_info("Historicos de deteccao gerados para %d especies", length(det_hist_list))
+
+log_step(6, "Escrevendo arquivos de saida")
+# Write outputs
+write.csv(record_table,        file.path(output_dir, "record_table.csv"),        row.names = FALSE)
+write.csv(cam_op,              file.path(output_dir, "camera_operation.csv"),     row.names = TRUE)
+write.csv(trap_effort,         file.path(output_dir, "trap_effort_summary.csv"),  row.names = FALSE)
+write.csv(records_per_species, file.path(output_dir, "records_per_species.csv"),  row.names = FALSE)
+
+if (length(det_hist_list) > 0) {
+  # Write the first species' detection history as default output
+  dh_df <- as.data.frame(det_hist_list[[1]])
+  write.csv(dh_df, file.path(output_dir, "detection_history.csv"), row.names = TRUE)
+  # Write all species if multiple
+  for (sp_name in names(det_hist_list)) {
+    dh_df_sp <- as.data.frame(det_hist_list[[sp_name]])
+    write.csv(dh_df_sp,
+              file.path(output_dir, paste0("detection_history_", sp_name, ".csv")),
+              row.names = TRUE)
+  }
+}
+
+log_info("Concluido. Saidas gravadas em: %s", output_dir)
+log_info("  record_table.csv: %d eventos independentes", nrow(record_table))
+log_info("  records_per_species.csv: %d especies", nrow(records_per_species))
+log_info("  trap_effort_summary.csv: %d estacoes", nrow(trap_effort))

package/skills/camera-trap-processing/scripts/process_camtrap_data.py

@@ -0,0 +1,192 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Process camera trap detection records from CSV output of camtrapR.
+Usage: python process_camtrap_data.py <record_table_csv> <output_dir> [species_name]
+
+Reads a record_table.csv produced by camtrapR's recordTable() function.
+Computes descriptive statistics per species and camera station.
+Generates a detection timeline plot.
+Does NOT require camtrapR — works with the CSV output only.
+
+Arguments:
+    record_table_csv : path to record_table.csv from camtrapR
+    output_dir       : directory for output files
+    species_name     : optional; filter to a single species
+"""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "camera-trap-processing"
+_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 pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+
+
+def load_records(csv_path: str) -> pd.DataFrame:
+    df = pd.read_csv(csv_path, parse_dates=["DateTimeOriginal"])
+    required = {"Station", "Species", "DateTimeOriginal"}
+    missing = required - set(df.columns)
+    if missing:
+        raise ValueError(f"Record table missing required columns: {missing}")
+    return df
+
+
+def species_summary(df: pd.DataFrame) -> pd.DataFrame:
+    summary = (
+        df.groupby("Species")
+        .agg(
+            n_events=("Species", "count"),
+            n_stations=("Station", "nunique"),
+            first_detection=("DateTimeOriginal", "min"),
+            last_detection=("DateTimeOriginal", "max"),
+        )
+        .reset_index()
+    )
+    summary["rai_per_100_trapnights"] = np.nan  # requires cam_op; computed externally
+    return summary
+
+
+def station_summary(df: pd.DataFrame) -> pd.DataFrame:
+    return (
+        df.groupby("Station")
+        .agg(
+            n_events=("Species", "count"),
+            n_species=("Species", "nunique"),
+            first_detection=("DateTimeOriginal", "min"),
+            last_detection=("DateTimeOriginal", "max"),
+        )
+        .reset_index()
+    )
+
+
+def plot_detection_timeline(df: pd.DataFrame, output_path: Path) -> None:
+    """Timeline of detections per species over time."""
+    species_list = df["Species"].unique()
+    species_codes = {sp: i for i, sp in enumerate(sorted(species_list))}
+
+    fig, ax = plt.subplots(figsize=(12, max(4, len(species_list) * 0.6)))
+    for _, row in df.iterrows():
+        y = species_codes[row["Species"]]
+        ax.plot(row["DateTimeOriginal"], y, "|", color="steelblue",
+                markersize=4, alpha=0.5)
+
+    ax.set_yticks(list(species_codes.values()))
+    ax.set_yticklabels([s.replace("_", " ") for s in species_codes.keys()],
+                       fontsize=8)
+    ax.xaxis.set_major_formatter(mdates.DateFormatter("%b %Y"))
+    fig.autofmt_xdate()
+    ax.set_xlabel("Date")
+    ax.set_title("Camera Trap Detection Timeline")
+    ax.grid(axis="x", linestyle="--", alpha=0.4)
+    plt.tight_layout()
+    fig.savefig(output_path, dpi=120)
+    plt.close(fig)
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(__doc__)
+        sys.exit(1)
+
+    record_csv = sys.argv[1]
+    output_dir = Path(sys.argv[2])
+    species_filter = sys.argv[3] if len(sys.argv) >= 4 else None
+
+    # ── Input precondition checks ────────────────────────────────────────────
+    if not Path(record_csv).exists():
+        logger.error(
+            "Input nao encontrado: %s\n  Causa provavel: process_camtrap_data.R nao foi executado ou falhou\n  Skill anterior: camera-trap-processing (process_camtrap_data.R)",
+            record_csv,
+        )
+        sys.exit(1)
+
+    log_decision("species_filter", species_filter,
+                 "None = todas as especies; nome especifico = filtro por especie")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_step(1, "Carregando registros da tabela CSV")
+    try:
+        df = load_records(record_csv)
+    except Exception as e:
+        logger.error(
+            "Falha ao carregar record_table CSV: %s\n  Causa provavel: colunas obrigatorias ausentes ou arquivo corrompido\n  Skill anterior: camera-trap-processing",
+            e,
+        )
+        sys.exit(1)
+
+    logger.info("Total de registros: %d, Especies: %d", len(df), df["Species"].nunique())
+
+    if species_filter:
+        log_step(2, f"Filtrando para a especie '{species_filter}'")
+        df = df[df["Species"] == species_filter]
+        logger.info("Filtrado para '%s': %d registros", species_filter, len(df))
+        if len(df) == 0:
+            logger.error(
+                "Nenhum registro encontrado para a especie '%s'\n  Causa provavel: nome de especie incorreto\n  Skill anterior: camera-trap-processing (process_camtrap_data.R)",
+                species_filter,
+            )
+            sys.exit(1)
+    else:
+        log_step(2, "Processando todas as especies")
+
+    log_step(3, "Calculando resumo por especie e estacao")
+    try:
+        sp_sum = species_summary(df)
+        st_sum = station_summary(df)
+    except Exception as e:
+        logger.error("Unexpected error in species/station summary: %s", e)
+        raise
+
+    sp_sum.to_csv(output_dir / "species_summary.csv", index=False)
+    st_sum.to_csv(output_dir / "station_summary.csv", index=False)
+    logger.info("species_summary.csv: %d especies", len(sp_sum))
+    logger.info("station_summary.csv: %d estacoes", len(st_sum))
+
+    low_events = sp_sum[sp_sum["n_events"] < 10]["Species"].tolist()
+    if low_events:
+        logger.warning(
+            "Especies com < 10 eventos (apenas RAI; sem estimativa de ocupancia): %s",
+            low_events,
+        )
+
+    log_step(4, "Gerando grafico de linha do tempo de deteccoes")
+    try:
+        plot_detection_timeline(df, output_dir / "detection_timeline.png")
+        logger.info("detection_timeline.png salvo")
+    except Exception as e:
+        logger.error("Unexpected error in plot_detection_timeline: %s", e)
+        raise
+
+    logger.info("Concluido. Saidas gravadas em: %s", output_dir)
+    logger.info("  species_summary.csv: %d especies", len(sp_sum))
+    logger.info("  station_summary.csv: %d estacoes", len(st_sum))
+
+
+if __name__ == "__main__":
+    main()

package/skills/community-ecology-ordination/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: community-ecology-ordination
+description: "Performs multivariate community ecology analyses including ordination, diversity metrics, and assemblage comparisons. Use this skill when the user mentions species composition, NMDS, PCA ordination, PERMANOVA, beta diversity, alpha diversity, species richness, Bray-Curtis dissimilarity, indicator species analysis, cluster analysis, species-by-site matrices, diversity indices, or assemblage structure comparisons."
+skill_version: 1.0.0
+---
+
+# Skill: community-ecology-ordination
+
+**Domain:** NMDS · PCA · PCoA · Diversity · Clustering · Composition  
+**Phase:** 3 — Specialist  
+**Used by:** analyze-community-structure
+
+---
+
+## Purpose
+
+Guides the agent through multivariate analysis of ecological communities: ordination of species assemblages, diversity metric computation, beta diversity partitioning, cluster analysis, and hypothesis testing on community composition.
+
+---
+
+## When to Invoke
+
+- Analysing species composition across multiple sites
+- Comparing community structure between treatments, habitats, or time periods
+- Computing alpha and beta diversity metrics
+- Identifying species groups or site clusters
+
+---
+
+## Inputs
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Species × site abundance or presence matrix | CSV | Yes |
+| Environmental metadata per site | CSV | Recommended |
+| Treatment or grouping variable | Factor column | Recommended |
+
+---
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `ordination_plot.png` | NMDS/PCA biplot |
+| `diversity_metrics.csv` | Alpha diversity per site |
+| `beta_diversity_matrix.csv` | Pairwise dissimilarity matrix |
+| `permanova_results.txt` | PERMANOVA output |
+| `cluster_dendrogram.png` | Hierarchical clustering dendrogram |
+| `community_report.md` | Full analysis narrative |
+
+---
+
+## Steps
+
+### 1. Data Preparation
+- Check for sites with zero species (remove or flag)
+- Check for species observed at only one site (rare species handling: keep or remove)
+- Standardise if needed (Hellinger, Wisconsin, presence/absence)
+- Choose dissimilarity metric: Bray-Curtis (abundance), Jaccard (presence/absence), UniFrac (phylogenetic)
+
+### 2. Alpha Diversity
+- Species richness (S)
+- Shannon index (H')
+- Simpson index (1−D)
+- Rarefaction curves to assess sampling adequacy
+- Report metric ± SE per group
+
+### 3. Ordination
+**NMDS:**
+- Run with k=2 (default) and k=3; choose lowest stress with acceptable fit
+- Stress < 0.1 = excellent, < 0.2 = acceptable, > 0.2 = poor
+- Run with ≥ 20 random starts; confirm convergence
+
+**PCA (for environmental gradients or species scores):**
+- Use Hellinger-transformed data or correlation matrix
+- Report eigenvalues and % variance per axis
+
+**PCoA / MDS:**
+- For non-Euclidean dissimilarity matrices
+
+### 4. Beta Diversity Partitioning
+- Partition total beta diversity into nestedness and turnover components (betapart)
+- Report contribution of each component per group comparison
+
+### 5. Hypothesis Testing
+- PERMANOVA (`adonis2`): test if group centroids differ
+- PERMDISP: test if group dispersions (variances) differ (required before interpreting PERMANOVA)
+- ANOSIM: alternative non-parametric test
+- Report F/R statistic, R², p-value (permutation-based)
+
+### 6. Species Contributions
+- SIMPER: identify species driving dissimilarity between groups
+- IndVal: identify indicator species per group
+- Report top N contributing species per axis or group
+
+### 7. Cluster Analysis
+- Hierarchical clustering: Ward.D2 linkage preferred
+- Cophenetic correlation to assess cluster quality
+- k-means as alternative for large datasets
+- Determine optimal k using silhouette or elbow method
+
+---
+
+## Key Decisions to Document
+
+- Dissimilarity metric and rationale
+- Rare species handling
+- Data transformation applied
+- Number of NMDS dimensions
+- Permutation count for PERMANOVA
+
+---
+
+## Tools and Libraries
+
+**R:** `vegan`, `betapart`, `indicspecies`, `ape`, `dendextend`, `ggplot2`  
+**Python:** `skbio`, `scipy.cluster`, `sklearn.manifold`
+
+---
+
+## Resources
+
+- `resources/dissimilarity-metric-guide.md` — which metric for which data type
+- `resources/nmds-interpretation-guide.md` — how to read and report NMDS plots
+- `examples/` — worked NMDS and PERMANOVA example
+
+---
+
+## Notes
+
+- Always run PERMDISP before interpreting PERMANOVA; significant dispersion differences can inflate PERMANOVA results
+- Stress value must be reported alongside all NMDS plots
+- Rarefaction is mandatory when sites have very different sampling intensities