skyan1002/flash-flood-benchmark

Flash Flood Benchmark — Interactive Data Portal (v1 map)

Looking for the paper-matched, agent-friendly release? See the new light-themed landing page [skyan1002/torrent-flash-flood-agent](https://huggingface.co/spaces/skyan1002/torrent-flash-flood-agent) and the updated dataset [skyan1002/flash-flood-benchmark-data](https://huggingface.co/datasets/skyan1002/flash-flood-benchmark-data) (L3 = 806 testbeds; conservative primary benchmark = 21 testbeds / 14 episodes / 21 gauges; boolean funnel flags + AGENTS.md + an annual L3-expansion pipeline). This portal is the original interactive map, kept for exploration.

A static web portal for exploring the CONUS Flash Flood Benchmark, with MRMS precipitation forcing, USGS streamflow hydrographs, CREST model output, per-watershed QC + flood-frequency metadata, and a downloadable data package per testbed.

Regenerate the portal data from the ds260603 benchmark with: `conda run -n rasterenv python ds260603/scripts/32export_portal.py`

Programmatic / CLI data access

The full L1–L3 data is published as an agent-friendly, CLI-queryable dataset: [skyan1002/flash-flood-benchmark-data](https://huggingface.co/datasets/skyan1002/flash-flood-benchmark-data). Query by level / US state / time range with curl + jq over a single manifest, then download via precomputed resolve_urls (or the hosted datasets-server /filter API). Example:

BASE=https://huggingface.co/datasets/skyan1002/flash-flood-benchmark-data/resolve/main
curl -sL "$BASE/manifest.jsonl" -o manifest.jsonl
jq -c 'select(.level=="L3" and .primary_state_abbrev=="TX" and .is_strict_flash_flood==true
  and .begin_date>="2025-07-01" and .begin_date<="2025-07-31")' manifest.jsonl

Live demo

Open index.html in any browser. No server, no build step, no API keys required.

Local testing

# Option 1: Python built-in server (recommended — fetch() needs same-origin)
python3 -m http.server 8000
# then open http://localhost:8000

# Option 2: Node
npx serve .

Note: index.html uses fetch('data/*.json') to load data, which requires a server (even local). Opening file:// directly will fail due to CORS.

Hugging Face deployment

This folder is a self-contained Hugging Face Space (SDK: static).

# From the repo root
cd portal/
git init
git add .
git commit -m "initial portal"
# Push to your HF Space
git remote add hf https://huggingface.co/spaces/<your-user>/<space-name>
git push hf main

The README.md frontmatter (sdk: static) tells HF Spaces to serve index.html directly — no container, no Python, instant deploy.

Replacing mock data with real data

All data is loaded from data/*.json. The portal ships with synthetic mock data so it can be demonstrated without the full 62-episode dataset.

Step 1 — Generate real JSON from the case library

conda run -n raster_env python3 \
  /media/scratch/skyan/flash_flood_benchmark/ds_260510/scripts/export_portal_data.py \
  --out /media/scratch/skyan/flash_flood_benchmark/portal/data/

(This script does not exist yet — see schema below to write it.)

Step 2 — Verify

Open index.html in a browser. The orange MOCK DATA badge in the header will change to REAL DATA automatically once real JSON files are present (the loader checks for the _schema.replace_with_real key — real data files should omit it or set it to null).

Data file schemas

Full field definitions are in _schema.fields inside each JSON file.

Real data sources

Dataset hierarchy

NCEI Flash Flood Episode (62 total)
└── Benchmark Watershed / USGS Gage (1–6 per episode)
    ├── MRMS 2-min precipitation (spatial + basin-mean)
    ├── CREST MaxUnitStreamflow (spatial)
    ├── USGS instantaneous streamflow (15-min IV)
    └── Static watershed attributes
        (area, slope, forest cover, soil Ksat, stream density, …)

Technology stack

No build tools. No backend. No API keys. Pure static HTML/CSS/JS.

File structure

portal/
├── index.html                        # Single-page app
├── README.md                         # This file (also HF Space metadata)
└── data/
    ├── episodes.json                 # 62 episodes (mock: 6)
    ├── watersheds.json               # All benchmark gages (mock: 12)
    ├── qc_metadata.json              # 8-field QC per gage
    ├── static_attributes.json        # Watershed geomorphic attributes
    ├── timeseries_streamflow.json    # 5-min discharge per gage
    └── timeseries_precipitation.json # 10-min basin-mean MRMS precip per gage