Retention Investment Prioritizer

CASSINI Space for Water hackathon MVP for ranking where additional flood-retention capacity should be investigated first.

The current demo focuses on the Nysa Kłodzka basin and replays Storm Boris using Copernicus, CEMS/GloFAS, IMGW, Copernicus EMS, local case files, and rough cost priors. It is a screening and investment-prioritisation tool, not engineering-grade hydrology and not a reservoir design package.

Quick Start

Fastest option, using the already generated dashboard:

python3 main.py

The launcher serves the dashboard at:

http://127.0.0.1:8000/

Recommended clean setup:

bash scripts/setup_venv.sh
source .venv/bin/activate
python main.py

Useful launcher options:

python3 main.py --no-browser        # do not open a browser automatically
python3 main.py --port 8080         # prefer another local port
python3 main.py --rebuild           # rerun the ranking and rebuild the dashboard
python3 main.py --check             # verify that the dashboard exists

Manual setup, without the helper script:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python main.py

Current Demo Result

For the calibrated Storm Boris replay, the top candidate is Kamieniec Ząbkowicki planned reservoir corridor.

The generated ranking estimates about 47.6% modelled risk reduction in the affected downstream corridor, 12 protected settlements, 153,500 protected population in the screening model, a 2.64 effect/cost proxy, and 96.5% top-candidate stability under coarse MVP uncertainty tests.

These values support the product claim: the tool helps water authorities choose where to spend the next feasibility and planning money first. They do not prove that a reservoir is permitted, engineered, or construction-ready.

What It Does

• Builds a simplified river network for the Nysa Kłodzka.
• Converts event rainfall and wetness into runoff with an SCS-CN-style model.
• Routes runoff through existing and virtual retention capacity.
• Estimates screening risk from peak/volume exceedance and downstream exposure.
• Ranks candidate retention corridors by risk reduction, protected settlements, population/assets, rough cost, and oversize penalties.
• Generates CSV outputs and a bilingual jury dashboard.

Data Sources

The current pipeline uses:

• Copernicus CDS ERA5-Land precipitation per model node.
• CEMS/GloFAS discharge and root-zone soil-wetness context.
• IMGW observed September 2024 hydrology and precipitation references.
• Copernicus EMSR756 flood-mapping products.
• OpenStreetMap river display geometry.
• Local CASSINI case files and provided raw measurements.
• Urząd Statystyczny spreadsheet priors for water context and rough cost framing.

See DATA_GUIDE.md for file locations, provenance notes, manual-download references, normalized schemas, and generated outputs.

Common Commands

Run the calibrated ranking:

PYTHONPATH=src python -m flood_decision.cli run-nysa-validation

Build the dashboard HTML:

PYTHONPATH=src python tools/build_jury_dashboard.py

Compare model signals with IMGW observations:

PYTHONPATH=src python -m flood_decision.cli compare-model-imgw

Analyze top-candidate stability:

PYTHONPATH=src python -m flood_decision.cli analyze-uncertainty \
  --network data/fixtures/nysa_klodzka_network_calibrated.json \
  --scenario data/fixtures/copernicus_boris_scenario.json \
  --output-dir outputs/uncertainty_analysis_calibrated

Run tests (install pytest first if your environment does not include it):

python -m pip install pytest
python -m pytest

Repository Layout

src/flood_decision/      Python package: model, ranking, calibration, data adapters, CLI
tools/                   dashboard builder
scripts/                 setup and optional data helper scripts
tests/                   regression tests for the MVP model
data/fixtures/           reusable basin/scenario fixtures
data/cache/              processed or downloaded cache files
data/raw/                provided and manually downloaded raw inputs
outputs/                 generated rankings, validation outputs, dashboard, reports
cases/                   CASSINI case PDFs reviewed for the hackathon
DATA_GUIDE.md            dataset guide and provenance notes
AGENTS.md                detailed project briefing for future AI/Codex sessions
PRESENTATION_PLAN.md     short pitch outline and demo flow

Main Outputs

outputs/jury_dashboard/risk_dashboard.html
outputs/copernicus_validation_calibrated/ranking_best_by_node.csv
outputs/copernicus_validation_calibrated/model_vs_imgw.csv
outputs/uncertainty_analysis_calibrated/uncertainty_summary.csv
outputs/cems/nysa_node_flood_evidence.csv
outputs/statistical_priors/retention_cost_priors.json

Scope And Limits

This is deliberately a lightweight screening MVP. It is strongest for CASSINI disaster-risk and flood-retention prioritisation. Case 2 water-quality alerts and Case 3 land-cover / green-blue infrastructure suitability are present as extension paths, but they are not the core validated demo.

Important limits:

• same-event calibration shows the pipeline is wired correctly, not independent generalization;
• raw Sentinel-1 SAR is not yet processed into terrain-corrected before/after flood extents;
• raw Sentinel-2/Sentinel-3 imagery is not yet processed directly;
• land-cover and water-quality support currently expects normalized summaries;
• uncertainty is exposed as coarse ranking stability, not a full spatial or hydrological ensemble.

For deeper implementation notes, product framing, hackathon guardrails, and operational commands, see AGENTS.md.