ecological-agent-skills 3.1.0

package/skills/species-distribution-modeling/scripts/sdm_pipeline.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+sdm_pipeline.py
+SDM pipeline scaffold using elapid (MaxEnt equivalent in Python) + sklearn.
+Usage: python sdm_pipeline.py <params_yaml> <output_dir>
+Requires: pandas, numpy, sklearn, elapid (optional), yaml, matplotlib
+"""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "species-distribution-modeling"
+_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 yaml
+import json
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn.ensemble import RandomForestClassifier, GradientBoostingClassifier
+from sklearn.metrics import roc_auc_score
+from sklearn.model_selection import StratifiedKFold
+
+try:
+    import elapid
+    HAS_ELAPID = True
+    logger.info("elapid disponivel para modelagem MaxEnt.")
+except ImportError:
+    HAS_ELAPID = False
+    logger.warning("elapid nao instalado (MaxEnt). Instale com: pip install elapid")
+
+
+def load_params(path: str) -> dict:
+    try:
+        with open(path) as f:
+            return yaml.safe_load(f)
+    except FileNotFoundError:
+        logger.error(
+            "Arquivo de parametros nao encontrado: %s\n  Causa provavel: arquivo nao gerado pelo passo anterior.\n  Verifique a saida de: species-distribution-modeling (preparacao de parametros)\n  Skill anterior: species-distribution-modeling",
+            path,
+        )
+        sys.exit(1)
+    except yaml.YAMLError as e:
+        logger.error(
+            "Falha ao analisar YAML '%s': %s\n  Causa provavel: YAML malformado ou encoding incorreto.\n  Skill anterior: species-distribution-modeling",
+            path, e,
+        )
+        sys.exit(1)
+
+
+def load_data(p: dict) -> tuple:
+    data_path = "data/processed/points_with_env.csv"
+    predictors_path = "outputs/selected_predictors.txt"
+
+    try:
+        pts = pd.read_csv(data_path)
+    except FileNotFoundError:
+        logger.error(
+            "Arquivo de dados nao encontrado: %s\n  Causa provavel: arquivo nao gerado pelo passo anterior.\n  Esperado como saida de: ecological-data-foundation (clean_occurrences)\n  Skill anterior: ecological-data-foundation",
+            data_path,
+        )
+        raise
+    except Exception as e:
+        logger.error(
+            "Falha ao carregar dados de pontos '%s': %s\n  Skill anterior: ecological-data-foundation",
+            data_path, e,
+        )
+        raise
+
+    try:
+        predictors = open(predictors_path).read().strip().split("\n")
+    except FileNotFoundError:
+        logger.error(
+            "Arquivo de preditores nao encontrado: %s\n  Causa provavel: etapa de selecao de variaveis nao concluida.\n  Skill anterior: species-distribution-modeling",
+            predictors_path,
+        )
+        raise
+
+    predictors = [pr for pr in predictors if pr in pts.columns]
+
+    if not predictors:
+        logger.error(
+            "Nenhum preditor valido encontrado em '%s' que coincida com as colunas de '%s'.\n  Causa provavel: nomes de colunas divergem entre os arquivos.\n  Skill anterior: species-distribution-modeling",
+            predictors_path, data_path,
+        )
+        raise ValueError("No valid predictors found.")
+
+    logger.info("Preditores carregados (%d): %s", len(predictors), predictors)
+
+    if "pa" in pts.columns:
+        y = pts["pa"].values
+        log_decision("response_col", "pa", "coluna 'pa' encontrada nos dados")
+    elif "presence" in pts.columns:
+        y = pts["presence"].values
+        log_decision("response_col", "presence", "coluna 'presence' usada como alternativa")
+    else:
+        logger.error(
+            "Nenhuma coluna de resposta encontrada nos dados. Esperado: 'pa' ou 'presence'.\n  Causa provavel: dados nao preparados pelo script de background.\n  Skill anterior: ecological-data-foundation",
+        )
+        raise KeyError("Missing response column 'pa' or 'presence'.")
+
+    X = pts[predictors].values
+
+    n_presence = int(y.sum())
+    n_bg       = int((y == 0).sum())
+    logger.info("Registros carregados — Presencas: %d | Background: %d", n_presence, n_bg)
+
+    if n_presence < 10:
+        logger.warning(
+            "Poucos registros de presenca (%d). SDM pode ser instavel. Recomendado: >= 30.",
+            n_presence,
+        )
+
+    return X, y, predictors
+
+
+def spatial_cv_splits(pts_df, fold_col="cv_fold"):
+    folds = pts_df[fold_col].unique()
+    for fold in sorted(folds):
+        test_idx  = pts_df.index[pts_df[fold_col] == fold].tolist()
+        train_idx = pts_df.index[pts_df[fold_col] != fold].tolist()
+        yield train_idx, test_idx
+
+
+def fit_rf(X_train, y_train, params: dict):
+    rf_p = params.get("hyperparameters", {}).get("random_forest", {})
+    n_trees       = rf_p.get("n_trees", 500)
+    min_node_size = rf_p.get("min_node_size", 5)
+    log_decision("rf_n_trees",       n_trees,       "numero de arvores do RF definido em params.yaml")
+    log_decision("rf_min_node_size", min_node_size, "tamanho minimo de no do RF definido em params.yaml")
+    try:
+        clf = RandomForestClassifier(
+            n_estimators=n_trees,
+            min_samples_leaf=min_node_size,
+            random_state=params["random_seeds"]["global"],
+            n_jobs=-1,
+        )
+        clf.fit(X_train, y_train)
+        return clf
+    except Exception as e:
+        logger.error(
+            "Falha ao ajustar RandomForest: %s\n  Causa provavel: dados de treinamento invalidos ou parametros incompativeis.\n  Skill anterior: species-distribution-modeling",
+            e,
+        )
+        raise
+
+
+def fit_brt(X_train, y_train, params: dict):
+    brt_p = params.get("hyperparameters", {}).get("brt", {})
+    n_trees       = brt_p.get("n_trees", [500])[0]
+    learning_rate = brt_p.get("learning_rate", [0.01])[0]
+    tree_depth    = brt_p.get("tree_complexity", [3])[0]
+    bag_fraction  = brt_p.get("bag_fraction", 0.75)
+    log_decision("brt_n_trees",       n_trees,       "numero de arvores do BRT definido em params.yaml")
+    log_decision("brt_learning_rate", learning_rate, "taxa de aprendizado do BRT definida em params.yaml")
+    log_decision("brt_tree_depth",    tree_depth,    "profundidade das arvores do BRT definida em params.yaml")
+    log_decision("brt_bag_fraction",  bag_fraction,  "fracao de subamostras por arvore (BRT) definida em params.yaml")
+    try:
+        clf = GradientBoostingClassifier(
+            n_estimators=n_trees,
+            learning_rate=learning_rate,
+            max_depth=tree_depth,
+            subsample=bag_fraction,
+            random_state=params["random_seeds"]["global"],
+        )
+        clf.fit(X_train, y_train)
+        return clf
+    except Exception as e:
+        logger.error(
+            "Falha ao ajustar GradientBoosting (BRT): %s\n  Causa provavel: dados de treinamento invalidos ou parametros incompativeis.\n  Skill anterior: species-distribution-modeling",
+            e,
+        )
+        raise
+
+
+def main():
+    logger.info("Script: sdm_pipeline.py | Skill: %s", SKILL_NAME)
+
+    params_file = sys.argv[1] if len(sys.argv) > 1 else "params.yaml"
+    output_dir  = Path(sys.argv[2]) if len(sys.argv) > 2 else Path("outputs/sdm")
+
+    logger.info("Params file : %s", params_file)
+    logger.info("Output dir  : %s", output_dir)
+
+    # Input precondition check
+    if not Path(params_file).exists():
+        logger.error(
+            "Input nao encontrado: %s\n  Causa provavel: arquivo nao gerado pelo passo anterior.\n  Verifique a saida de: species-distribution-modeling (preparacao de parametros)\n  Skill anterior: species-distribution-modeling",
+            params_file,
+        )
+        sys.exit(1)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    logger.info("Diretorio de saida pronto: %s", output_dir)
+
+    log_step(1, "Carregar parametros YAML")
+    p = load_params(params_file)
+
+    np.random.seed(p["random_seeds"]["global"])
+    log_decision("random_seed", p["random_seeds"]["global"], "semente global definida em params.yaml para reprodutibilidade")
+    log_decision("algorithms",  p["modeling"]["algorithms"],  "algoritmos definidos em params.yaml")
+    log_decision("cv_folds",    p["modeling"]["cv_folds"],    "numero de folds definido em params.yaml")
+
+    logger.info("Pipeline SDM | Algoritmos: %s", p["modeling"]["algorithms"])
+
+    log_step(2, "Carregar dados de ocorrencia e preditores")
+    try:
+        X, y, predictors = load_data(p)
+    except FileNotFoundError as e:
+        logger.error(
+            "Arquivo de entrada nao encontrado: %s\n  Esperado como saida de: ecological-data-foundation\n  Verifique se o passo anterior foi concluido.",
+            e,
+        )
+        logger.info("Scaffold carregado. Adicione o carregamento de dados para seu estudo.")
+        return
+    except Exception as e:
+        logger.error(
+            "Nao foi possivel carregar dados: %s\n  Scaffold carregado. Adicione o carregamento de dados para seu estudo.",
+            e,
+        )
+        return
+
+    log_step(3, "Executar validacao cruzada estratificada por fold")
+    log_decision(
+        "cv_method", "StratifiedKFold",
+        "fallback para k-fold estratificado quando coluna cv_fold nao esta presente",
+    )
+    skf = StratifiedKFold(
+        n_splits=p["modeling"]["cv_folds"],
+        shuffle=True,
+        random_state=p["random_seeds"]["global"],
+    )
+    auc_rf, auc_brt = [], []
+
+    try:
+        for fold, (train_idx, test_idx) in enumerate(skf.split(X, y)):
+            X_tr, X_te = X[train_idx], X[test_idx]
+            y_tr, y_te = y[train_idx], y[test_idx]
+
+            if "random_forest" in p["modeling"]["algorithms"]:
+                rf = fit_rf(X_tr, y_tr, p)
+                fold_auc = roc_auc_score(y_te, rf.predict_proba(X_te)[:, 1])
+                auc_rf.append(fold_auc)
+                logger.info("Fold %d | RF AUC = %.3f", fold + 1, fold_auc)
+                if fold_auc < 0.7:
+                    logger.warning(
+                        "Fold %d: RF AUC baixo (%.3f). Verifique qualidade dos dados de background.",
+                        fold + 1, fold_auc,
+                    )
+
+            if "brt" in p["modeling"]["algorithms"]:
+                brt = fit_brt(X_tr, y_tr, p)
+                fold_auc_brt = roc_auc_score(y_te, brt.predict_proba(X_te)[:, 1])
+                auc_brt.append(fold_auc_brt)
+                logger.info("Fold %d | BRT AUC = %.3f", fold + 1, fold_auc_brt)
+                if fold_auc_brt < 0.7:
+                    logger.warning(
+                        "Fold %d: BRT AUC baixo (%.3f). Verifique qualidade dos dados de background.",
+                        fold + 1, fold_auc_brt,
+                    )
+    except Exception as e:
+        logger.error(
+            "Falha durante validacao cruzada: %s\n  Causa provavel: dados de treinamento invalidos, preditores com NaN, ou parametros incompativeis.\n  Skill anterior: species-distribution-modeling",
+            e,
+        )
+        raise
+
+    log_step(4, "Compilar e salvar metricas de desempenho")
+    results = {}
+    if auc_rf:
+        results["RandomForest"] = {"AUC_mean": float(np.mean(auc_rf)), "AUC_sd": float(np.std(auc_rf))}
+        logger.info("RandomForest — AUC medio: %.3f (+/- %.3f)", np.mean(auc_rf), np.std(auc_rf))
+    if auc_brt:
+        results["BRT"] = {"AUC_mean": float(np.mean(auc_brt)), "AUC_sd": float(np.std(auc_brt))}
+        logger.info("BRT — AUC medio: %.3f (+/- %.3f)", np.mean(auc_brt), np.std(auc_brt))
+
+    results_df = pd.DataFrame(results).T
+
+    try:
+        results_df.to_csv(output_dir / "cv_performance.csv")
+        logger.info("Gravado: %s", output_dir / "cv_performance.csv")
+    except OSError as e:
+        logger.error(
+            "Falha ao gravar cv_performance.csv em '%s': %s\n  Causa provavel: sem permissao de escrita no diretorio.\n  Skill anterior: species-distribution-modeling",
+            output_dir, e,
+        )
+        raise
+
+    logger.info("Desempenho de CV:\n%s", results_df.to_string())
+    logger.info("Saidas gravadas em: %s", output_dir)
+
+
+if __name__ == "__main__":
+    main()

package/skills/species-distribution-modeling/scripts/tune_maxnet.R

@@ -0,0 +1,344 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript tune_maxnet.R <points_with_env_csv> <output_dir> [rm_values] [fc_values]
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "species-distribution-modeling"
+.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)
+
+#
+# Arguments:
+#   points_with_env_csv : CSV with columns decimalLongitude, decimalLatitude + env variables
+#   output_dir          : Directory to write all outputs (created if absent)
+#   rm_values           : Optional comma-separated RM grid (default: "0.5,1,1.5,2,3,4,6")
+#   fc_values           : Optional comma-separated FC grid (default: "L,LQ,LQH,LQHP,LQHPT")
+#
+# Outputs:
+#   calibration_results.csv  — all 35 model combinations with metrics
+#   best_model_params.csv    — models selected by OR_AICc criterion
+#   calibration_plot.png     — delta_AICc × OR10 scatterplot
+#   best_maxnet.rds          — fitted maxnet model with best parameters
+
+suppressPackageStartupMessages(library(ENMeval))
+suppressPackageStartupMessages(library(terra))
+suppressPackageStartupMessages(library(dplyr))
+suppressPackageStartupMessages(library(ggplot2))
+
+# ── 1. Parse arguments ──────────────────────────────────────────────────────
+log_step(1, "Analisar argumentos da linha de comando")
+args <- commandArgs(trailingOnly = TRUE)
+
+if (length(args) < 2) {
+  # Defaults for interactive/test use
+  occ_csv    <- "tests/data/points_with_env.csv"
+  output_dir <- "output/sdm_calibration"
+  rm_vals    <- c(0.5, 1, 1.5, 2, 3, 4, 6)
+  fc_vals    <- c("L", "LQ", "LQH", "LQHP", "LQHPT")
+  log_warn("Menos de 2 argumentos. Usando valores padrao para teste interativo.")
+} else {
+  occ_csv    <- args[1]
+  output_dir <- args[2]
+  rm_vals    <- if (length(args) >= 3) as.numeric(strsplit(args[3], ",")[[1]]) else c(0.5, 1, 1.5, 2, 3, 4, 6)
+  fc_vals    <- if (length(args) >= 4) strsplit(args[4], ",")[[1]] else c("L", "LQ", "LQH", "LQHP", "LQHPT")
+}
+
+log_info("Script: tune_maxnet.R | Skill: %s", SKILL_NAME)
+log_info("OCC CSV    : %s", occ_csv)
+log_info("Output dir : %s", output_dir)
+
+# ── Input precondition check ──────────────────────────────────────────────────
+if (!file.exists(occ_csv)) {
+  log_error(
+    "Input nao encontrado: %s\nCausa provavel: arquivo nao gerado pelo passo anterior.\nVerifique a saida de: ecological-data-foundation (clean_occurrences)\nSkill anterior: ecological-data-foundation",
+    occ_csv
+  )
+  stop("Missing: ", occ_csv)
+}
+
+# ── 2. Create output directory ───────────────────────────────────────────────
+log_step(2, "Criar diretorio de saida")
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+log_info("Diretorio de saida pronto: %s", output_dir)
+
+log_decision("rm_vals", paste(rm_vals, collapse = ","), "grade de multiplicadores de regularizacao para busca em grade MaxEnt")
+log_decision("fc_vals", paste(fc_vals, collapse = ","), "grade de classes de features para busca em grade MaxEnt")
+log_decision("total_models", length(rm_vals) * length(fc_vals), "numero total de combinacoes RM x FC")
+
+# ── 3. Load occurrence data ──────────────────────────────────────────────────
+log_step(3, "Carregar dados de ocorrencia com variaveis ambientais")
+tryCatch({
+  occ_data <- read.csv(occ_csv)
+  log_info("Registros carregados: %d | Colunas: %d", nrow(occ_data), ncol(occ_data))
+}, error = function(e) {
+  log_error(
+    "Falha ao ler CSV de ocorrencias '%s': %s\nCausa provavel: arquivo corrompido ou formato invalido.\nVerifique: %s\nSkill anterior: ecological-data-foundation",
+    occ_csv, conditionMessage(e), occ_csv
+  )
+  stop(e)
+})
+
+# Identify coordinate columns (standard names)
+lon_col <- intersect(c("decimalLongitude", "longitude", "lon", "x"), names(occ_data))[1]
+lat_col <- intersect(c("decimalLatitude",  "latitude",  "lat", "y"), names(occ_data))[1]
+
+if (is.na(lon_col) || is.na(lat_col)) {
+  log_error(
+    "Colunas de coordenadas nao encontradas.\nEsperadas: decimalLongitude/decimalLatitude (ou longitude/latitude, lon/lat, x/y).\nColunas presentes: %s\nCausa provavel: CSV nao processado por clean_occurrences.\nSkill anterior: ecological-data-foundation",
+    paste(names(occ_data), collapse = ", ")
+  )
+  stop("Cannot find coordinate columns. Expected: decimalLongitude/decimalLatitude")
+}
+
+log_info("Coluna de longitude: '%s' | Coluna de latitude: '%s'", lon_col, lat_col)
+occ_pts <- occ_data[, c(lon_col, lat_col)]
+names(occ_pts) <- c("x", "y")
+
+# Environmental predictor columns = everything except coordinates and species metadata
+meta_cols <- c(lon_col, lat_col, "species", "scientificName", "gbifID",
+               "occurrenceID", "datasetKey")
+env_cols  <- setdiff(names(occ_data), meta_cols)
+
+log_info("Registros de ocorrencia: %d", nrow(occ_pts))
+log_info("Variaveis ambientais (%d): %s", length(env_cols), paste(env_cols, collapse = ", "))
+
+if (nrow(occ_pts) < 10) {
+  log_error(
+    "Registros de ocorrencia insuficientes (%d). Minimo requerido: 10.\nCausa provavel: filtragem excessiva em clean_occurrences ou especie com distribuicao muito restrita.\nSkill anterior: ecological-data-foundation",
+    nrow(occ_pts)
+  )
+  stop("Too few occurrences (", nrow(occ_pts), ") for calibration. Minimum required: 10")
+}
+
+if (nrow(occ_pts) < 30) {
+  log_warn(
+    "Poucos registros de ocorrencia (%d). Resultados de calibracao podem ser instáveis. Recomendado: >= 30.",
+    nrow(occ_pts)
+  )
+}
+
+# ── 4. Build environmental SpatRaster from occurrence columns ────────────────
+log_step(4, "Preparar dados ambientais e pontos de background")
+# When a raster stack is not provided, construct a mock raster for ENMeval
+# using the env values in the CSV. In full use, load a real raster stack instead.
+log_warn("Construindo background a partir de valores env no CSV. Para uso em producao, use um SpatRaster real.")
+
+env_mat <- as.matrix(occ_data[, env_cols])
+
+# Background: if CSV has a 'background' column flagging bg points, use them;
+# otherwise use a random sample of all non-occurrence rows.
+if ("type" %in% names(occ_data)) {
+  bg_idx  <- occ_data$type == "background"
+  bg_pts  <- occ_data[bg_idx, c(lon_col, lat_col)]
+  bg_env  <- occ_data[bg_idx, env_cols]
+  occ_env <- occ_data[!bg_idx, env_cols]
+  log_info("Coluna 'type' encontrada. Usando %d pontos de background definidos.", sum(bg_idx))
+  log_decision("background_source", "type column", "coluna 'type' presente no CSV define pontos de background")
+} else {
+  # Use all points as both occurrences and generate background by jittering
+  # In production: load bg from a proper background CSV
+  log_warn("Coluna 'type' ausente. Gerando pseudo-background por jitter. Use um CSV de background real em producao.")
+  log_decision("background_source", "jitter", "coluna 'type' ausente; pseudo-background gerado por jitter aleatorio")
+  set.seed(42)
+  n_bg   <- min(10000, nrow(occ_data) * 10)
+  bg_pts <- data.frame(
+    x = occ_pts$x + runif(n_bg, -2, 2),
+    y = occ_pts$y + runif(n_bg, -2, 2)
+  )
+  bg_env  <- occ_data[sample(nrow(occ_data), n_bg, replace = TRUE), env_cols]
+  occ_env <- occ_data[, env_cols]
+  log_info("Pseudo-background gerado: %d pontos", n_bg)
+}
+
+names(bg_pts) <- c("x", "y")
+
+# ── 5. Run ENMeval grid search ───────────────────────────────────────────────
+log_step(5, "Executar busca em grade ENMeval (MaxNet)")
+log_info("Valores de RM  : %s", paste(rm_vals, collapse = ", "))
+log_info("Valores de FC  : %s", paste(fc_vals, collapse = ", "))
+log_info("Total de modelos: %d", length(rm_vals) * length(fc_vals))
+log_decision(
+  "partitions", "block",
+  "particao espacial por blocos geograficos — evita inflacao de AUC por autocorrelacao espacial"
+)
+
+# ENMevaluate with maxnet and spatial block CV
+# block partitioning divides geographic space into quadrants for spatial CV
+eval_out <- tryCatch({
+  ENMevaluate(
+    occs       = occ_pts,
+    envs       = NULL,          # using occs.testing below when envs is NULL
+    bg         = bg_pts,
+    occs.testing = NULL,
+    algorithm  = "maxnet",
+    partitions = "block",       # spatial cross-validation — avoids autocorrelation inflation
+    tune.args  = list(
+      rm = rm_vals,
+      fc = fc_vals
+    ),
+    other.settings = list(
+      abs.auc.diff = FALSE
+    ),
+    occs.grp   = NULL,
+    bg.grp     = NULL
+  )
+}, error = function(e) {
+  log_error(
+    "Falha em ENMevaluate: %s\nCausa provavel: dados ambientais insuficientes, pacote ENMeval nao instalado, ou pontos de ocorrencia fora do extent dos preditores.\nVerifique: install.packages('ENMeval') e a qualidade dos dados de entrada.\nSkill anterior: ecological-data-foundation",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+log_info("Calibracao ENMeval concluida.")
+
+# ── 6. Extract and process results table ─────────────────────────────────────
+log_step(6, "Extrair e processar tabela de resultados da calibracao")
+tryCatch({
+  res <- eval.results(eval_out)
+
+  # Compute delta_AICc relative to the best (lowest AICc) model
+  res$delta.AICc <- res$AICc - min(res$AICc, na.rm = TRUE)
+
+  # Rename for clarity
+  res <- res %>%
+    rename(
+      OR10 = or.10p.avg,
+      AUC_train = auc.train,
+      AUC_val   = auc.val.avg
+    ) %>%
+    arrange(delta.AICc)
+
+  # Save full calibration table
+  calib_path <- file.path(output_dir, "calibration_results.csv")
+  write.csv(res, calib_path, row.names = FALSE)
+  log_info("Gravado: %s", calib_path)
+}, error = function(e) {
+  log_error(
+    "Falha ao extrair resultados da calibracao: %s\nCausa provavel: objeto ENMeval com estrutura inesperada ou colunas renomeadas na versao do pacote.\nVerifique a versao do ENMeval instalada.\nSkill anterior: species-distribution-modeling",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 7. Select best models by OR_AICc criterion ───────────────────────────────
+log_step(7, "Selecionar melhores modelos pelo criterio OR_AICc")
+# Rule: OR10 <= 0.15 (allows slight tolerance above 0.10 expected)
+#       AND delta_AICc < 2 (equivalent models by Burnham & Anderson)
+or_threshold   <- 0.15
+aicc_threshold <- 2
+
+log_decision("or_threshold",   or_threshold,   "tolerancia acima de 0.10 conforme Anderson et al. 2010")
+log_decision("aicc_threshold", aicc_threshold, "modelos equivalentes por Burnham & Anderson 2002 (delta_AICc < 2)")
+
+best_models <- tryCatch({
+  bm <- res %>%
+    filter(OR10 <= or_threshold, delta.AICc < aicc_threshold) %>%
+    arrange(OR10, delta.AICc)
+
+  if (nrow(bm) == 0) {
+    # Fallback: relax OR threshold and take AICc-best model
+    log_warn(
+      "Nenhum modelo atende OR10 <= %.2f E delta_AICc < %.1f. Usando modelo com menor AICc como fallback.",
+      or_threshold, aicc_threshold
+    )
+    log_decision(
+      "selection_fallback", "aicc_best",
+      "nenhum modelo no quadrante ideal; selecionado o melhor por AICc para prosseguir"
+    )
+    bm <- res[1, ]
+  } else {
+    log_info("%d modelo(s) atendem ao criterio OR_AICc.", nrow(bm))
+  }
+  bm
+}, error = function(e) {
+  log_error(
+    "Falha ao selecionar melhores modelos: %s\nCausa provavel: colunas OR10 ou AICc ausentes na tabela de resultados.\nSkill anterior: species-distribution-modeling",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+best_path <- file.path(output_dir, "best_model_params.csv")
+write.csv(best_models, best_path, row.names = FALSE)
+log_info("Gravado: %s", best_path)
+log_info("Melhores modelos (primeiras linhas):")
+message(capture.output(print(best_models[, c("tune.args.rm", "tune.args.fc", "OR10", "AICc", "delta.AICc")])))
+
+# ── 8. Calibration plot ───────────────────────────────────────────────────────
+log_step(8, "Gerar grafico de calibracao (delta_AICc x OR10)")
+tryCatch({
+  p <- ggplot(res, aes(x = delta.AICc, y = OR10,
+                        colour = tune.args.fc, size = tune.args.rm)) +
+    geom_point(alpha = 0.8) +
+    geom_hline(yintercept = or_threshold, linetype = "dashed", colour = "red",
+               linewidth = 0.7) +
+    geom_vline(xintercept = aicc_threshold, linetype = "dashed", colour = "blue",
+               linewidth = 0.7) +
+    annotate("text", x = aicc_threshold + 0.5, y = max(res$OR10) * 0.95,
+             label = "delta_AICc = 2", colour = "blue", hjust = 0, size = 3) +
+    annotate("text", x = max(res$delta.AICc) * 0.7, y = or_threshold + 0.005,
+             label = "OR10 = 0.15", colour = "red", size = 3) +
+    labs(
+      title    = "MaxEnt Calibration: OR10 vs delta_AICc",
+      subtitle = "Lower-left quadrant = best models (low omission + parsimonious)",
+      x        = "delta AICc (relative to best model)",
+      y        = "OR10 (omission rate at 10% training threshold)",
+      colour   = "Feature Class",
+      size     = "Regularization Multiplier"
+    ) +
+    theme_bw(base_size = 12)
+
+  plot_path <- file.path(output_dir, "calibration_plot.png")
+  ggsave(plot_path, p, width = 10, height = 7, dpi = 150)
+  log_info("Gravado: %s", plot_path)
+}, error = function(e) {
+  log_error(
+    "Falha ao gerar grafico de calibracao: %s\nCausa provavel: pacote ggplot2 nao instalado ou colunas ausentes na tabela de resultados.\nVerifique: install.packages('ggplot2')\nSkill anterior: species-distribution-modeling",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 9. Fit final model with best parameters ────────────────────────────────
+log_step(9, "Ajustar modelo final com os melhores parametros")
+best_rm <- best_models$tune.args.rm[1]
+best_fc <- best_models$tune.args.fc[1]
+log_info("Ajustando modelo final: RM = %s | FC = %s", best_rm, best_fc)
+log_decision("final_rm", best_rm, "RM do modelo de melhor desempenho no criterio OR_AICc")
+log_decision("final_fc", best_fc, "FC do modelo de melhor desempenho no criterio OR_AICc")
+
+tryCatch({
+  # Retrieve the fitted model object from ENMeval results
+  best_idx <- which(res$tune.args.rm == best_rm & res$tune.args.fc == best_fc)[1]
+  best_model_obj <- eval.models(eval_out)[[best_idx]]
+
+  # Save as RDS for downstream projection
+  rds_path <- file.path(output_dir, "best_maxnet.rds")
+  saveRDS(best_model_obj, rds_path)
+  log_info("Gravado: %s", rds_path)
+}, error = function(e) {
+  log_error(
+    "Falha ao ajustar ou salvar modelo final: %s\nCausa provavel: indice do modelo nao encontrado nos resultados ENMeval ou erro ao serializar o objeto.\nSkill anterior: species-distribution-modeling",
+    conditionMessage(e)
+  )
+  stop(e)
+})
+
+# ── 10. Summary ──────────────────────────────────────────────────────────────
+log_step(10, "Exibir resumo da calibracao")
+log_info("========== RESUMO DA CALIBRACAO ==========")
+log_info("Modelos avaliados      : %d", nrow(res))
+log_info("Modelos OR_AICc-ok     : %d", nrow(best_models))
+log_info("RM selecionado         : %s", best_rm)
+log_info("FC selecionado         : %s", best_fc)
+log_info("Melhor OR10            : %.3f", best_models$OR10[1])
+log_info("Melhor AUC (val)       : %.3f", best_models$AUC_val[1])
+log_info("Melhor delta_AICc      : %.3f", best_models$delta.AICc[1])
+log_info("==========================================")