Stochastic Flood-Frequency Response
Purpose
P114.5 adds stochastic flood-frequency fits, paired-watershed response ratios, and nonstationary GEV response surfaces. These are planning and screening tools for return-period-specific hydrologic response.
They do not replace hydrologist review, public-gauge calibration, or regulatory
flood analysis. The fit schema is femic.hydrology.flood_frequency.v1 and the
response surface uses femic.hydrology.flood_response.v1. This is not a regulatory flood map. P114.9 owns the public-gauge benchmark and pilot
validation.
Frequency Models
The module supports:
stationary GEV on annual maxima;
LP3 on annual maxima, fitted as Pearson III on log10 flows;
Poisson-GPD peaks-over-threshold;
paired baseline/treatment return-level ratios;
nonstationary GEV with a linear location model in covariates;
return-period response surfaces from nonstationary scenarios;
benchmark-envelope checks.
Annual Maxima And POT
from datetime import date
from femic.hydrology.flood import (
FloodEvent,
extract_annual_maxima,
extract_peaks_over_threshold,
)
events = (
FloodEvent(date(2020, 1, 1), 120.0),
FloodEvent(date(2020, 1, 3), 110.0),
FloodEvent(date(2020, 6, 1), 140.0),
)
annual = extract_annual_maxima(events, station_id="station-1")
pot = extract_peaks_over_threshold(
events,
threshold=100.0,
min_separation_days=10,
station_id="station-1",
)
POT peaks are selected in descending magnitude with a minimum day separation.
Stationary Fits
from femic.hydrology.flood import fit_flood_frequency
fit = fit_flood_frequency(
annual,
method="gev",
return_periods=(2, 5, 10, 25, 50, 100),
bootstrap_samples=200,
seed=42,
)
Return periods use annual-maximum non-exceedance probability 1 - 1/T.
Bootstrap intervals are percentile intervals.
The stationary GEV uses an unconstrained maximum-likelihood fit when its shape
is inside the screening bounds [-0.5, 0.5]. If the unconstrained shape is
outside those bounds, the fit falls back to a bounded-shape maximum-likelihood
fit and records fit_strategy="constrained" plus a warning. Bootstrap fits
use the same fallback. Inspect the strategy before using the tail; the bound is
a screening guard, not a substitute for hydrologist review.
Paired Response
from femic.hydrology.flood import paired_frequency_response
pairing = paired_frequency_response(
baseline,
treatment,
method="gev",
return_periods=(2, 10, 100),
)
The result records return-period-specific ratios, differences, and bootstrap ratio intervals.
Nonstationary Response Surface
from femic.hydrology.flood import (
FloodScenario,
build_response_surface,
fit_nonstationary_gev,
)
fit = fit_nonstationary_gev(
sample,
{"harvest_fraction": harvest_fraction_by_year},
return_periods=(2, 10, 100),
)
surface = build_response_surface(
fit,
(
FloodScenario("baseline", {"harvest_fraction": 0.0}),
FloodScenario("high", {"harvest_fraction": 0.4}),
),
)
The nonstationary GEV uses a linear location model. Coefficients are point estimates; uncertainty propagation belongs to P114.7.
Uncertainty
Stationary fits report bootstrap percentile intervals.
Paired responses report bootstrap ratio intervals.
Nonstationary coefficients are point estimates.
Structural, climate, and record-length uncertainty remain explicit caveats.
Bootstrap intervals are not a full Bayesian posterior.
Calibration And Validation
FloodBenchmark and evaluate_frequency_benchmark compare paired response
ratios against a reviewed lower/upper envelope by return period. A benchmark
pass is a consistency check, not proof of hydrological correctness.
Public-gauge calibration and published paired-watershed validation are P114.9.
Limits
No regulatory flood map or design-flood service.
Short records limit tail inference.
Nonstationarity is represented only through the supplied covariates.
Potentially influential covariates must be reviewed; correlation is not causation.
Regionalization and climate projection are later work.
Hydrologist review is required before operational use.