Skip to content

Climate Analysis

Salvador Navas edited this page Jul 3, 2026 · 2 revisions

Climate Analysis

The pyhydra.climate package contains time-series analysis, bias correction, spatial statistics and stochastic generation tools.

Time-Series Events

Package: pyhydra.climate.time_series.events

Main APIs:

  • extract_events
  • extract_discharge_events
  • extract_precipitation_events
  • extract_precipitation_events_pot
  • extract_precipitation_events_nday
  • extract_concurrent_events

Typical uses include separating rainfall spells, extracting independent POT events and pairing event windows across multiple hydroclimatic series.

Extreme-Value Analysis

Package: pyhydra.climate.time_series.extremes

Main APIs:

  • extract_block_maxima
  • extract_pot
  • threshold_stability_plot
  • fit_gev
  • fit_gpd
  • return_level_gev
  • return_level_gpd
  • return_levels
  • return_level_ci
  • plot_return_levels
  • plot_diagnostic

Example:

from pyhydra.climate.time_series import extract_block_maxima, fit_gev, return_levels

annual_maxima = extract_block_maxima(series, freq="YE")
params = fit_gev(annual_maxima, method="mle")
levels = return_levels(params, [10, 50, 100], dist="gev")

Bayesian and Fisher-information variants are available through:

  • fit_gev_map
  • fit_gev_fisher
  • fit_gev_mcmc

Use them only when their assumptions and dependencies are appropriate for the study.

Model-Performance Statistics

Package: pyhydra.climate.time_series.stats

  • compute_nse
  • compute_kge
  • compute_pbias

These functions compare observed and simulated series.

Bias Correction

Package: pyhydra.climate.bias_correction

Main APIs:

  • delta_method
  • BiasCorrection

BiasCorrection provides empirical quantile mapping, quantile delta mapping and scaled distribution mapping workflows. Typical usage:

from pyhydra.climate.bias_correction import BiasCorrection

corrected = BiasCorrection.fit_transform(
    obs=obs_series,
    hist=historical_model_series,
    future=future_model_series,
    var="pr",
    method="qdm",
)

Spatial Analysis

Package: pyhydra.climate.spatial_analysis

Regional Frequency Analysis

  • fit_gev_mle
  • fit_gev_lmom
  • fit_gev_bayes
  • return_level
  • return_level_bayes
  • regional_index_flood
  • fit_regional_gev
  • regional_return_levels
  • regional_discordancy
  • discordancy_critical_value
  • regional_heterogeneity

Example:

from pyhydra.climate.spatial_analysis import regional_return_levels

levels = regional_return_levels(
    annual_maxima_by_station,
    T_values=[10, 50, 100, 500],
)

fit_regional_gev/regional_return_levels also accept method="bayes": the pooled, normalised data are fit with fit_gev_bayes (PyMC), and regional_return_levels then returns a (median, lower, upper) tuple of DataFrames — each station's regional posterior scaled by its own index flood — instead of a single point-estimate DataFrame.

Homogeneity Diagnostics (Hosking & Wallis 1997)

Before pooling stations into a region, check that the pooling is statistically justified. Formulas are cross-checked against Hosking & Wallis's own reference implementation (lmomRFA::regtst.s(), R package lmomRFA):

  • regional_discordancy(data_dict) — per-station discordancy statistic Di (a Mahalanobis-type distance between a station's L-CV/L-skew/ L-kurtosis and the regional average) plus the Hosking & Wallis (1997, Table 3.1) critical value and a discordant flag.
  • discordancy_critical_value(n_sites) — the critical value alone.
  • regional_heterogeneity(data_dict, n_sim=1000) — the H statistic, from Monte Carlo simulation of homogeneous regions drawn from a kappa distribution fitted to the record-length-weighted regional-average L-moments. H < 1: acceptably homogeneous; 1 <= H < 2: possibly heterogeneous; H >= 2: definitely heterogeneous — do not pool as a single region.

Both require lmoments3 (see Installation).

Interpolation

  • IDWInterpolator
  • KrigingInterpolator
  • GaussianProcessInterpolator
  • NeopreneGPReconstructor
  • CopulaCDFEmulator

Kriging and Gaussian-process workflows require optional dependencies and careful validation against station density and spatial covariance assumptions.

Copulas

  • FloodEventCopula
  • fit_marginal
  • fit_discrete_marginal
  • BivariateCopula
  • TrivariateCopula
  • VineCopula
  • GaussianCopulaSampler

Copula workflows are intended for dependence modelling in multivariate event analysis and synthetic event generation.

Bayesian Hierarchical GEV

  • HierarchicalGEV

This module supports hierarchical modelling workflows and should be interpreted with the same care as any Bayesian extreme-value model.

Clone this wiki locally