flood-confidence

Capa de confianza calibrada para pronósticos de inundación de modelos hidrológicos open-source ya existentes. Convierte un "caudal pronosticado" crudo en una decisión informada: P(se supera el umbral de inundación) calibrada + intervalo de incertidumbre + ECE medido antes/después.

Problema

Los modelos SOTA de pronóstico de inundación (HydroGAT, LarNO, neuralhydrology) son cajas negras: dan una cifra de caudal sin decir cuánto confiar en ella. Eso bloquea decisiones de seguridad pública (evacuación). Los papers 2607.23237 (Trustworthy Flood Prediction, IJCAI 2026) y 2607.23983 (HydroAgent) lo declaran explícitamente. La capa de confianza calibrada reutilizable no existe como OSS (verificado: 0 repos en GitHub para flood forecast confidence calibration, trustworthy flood prediction tool y flood prediction uncertainty quantification python).

Qué hace

• Calibración de probabilidad (Platt / isotonic) sobre el score crudo del modelo.
• Intervalos conformales (split conformal, cobertura 1−α configurable).
• ECE (Expected Calibration Error, Guo et al. 2017) antes y después de calibrar — el delta se reporta SIEMPRE; si la calibración empeora el ECE, emite aviso (KI-1).
• Salida no engañosa: nunca un score suelto; siempre método + umbral + intervalo
  • ECE + n de holdout.

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

Instalación

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[testing]"

Uso

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

Opciones clave:

Opción	Default	Descripción
--method	platt	platt | isotonic | conformal
--threshold	0.9	percentil local del evento de inundación (p90)
--alpha	0.10	nivel de incertidumbre conformal (cobertura 90%)
--min-holdout	300	mínimo de días de holdout para emitir ECE fiable (AC-9)
--site	unknown	identificador de estación (solo reporte)

Entrada: CSV o JSON con columnas date,value (pronóstico y observado por separado).

Ejemplo de salida (método platt):

{
  "site": "01646500",
  "forecast": 7257.3,
  "threshold": 28640.0,
  "prob_exceed": 0.043,
  "interval_low": null,
  "interval_high": null,
  "alpha": 0.1,
  "method": "platt",
  "ece_before": 0.186,
  "ece_after": 0.027,
  "n_holdout": 329,
  "n_train": 767,
  "coverage_empirical": null,
  "warning": null
}

Datos

Caudal diario real vía USGS NWIS (dominio público, sin auth). Los datos completos no se commitean al repo; los tests usan un subconjunto cacheado en tests/data/. El fetch en vivo vive detrás de @pytest.mark.slow.

Tests

pytest -m "not slow"   # fast: 49 tests, sin red, determinista
pytest -m slow         # fetch USGS en vivo (skip sin red)
pytest --cov=flood_conf  # cobertura medida

Research

Tesis del problema, gap verificado (total_counts reales), auditoría del competidor adyacente cacd-flood y limitaciones en RESEARCH.md.

Licencia

AGPL-3.0-or-later — Copyright (C) 2026 Pedro Sordo Martínez <amurlaniakea@gmail.com>