Flood Risk Assessment Workflow for GR4H-Based Design Flood Analysis.
pyfloodrisk is a Python port of an R-based design flood workflow built
around the GR4H hourly rainfall-runoff model. It covers the full pipeline
from streamflow calibration through to design flood simulation:
- GR4H — hourly production/routing rainfall-runoff model
(
pyfloodrisk.gr4h). Events can be hot-started from an explicit state — both stores and the unit-hydrograph memory — so a design event continues a continuous run rather than starting from empty (GR4H.run_from_state,continuous_state_table). - Calibration — DREAM-based calibration against observed streamflow,
plus an optional robust re-calibration step that re-ranks the
behavioural posterior against design storm events
(
calibration,behavioural_posterior,robust_calibration). - Event delineation — baseflow separation and hydrologic event
extraction (peaks-over-threshold or local maxima), trimmed to the
largest events per year by peak flow or volume, 6 EY by default
(
hydro_event_pipeline). - Antecedent states — the model state the catchment was actually in
before its own large rainfall bursts, taken separately for each storm
duration, so a 72 h design storm starts from the wetness that precedes
72 h bursts (
rainfall_events,extract_initial_states_per_duration). This is used in place of design pre-burst rainfall or an adjusted initial loss. - Design rainfall — Bureau of Meteorology IFD downloads read as
issued (
ifd_table_from_bom_csv), reduced from point to catchment depths by the ARR 2019 areal reduction factors (ARR2019ARF), with ARR Data Hub temporal patterns (TemporalPatternLibrary). - Design storms — built from temporal-pattern increment files, at
any duration the file covers. The increment timestep is read from the
file rather than assumed, since ARR coarsens it as the storm
lengthens (
build_design_storm). - Design flood simulation — runs GR4H forward across every
combination of temporal pattern and antecedent state to produce a
design flood ensemble for one design storm
(
simulate_design_flood,run_demo_workflow). - Derived flood frequency analysis — a stratified Monte Carlo (joint
probability) framework in the ARR event-based form, with the sampled
initial loss replaced by a GR4H state vector drawn jointly from a
continuous run, producing a full flood frequency curve rather than a
single design event (
pyfloodrisk.dffa; see docs/dffa.md).
A bundled demo dataset — climate records, BoM IFD tables and ARR temporal-pattern increments for three stations (117002A, 303203 and 405214, 51–357 km²) — lets the whole workflow run end to end without any external data.
pip install pyfloodriskRequires Python 3.10 or newer.
Optional extra: pip install pyfloodrisk[copula] for the copula and KDE
methods of sampling the initial state distribution. The default
bootstrap method needs none of it.
Design flood ensemble for one design storm. duration_hours sets the
storm duration and the bursts the antecedent states are drawn from, so
the two cannot drift apart:
from pyfloodrisk import run_demo_workflow
results = run_demo_workflow(station="117002A", duration_hours=12)Derived flood frequency curve across the whole probability domain, with one state distribution per storm duration:
from pyfloodrisk import run_dffa
out = run_dffa(station="303203")
print(out["results"].summary())Both are demonstrations. Their design rainfalls are the station's
bundled BoM IFD download, areally reduced with ARR2019ARF. Design
rainfalls enter one way only — ifd_table_from_bom_csv, reading a
Bureau IFD download as it was issued. docs/dffa.md
sets out what to replace before the numbers mean anything, and
examples/dffa_demo.py builds the same analysis input by input.
pyfloodrisk.gr4h is a leaf: the model, its calibration, and the state
table it produces. The main package builds on it, and
pyfloodrisk.dffa builds on both — never the other way round.
MIT — see LICENSE.