environmentaltools.spatiotemporal.indicators.mean_excess_over_exceedance_area

environmentaltools.spatiotemporal.indicators.mean_excess_over_exceedance_area(data, thresholds=None)

Compute mean excess (difference from threshold) over exceedance area only.

Calculates the average amount by which values exceed each threshold, considering only the spatial points where exceedance occurs. This indicator (WMDW - Weighted Mean excess Difference over exceedance area) provides the conditional mean excess given that the threshold is exceeded.

Parameters:

• data (array_like) – 1D array of spatial data values to analyze.

• thresholds (array_like, optional) – Array of threshold values to evaluate. If None, generates 100 equally spaced thresholds from 0 to the maximum data value.

Returns:

• thresholds (np.ndarray) – Array of threshold values used in the analysis.

• conditional_excess (np.ndarray) – Mean excess values conditional on exceeding each threshold.

Notes

The mean excess over exceedance area is computed as:

\[WMDW(t) = \frac{\sum_{i: x_i \geq t} (x_i - t)}{\sum_{i=1}^{N} \mathbb{1}(x_i \geq t)}\]

This represents the expected excess conditional on exceeding the threshold: \(E[X - t | X \geq t]\), also known as the mean excess function in extreme value theory.

Examples

>>> import numpy as np
>>> data = np.random.pareto(2, 1000)
>>> thresholds, cond_excess = mean_excess_over_exceedance_area(data)