Fenix

Posted on Aug 12

flood-confidence: capa de confianza calibrada para pronósticos de inundación (ECE 0.171 0.020)

#showdev #ai #python #opensource

flood-confidence: capa de confianza calibrada para pronósticos de inundación (ECE 0.171 → 0.020)

Los modelos de pronóstico de inundación son cajas negras: dan un caudal sin decir cuánto confiar en él. flood-confidence añade la capa que falta — calibración de probabilidad, intervalos conformales y ECE medido antes/después — sobre modelos OSS ya existentes. Código abierto, AGPL-3.0, 50 tests.

El problema

Los modelos de pronóstico de inundación de última generación (HydroGAT, LarNO, neuralhydrology) producen una cifra: "el río llegará a 3,2 metros". No dicen cuánto confiar en esa cifra.

Con decisiones de seguridad pública (evacuación, cierre de carreteras), "confía en mí" no es suficiente. Los papers lo declaran explícitamente:

Levinkopf, Morin & Goldman (IJCAI 2026) — "the 'black box' nature of state-of-the-art Deep Learning models creates a barrier to trust and accountability in high-stakes public safety decisions".
HydroAgent (2026) — "operational flood forecasting depends on tacit forecaster expertise that is difficult to formalize, audit, and transfer".

El gap (verificado, no asumido)

Busqué en GitHub con llamadas reales a la API antes de escribir una línea de código:

Query	total_count
`flood forecast confidence calibration`	0
`trustworthy flood prediction tool`	0
`flood prediction uncertainty quantification python`	0

El ecosistema de modelos existe (25 repos en topic:flood-forecasting). La capa de confianza calibrada reutilizable no existe como OSS. Ese es el hueco.

El repo adyacente más cercano (cacd-flood, del paper 2607.23237) es interpretabilidad conceptual (SHAP → conceptos), acoplado a un único LSTM, sin calibración de probabilidad ni intervalos conformales. Es XAI, no UQ — complementario, no competidor.

La solución

Un CLI en Python que convierte un pronóstico crudo en una decisión informada:

Calibración de probabilidad (Platt / isotonic) sobre el score del modelo → "P(se supera el umbral de inundación) calibrada".
Intervalos conformales (split conformal, cobertura 1−α configurable) → rango de incertidumbre con garantía estadística.
ECE (Expected Calibration Error, Guo et al. 2017) antes y después de calibrar — el delta se reporta siempre.

No entrena ningún modelo. Es la capa de confianza sobre modelos ya existentes.

pip install -e ".[testing]"

flood-conf calibrate --forecast fcast.csv --observed obs.csv \
  --threshold 0.9 --method platt --alpha 0.10 --out report.json

Salida (ejemplo real, estación Potomac):

{
  "site": "01646500",
  "forecast": 7257.3,
  "threshold": 28640.0,
  "prob_exceed": 0.043,
  "method": "platt",
  "ece_before": 0.186,
  "ece_after": 0.027,
  "n_holdout": 329,
  "warning": null
}

Cómo funciona

Split temporal estricto (70/30 por fecha, nunca aleatorio) — sin leakage entre calibración y evaluación.
Calibración sobre la parte temporal de entrenamiento; evaluación en holdout aislado.
ECE con 10 bins — si un bin tiene menos de 25 muestras, se declara "bajo fiabilidad".
Conformal split: cuantil 1−α del residuo relativo sobre la muestra de calibración; cobertura empírica vs nominal reportada.

Resultados (datos reales, USGS NWIS)

Caudal diario real de 5 estaciones USGS × 10 años (2010-2019), con split temporal. El modelo base del test es un baseline móvil de 30 días — la capa es agnóstica al modelo; HydroGAT/LarNO se integran como backends.

Estación	ECE sin calibrar	ECE tras Platt
Potomac (DC)	0.125	0.080
Waccamaw (NC)	0.199	0.036
American River (CA)	0.253	0.052
Kankakee (IN)	0.262	0.074
Willamette (OR)	0.171	0.020

Conformal (Willamette): cobertura empírica 0.940 vs nominal 0.90 — sobre-cobertura conservadora, esperada con muestra de calibración finita.

Limitaciones honestas

La calibración no siempre mejora el ECE. En el spike con otro baseline (climatología), Potomac empeoraba (0.082 → 0.217) por su alta tasa de eventos. Por eso el CLI reporta el delta SIEMPRE y emite aviso si empeora — no promete "ECE ≤ 0.05 universal".
El MVP valida la capa con baselines; los modelos SOTA (HydroGAT, neuralhydrology) son Fase 2.
Umbral de inundación local por estación (percentil configurable), no universal.
Detalles en KNOWN_ISSUES.md del repo.

Pruébalo

git clone https://github.com/amurlaniakea/flood-confidence.git
cd flood-confidence
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[testing]"
pytest -m "not slow"   # 49 tests, sin red

Los tests usan datos USGS cacheados (2 estaciones × 3 años) — deterministas, sin red. El fetch en vivo va detrás de pytest -m slow.

Stack

Python 3.10+, scikit-learn (Platt/isotonic), numpy (conformal/ECE), Typer (CLI), pytest. Sin torch, sin GPU. Datos: USGS NWIS (dominio público).

DEV Community