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.

  • FloodResponseSurface Versioned 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: object

Published 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: object

Benchmark comparison outcome.

Parameters:
  • benchmark_name (str)

  • is_pass (bool)

  • rows (tuple[FloodBenchmarkRow, ...])

  • warnings (tuple[str, ...])

benchmark_name: str
is_pass: bool
rows: tuple[FloodBenchmarkRow, ...]
to_dict()[source]

Return the check as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...] = ()
class femic.hydrology.flood.FloodBenchmarkRow(return_period, observed_ratio, lower_ratio, upper_ratio, within_envelope)[source]

Bases: object

One 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
to_dict()[source]

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

upper_ratio: float
within_envelope: bool
class femic.hydrology.flood.FloodEvent(event_date, value)[source]

Bases: object

One observed peak-flow event.

Parameters:
  • event_date (date)

  • value (float)

event_date: date
to_dict()[source]

Return the event as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Stationary 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
to_dict()[source]

Return the fit as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Return-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: object

One 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
to_dict()[source]

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.flood.FloodSample(station_id, years, values, regime='unknown')[source]

Bases: object

Annual-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
to_dict()[source]

Return the sample as a JSON-serializable mapping.

Return type:

dict[str, object]

values: tuple[float, ...]
years: tuple[int, ...]
class femic.hydrology.flood.FloodScenario(name, covariates)[source]

Bases: object

One covariate scenario for a response surface.

Parameters:
  • name (str)

  • covariates (dict[str, float])

covariates: dict[str, float]
name: str
to_dict()[source]

Return the scenario as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.flood.FrequencyPairingResult(baseline, treatment, return_periods, ratios, ratio_lower, ratio_upper, differences, warnings=(), caveats=())[source]

Bases: object

Baseline/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: RuntimeError

Raised 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: object

Nonstationary 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
to_dict()[source]

Return the fit as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Declustered 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
to_dict()[source]

Return the sample as a JSON-serializable mapping.

Return type:

dict[str, object]

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:
Return type:

FloodResponseSurface

femic.hydrology.flood.evaluate_frequency_benchmark(pairing, benchmark)[source]

Compare paired return-period ratios with a benchmark envelope.

Parameters:
Return type:

FloodBenchmarkCheck

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:

FloodSample

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:

PotSample

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:

FloodFrequencyFit

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:

NonstationaryGevFit

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:

FloodFrequencyFit

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:

FrequencyPairingResult

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:
Return type:

tuple[float, …]

femic.hydrology.flood.write_flood_frequency_report(fit, path)[source]

Write a stationary frequency fit as JSON.

Parameters:
Return type:

Path

femic.hydrology.flood.write_response_surface(surface, path)[source]

Write a flood response surface as JSON.

Parameters:
Return type:

Path