environmentaltools.spatiotemporal.indicators.mean_excess_over_total_area

environmentaltools.spatiotemporal.indicators.mean_excess_over_total_area(data, thresholds=None)[source]

Compute mean excess (difference from threshold) normalized by total area.

Calculates the average amount by which values exceed each threshold, normalized by the total number of spatial points. This indicator (MEDW - Mean Excess Difference over Whole domain) measures the average magnitude of exceedances over the entire domain.

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.

  • mean_excess (np.ndarray) – Mean excess values (difference from threshold) normalized by total area.

Notes

The mean excess over total area is computed as:

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

This provides a measure of how much, on average across the entire domain, values exceed the threshold.

Examples

>>> import numpy as np
>>> data = np.random.gamma(2, 2, 1000)
>>> thresholds, excess = mean_excess_over_total_area(data)