femic.hydrology.flood Module
The femic.hydrology.flood module owns P114.5 stochastic flood-frequency
work. It extracts annual maxima and POT samples, fits GEV/LP3 and Poisson-GPD
models, computes paired baseline/treatment response ratios, fits nonstationary
GEV location models, builds return-period response surfaces, and checks
benchmark envelopes.
It is decision-support and screening, not regulatory flood analysis.
Start Here If…
Use this page first if you are trying to:
fit a stationary GEV or LP3 frequency distribution;
extract and fit declustered peaks over a threshold;
compare baseline and treatment return levels;
fit a nonstationary GEV with harvest/road covariates;
build a return-period response surface; or
check response ratios against a reviewed benchmark envelope.
Typical Usage
from femic.hydrology.flood import (
FloodScenario,
build_response_surface,
fit_flood_frequency,
fit_nonstationary_gev,
paired_frequency_response,
)
fit = fit_flood_frequency(
annual,
method="gev",
return_periods=(2, 10, 100),
bootstrap_samples=200,
seed=42,
)
pairing = paired_frequency_response(
baseline,
treatment,
method="gev",
return_periods=(2, 10, 100),
)
nonstationary = fit_nonstationary_gev(
sample,
{"harvest_fraction": harvest_fraction_by_year},
return_periods=(2, 10, 100),
)
surface = build_response_surface(
nonstationary,
(
FloodScenario("baseline", {"harvest_fraction": 0.0}),
FloodScenario("high", {"harvest_fraction": 0.4}),
),
)
Key Entry Surfaces
extract_annual_maxima()extract_peaks_over_threshold()Build annual-maximum and declustered POT samples.fit_flood_frequency()Fit GEV or LP3 with bootstrap intervals.fit_pot_frequency()Fit Poisson-GPD.paired_frequency_response()Compare baseline/treatment return levels.fit_nonstationary_gev()Fit a linear-location GEV.predict_nonstationary_quantiles()Predict one scenario.build_response_surface()Build a return-period surface.evaluate_frequency_benchmark()Check paired ratios against a reviewed envelope.FloodResponseSurfaceVersioned scenario/return-period surface.
Cross-References
Stochastic flood-frequency response surfaces.
P114.5 provides screening/decision-support frequency fits, paired-watershed response ratios, and nonstationary GEV response surfaces. It does not replace hydrologist review, public-gauge calibration, or regulatory flood analysis.
- class femic.hydrology.flood.FloodBenchmark(name, return_periods, lower_ratio, upper_ratio, source='', notes='')[source]
Bases:
objectPublished or reviewed return-period ratio envelope.
- Parameters:
name (str)
return_periods (tuple[float, ...])
lower_ratio (tuple[float, ...])
upper_ratio (tuple[float, ...])
source (str)
notes (str)
- lower_ratio: tuple[float, ...]
- name: str
- notes: str = ''
- return_periods: tuple[float, ...]
- source: str = ''
- to_dict()[source]
Return the benchmark as a JSON-serializable mapping.
- Return type:
dict[str, object]
- upper_ratio: tuple[float, ...]
- class femic.hydrology.flood.FloodBenchmarkCheck(benchmark_name, is_pass, rows, warnings=())[source]
Bases:
objectBenchmark comparison outcome.
- Parameters:
benchmark_name (str)
is_pass (bool)
rows (tuple[FloodBenchmarkRow, ...])
warnings (tuple[str, ...])
- benchmark_name: str
- is_pass: bool
- rows: tuple[FloodBenchmarkRow, ...]
- warnings: tuple[str, ...] = ()
- class femic.hydrology.flood.FloodBenchmarkRow(return_period, observed_ratio, lower_ratio, upper_ratio, within_envelope)[source]
Bases:
objectOne benchmark comparison row.
- Parameters:
return_period (float)
observed_ratio (float)
lower_ratio (float)
upper_ratio (float)
within_envelope (bool)
- lower_ratio: float
- observed_ratio: float
- return_period: float
- upper_ratio: float
- within_envelope: bool
- class femic.hydrology.flood.FloodEvent(event_date, value)[source]
Bases:
objectOne observed peak-flow event.
- Parameters:
event_date (date)
value (float)
- event_date: date
- value: float
- class femic.hydrology.flood.FloodFrequencyFit(station_id, method, return_periods, quantiles, lower_bounds, upper_bounds, parameters, log_likelihood, aic, sample_size, bootstrap_samples, warnings=(), caveats=(), schema_version='femic.hydrology.flood_frequency.v1')[source]
Bases:
objectStationary flood-frequency fit and return-level interval.
- Parameters:
station_id (str)
method (str)
return_periods (tuple[float, ...])
quantiles (tuple[float, ...])
lower_bounds (tuple[float | None, ...])
upper_bounds (tuple[float | None, ...])
parameters (dict[str, object])
log_likelihood (float)
aic (float)
sample_size (int)
bootstrap_samples (int)
warnings (tuple[str, ...])
caveats (tuple[str, ...])
schema_version (str)
- aic: float
- bootstrap_samples: int
- caveats: tuple[str, ...] = ()
- log_likelihood: float
- lower_bounds: tuple[float | None, ...]
- method: str
- parameters: dict[str, object]
- quantiles: tuple[float, ...]
- return_periods: tuple[float, ...]
- sample_size: int
- schema_version: str = 'femic.hydrology.flood_frequency.v1'
- station_id: str
- upper_bounds: tuple[float | None, ...]
- warnings: tuple[str, ...] = ()
- class femic.hydrology.flood.FloodResponseSurface(surface_id, generated_utc, station_id, method, baseline_name, return_periods, scenarios, rows, diagnostics=<factory>, warnings=(), caveats=(), schema_version='femic.hydrology.flood_response.v1')[source]
Bases:
objectReturn-period-specific response surface.
- Parameters:
surface_id (str)
generated_utc (str)
station_id (str)
method (str)
baseline_name (str)
return_periods (tuple[float, ...])
scenarios (tuple[FloodScenario, ...])
rows (tuple[FloodResponseSurfaceRow, ...])
diagnostics (dict[str, object])
warnings (tuple[str, ...])
caveats (tuple[str, ...])
schema_version (str)
- baseline_name: str
- caveats: tuple[str, ...] = ()
- diagnostics: dict[str, object]
- generated_utc: str
- method: str
- return_periods: tuple[float, ...]
- rows: tuple[FloodResponseSurfaceRow, ...]
- scenarios: tuple[FloodScenario, ...]
- schema_version: str = 'femic.hydrology.flood_response.v1'
- station_id: str
- surface_id: str
- to_dict()[source]
Return the surface as a JSON-serializable mapping.
- Return type:
dict[str, object]
- warnings: tuple[str, ...] = ()
- class femic.hydrology.flood.FloodResponseSurfaceRow(scenario, return_period, quantile, baseline_quantile, ratio, difference)[source]
Bases:
objectOne scenario/return-period response row.
- Parameters:
scenario (str)
return_period (float)
quantile (float)
baseline_quantile (float)
ratio (float)
difference (float)
- baseline_quantile: float
- difference: float
- quantile: float
- ratio: float
- return_period: float
- scenario: str
- class femic.hydrology.flood.FloodSample(station_id, years, values, regime='unknown')[source]
Bases:
objectAnnual-maximum peak-flow sample for one station.
- Parameters:
station_id (str)
years (tuple[int, ...])
values (tuple[float, ...])
regime (str)
- regime: str = 'unknown'
- station_id: str
- values: tuple[float, ...]
- years: tuple[int, ...]
- class femic.hydrology.flood.FloodScenario(name, covariates)[source]
Bases:
objectOne covariate scenario for a response surface.
- Parameters:
name (str)
covariates (dict[str, float])
- covariates: dict[str, float]
- name: str
- class femic.hydrology.flood.FrequencyPairingResult(baseline, treatment, return_periods, ratios, ratio_lower, ratio_upper, differences, warnings=(), caveats=())[source]
Bases:
objectBaseline/treatment frequency pairing and return-period ratios.
- Parameters:
baseline (FloodFrequencyFit)
treatment (FloodFrequencyFit)
return_periods (tuple[float, ...])
ratios (tuple[float, ...])
ratio_lower (tuple[float | None, ...])
ratio_upper (tuple[float | None, ...])
differences (tuple[float, ...])
warnings (tuple[str, ...])
caveats (tuple[str, ...])
- baseline: FloodFrequencyFit
- caveats: tuple[str, ...] = ()
- differences: tuple[float, ...]
- ratio_lower: tuple[float | None, ...]
- ratio_upper: tuple[float | None, ...]
- ratios: tuple[float, ...]
- return_periods: tuple[float, ...]
- to_dict()[source]
Return the pairing as a JSON-serializable mapping.
- Return type:
dict[str, object]
- treatment: FloodFrequencyFit
- warnings: tuple[str, ...] = ()
- exception femic.hydrology.flood.HydrologyFloodError[source]
Bases:
RuntimeErrorRaised when a flood sample, fit, or response surface is invalid.
- class femic.hydrology.flood.NonstationaryGevFit(station_id, covariate_names, coefficients, log_likelihood, aic, sample_size, return_periods, baseline_covariates, baseline_quantiles, warnings=(), caveats=())[source]
Bases:
objectNonstationary GEV with a linear location model in covariates.
- Parameters:
station_id (str)
covariate_names (tuple[str, ...])
coefficients (dict[str, float])
log_likelihood (float)
aic (float)
sample_size (int)
return_periods (tuple[float, ...])
baseline_covariates (dict[str, float])
baseline_quantiles (tuple[float, ...])
warnings (tuple[str, ...])
caveats (tuple[str, ...])
- aic: float
- baseline_covariates: dict[str, float]
- baseline_quantiles: tuple[float, ...]
- caveats: tuple[str, ...] = ()
- coefficients: dict[str, float]
- covariate_names: tuple[str, ...]
- log_likelihood: float
- return_periods: tuple[float, ...]
- sample_size: int
- station_id: str
- warnings: tuple[str, ...] = ()
- class femic.hydrology.flood.PotSample(station_id, events, threshold, min_separation_days, record_start_year, record_end_year, regime='unknown')[source]
Bases:
objectDeclustered peaks-over-threshold sample.
- Parameters:
station_id (str)
events (tuple[FloodEvent, ...])
threshold (float)
min_separation_days (int)
record_start_year (int)
record_end_year (int)
regime (str)
- property annual_rate: float
Return the mean number of selected peaks per year.
- events: tuple[FloodEvent, ...]
- min_separation_days: int
- record_end_year: int
- record_start_year: int
- regime: str = 'unknown'
- station_id: str
- threshold: float
- property values: tuple[float, ...]
Return the declustered peak values.
- femic.hydrology.flood.build_response_surface(fit, scenarios, *, baseline_name=None, generated_utc=None)[source]
Build a return-period-specific response surface from scenarios.
- Parameters:
fit (NonstationaryGevFit)
scenarios (Sequence[FloodScenario])
baseline_name (str | None)
generated_utc (str | None)
- Return type:
- femic.hydrology.flood.evaluate_frequency_benchmark(pairing, benchmark)[source]
Compare paired return-period ratios with a benchmark envelope.
- Parameters:
pairing (FrequencyPairingResult)
benchmark (FloodBenchmark)
- Return type:
- femic.hydrology.flood.extract_annual_maxima(events, *, station_id, regime='unknown')[source]
Extract one annual maximum per calendar year from event records.
- Parameters:
events (Sequence[FloodEvent])
station_id (str)
regime (str)
- Return type:
- femic.hydrology.flood.extract_peaks_over_threshold(events, *, threshold, min_separation_days, station_id, regime='unknown')[source]
Extract declustered peaks over a threshold.
Peaks are selected in descending magnitude with a minimum day separation. The record start/end years come from all supplied events, not only the selected peaks.
- Parameters:
events (Sequence[FloodEvent])
threshold (float)
min_separation_days (int)
station_id (str)
regime (str)
- Return type:
- femic.hydrology.flood.fit_flood_frequency(sample, *, method='gev', return_periods=(2.0, 5.0, 10.0, 25.0, 50.0, 100.0), bootstrap_samples=200, seed=0)[source]
Fit a stationary GEV or LP3 frequency distribution.
Return periods are in years and use annual-maximum non-exceedance probability
1 - 1/T. Bootstrap intervals are percentile intervals.- Parameters:
sample (FloodSample)
method (str)
return_periods (Sequence[float])
bootstrap_samples (int)
seed (int)
- Return type:
- femic.hydrology.flood.fit_nonstationary_gev(sample, covariates, *, return_periods=(2.0, 5.0, 10.0, 25.0, 50.0, 100.0), baseline_covariates=None)[source]
Fit a GEV whose location is linear in time-varying covariates.
- Parameters:
sample (FloodSample)
covariates (Mapping[str, Sequence[float]])
return_periods (Sequence[float])
baseline_covariates (Mapping[str, float] | None)
- Return type:
- femic.hydrology.flood.fit_pot_frequency(sample, *, return_periods=(2.0, 5.0, 10.0, 25.0, 50.0, 100.0), bootstrap_samples=200, seed=0)[source]
Fit a Poisson-GPD peaks-over-threshold frequency model.
- Parameters:
sample (PotSample)
return_periods (Sequence[float])
bootstrap_samples (int)
seed (int)
- Return type:
- femic.hydrology.flood.paired_frequency_response(baseline, treatment, *, method='gev', return_periods=(2.0, 5.0, 10.0, 25.0, 50.0, 100.0), bootstrap_samples=200, seed=0)[source]
Compare baseline and treatment return levels by return period.
- Parameters:
baseline (FloodSample)
treatment (FloodSample)
method (str)
return_periods (Sequence[float])
bootstrap_samples (int)
seed (int)
- Return type:
- femic.hydrology.flood.predict_nonstationary_quantiles(fit, covariates, *, return_periods=(2.0, 5.0, 10.0, 25.0, 50.0, 100.0))[source]
Predict return levels for one covariate scenario.
- Parameters:
fit (NonstationaryGevFit)
covariates (Mapping[str, float])
return_periods (Sequence[float])
- Return type:
tuple[float, …]
- femic.hydrology.flood.write_flood_frequency_report(fit, path)[source]
Write a stationary frequency fit as JSON.
- Parameters:
fit (FloodFrequencyFit)
path (Path)
- Return type:
Path
- femic.hydrology.flood.write_response_surface(surface, path)[source]
Write a flood response surface as JSON.
- Parameters:
surface (FloodResponseSurface)
path (Path)
- Return type:
Path