environmentaltools.spatiotemporal.indicators.fractional_exceedance_area

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

Compute fractional area exceeding threshold values.

Calculates the proportion of the spatial domain where values exceed each specified threshold. This indicator (RAEH - Ratio of Area Exceeding thresHold) is useful for assessing the spatial extent of threshold exceedances.

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.

  • exceedance_fractions (np.ndarray) – Fraction of area exceeding each threshold, ranging from 0 to 1.

Notes

The fractional exceedance area is computed as:

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

where \(N\) is the total number of spatial points, \(x_i\) are the data values, \(t\) is the threshold, and \(\mathbb{1}\) is the indicator function.

Examples

>>> import numpy as np
>>> data = np.random.normal(10, 2, 1000)
>>> thresholds, fractions = fractional_exceedance_area(data)
>>> # fractions[0] will be close to 1.0 (most area exceeds low threshold)
>>> # fractions[-1] will be close to 0.0 (little area exceeds high threshold)