environmentaltools.temporal.annual_maxima_method

environmentaltools.temporal.annual_maxima_method(df, alpha, method, func, resample, ci_method, tr=None)[source]

Fit GEV or Gumbel distribution to annual maxima with bootstrap CI.

Performs extreme value analysis using annual maxima approach. Fits Generalized Extreme Value (GEV) or Gumbel distribution with bootstrap resampling to estimate confidence intervals.

Parameters:

  • df (pd.DataFrame) – Time series data with datetime index

  • alpha (float) – Significance level for confidence intervals (e.g., 0.05 for 95% CI)

  • method ({'MLE', 'L-MOM'}) –

    Parameter estimation method:

    • ’MLE’: Maximum Likelihood Estimation

    • ’L-MOM’: L-moments method

  • func (str or scipy.stats distribution) –

    Distribution to fit:

    • For L-MOM: ‘genextreme’, ‘gumbel_r’

    • For MLE: scipy.stats distribution object (e.g., st.genextreme)

  • resample ({'parametric', 'non-parametric'}) – Bootstrap resampling method

  • ci_method ({'standard', 'bca'}) –

    Confidence interval computation method:

    • ’standard’: Percentile method

    • ’bca’: Bias-corrected and accelerated

  • tr (array-like, optional) – Return periods to evaluate (in years). If None, uses default range from 1.1 to 1000 years

Returns:

  • tr (np.ndarray) – Return periods evaluated

  • pannumax (np.ndarray) – Plotting positions for annual maxima

  • annumax (pd.Series) – Annual maxima values

  • boot (list of lists) – Bootstrap results [GEV_results, Gumbel_results (if applicable)]

  • orig (list of lists) – Original parameter estimates

  • ci (list of lists) – Confidence intervals

Notes

The annual maxima method:

  1. Extracts one maximum value per year

  2. Fits GEV distribution: F(x) = exp{-[1+ξ(x-μ)/σ]^(-1/ξ)}

  3. If shape parameter CI includes 0, also fits Gumbel (ξ=0)

Return levels are computed as: x_T = F^(-1)(1 - 1/T)

Gumbel is a special case of GEV with shape parameter ξ=0.

Raises:

ValueError – If invalid method, function, resample, or ci_method specified

Examples

>>> df = pd.DataFrame({
...     'Hs': np.random.weibull(1.5, 3650)
... }, index=pd.date_range('2010', periods=3650, freq='D'))
>>> tr, p, maxima, boot, orig, ci = annual_maxima_method(
...     df, alpha=0.05, method='L-MOM', func='genextreme',
...     resample='parametric', ci_method='standard'
... )