ecological-agent-skills 3.1.0

package/skills/environmental-time-series/scripts/recovery_trajectory.R

@@ -0,0 +1,305 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript recovery_trajectory.R <timeseries.csv> <disturbance_date> <output_dir>
+# Estimate post-disturbance vegetation recovery trajectory
+# Usage: Rscript recovery_trajectory.R <timeseries_csv> <disturbance_date> <output_dir>
+# Requires: dplyr, ggplot2, zoo, broom, lubridate
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "environmental-time-series"
+.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(dplyr)
+  library(ggplot2)
+  library(zoo)
+  library(broom)
+})
+
+args             <- commandArgs(trailingOnly = TRUE)
+ts_file          <- ifelse(length(args) >= 1, args[1], "tests/data/ndvi_monthly_series.csv")
+disturbance_date <- ifelse(length(args) >= 2, args[2], "2010-01-01")
+output_dir       <- ifelse(length(args) >= 3, args[3], "outputs/recovery")
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_info("Skill: %s | ts_file=%s | disturbance_date=%s | output_dir=%s",
+         SKILL_NAME, ts_file, disturbance_date, output_dir)
+
+# ── Input precondition check ──────────────────────────────────────────────────
+if (!file.exists(ts_file)) {
+  log_error(
+    "Input nao encontrado: %s\nCausa provavel: serie temporal nao gerada pelo passo anterior ou caminho incorreto.\nVerifique: execute primeiro o script de extracao de NDVI ou forneca o CSV correto.\nSkill anterior: geoprocessing-for-ecology ou remote-sensing-analysis.",
+    ts_file
+  )
+  stop("Missing: ", ts_file)
+}
+
+# ── 1. Load and parse ──────────────────────────────────────────────────────────
+log_step(1, "Carregar e parsear serie temporal")
+dat <- tryCatch({
+  read.csv(ts_file)
+}, error = function(e) {
+  log_error(
+    "Falha ao ler CSV de serie temporal: %s\nCausa provavel: arquivo corrompido, encoding incorreto ou separador diferente de virgula.\nVerifique: abra o arquivo em editor de texto e confira o formato.\nSkill anterior: geoprocessing-for-ecology.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+val_col  <- if ("value" %in% names(dat)) "value" else names(dat)[ncol(dat)]
+date_col <- if ("date"  %in% names(dat)) "date"  else names(dat)[1]
+
+log_decision("val_col",  val_col,  "coluna 'value' usada se presente, caso contrario ultima coluna numerica")
+log_decision("date_col", date_col, "coluna 'date' usada se presente, caso contrario primeira coluna")
+
+dat[[date_col]] <- tryCatch({
+  as.Date(dat[[date_col]])
+}, error = function(e) {
+  log_error(
+    "Falha ao converter coluna '%s' para Date: %s\nCausa provavel: formato de data nao reconhecido (esperado YYYY-MM-DD).\nVerifique: todos os valores da coluna de data devem seguir o formato ISO 8601.\nSkill anterior: geoprocessing-for-ecology.",
+    date_col, conditionMessage(e)
+  )
+  stop(e)
+})
+
+dist_date <- tryCatch({
+  as.Date(disturbance_date)
+}, error = function(e) {
+  log_error(
+    "Falha ao parsear disturbance_date='%s': %s\nCausa provavel: formato invalido; use YYYY-MM-DD.\nVerifique: o segundo argumento do script.\nSkill anterior: nenhuma.",
+    disturbance_date, conditionMessage(e)
+  )
+  stop(e)
+})
+
+n_na_val <- sum(is.na(dat[[val_col]]))
+if (n_na_val > 0) {
+  log_warn("Coluna '%s' contem %d valores NA — podem afetar calculo de baseline e minimo.", val_col, n_na_val)
+}
+
+log_info("Comprimento da serie: %d | Data de disturbio: %s", nrow(dat), format(dist_date))
+
+# ── 2. Define periods ──────────────────────────────────────────────────────────
+log_step(2, "Separar periodos pre e pos-disturbio")
+pre  <- dat[dat[[date_col]] <  dist_date, ]
+post <- dat[dat[[date_col]] >= dist_date, ]
+log_info("Obs pre-disturbio: %d | Pos: %d", nrow(pre), nrow(post))
+log_decision("period_split", format(dist_date),
+             "divisao estrita: pre < disturbance_date, pos >= disturbance_date")
+
+if (nrow(pre) < 12) {
+  log_error(
+    "Observacoes pre-disturbio insuficientes: %d (minimo 12 necessario).\nCausa provavel: a data de disturbio e muito proxima ao inicio da serie.\nVerifique: a data de disturbio e os dados disponiveis antes dela.\nSkill anterior: geoprocessing-for-ecology.",
+    nrow(pre)
+  )
+  stop("Need at least 12 pre-disturbance observations for baseline.")
+}
+
+if (nrow(post) < 5) {
+  log_warn("Apenas %d observacoes pos-disturbio — ajuste de curva pode ser instavel.", nrow(post))
+}
+
+# ── 3. Baseline statistics ─────────────────────────────────────────────────────
+log_step(3, "Calcular estatisticas de baseline pre-disturbio (ultimos 24 meses)")
+recent_pre    <- tail(pre, 24)
+baseline_mean <- mean(recent_pre[[val_col]], na.rm = TRUE)
+baseline_sd   <- sd(recent_pre[[val_col]],   na.rm = TRUE)
+log_info("Baseline pre-disturbio: %.4f +/- %.4f (n=%d obs)", baseline_mean, baseline_sd, nrow(recent_pre))
+log_decision("baseline_window", "24 observacoes mais recentes antes do disturbio",
+             "janela de 2 anos captura condicoes imediatamente anteriores ao impacto")
+
+if (nrow(recent_pre) < 24) {
+  log_warn("Janela de baseline reduzida para %d obs (esperado 24) — serie pre-disturbio curta.", nrow(recent_pre))
+}
+
+# ── 4. Minimum post-disturbance value ─────────────────────────────────────────
+log_step(4, "Identificar minimo pos-disturbio com suavizacao (janela 3)")
+post_smooth <- tryCatch({
+  rollapply(post[[val_col]], width = 3, FUN = mean, align = "center", fill = NA)
+}, error = function(e) {
+  log_error(
+    "Falha na suavizacao rolante: %s\nCausa provavel: serie pos-disturbio muito curta para janela de 3 observacoes.\nVerifique: numero de observacoes pos-disturbio.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+min_val  <- min(post_smooth, na.rm = TRUE)
+min_idx  <- which.min(post_smooth)
+min_date <- post[[date_col]][min_idx]
+log_info("Minimo pos-disturbio: %.4f em %s", min_val, format(min_date))
+log_decision("smoothing_width", "3",
+             "suavizacao com janela de 3 reduz ruido de sensor sem mascarar dinamica de recuperacao")
+
+if (baseline_mean <= min_val) {
+  log_warn("Minimo pos-disturbio (%.4f) nao e menor que a media baseline (%.4f) — possivel ausencia de disturbio detectavel.", min_val, baseline_mean)
+}
+
+# ── 5. Recovery Indicator (RI) ─────────────────────────────────────────────────
+log_step(5, "Calcular Recovery Indicator (RI) e salvar serie")
+# RI_t = (value_t - min_val) / (baseline_mean - min_val)
+post$RI <- (post[[val_col]] - min_val) / (baseline_mean - min_val + 1e-10)
+
+tryCatch({
+  write.csv(post[, c(date_col, val_col, "RI")],
+            file.path(output_dir, "recovery_indicator.csv"), row.names = FALSE)
+  log_info("recovery_indicator.csv salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao salvar recovery_indicator.csv: %s\nCausa provavel: permissao negada ou disco cheio.\nVerifique: permissoes do diretorio de saida.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_decision("RI_formula", "RI = (value - min) / (baseline_mean - min + 1e-10)",
+             "normalizacao 0->1 onde 0=minimo pos-disturbio e 1=baseline pre-disturbio; epsilon evita divisao por zero")
+
+# ── 6. Fit recovery curves ─────────────────────────────────────────────────────
+log_step(6, "Ajustar curvas de recuperacao (linear e exponencial)")
+# t = months since minimum
+post$t_months <- as.numeric(difftime(post[[date_col]], min_date, units = "days")) / 30.44
+post_fit      <- post[post$t_months >= 0, ]
+
+results_list <- list()
+
+m_lin <- tryCatch({
+  lm(RI ~ t_months, data = post_fit)
+}, error = function(e) {
+  log_error(
+    "Falha ao ajustar modelo linear de recuperacao: %s\nCausa provavel: dados pos-disturbio insuficientes ou sem variacao em t_months.\nVerifique: numero de observacoes pos-disturbio apos o minimo.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+results_list$linear <- broom::glance(m_lin) |>
+  mutate(model = "linear", formula = "RI ~ t")
+log_info("Modelo linear ajustado: R2=%.4f", summary(m_lin)$r.squared)
+
+# Exponential (log-linear)
+post_fit_pos <- post_fit[post_fit$RI > 0.01, ]  # avoid log(0)
+if (nrow(post_fit_pos) > 5) {
+  tryCatch({
+    m_exp <- lm(log(RI) ~ t_months, data = post_fit_pos)
+    results_list$exponential <- broom::glance(m_exp) |>
+      mutate(model = "exponential", formula = "log(RI) ~ t")
+    log_info("Modelo exponencial ajustado: R2=%.4f", summary(m_exp)$r.squared)
+  }, error = function(e) {
+    log_warn("Falha ao ajustar modelo exponencial: %s — continuando apenas com modelo linear.", conditionMessage(e))
+  })
+} else {
+  log_warn("Apenas %d obs com RI > 0.01 — modelo exponencial nao ajustado (minimo 5 necessario).", nrow(post_fit_pos))
+}
+
+# ── 7. Estimate time to 80% and 100% recovery ─────────────────────────────────
+log_step(7, "Estimar tempo para 80%% e 100%% de recuperacao (modelo linear)")
+slope     <- coef(m_lin)[["t_months"]]
+intercept <- coef(m_lin)[["(Intercept)"]]
+# RI = intercept + slope * t → t = (RI_target - intercept) / slope
+t_80  <- if (slope > 0) round((0.80 - intercept) / slope, 1) else NA
+t_100 <- if (slope > 0) round((1.00 - intercept) / slope, 1) else NA
+
+log_info("Tempo estimado para 80%% de recuperacao: %s meses", ifelse(is.na(t_80), "NA (inclinacao negativa)", t_80))
+log_info("Tempo estimado para 100%% de recuperacao: %s meses", ifelse(is.na(t_100), "NA (inclinacao negativa)", t_100))
+log_decision("recovery_model", "linear",
+             "modelo linear usado para projecao de tempo de recuperacao por simplicidade e interpretabilidade")
+
+if (slope <= 0) {
+  log_warn("Inclinacao linear negativa (%.6f) — sem recuperacao detectada no periodo pos-disturbio.", slope)
+}
+
+recovery_metrics <- data.frame(
+  baseline_mean        = round(baseline_mean, 4),
+  baseline_sd          = round(baseline_sd,   4),
+  disturbance_date     = format(dist_date),
+  post_minimum_value   = round(min_val, 4),
+  post_minimum_date    = format(min_date),
+  magnitude_of_decline = round((baseline_mean - min_val) / baseline_mean * 100, 2),
+  RI_current           = round(tail(post$RI, 1), 4),
+  slope_linear         = round(slope, 6),
+  r2_linear            = round(summary(m_lin)$r.squared, 4),
+  t_to_80pct_months    = t_80,
+  t_to_100pct_months   = t_100
+)
+
+tryCatch({
+  write.csv(recovery_metrics, file.path(output_dir, "recovery_metrics.csv"), row.names = FALSE)
+  log_info("recovery_metrics.csv salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao salvar recovery_metrics.csv: %s\nCausa provavel: permissao negada ou disco cheio.\nVerifique: permissoes do diretorio de saida.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 8. Plot recovery trajectory ────────────────────────────────────────────────
+log_step(8, "Gerar grafico de trajetoria de recuperacao")
+tryCatch({
+  pred_df <- data.frame(t_months = seq(0, max(post_fit$t_months, na.rm=TRUE), by=1))
+  pred_df$RI_pred <- intercept + slope * pred_df$t_months
+
+  p <- ggplot() +
+    geom_hline(yintercept = 1.0, linetype = "dashed", colour = "forestgreen", alpha = 0.7) +
+    geom_hline(yintercept = 0.8, linetype = "dashed", colour = "orange",      alpha = 0.7) +
+    geom_line(data = post_fit, aes(x = t_months, y = RI), colour = "grey50", linewidth = 0.8) +
+    geom_point(data = post_fit, aes(x = t_months, y = RI), size = 1.5, alpha = 0.7) +
+    geom_line(data = pred_df, aes(x = t_months, y = RI_pred),
+              colour = "#2166ac", linewidth = 1.1, linetype = "solid") +
+    annotate("text", x = max(post_fit$t_months)*0.05, y = 1.02, label = "100% recovery",
+             colour = "forestgreen", size = 3, hjust = 0) +
+    annotate("text", x = max(post_fit$t_months)*0.05, y = 0.82, label = "80% recovery",
+             colour = "orange", size = 3, hjust = 0) +
+    labs(x = "Months since post-disturbance minimum",
+         y = "Recovery Indicator (RI)",
+         title = "Post-Disturbance Recovery Trajectory",
+         subtitle = paste0("Disturbance: ", format(dist_date),
+                           " | Linear model R\u00b2 = ", round(summary(m_lin)$r.squared, 3))) +
+    theme_bw()
+
+  ggsave(file.path(output_dir, "recovery_trajectory.png"), p, width = 8, height = 5, dpi = 150)
+  log_info("recovery_trajectory.png salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao gerar grafico de trajetoria de recuperacao: %s\nCausa provavel: dados insuficientes para projecao ou diretorio sem permissao de escrita.\nVerifique: se post_fit contem observacoes validas.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 9. Full time series context plot ───────────────────────────────────────────
+log_step(9, "Gerar grafico de contexto da serie temporal completa")
+tryCatch({
+  p2 <- ggplot(dat, aes(x = .data[[date_col]], y = .data[[val_col]])) +
+    geom_line(colour = "grey60", linewidth = 0.6) +
+    geom_vline(xintercept = as.numeric(dist_date), linetype = "dashed",
+               colour = "red", linewidth = 0.8) +
+    geom_hline(yintercept = baseline_mean, linetype = "dotted",
+               colour = "forestgreen", linewidth = 0.8) +
+    annotate("text", x = dist_date, y = max(dat[[val_col]], na.rm=TRUE),
+             label = " Disturbance", hjust = 0, colour = "red", size = 3.2) +
+    annotate("text", x = min(dat[[date_col]]), y = baseline_mean + 0.005,
+             label = "Pre-disturbance baseline", hjust = 0, colour = "forestgreen", size = 3) +
+    labs(x = NULL, y = val_col, title = "Full NDVI Time Series with Disturbance Event") +
+    theme_bw()
+  ggsave(file.path(output_dir, "timeseries_context.png"), p2, width = 10, height = 4, dpi = 150)
+  log_info("timeseries_context.png salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao gerar grafico de contexto da serie temporal: %s\nCausa provavel: colunas de data ou valor invalidas ou diretorio sem permissao de escrita.\nVerifique: integridade do CSV de entrada.\nSkill anterior: geoprocessing-for-ecology.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Analise de recuperacao concluida. Saidas em: %s", output_dir)
+log_info("Metricas-chave:")
+print(t(recovery_metrics))

package/skills/environmental-time-series/scripts/recovery_trajectory.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+recovery_trajectory.py
+Estimate post-disturbance vegetation recovery trajectory.
+Usage: python recovery_trajectory.py <timeseries_csv> <disturbance_date> <output_dir>
+Requires: pandas, numpy, scipy, matplotlib
+"""
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "environmental-time-series"
+_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.stats import linregress
+from scipy.ndimage import uniform_filter1d
+
+
+def main():
+    ts_file    = sys.argv[1] if len(sys.argv) > 1 else "tests/data/ndvi_monthly_series.csv"
+    dist_date  = sys.argv[2] if len(sys.argv) > 2 else "2010-01-01"
+    output_dir = Path(sys.argv[3]) if len(sys.argv) > 3 else Path("outputs/recovery")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    log_decision("ts_file", ts_file, "Input time series CSV")
+    log_decision("dist_date", dist_date, "Disturbance event date for pre/post split")
+    log_decision("output_dir", str(output_dir), "Directory for recovery outputs")
+
+    if not Path(ts_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",
+            ts_file
+        )
+        sys.exit(1)
+
+    try:
+        log_step(1, "Loading and splitting time series at disturbance date")
+        dat = pd.read_csv(ts_file, parse_dates=[0])
+        date_col = dat.columns[0]
+        val_col  = "value" if "value" in dat.columns else dat.columns[-1]
+        dist_dt  = pd.to_datetime(dist_date)
+
+        pre  = dat[dat[date_col] <  dist_dt].copy()
+        post = dat[dat[date_col] >= dist_dt].copy()
+        logger.info("Pre: %d obs | Post: %d obs | Disturbance: %s", len(pre), len(post), dist_date)
+        if len(pre) < 12:
+            raise ValueError("Need >= 12 pre-disturbance observations.")
+        if len(post) == 0:
+            logger.warning("No post-disturbance observations found. Recovery metrics will be empty.")
+
+        log_step(2, "Computing pre-disturbance baseline (last 24 months)")
+        # Baseline: last 24 pre-disturbance months
+        recent_pre   = pre.tail(24)
+        baseline_mean = recent_pre[val_col].mean()
+        baseline_sd   = recent_pre[val_col].std()
+        log_decision("baseline_window", 24,
+                     "Last 24 pre-disturbance observations used as baseline reference period")
+        logger.info("Baseline: %.4f +/- %.4f", baseline_mean, baseline_sd)
+
+        log_step(3, "Detecting post-disturbance minimum via smoothed series")
+        # Smoothed minimum
+        smooth = uniform_filter1d(post[val_col].values, size=3)
+        min_idx = np.nanargmin(smooth)
+        min_val = smooth[min_idx]
+        min_date = post[date_col].iloc[min_idx]
+        logger.info("Post-disturbance minimum: %.4f at %s", min_val, min_date.date())
+
+        log_step(4, "Computing Recovery Indicator (RI) and linear fit")
+        # Recovery Indicator
+        post = post.copy()
+        post["RI"] = (post[val_col] - min_val) / (baseline_mean - min_val + 1e-10)
+        post["t_months"] = ((post[date_col] - min_date).dt.days / 30.44).clip(lower=0)
+        post.to_csv(output_dir / "recovery_indicator.csv", index=False)
+
+        # Linear fit
+        fit_df = post[post["t_months"] >= 0].dropna(subset=["RI"])
+        slope, intercept, r, p_val, se = linregress(fit_df["t_months"], fit_df["RI"])
+        r2 = r**2
+        logger.info("Linear fit: slope=%.5f/month | R2=%.3f", slope, r2)
+
+        t_80  = round((0.80 - intercept) / slope, 1) if slope > 0 else None
+        t_100 = round((1.00 - intercept) / slope, 1) if slope > 0 else None
+        logger.info("Estimated recovery: 80%% at %s months | 100%% at %s months", t_80, t_100)
+        if slope <= 0:
+            logger.warning(
+                "Recovery slope is non-positive (slope=%.5f). "
+                "Vegetation may not be recovering — review disturbance date or data quality.",
+                slope
+            )
+
+        log_step(5, "Saving recovery metrics CSV")
+        metrics = pd.DataFrame([{
+            "baseline_mean": round(baseline_mean, 4),
+            "baseline_sd":   round(baseline_sd, 4),
+            "disturbance_date": dist_date,
+            "post_minimum_value": round(float(min_val), 4),
+            "post_minimum_date": str(min_date.date()),
+            "magnitude_decline_pct": round((baseline_mean - min_val)/baseline_mean*100, 2),
+            "RI_current": round(float(post["RI"].iloc[-1]), 4),
+            "slope_linear": round(slope, 6),
+            "r2_linear": round(r2, 4),
+            "t_to_80pct_months": t_80,
+            "t_to_100pct_months": t_100,
+        }])
+        metrics.to_csv(output_dir / "recovery_metrics.csv", index=False)
+
+        log_step(6, "Generating recovery trajectory and context plots")
+        # Recovery plot
+        t_range = np.linspace(0, fit_df["t_months"].max(), 200)
+        ri_pred = intercept + slope * t_range
+        fig, ax = plt.subplots(figsize=(8, 5))
+        ax.axhline(1.0, linestyle="--", color="forestgreen", alpha=0.7, label="100% recovery")
+        ax.axhline(0.8, linestyle="--", color="orange",      alpha=0.7, label="80% recovery")
+        ax.scatter(fit_df["t_months"], fit_df["RI"], s=20, alpha=0.7, color="grey")
+        ax.plot(fit_df["t_months"], fit_df["RI"], color="grey", linewidth=0.7)
+        ax.plot(t_range, ri_pred, color="steelblue", linewidth=1.5,
+                label=f"Linear fit R2={r2:.3f}")
+        ax.set_xlabel("Months since post-disturbance minimum")
+        ax.set_ylabel("Recovery Indicator (RI)")
+        ax.set_title(f"Recovery Trajectory — disturbance: {dist_date}")
+        ax.legend(); plt.tight_layout()
+        plt.savefig(output_dir / "recovery_trajectory.png", dpi=150)
+        plt.close()
+
+        # Context plot
+        fig2, ax2 = plt.subplots(figsize=(10, 4))
+        ax2.plot(dat[date_col], dat[val_col], color="grey", linewidth=0.8)
+        ax2.axvline(dist_dt, color="red", linestyle="--", linewidth=1, label="Disturbance")
+        ax2.axhline(baseline_mean, color="forestgreen", linestyle=":", linewidth=1,
+                    label=f"Baseline ({baseline_mean:.3f})")
+        ax2.set_xlabel("Date"); ax2.set_ylabel(val_col)
+        ax2.set_title("Full Time Series with Disturbance Event")
+        ax2.legend(); plt.tight_layout()
+        plt.savefig(output_dir / "timeseries_context.png", dpi=150)
+        plt.close()
+        logger.info("Outputs written to: %s", output_dir)
+
+    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 recovery trajectory analysis: %s", e)
+        raise
+
+if __name__ == "__main__":
+    main()

package/skills/environmental-time-series/scripts/trend_analysis.R

@@ -0,0 +1,192 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript trend_analysis.R <timeseries.csv> <output_dir> [frequency] [baseline_end]
+# Mann-Kendall trend + Sen's slope + BFAST breakpoints
+# Usage: Rscript trend_analysis.R <timeseries_csv> <output_dir> [frequency]
+# Requires: trend, bfast, zoo, ggplot2
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "environmental-time-series"
+.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(trend)
+  library(bfast)
+  library(zoo)
+  library(ggplot2)
+})
+
+args       <- commandArgs(trailingOnly = TRUE)
+ts_file    <- ifelse(length(args) >= 1, args[1], "data/ndvi_series.csv")
+output_dir <- ifelse(length(args) >= 2, args[2], "outputs/timeseries")
+freq       <- ifelse(length(args) >= 3, as.integer(args[3]), 12L)
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_info("Skill: %s | ts_file=%s | output_dir=%s | freq=%d",
+         SKILL_NAME, ts_file, output_dir, freq)
+log_decision("freq", as.character(freq),
+             "frequencia da serie temporal (observacoes por ano); padrao 12 para dados mensais")
+
+# ── Input precondition check ──────────────────────────────────────────────────
+if (!file.exists(ts_file)) {
+  log_error(
+    "Input nao encontrado: %s\nCausa provavel: serie temporal nao gerada ou caminho incorreto.\nVerifique: execute primeiro o script de extracao/exportacao da serie temporal.\nSkill anterior: geoprocessing-for-ecology ou remote-sensing-analysis.",
+    ts_file
+  )
+  stop("Missing: ", ts_file)
+}
+
+# ── Load ───────────────────────────────────────────────────────────────────────
+log_step(1, "Carregar serie temporal e validar coluna 'value'")
+dat <- tryCatch({
+  read.csv(ts_file)
+}, error = function(e) {
+  log_error(
+    "Falha ao ler CSV de serie temporal: %s\nCausa provavel: arquivo corrompido, encoding incorreto ou separador diferente de virgula.\nVerifique: abra o arquivo em editor de texto e confira o formato.\nSkill anterior: geoprocessing-for-ecology.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+if (!"value" %in% names(dat)) {
+  log_error(
+    "Coluna 'value' nao encontrada no CSV (colunas presentes: %s).\nCausa provavel: CSV exportado com nome de coluna diferente.\nVerifique: renomeie a coluna de valores para 'value' ou ajuste o script.\nSkill anterior: geoprocessing-for-ecology.",
+    paste(names(dat), collapse = ", ")
+  )
+  stop("Missing column: value")
+}
+
+n_na <- sum(is.na(dat$value))
+if (n_na > 0) {
+  log_warn("Coluna 'value' contem %d valores NA — Mann-Kendall pode ser afetado.", n_na)
+}
+
+log_info("Observacoes: %d | Frequencia: %d", nrow(dat), freq)
+
+ts_obj <- ts(dat$value, frequency = freq)
+
+# ── Mann-Kendall + Sen's slope ─────────────────────────────────────────────────
+log_step(2, "Teste de Mann-Kendall e inclinacao de Sen")
+mk  <- tryCatch({
+  mk.test(dat$value)
+}, error = function(e) {
+  log_error(
+    "Falha no teste de Mann-Kendall: %s\nCausa provavel: serie com todos os valores iguais ou NA excessivo.\nVerifique: variabilidade dos dados de entrada.\nSkill anterior: geoprocessing-for-ecology.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+sen <- tryCatch({
+  sens.slope(dat$value)
+}, error = function(e) {
+  log_error(
+    "Falha ao calcular inclinacao de Sen: %s\nCausa provavel: serie insuficiente ou sem variacao.\nVerifique: numero de observacoes validas.\nSkill anterior: geoprocessing-for-ecology.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Mann-Kendall: tau=%.4f | p=%.4f", mk$statistic, mk$p.value)
+log_info("Inclinacao de Sen: %.6f (unidades/observacao)", sen$estimates)
+
+if (mk$p.value < 0.05) {
+  trend_dir <- ifelse(mk$statistic > 0, "crescente", "decrescente")
+  log_info("Tendencia significativa detectada (p<0.05): %s", trend_dir)
+} else {
+  log_info("Nenhuma tendencia significativa detectada (p=%.4f >= 0.05).", mk$p.value)
+}
+
+mk_results <- data.frame(
+  tau = mk$statistic, p_value = mk$p.value,
+  sens_slope = as.numeric(sen$estimates),
+  trend_direction = ifelse(mk$p.value < 0.05,
+                           ifelse(mk$statistic > 0, "increasing", "decreasing"),
+                           "no significant trend")
+)
+
+tryCatch({
+  write.csv(mk_results, file.path(output_dir, "trend_results.csv"), row.names = FALSE)
+  log_info("trend_results.csv salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao salvar trend_results.csv: %s\nCausa provavel: permissao negada ou disco cheio.\nVerifique: permissoes do diretorio de saida.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── BFAST breakpoints ──────────────────────────────────────────────────────────
+log_step(3, "Detectar quebras estruturais com BFAST")
+min_length_bfast <- 3 * freq
+if (length(ts_obj) >= min_length_bfast) {
+  log_info("Serie suficiente para BFAST (%d obs >= %d minimo). Executando...", length(ts_obj), min_length_bfast)
+  log_decision("bfast_h", "0.15",
+               "h=0.15 requer pelo menos 15%% da serie entre quebras; equilibrio entre sensibilidade e estabilidade")
+  log_decision("bfast_season", "harmonic",
+               "modelo harmonico para sazonalidade adequado para series de vegetacao com ciclo anual")
+  tryCatch({
+    bf <- bfast(ts_obj, h = 0.15, season = "harmonic", max.iter = 20)
+    bp <- bf$output[[1]]$bp.Vt$breakpoints
+    if (length(bp) == 0 || all(is.na(bp))) {
+      log_info("BFAST: nenhuma quebra estrutural detectada.")
+    } else {
+      log_info("BFAST: quebras detectadas nas observacoes: %s", paste(bp, collapse = ", "))
+    }
+    write.csv(data.frame(breakpoint_obs = bp),
+              file.path(output_dir, "breakpoints.csv"), row.names = FALSE)
+    log_info("breakpoints.csv salvo em: %s", output_dir)
+    png(file.path(output_dir, "bfast_plot.png"), width = 1200, height = 600, res = 150)
+    plot(bf)
+    dev.off()
+    log_info("bfast_plot.png salvo em: %s", output_dir)
+  }, error = function(e) {
+    log_warn("BFAST falhou: %s — continuando sem deteccao de quebras.", conditionMessage(e))
+  })
+} else {
+  log_warn("Serie muito curta para BFAST: %d obs < %d minimo (3 ciclos completos de frequencia %d).",
+           length(ts_obj), min_length_bfast, freq)
+}
+
+# ── Anomalies ──────────────────────────────────────────────────────────────────
+log_step(4, "Calcular anomalias em relacao ao baseline")
+baseline_n    <- min(freq * 10, length(dat$value) %/% 2)
+baseline_mean <- mean(dat$value[1:baseline_n], na.rm = TRUE)
+baseline_sd   <- sd(dat$value[1:baseline_n],   na.rm = TRUE)
+
+log_decision("baseline_n", as.character(baseline_n),
+             "minimo entre 10 anos de dados e metade da serie; evita que o baseline abranja o periodo de mudanca")
+log_info("Baseline: %.4f +/- %.4f (primeiras %d observacoes)", baseline_mean, baseline_sd, baseline_n)
+
+if (baseline_sd == 0) {
+  log_warn("Desvio padrao do baseline e zero — todas as anomalias serao infinitas ou NaN.")
+}
+
+dat$anomaly_z <- (dat$value - baseline_mean) / baseline_sd
+
+n_extreme <- sum(abs(dat$anomaly_z) > 3, na.rm = TRUE)
+if (n_extreme > 0) {
+  log_warn("%d observacao(oes) com anomalia |Z| > 3 detectada(s) — possiveis outliers ou eventos extremos.", n_extreme)
+}
+
+tryCatch({
+  write.csv(dat[, c(names(dat)[1], "value", "anomaly_z")],
+            file.path(output_dir, "anomaly_series.csv"), row.names = FALSE)
+  log_info("anomaly_series.csv salvo em: %s", output_dir)
+}, error = function(e) {
+  log_error(
+    "Falha ao salvar anomaly_series.csv: %s\nCausa provavel: permissao negada ou disco cheio.\nVerifique: permissoes do diretorio de saida.\nSkill anterior: nenhuma.",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Anomalias calculadas em relacao as primeiras %d observacoes.", baseline_n)
+log_info("Analise de tendencia concluida. Saidas em: %s", output_dir)