Lindsay Millard

AI Flood Forecasting Is Arriving Fast — Here’s What a Practitioner Should Actually Check

2026-09-01T00:00:00+00:00

Two AI weather/flood tools crossed my feed within a few months of each other, both with genuinely impressive claims. DeepMind’s GraphCast could generate a full 10-day global forecast in under a minute on a retail-grade GPU, and was already competitive with the ECMWF’s operational model on several parameters. Google’s Flood Hub was forecasting river levels up to 7 days out — trained on public weather products, gauge records and satellite imagery, and claiming better skill than GloFAS, the widely-used global standard.

Neither of those claims surprises me, and I’d expect the state of the art to have moved further again by the time you’re reading this — this is a fast-moving space and anything I say about specific coverage or benchmark numbers will be stale within a year. What’s more durable is the set of questions worth asking before any of these get near an actual warning decision, and six years running DELFT-FEWS in Seqwater’s Flood Operations Centre shaped mine fairly specifically.

The questions that actually matter operationally

Where does the training data come from, and does that match your catchment? A global model trained predominantly on well-gauged basins in the northern hemisphere is not obviously going to perform the same way on a flashy, poorly-gauged Australian catchment with a completely different rainfall-runoff regime. “Trained on publicly available global weather products, river gauge measurements and satellite imagery” is a reasonable pedigree — it’s also a description that could apply equally well to a tool that performs brilliantly on the Mississippi and mediocrely on Norman Creek.

Is the skill claim benchmarked against events you’d actually care about? Beating GloFAS on aggregate skill metrics across a global gauge network is a real achievement. It’s a different question from “would this have given useful lead time on the February 2022 Brisbane event,” and the second question is the one that matters to an emergency manager deciding whether to trust a 7-day forecast enough to act on it.

Can you explain a bad forecast after the fact? Traditional hydraulic and hydrologic models have an interpretable failure mode — you can trace a bad forecast back to a rainfall input, a loss parameter, a routing assumption. A learned model’s failure mode is a black box until someone builds the tooling to open it. For a tool sitting upstream of an evacuation decision, “the model was wrong and we don’t fully know why” is a materially worse position to be in than “the model was wrong because the rainfall forecast busted,” even when both produce the same bad outcome.

What’s the actual deployment path into an operational system? A public API and a genuinely useful research result are not yet an operational flood forecasting system. Getting from “impressive demo” to “trusted input alongside DELFT-FEWS in a 24/7 flood operations centre” involves validation, redundancy, failure handling, and institutional trust-building that has nothing to do with the underlying model’s skill score — and everything to do with why operational forecasting systems tend to be conservative about adopting new components regardless of how good the headline numbers look.

Where I actually expect this to land first

Not, I think, as a wholesale replacement for physically-based operational systems in the near term — the explainability and validation gaps above are real, not just bureaucratic caution. More likely: as a genuinely valuable second opinion sitting alongside a traditional system, flagging situations worth a forecaster’s attention, or extending lead time in catchments where a physically-based model isn’t economically justified to build and maintain (which, for a country the size of Australia with the gauge density we actually have, is most of them).

That’s not a small role. A tool that gives a reasonable early warning on a catchment that currently has no forecasting capability at all is a genuine public safety improvement, even with all the caveats above attached. The risk isn’t AI forecasting existing — it’s AI forecasting arriving in an operational context faster than the validation and explainability tooling needed to trust it in a warning decision, which is a people-and-process problem as much as a modelling one.

AI Doesn’t Remove the Judgment Calls in Climate Science — It Just Makes Them Easier to Miss

2026-09-01T00:00:00+00:00

A paper crossed my feed this week benchmarking AI methods for precipitation downscaling over Australia — refining coarse climate model output down to a resolution useful for local planning. The finding that stuck with me: model performance rankings changed depending on which metric you evaluated against — total rainfall, spatial pattern, seasonal cycle, or long-term trend — and depending on which region of Australia you looked at. No model won across the board.

That’s not a failure. It’s the same lesson I landed on writing up pyraingen a few days ago, from a completely different angle: whether a tool is “good” isn’t a yes/no question. It depends what you actually need it to get right, at what scale, for what decision. A downscaling model tuned to reproduce seasonal totals isn’t automatically the right choice for someone who needs trend fidelity, and neither of those is wrong — they’re answering different questions.

The actual argument, which isn’t “AI bad”

I found that paper via a piece from the ARC Centre of Excellence for 21st Century Weather, by Taimoor Sohail (University of Melbourne) and Sanaa Hobeichi (UNSW Sydney) — “A wave of AI slop is coming for climate science”. The title reads more alarmist than the piece actually is. Their real argument is more precise than “AI produces bad science,” and worth taking on its own terms rather than the headline: every quantitative study already involves judgment calls — which data to include, how to handle missing values, what baseline to use, how to aggregate results. None of that is new to AI. What changes is that these choices become more numerous, less visible, and easier to propagate once a pipeline involves a trained model — sitting in a preprocessing step, a resampling choice, a default setting, discoverable only in a script, if documented at all.

Their own example is the honest version of this: quality-checking Antarctic Ocean salinity data with a neural network, they found a genuine result — seal-mounted sensors carry a consistent salty bias that survives existing quality control. Getting there required building a synthetic dataset from a high-resolution ocean model to reconcile ship, float and seal data collected in different places and seasons, and that process ended up duplicating somewhere between 7% and 17% of synthetic profiles, depending on source. They caught it, checked whether it distorted the result, and reported it themselves in the paper. That’s not a cautionary tale about a mistake — it’s what the discipline they’re arguing for actually looks like in practice.

The downscaling paper (the one I opened with) is their second example — and it turns out to be their own work: Sanaa Hobeichi is the corresponding author on both the paper and the piece that pointed me to it. Three ML models (a generative diffusion model, a vision transformer, and a recurrent neural network) were benchmarked against 24 regional climate model simulations across four fundamental rainfall characteristics — totals, spatial pattern, seasonal cycle, trend — using pre-defined minimum skill thresholds rather than just ranking whatever came out on top. All three ML models cleared the bar; so did 10 of the 24 RCMs. The paper doesn’t claim “AI wins” — it publishes the benchmark methodology and the raw model outputs alongside the RCM scores, specifically so other researchers can check the claim rather than take it on trust. That’s the provenance argument made concrete, not asserted as a slogan.

Where this lands for me

I don’t have a horse in the AI-and-climate-science-jobs debate — that’s not my field, and the piece raises a real point about timing that’s above my pay grade to weigh in on (they note this is landing in the same year as real job losses across the climate and environmental sector, which is its own separate problem). What I do have an opinion on, from direct experience this week, is the mechanics of the actual argument: judgment calls don’t disappear because a tool is faster. They just get easier to leave unexamined if nobody’s checking.

That’s the whole reason the pyraingen write-up turned into a bug report instead of a tutorial — I went in expecting to demonstrate a working pipeline, and instead found a dependency pin that breaks on install, a compiled binary that only runs on one platform, and a helper function whose own return shape doesn’t match its documentation. None of that was hidden maliciously. It’s exactly the “competent, well-intentioned team that didn’t happen to look closely enough at one particular step” failure mode Sohail and Hobeichi describe — just in a small open-source package instead of a published dataset. The Mann-Kendall self-check in the FFA post the same week was the same instinct from the other direction: before trusting a statistical test on anything real, prove it can tell a known answer from a known non-answer.

None of that requires being an AI researcher. It requires treating “the tool produced an output” and “the output is right for what I need” as two separate questions, and being willing to actually check the gap between them — logging what you tried, what you checked, and what you’re still unsure about, rather than presenting a clean result and hoping nobody asks. That’s a fairly old engineering habit wearing a new hat. AI just raises the stakes on keeping it, because it’s now cheap enough to skip.

References:

Sohail, T. & Hobeichi, S. (2026). A wave of AI slop is coming for climate science — the best defence is to retain and upskill our scientists. ARC Centre of Excellence for 21st Century Weather.
Applying a Standardized Benchmarking Framework to Evaluate AI Methods for Precipitation Downscaling over Australia. Artificial Intelligence for the Earth Systems, 5(1), 2026.

Areal Reduction Factors in Python — a Port of Tony Ladson’s ARR 2019 Method

2026-09-01T00:00:00+00:00

This post sat as a scaffold for a while. The short-duration Areal Reduction Factor equation was reconstructed, unverified, from a third-party spreadsheet vendor’s published formula; the long-duration equation, its 10 regional coefficient sets, and the interpolation logic for catchments under 10 km² and durations between 12 and 24 hours were all open TODOs, because the ARR 2019 PDF wasn’t directly accessible in the session that started it.

Finding Tony Ladson’s real, working ARR 2019 implementation resolved all of it. As with the rest of this series: the method and the explanation are his (ARR2019 – Areal Reduction Factors and Areal reduction factors – some edge cases); this is a Python port, checked against values he publishes directly, not a reconstruction from a secondary source this time.

What ARFs are for

Point rainfall — an IFD estimate at a single location — systematically overstates the rainfall actually falling, on average, over a large catchment at any given moment, because storm cells don’t cover a whole large catchment with uniform intensity simultaneously. An Areal Reduction Factor (always ≤ 1) corrects for this before a design rainfall depth goes into a URBS, RORB, or WBNM model. Skipping it on anything but a very small catchment systematically overestimates design flood peaks.

The two equations

Short duration (≤12h, one national equation):

import numpy as np

def arf_short(area, duration, aep):
    """ARR 2019 short-duration (<=720 min) Areal Reduction Factor."""
    a, b, c, d = 0.287, 0.265, 0.439, 0.36
    e, f, g = 0.00226, 0.226, 0.125
    h, i, j = 0.0141, -0.021, 0.213
    val = (1
           - a * (area**b - c * np.log10(duration)) * duration**(-d)
           + e * area**f * duration**g * (0.3 + np.log10(aep))
           + h * area**j * 10**(i * (1/1440) * (duration - 180)**2) * (0.3 + np.log10(aep)))
    return min(1.0, val)

This turned out to be identical to what the earlier, unverified draft had reconstructed from a third-party source — every coefficient matches Ladson’s real implementation exactly. Worth knowing, but not something I’d have wanted to publish on the strength of that source alone.

Long duration (24–168h, 10 climatological regions):

REGIONS = {
    'East Coast North':     (0.327,  0.241, 0.448, 0.36,  0.00096,   0.48,   -0.21,  0.012,   -0.0013),
    'Semi-arid Inland QLD': (0.159,  0.283, 0.25,  0.308, 7.3e-07,   1.0,     0.039, 0.0,      0.0),
    'Tasmania':              (0.0605, 0.347, 0.2,  0.283, 0.00076,   0.347,   0.0877,0.012,   -0.00033),
    'SW WA':                 (0.183,  0.259, 0.271,0.33,  3.845e-06, 0.41,    0.55,  0.00817, -0.00045),
    'Central NSW':           (0.265,  0.241, 0.505,0.321, 0.00056,   0.414,  -0.021, 0.015,   -0.00033),
    'SE Coast':               (0.06,   0.361, 0.0, 0.317, 8.11e-05,  0.651,   0.0,   0.0,      0.0),
    'Southern Semi-arid':     (0.254,  0.247, 0.403,0.351, 0.0013,    0.302,   0.058, 0.0,      0.0),
    'Southern Temperate':     (0.158,  0.276, 0.372,0.315, 0.000141,  0.41,    0.15,  0.01,    -0.0027),
    'Northern Coastal':       (0.326,  0.223, 0.442,0.323, 0.0013,    0.58,   -0.374, 0.013,   -0.0015),
    'Inland Arid':            (0.297,  0.234, 0.449,0.344, 0.00142,   0.216,   0.129, 0.0,      0.0),
}

def arf_long(area, duration, aep, region):
    """ARR 2019 long-duration (>=1440 min) Areal Reduction Factor."""
    a, b, c, d, e, f, g, h, i = REGIONS[region]
    val = (1
           - a * (area**b - c * np.log10(duration)) * duration**(-d)
           + e * area**f * duration**g * (0.3 + np.log10(aep))
           + h * 10**(i * area * duration / 1440) * (0.3 + np.log10(aep)))
    return min(1.0, val)

Ten regions, not the 11 an earlier version of this draft’s notes assumed — East Coast North, Semi-arid Inland QLD, Tasmania, SW WA, Central NSW, SE Coast, Southern Semi-arid, Southern Temperate, Northern Coastal, Inland Arid. Climatologically delineated, not by state.

Validated directly against Ladson’s own output

His ARF_edge_cases.R prints two specific values while investigating a real ARR 2019 quirk (below). Both checked here, not eyeballed:

v_short = arf_short(26, 720, 0.0005)
v_long = arf_long(26, 1440, 0.0005, 'Tasmania')

arf_short(26, 720, 0.0005)             = 0.9377527  (Ladson: 0.9377527)
arf_long(26, 1440, 0.0005, 'Tasmania')  = 0.9322746  (Ladson: 0.9322746)

Both match to 7 decimal places.

The part that isn’t obvious from the ARR text

Two things the standard doesn’t spell out clearly, that Ladson’s implementation handles explicitly:

Catchments under 10 km² — neither equation is evaluated directly. Instead, compute the ARF at 10 km² first, then interpolate down to the actual area:

arf_at_10km2 = arf_long(10, duration, aep, region)  # or arf_short, depending on duration
arf_value = 1 - 0.6614 * (1 - arf_at_10km2) * (area**0.4 - 1)

Duration between 12h and 24h — not simply linear interpolation on the ARF value at the target duration. Compute the short-duration ARF at exactly 12h and the long-duration ARF at exactly 24h (both at the target area, or at 10 km² first if area < 10 km²), then interpolate linearly between those two by how far the target duration sits between 720 and 1440 minutes:

arf_short_12 = arf_short(area, 720, aep)
arf_long_24 = arf_long(area, 1440, aep, region)
arf_value = arf_short_12 + (arf_long_24 - arf_short_12) * (duration - 720) / 720

Checking continuity across both boundaries confirms the interpolation is implemented correctly — no visible jump:

Continuity at 12h:  719 min -> 0.8523   720 min -> 0.8523   721 min -> 0.8524
Continuity at 24h:  1439 min -> 0.6254  1440 min -> 0.6256

A genuine ARR 2019 quirk, not a bug

For some catchments, the short-duration ARF at 12h is larger than the long-duration ARF at 24h — the ARF-vs-duration curve briefly slopes downhill right at the transition, rather than monotonically decreasing with duration the way intuition suggests:

26 km² Tasmanian catchment, AEP=0.05%:
  short-duration ARF at 12h = 0.9378
  long-duration ARF at 24h  = 0.9323
  short > long: True

Ladson documents this explicitly in his edge-cases post. It’s a real feature of the two equations meeting at the boundary, not an implementation error — worth knowing before assuming any ARF curve has to be monotonic.

ARF vs. duration, Tasmania region, AEP=0.5%, three catchment areas. Curves pass smoothly through the 12h and 24h boundaries. The 26 km² non-monotonic dip from above is real but subtle at this scale — the numeric check is the reliable way to see it, not the eye.

Full validity range

Raises rather than silently extrapolating outside ARR 2019’s stated range: area (0, 30000] km², AEP [0.005, 0.5] (0.5%–50% — not 0.05% as an earlier version of this draft’s notes assumed), duration [0, 10080] min. Short-duration equations are additionally invalid above 1000 km².

Usage: an ARF matrix for a design storm workflow

AREA, REGION = 850, 'East Coast North'
durations_h = [1, 2, 3, 6, 9, 12, 18, 24, 36, 48, 72]
aeps = [0.5, 0.2, 0.1, 0.05, 0.02, 0.01, 0.005]

for dh in durations_h:
    row = [arf(AREA, dh * 60, a, REGION) for a in aeps]
    print(dh, row)

Decreasing ARF at fixed duration as AEP gets rarer (more spatially concentrated storms need more reduction), increasing ARF at fixed AEP as duration lengthens (more spatially uniform) — both directions matching the physical intuition ARFs are meant to capture.

Limitations

ARF regions are climatological, not administrative — don’t assume a catchment near a region boundary behaves like the interior of either region without checking.
The equations assume a nominally circular/compact catchment shape typical of ARF derivation methodology; check ARR guidance before applying to strongly elongated catchments without adjustment.
Valid only within the stated ranges above — the function raises outside them rather than extrapolating.

Companion notebook: notebooks/03_arf_calculator/

Source: Ladson, A.R. (2020). ARR2019 – Areal Reduction Factors; Areal reduction factors – some edge cases. R source: gist.github.com/TonyLadson/fc870cf7ebfe39ea3d1a812bcc53c8fb, gist.github.com/TonyLadson/b8baac6c450fe7f32f5020eb496e8b62.

Reference: Ball, J., Babister, M., Nathan, R., Weeks, W., Weinmann, E., Retallick, M. and Testoni, I. (Editors) (2019). Australian Rainfall and Runoff: A Guide to Flood Estimation. Commonwealth of Australia. Book 2.

Screening ARR 2019 Temporal Patterns for Embedded Burst Errors

2026-09-01T00:00:00+00:00

The problem with embedded bursts

ARR 2019’s ensemble temporal patterns exist to represent the natural variability of how rainfall is distributed through a design storm — running all 10 patterns for a duration and taking the median (or a specific percentile) of the resulting flood peaks is standard practice, precisely because no single pattern is “correct” and the ensemble is the point.

Some patterns in the ARR temporal pattern set have a specific, recognisable error signature: two large rainfall bursts sitting suspiciously close to exactly 24 hours apart. That’s not a natural storm characteristic — real storms occasionally do produce multiple intense bursts, but a near-exact 24-hour separation between the two largest increments is a signature of how some patterns were extracted from historical pluviograph records, not a physical feature of the storm itself. Run that pattern through a runoff-routing model and you can get a double-peaked or artificially inflated flood hydrograph that has nothing to do with the catchment’s actual response — it’s an artefact of the input, not a result worth reporting.

Ladson (2021) documents this issue in more detail than covered here; treat the screening function below as a first-pass triage tool that tells you which patterns are worth a closer look, not a substitute for reading that paper if you’re screening patterns for something that matters.

The screening algorithm

import numpy as np

def screen_embedded_bursts(increments, timestep_hours, flag_window_hours=24, tolerance_hours=1.5):
    """Flag a temporal pattern for a suspected embedded-burst error.

    Finds the two largest rainfall increments in the pattern and checks
    whether they sit suspiciously close to `flag_window_hours` apart -- the
    signature of a duplication/extraction artefact rather than a genuine
    double-peaked storm. Screening heuristic, not a proof of error: see the
    note on Ladson (2021) above before treating a flag as definitive.

    Parameters
    ----------
    increments : array-like
        Rainfall depth increments at each timestep (any consistent unit).
    timestep_hours : float
        Duration of each increment, in hours.
    flag_window_hours : float
        The suspicious separation to screen for (default 24h).
    tolerance_hours : float
        How close to `flag_window_hours` counts as a match.
    """
    increments = np.asarray(increments, dtype=float)
    order = np.argsort(increments)[::-1]
    idx1, idx2 = order[0], order[1]
    time1, time2 = idx1 * timestep_hours, idx2 * timestep_hours
    separation = abs(time1 - time2)
    flagged = abs(separation - flag_window_hours) <= tolerance_hours
    return {
        "flagged": bool(flagged),
        "largest_increment": float(increments[idx1]),
        "largest_time_hr": float(time1),
        "second_increment": float(increments[idx2]),
        "second_time_hr": float(time2),
        "separation_hr": float(separation),
    }

Two known-answer test cases before trusting it on anything real:

rng = np.random.default_rng(0)

# A clean, single-peaked pattern -- should NOT flag
clean = np.abs(rng.normal(2, 1, 48))
clean[20] = 25.0
assert screen_embedded_bursts(clean, timestep_hours=1)["flagged"] is False

# A pattern with a duplicated burst 24h apart -- SHOULD flag
suspect = np.abs(rng.normal(2, 1, 48))
suspect[10] = 25.0
suspect[34] = 24.5
assert screen_embedded_bursts(suspect, timestep_hours=1)["flagged"] is True

Both pass.

Visualisation: suspect versus clean patterns

Left: a single dominant burst, not flagged. Right: two comparably large bursts exactly 24 hours apart — flagged for manual review. Synthetic examples built to illustrate the screening logic clearly, not real ARR patterns.

Recommended workflow

Screen every pattern in a duration’s ensemble before you commit to a full ensemble run, not after you’ve already generated results and are wondering why one pattern’s peak looks strange. A flagged pattern isn’t automatically wrong — inspect it, and if it genuinely looks like an extraction artefact rather than a plausible storm, that’s a defensible basis to note it in your methodology and either exclude it or flag the sensitivity it introduces, rather than silently averaging it into an ensemble median as if it were an equally trustworthy input.

Accessing ARR temporal patterns — over to you

This is the one piece I couldn’t complete without ARR Data Hub access, which isn’t available in the environment this was drafted in. The screening function above works on any array of rainfall increments regardless of source — manually exported from the ARR Data Hub web tool, or pulled programmatically if you’re set up with requests against the Data Hub API. If you wire up the API retrieval, the natural extension is a loop that pulls all 10 patterns for a duration, runs each through screen_embedded_bursts, and prints a one-line summary per pattern — straightforward to add once the retrieval side is sorted, and a good candidate for a follow-up post once it’s built and tested against real patterns.

Limitations

This screens for one specific, recognisable error signature (near-24h duplicate bursts). It is not a general-purpose temporal pattern QA tool — a pattern that passes this check can still have other problems.
flag_window_hours=24 and tolerance_hours=1.5 are reasonable starting defaults, not values validated against the full ARR pattern set — tighten or loosen based on what you see when you actually run this against real patterns.
Always read a flagged pattern’s hyetograph before deciding what to do with it. This function tells you where to look, not what to conclude.

Reference: Ladson, A.R. (2021). Review of temporal patterns from Australian Rainfall and Runoff 2019. 39th Hydrology and Water Resources Symposium.

Better Line Graphs for Hydrologic Data — a Python Port of Tony Ladson’s R Method

2026-09-01T00:00:00+00:00

Third in an occasional series porting specific methods from Tony Ladson’s blog to Python — his explanation and the underlying method are his; I’m just providing a translation for readers who know Python better than R. Sources: Visualising Hydrologic Data and the concrete worked example, Better line graphs for hydrologic data, R in his gist.

Six creeks, six unrelated peak-flow-vs-duration lines on one chart. Ladson’s example (invented creek names, made-up numbers — a teaching example, not a real gauge record) makes two points at once.

Point one: sequential palettes are for ordered data

blues = plt.cm.Blues(np.linspace(0.35, 0.95, len(creeks)))  # mimics brewer.pal(8,'Blues')[3:8]

fig, ax = plt.subplots(figsize=(7, 5))
for (name, flows), color in zip(creeks.items(), blues):
    ax.plot(durations, flows, marker='o', color=color, label=name)
ax.legend(fontsize=8)

Sequential palette on unordered categories. Rocky, Reedy and Waterhole Creeks — the three lines closest together in value, exactly where the reader most needs contrast — are also the three closest together in colour.

A sequential palette encodes order — light to dark implies low to high. These six creeks have no natural order; picking a sequential palette to tell them apart imports a ranking that isn’t there, and (worse, practically) the mid-range blues used for the middle of the palette are genuinely hard to tell apart at a glance.

Point two: a legend makes the reader do the work

The fix is two changes at once: a qualitative palette built for categorical data (Dark2 — matplotlib ships the identical ColorBrewer palette Ladson uses in R), and labelling each line directly instead of routing identification through a legend the reader has to look back and forth to.

dark2 = plt.cm.Dark2(np.linspace(0, 1, len(creeks)))

fig, ax = plt.subplots(figsize=(8, 5.5))
for (name, flows), color in zip(creeks.items(), dark2):
    ax.plot(durations, flows, marker='o', color=color)
    ax.annotate(name, xy=(durations[0], flows[0]), xytext=(-8, 0),
                textcoords='offset points', ha='right', va='center', fontsize=8, color=color)
    ax.annotate(name, xy=(durations[-1], flows[-1]), xytext=(8, 0),
                textcoords='offset points', ha='left', va='center', fontsize=8, color=color)
for spine in ['top', 'right']:
    ax.spines[spine].set_visible(False)

Qualitative palette, labelled directly at both ends, minimal frame. No legend to decode; each creek reads as itself.

Not perfect — where lines start close together (Reedy, Rocky and Waterhole Creeks all begin within about 150 units of each other), the left-hand labels still sit tight against one another. That’s an honest limitation of direct labelling when the data itself is genuinely bunched, not something the technique fixes for free — it shows up in Ladson’s original R version too, for the same reason.

Companion notebook: notebooks/10_better_line_graphs/

Source: Ladson, A.R. (2018). Better line graphs for hydrologic data; companion page Visualising Hydrologic Data. R source: gist.github.com/TonyLadson/732e3dbcb8aeaf76fd25c04f6ff246b7.

Was That Flood an Outlier? A Python Diagnostic for Non-Stationarity in Flood Frequency Analysis

2026-09-01T00:00:00+00:00

After a big flood, “unprecedented” gets used a lot — sometimes accurately, sometimes as a stand-in for “this felt very bad.” Reading the 2024 Kedron Brook Flood Study earlier this year, I found a real, useful counter-example: Brisbane City Council’s consultants worked through exactly this question for the 2022 Brisbane flood events at two Kedron Brook gauges, and found the answer was closer to “rare — roughly 5–10% AEP — not extreme.” That’s a genuinely more useful piece of information than “unprecedented,” and it came from a specific, checkable method: fit the historical record, read off where the new event sits, and run a sensitivity check on how much that one event moves the curve.

This post is the Python mechanics behind that kind of question, generalised: fit a stationary distribution, test the record for trend, and diagnose what a model that assumes nothing has changed would make of a new or recent event.

A data note, upfront: I don’t have access to a real gauge record I can publish here, so everything below runs on synthetic annual-maximum series, disclosed as such throughout. That’s enough to validate that the methods work correctly — it is not a claim about any specific river. Swap in your own project’s annual maximum series and the numbers below become genuinely yours; until then, treat this as the method demonstrated, not a result.

Two synthetic records, one with a trend

Two 55-year annual-maximum series, both drawn from a Log-Pearson III generator — so both are genuinely LP3-distributed by construction, matching what ARR 2019 assumes for Australian at-site flood frequency analysis:

import numpy as np
from scipy import stats

N_YEARS = 55

def make_series(trend_per_year=0.0, seed=0):
    """LP3-distributed annual maxima in log10 space, with optional linear
    drift added to the log-space location term to simulate a trend."""
    rng = np.random.default_rng(seed)
    skew, log_mean, log_sd = 0.3, 2.1, 0.22
    years = np.arange(N_YEARS)
    drift = trend_per_year * years
    log_q = stats.pearson3.rvs(skew=skew, loc=log_mean, scale=log_sd,
                                size=N_YEARS, random_state=rng)
    return 10 ** (log_q + drift)

series_stationary = make_series(trend_per_year=0.0, seed=1)   # control: no trend
series_trended = make_series(trend_per_year=0.006, seed=2)    # 0.6%/yr log-space drift

Two synthetic 55-year annual-maximum series. Left: no trend, a control. Right: a 0.6%/year log-space drift injected into the same generator. Both are genuinely LP3-distributed by construction — the difference is entirely the drift term.

Fitting the stationary model

scipy.stats.pearson3 parameterises directly as loc/scale/skew — fitting it to log10(annual_max) is Log-Pearson III:

def fit_lp3(annual_max):
    """MLE fit of LP3 (Pearson III on log10-transformed data)."""
    log_q = np.log10(annual_max)
    skew, loc, scale = stats.pearson3.fit(log_q)
    return skew, loc, scale

def lp3_quantile(aep, skew, loc, scale):
    return 10 ** stats.pearson3.ppf(1 - aep, skew=skew, loc=loc, scale=scale)

def lp3_aep(value, skew, loc, scale):
    return 1 - stats.pearson3.cdf(np.log10(value), skew=skew, loc=loc, scale=scale)

ARR 2019 practice often prefers L-moments over MLE for robustness on short records — my pyextremes fork supports that. MLE via plain scipy is enough to demonstrate the diagnostic here without the extra dependency.

Trend testing: Mann-Kendall, and checking the test itself

The Mann-Kendall test is the standard non-parametric trend test in the water-resources literature (Helsel & Hirsch, 2002) — it doesn’t assume a particular distribution, which matters for a right-skewed annual-maximum series. The mechanics: for every pair of observations, count whether the later one is larger, smaller, or tied; sum those signs into a statistic S; compare S to its expected variance under “no trend.” Sen’s slope — the median of all pairwise slopes — gives a trend magnitude that isn’t dragged around by one or two large events the way an ordinary linear regression slope would be.

def mann_kendall(x):
    """Mann-Kendall trend test. Returns S, Z, two-sided p-value, and Sen's slope."""
    n = len(x)
    s = 0
    for k in range(n - 1):
        s += np.sum(np.sign(x[k+1:] - x[k]))
    s = int(s)
    var_s = n * (n - 1) * (2 * n + 5) / 18
    if s > 0:
        z = (s - 1) / np.sqrt(var_s)
    elif s < 0:
        z = (s + 1) / np.sqrt(var_s)
    else:
        z = 0.0
    p = 2 * (1 - stats.norm.cdf(abs(z)))
    slopes = [(x[j] - x[i]) / (j - i) for i in range(n - 1) for j in range(i + 1, n)]
    return s, z, p, float(np.median(slopes))

Before trusting this on anything real, it needs to correctly tell the two synthetic series apart — that’s the actual point of having a known-stationary control:

for name, series in [('Stationary (control)', series_stationary), ('Trended', series_trended)]:
    s, z, p, sen = mann_kendall(series)
    verdict = 'SIGNIFICANT trend (p < 0.05)' if p < 0.05 else 'no significant trend (p >= 0.05)'
    print(f'{name:22s} S={s:5d}  Z={z:+.2f}  p={p:.4f}  Sen\'s slope={sen:+.3f}/yr  -> {verdict}')

Stationary (control)  S=   41  Z=+0.29  p=0.7715  Sen's slope=+0.110/yr  -> no significant trend (p >= 0.05)
Trended                S=  319  Z=+2.31  p=0.0210  Sen's slope=+1.459/yr  -> SIGNIFICANT trend (p < 0.05)

Correctly quiet on the control, correctly flags the trended series at the conventional 5% level. That’s the implementation earning the right to be used on a real record — not a substitute for checking it against a reference implementation before it matters for a real project, but a reasonable first bar.

The percentile diagnostic

This is the question a “how unusual was that, really” discussion is actually asking, made explicit: fit LP3 to the historical record, then read off what AEP a model that assumes nothing has changed would assign to a given value.

history = series_stationary  # the full 55-yr historical-only record
skew, loc, scale = fit_lp3(history)

target_aeps = {
    'Scenario A -- rare, not extreme': 0.07,
    'Scenario B -- statistically inconsistent': 0.004,
}
for label, target_aep in target_aeps.items():
    value = lp3_quantile(target_aep, skew, loc, scale)
    recovered_aep = lp3_aep(value, skew, loc, scale)
    print(f'{label}: value={value:.1f}, model AEP={recovered_aep*100:.2f}% (~1-in-{1/recovered_aep:.0f} yr)')

Scenario A -- rare, not extreme: value=214.6, model AEP=7.00% (~1-in-14 yr)
Scenario B -- statistically inconsistent: value=338.9, model AEP=0.40% (~1-in-250 yr)

Both values here are constructed, not observed — chosen deliberately to sit at two different points on the curve so the diagnostic has something to show. Scenario A sits in the same AEP territory the real Kedron Brook analysis found for the 2022 Brisbane event: rare, exactly the kind of thing a 55-year record should occasionally produce, nothing in that number alone suggesting the model is wrong. Scenario B sits somewhere a 55-year stationary record essentially never produces — the kind of result that’s a legitimate reason to look closer, the same way the Kedron Brook study’s sensitivity analysis (re-running the FFA with 2022 excluded) was a reason to check how much one event was moving the whole curve.

The historical-only LP3 fit (blue line) against the 55-year record (grey, Cunnane plotting position), with the two constructed scenarios marked at their model-implied AEP. Scenario A (green) sits comfortably on the existing curve; Scenario B (red) sits well beyond where the historical-only record has any real support.

What this diagnostic can and can’t tell you

What it can do: replace “unprecedented” with an actual, repeatable AEP against a stated model. Flag when a record is being dominated by one or two large values — a legitimate reason to run the same kind of sensitivity check the Kedron Brook study did. Give the trend question a proper non-parametric test rather than an eyeballed slope.

What it can’t do: explain why an event landed where it did. A Scenario-B-type result is consistent with several different explanations — genuine non-stationarity, a short and unrepresentative record, rating-curve error at extreme flows most gauges are never actually calibrated against, or simply an unlucky draw from a correctly-specified stationary distribution (rare events are, by definition, supposed to happen occasionally). Distinguishing between those is a harder and different question than the one this diagnostic answers.

It also isn’t formal climate attribution. Attribution studies — the World Weather Attribution methodology is the best-known example — use climate model ensembles to estimate how much more likely or intense a specific event was made by warming. That’s a materially different question, answered with different tools, by people whose primary discipline is climate science. Running a Mann-Kendall test on an annual maximum series is a legitimate flood-engineering diagnostic; it is not that, and I’d rather say so plainly than let the two blur together.

Limitations

55 years is a generous record length by Australian standards. Many real gauge records are shorter, and both the LP3 fit and the trend test should be read with correspondingly wider uncertainty the shorter the record actually is.
The Mann-Kendall variance formula used here has no tie correction — fine for continuous synthetic data, but real gauge records with rounded or repeated values need the tie-corrected variance term (Helsel & Hirsch, 2002, cover this).
LP3 fit here uses MLE for simplicity. For a real project, L-moments or LH-moments (see the pyextremes fork post) are generally the more defensible choice on short, possibly outlier-influenced records.

Companion notebook: notebooks/06_ffa_nonstationarity_diagnostic/ — the Mann-Kendall self-validation (control vs. trended series) is asserted in-notebook, not just eyeballed.

References:

Ball, J. et al. (2019). Australian Rainfall and Runoff. Book 3, Chapter 2.
Mann, H.B. (1945). Nonparametric tests against trend. Econometrica 13(3): 245–259.
Kendall, M.G. (1975). Rank Correlation Methods. Griffin.
Helsel, D.R. & Hirsch, R.M. (2002). Statistical Methods in Water Resources. USGS Techniques of Water-Resources Investigations, Book 4, Chapter A3.
Brisbane City Council (2024). Kedron Brook Flood Study, Vol. 1 (for information only, not Council policy).

How Big Is 1 in 2000? Framing Extreme Probabilities for Clients and Regulators

2026-09-01T00:00:00+00:00

I’m often discussing probabilities with clients and regulators, and there’s a common misunderstanding that keeps coming up: the order of magnitude of an event’s probability. A 1 in 100 Annual Exceedance Probability (AEP) and a 1 in 2000 AEP both just register as “rare” to most people — but they’re twenty times apart, and that gap matters enormously when you’re deciding what a piece of infrastructure needs to survive.

Percentages and “1 in N” notation don’t build intuition for most people. Here’s a framing that does: imagine picking one random second out of a span of time.

The framework

2% AEP — that’s picking one particular second out of the next 50 seconds.

1% AEP — one second out of the next 100 seconds.

1 in 2000 AEP — one second out of about 33 minutes. This also happens to be roughly the number of years between now and the reign of Tiberius in Rome (14–37 AD) — pick a random year in that span, and you’ve picked the year with about the same odds. This is worth sitting with: 1 in 2000 AEP is the generally accepted credible limit of extrapolation for design flood events. Past this point you’re extrapolating into territory the framing above should make viscerally uncomfortable.

1 in 10,000 — one second out of 2.8 hours. Or a random year between now and the late Neolithic adoption of pottery.

A Probable Maximum Flood (PMF), on a small catchment, sits somewhere around 1 in several million to 1 in tens of millions depending on catchment characteristics — genuinely difficult to build intuition for at all. A few equivalents that land in the same range:

Picking one specific second between last New Year’s Day and 5pm on ANZAC Day (1 in ~9.9 million)
Calling the correct colour on a roulette wheel 23 times in a row (1 in ~15.8 million)
Stopping your car on one specific metre of a return road trip from Brisbane to Perth (1 in ~8.6 million)

All three land within the same order of magnitude — which is itself a useful sanity check: wildly different physical framings converging on the same “several million to one” territory is a reasonable indication the framing is doing its job rather than an artefact of one particular analogy.

Why this matters in practice

None of this is just a communication trick — it’s central to how design events actually get chosen and defended. The framing above earns its keep in a few specific moments:

Explaining to a client why a 1 in 2000 AEP assessment costs more scrutiny than a 1 in 100. They’re not “both rare” — one is twenty times rarer, and the credible-extrapolation-limit framing above explains why that specific number shows up so often in guidance documents rather than being an arbitrary round figure.
Explaining to a regulator or a community group why a PMF-based spillway design isn’t overkill. “1 in several million” doesn’t land as a number. “Stopping on a specific metre of the Brisbane–Perth highway” does.
Catching your own extrapolation creep. If a design event feels routine to reason about, and the framing above says it shouldn’t, that’s worth a second look at whether the record actually supports the number you’re using.

The human mind isn’t built to distinguish the very big from the very small — probabilities below about 1% mostly just collapse into an undifferentiated “unlikely” bucket. Reframing the number as a physical quantity — time, distance, repeated coin flips — is one of the few reliable ways to restore the distinction.

Do you have a framing that’s worked for you? I’d be interested to hear it.

Fitting Non-linear Models in Python: Confidence vs. Prediction Intervals

2026-09-01T00:00:00+00:00

Fifth in an occasional series drawing on Tony Ladson’s blog — his explanation and the underlying method are his; I’m providing a translation for readers who know Python better than R. Usually this series is a fairly direct port of his R, checked against his own published numbers. This one isn’t, and it’s worth being upfront about why.

A note on scope, unlike the rest of this series: the tool I use to fetch his gists declined to reproduce the source for Fitting non-linear models verbatim, citing the original research dataset behind it (an Antecedent Precipitation Index vs. Initial Loss relationship). So what follows is an original Python demonstration of the same general method his post covers, on a different, standard example — a stage-discharge rating curve — with clearly synthetic data, rather than a reconstruction of his dataset from a declined fetch. Read his original post for his actual worked example; this is the Python side of the general technique, not a translation of his specific one.

The problem his post flags

R’s lm() gives you confidence and prediction intervals for free. nls() — the nonlinear equivalent — doesn’t; you need a separate package (he points to propagate::predictNLS) or to propagate the uncertainty yourself. It’s exactly as true in Python: scipy.optimize.curve_fit hands you a point estimate and a covariance matrix, and what you do with the covariance matrix is entirely up to you.

A synthetic rating curve

Stage-discharge rating: Q = C·(h − h0)ⁿ — standard power-law form, fit to synthetic gaugings generated from a known “true” relationship plus 6% measurement noise, so there’s a ground truth to check against.

import numpy as np
from scipy import optimize, stats

rng = np.random.default_rng(20260901)
true_C, true_h0, true_n = 45.0, 0.15, 1.85
h_obs = np.sort(rng.uniform(0.3, 3.5, 22))
Q_true = true_C * (h_obs - true_h0) ** true_n
Q_obs = Q_true * (1 + rng.normal(0, 0.06, size=h_obs.size))

def rating_curve(h, C, h0, n):
    return C * np.maximum(h - h0, 1e-6) ** n

popt, pcov = optimize.curve_fit(rating_curve, h_obs, Q_obs, p0=[1.0, 0.0, 2.0], maxfev=10000)

Fitted: C=66.38+/-18.98   h0=0.371+/-0.202   n=1.541+/-0.177
(true:  C=45.0            h0=0.15            n=1.85)

A real gotcha, not the point of the post but worth knowing

The fitted parameters are noticeably off their “true” values — not because the fit failed, but because power-law rating curve parameters are famously correlated with each other:

D = np.sqrt(np.diag(pcov))
corr = pcov / np.outer(D, D)

[[ 1.     0.985 -0.986]
 [ 0.985  1.    -0.950]
 [-0.986 -0.950  1.   ]]

Every pair of parameters is correlated above 0.9 in magnitude. Several different (C, h0, n) combinations trace out nearly the same curve over the range the data actually covers — a well-known feature of this class of model, not a bug in the fit. Which is exactly why it’s worth checking the fitted curve separately from the individual parameters before deciding the fit is good or bad.

Confidence interval vs. prediction interval

Confidence interval — uncertainty in the fitted curve itself: where the true mean relationship probably sits, given parameter uncertainty.
Prediction interval — uncertainty in a new individual observation: necessarily wider, since it adds residual scatter on top of parameter uncertainty.

The delta method gets both explicitly: propagate the parameter covariance through the model’s own gradient to get the curve’s variance, then add the residual variance for the prediction interval.

def rating_curve_grad(h, C, h0, n):
    base = np.maximum(h - h0, 1e-6)
    dC = base ** n
    dh0 = -C * n * base ** (n - 1)
    dn = C * base ** n * np.log(base)
    return np.stack([dC, dh0, dn], axis=-1)

resid = Q_obs - rating_curve(h_obs, *popt)
dof = len(h_obs) - len(popt)
resid_var = np.sum(resid**2) / dof

h_grid = np.linspace(h_obs.min(), h_obs.max(), 100)
J = rating_curve_grad(h_grid, *popt)
var_mean = np.einsum('ij,jk,ik->i', J, pcov, J)   # confidence interval variance
se_pred = np.sqrt(var_mean + resid_var)            # prediction interval std error

At h=2.0 m: fitted Q=140.8
  95% CI: (134.9, 150.3)  width=15.4
  95% PI: (116.5, 168.7)  width=52.1
  Confirmed: PI is wider than CI, as it must be.

Fitted rating curve (line), 95% confidence interval (darker band), and 95% prediction interval (lighter band). The curve tracks the synthetic gaugings well despite the individual parameter correlation noted above — a reminder that fit quality and parameter identifiability are two different questions.

Companion notebook: notebooks/12_nonlinear_model_fitting/

Topic inspiration: Ladson, A.R. (2016). Fitting non-linear models — this notebook’s specific data and code are original, not a port of his.

Fitting a Probability Model to POT Data — a Python Port of Tony Ladson’s R Method

2026-09-01T00:00:00+00:00

Tony Ladson’s blog has come up as a reference more than once on this site already — his baseflow separation method, his writing on model performance metrics, his work on ARR loss distributions. I learned a lot of practical Australian hydrology from reading his R, and I’d like to start properly returning the favour: porting specific methods from his blog to Python, checked against his own published numbers rather than just “inspired by” them. This is the first one — and the pattern for the whole series: the explanation and the underlying method are his; I’m just providing a hopefully useful translation service for readers who, like me, know Python better than R.

The source is Fitting a probability model to POT data (25 March 2019), with the R source published separately as a gist. Read his original post for the full explanation — what follows is a Python port and my own summary of the method, not a substitute for it.

Why POT needs a different AEP conversion

An annual maximum series gives you exactly one value per year, so a plotting position formula (Cunnane, Weibull, whatever your convention) hands you an empirical AEP directly. A Partial Duration Series — peaks over some threshold, which can produce several events in a wet year and none in a dry one — doesn’t have that property, and a plotting position formula applied naively to it doesn’t give a valid AEP.

The fix Ladson’s post lays out, following ARR 2016/2019 Book 3 Section 2.8.11: work in EY (expected exceedances per year) instead, and only convert to AEP at the end via the Poisson relationship between the two:

# Ladson's R (from the gist)
AEP2EY <- function(AEP) {
  -log(1-AEP)
}
EY2AEP <- function(EY) {
  (exp(EY) - 1)/exp(EY)
}

def aep_to_ey(AEP):
    return -np.log(1 - AEP)

def ey_to_aep(EY):
    return (np.exp(EY) - 1) / np.exp(EY)  # == 1 - exp(-EY)

The exponential fit, via L-moments

The worked example fits an exponential distribution — parameterised by scale beta and location q_star — using the L-moments method from Wang (1996), on the Styx River at Jeogla partial series (47 peaks). Ladson’s L2() function is the direct sample estimator:

# Ladson's R
L2 <- function(q){
  q <- sort(q)
  n <- length(q)
  0.5*(1/choose(n,2))*sum((0:(n-1) - (n-1):0)*q)
}

from math import comb
import numpy as np

def l2_wang(q):
    """Second L-moment, direct sample estimator (Wang 1996)."""
    q = np.sort(np.asarray(q, dtype=float))
    n = len(q)
    i = np.arange(n)
    weights = i - (n - 1 - i)
    return 0.5 * (1 / comb(n, 2)) * np.sum(weights * q)

Run on the same 47-peak Styx River series he publishes:

styx = np.array([74.0, 79.9, 85.2, 88.6, 91.7, 92.2, 92.2, 98.0, 105.0, 108.0, 111.0,
                  117.0, 117.0, 118.0, 119.0, 126.0, 129.0, 129.0, 134.0, 149.0, 150.0, 164.0,
                  186.0, 190.0, 194.0, 196.0, 206.0, 220.0, 221.0, 235.0, 238.0, 255.0, 255.0,
                  258.0, 283.0, 294.0, 300.0, 301.0, 309.0, 315.0, 405.0, 411.0, 436.0, 513.0, 521.0, 541.0, 878.0])

L1 = styx.mean()
L2 = l2_wang(styx)
beta = 2 * L2
q_star = L1 - beta

L1     = 226.36      (Ladson: 226.36)
L2     = 79.12       (Ladson: 79.12)
beta   = 158.23996   (Ladson: 158.240)
q_star = 68.11748    (Ladson: 68.11748)

Matches to the precision he published.

The flood quantile table

def flood_quantile(EY, beta, q_star, nu=1.0):
    return q_star - beta * np.log(EY / nu)

standard_EY = np.array([1, 0.69, 0.5, 0.22, 0.2, 0.11, 0.05, 0.02, 0.01])
Q = flood_quantile(standard_EY, beta, q_star)

    EY      AEP      ARI        Q     Ladson Q
00   0.6321     1.00     68.1         68.1
69   0.4984     1.45    126.8        127.0
50   0.3935     2.00    177.8        178.0
22   0.1975     4.55    307.7        308.0
20   0.1813     5.00    322.8        323.0
11   0.1042     9.09    417.4        417.0
05   0.0488    20.00    542.2        542.0
02   0.0198    50.00    687.2        687.0
01   0.0100   100.00    796.8        797.0

All nine match his table, including the explicit check value he calls out in a comment: EY=0.01 → 796.8394.

Bootstrap confidence intervals

Ladson uses R’s boot::boot with 5,000 resamples and BCa (bias-corrected and accelerated) intervals. scipy.stats.bootstrap supports the same method directly:

from scipy import stats

def exp_params(q):
    q = np.asarray(q)
    b = 2 * l2_wang(q)
    return b, q.mean() - b

def q01_stat(sample, axis=-1):
    return np.apply_along_axis(lambda s: flood_quantile(0.01, *exp_params(s)), axis, sample)

res = stats.bootstrap((styx,), q01_stat, n_resamples=5000, method='BCa', confidence_level=0.95)

Q at EY=0.01:  point=796.84   95% CI=(626, 1109)   Ladson: est=796.84, CI=(628, 1132)

Point estimates match exactly, since they’re deterministic. The confidence interval bounds don’t match bit-for-bit — different RNG draws — but land in essentially the same range, which is what you’d want from two independent runs of the same method.

The fitted exponential (blue) against the 47 Styx River peaks (grey), with a 95% bootstrap confidence band. The single largest peak in the record — 878 m³/s — sits above the fitted curve and outside the upper confidence band. That's not a bug in the fit; it's the real record showing its largest event isn't fully explained by an exponential model fit to the bulk of the data, which is exactly the kind of thing worth noticing rather than smoothing over.

What this checked, and what it didn’t

Every number above that could be checked against Ladson’s own published output was checked, in the notebook itself, with an assertion rather than a visual eyeball — L-moments, fitted parameters, all nine quantiles, the explicit check value, and the bootstrap range. What this port doesn’t independently re-derive is whether the exponential distribution is actually the right model for the Styx River series specifically — that’s a modelling choice inherited from the ARR worked example Ladson’s post follows, not something this notebook re-litigates. The 878 m³/s outlier sitting outside the confidence band is a reasonable prompt to ask that question, not an answer to it.

Companion notebook: notebooks/08_pot_exponential_fit/

Source: Ladson, A.R. (2019). Fitting a probability model to POT data. R source: gist.github.com/TonyLadson/5b01838fef1140293397e23eebe12079.

References:

Wang, Q.J. (1996). Direct sample estimates of L moments. Water Resources Research 32(12): 3617–3619.
Ball, J. et al. (2019). Australian Rainfall and Runoff. Book 3, Section 2.8.11.

Stochastic Rainfall Generation with pyraingen: A Practitioner’s Evaluation

2026-09-01T00:00:00+00:00

A single historical rainfall record is one realisation of what the climate at a site could produce — not the only one, and not necessarily the most extreme one. Stochastic rainfall generation addresses that directly: instead of one 50-year record, produce many statistically plausible 50-year records with the same broad statistical properties, and see how design rainfall at different durations and AEPs behaves across the whole set. That’s a genuinely useful tool for probing how much a design estimate depends on which particular sequence of years happened to get recorded — a different and more modest question than asking how a warming climate will change future rainfall, but a useful one on its own terms.

pyraingen is one of the few Python packages attempting this for Australian conditions, so I wanted to actually use it — not just describe it — for the Climate Risk series. This post is what I found doing that.

What it promises

From the package’s own documentation: pyraingen “can be used to stochastically generate regionalised daily rainfall, disaggregate daily rainfall to subdaily fragments and constrain generated rainfall to observed or predicted Intensity Frequency Duration (IFD) relationships,” via three main functions — regionaliseddailysim, regionalisedsubdailysim, and ifdcond. The subdaily disaggregation step implements the method from Westra et al. (2012), “Continuous rainfall simulation 1: A regionalised subdaily disaggregation approach” (cited directly in the package’s own docstrings); the IFD-conditioning step implements “Algorithm from Fitsum et al. (2016) for Constraining continuous rainfall simulations for derived design flood estimation” — also per its own docstring. Both are legitimate, real methods. The question was whether the current release actually runs.

pip install pyraingen

Problem 1: a dependency pin that doesn’t work today

pyraingen 1.0.0’s own package metadata declares:

Requires-Dist: numpy (>=1.23.5)
Requires-Dist: pandas (==1.5.3)
Requires-Dist: xarray (==2023.01.0)

No upper bound on numpy, but pandas and xarray hard-pinned to versions that predate numpy 2.0 (released mid-2024) — and whose compiled C extensions are ABI-incompatible with it. I confirmed this isn’t an artifact of one messy environment: in a completely clean virtualenv, pip install pyraingen resolves numpy 2.x (nothing stops it), and importing anything that touches pandas fails:

ValueError: numpy.dtype size changed, may indicate binary incompatibility.
Expected 96 from C header, got 88 from PyObject

The fix, if you want to use this package today: pin numpy yourself before installing.

pip install "numpy<2" pyraingen

With that pin, pandas==1.5.3 and xarray==2023.01.0 both import cleanly.

Problem 2: the core generator doesn’t run on Linux at all

With the numpy pin fixed, the package’s actual daily rainfall generator still fails:

>>> from pyraingen.regionaliseddailysim import regionaliseddailysim
...
ImportError: cannot import name 'regionalised_dailyT4' from 'pyraingen.fortran_daily'

The installed package’s own file listing explains why — pyraingen/fortran_daily/ contains:

regionalised_dailyT.cp38-win_amd64.pyd
regionalised_dailyT4.cp38-win_amd64.pyd
regionalised_dailyT.for
regionalised_dailyT4.for

.pyd files are compiled Windows extension modules, and these are built specifically for CPython 3.8 on 64-bit Windows. There’s no Linux (.so) or macOS build anywhere in the package, and no automatic source-compilation fallback. The Fortran source is there, so compiling it yourself with f2py is possible in principle — I didn’t attempt it here.

In practice: regionaliseddailysim — the actual stochastic daily rainfall generator, the core of what the package does — is not runnable via a plain pip install pyraingen on Linux or macOS. That matters because Linux is where most cloud, CI, and HPC-based hydrology computation happens today. regionalisedsubdailysim has code paths that can work from existing daily data without touching the Fortran generator, but its “generate everything from scratch” option hits the same wall.

What does run: computeIFD, and a shape that doesn’t match its own docstring

One piece has no compiled or pinned-package dependency at all: computeIFD, described in its own docstring as an internal helper “designed to be used inside the IFD Conditioning code” rather than something meant for direct use. It takes a pre-built 6-minute rainfall array and is meant to return an annual-maximum table by duration. I fed it a small, deliberately synthetic 6-minute series — random sparse bursts, not real rainfall — purely to exercise the function’s contract:

import numpy as np
from pyraingen.computeifd import computeIFD

rng = np.random.default_rng(20260901)
n_days, n_sims, n_records_per_day = 365 * 10, 3, 240

rainfall = np.zeros((n_records_per_day, n_days, n_sims))
for sim in range(n_sims):
    n_bursts = 300
    burst_days = rng.integers(0, n_days, n_bursts)
    burst_starts = rng.integers(0, n_records_per_day - 10, n_bursts)
    burst_depths = rng.gamma(shape=2.0, scale=3.0, size=n_bursts)
    for d, s, depth in zip(burst_days, burst_starts, burst_depths):
        dur = rng.integers(1, 8)
        rainfall[s:s+dur, d, sim] += depth / dur

years_vector = np.repeat(np.arange(2016, 2026), 365)
ifd_durations = [6, 30, 60, 360, 1440]  # minutes

IFD = computeIFD(rainfall, years_vector, ifd_durations)
print(f'Output shape: {IFD.shape}')

Output shape: (10, 240, 5)

I’d asked for 3 simulations. The docstring says the output should be (nYears, nSimulations, nIFDDurations) — (10, 3, 5). What came back has 240 in the middle slot, not 3. Reading the source explains why: the output array is allocated with np.size(rainfallSeries, axis=0), which is the 240 six-minute-slots-per-day count, not the simulations axis. The fill loop then collapses across both the simulation axis and the within-year day axis before assigning into that 240-long slot — which doesn’t produce a per-simulation annual-maximum-by-duration table.

The function’s own source has a comment that reads like the original author flagged this themselves:

# The general process for each simulation is:
#   -) Aggregate up from 6 minute if required.
#   -) Extract the annual maximum series
#   -) ?

I wouldn’t trust this specific function’s return values for a real project without independently re-deriving the annual maxima myself — the trailing ? is in the package’s own source, not something I’ve added for effect.

What I’d actually tell a colleague

The underlying methods — Westra et al.’s subdaily disaggregation, Fitsum et al.’s IFD conditioning — are legitimate and exactly the right tools for the question “how much does design rainfall at different durations and AEPs depend on the particular 50 years we happened to record.” pyraingen is a genuine, serious attempt at packaging that for Australian conditions in Python, and I’d rather see it exist, with rough edges, than not exist at all.

But as released today (1.0.0), I wouldn’t build a real project workflow on it without addressing all three of the above first: pin numpy<2 yourself, either work on Windows/Python 3.8 or compile the bundled Fortran source for your platform, and independently verify computeIFD’s output rather than trusting the shape the docstring promises. For a Linux-based team, that’s currently closer to “a well-documented methodology worth reimplementing the disaggregation and conditioning steps around” than “a package you pip install and use.”

Limitations of this evaluation

I did not attempt to compile the bundled Fortran source with f2py — that may well resolve the Linux blocker; I’m reporting what the released PyPI package does out of the box, not what’s theoretically achievable with more effort.
I have not run this on Windows/Python 3.8, where the shipped binaries are presumably functional.
The computeIFD finding is based on reading the source and one test run, not an exhaustive test suite — I’d want to see the package’s own tests (if any exist) before stating definitively that it’s wrong rather than differently-intentioned than its docstring suggests.

Companion notebook: notebooks/07_pyraingen_evaluation/

References:

Dykman, C. pyraingen 1.0.0. pypi.org/project/pyraingen, docs at pyraingen.readthedocs.io.
Westra, S. et al. (2012). Continuous rainfall simulation: 1. A regionalised subdaily disaggregation approach — as cited in the package’s own docstrings.
Fitsum, et al. (2016). Constraining continuous rainfall simulations for derived design flood estimation — as cited in the package’s own docstrings.