environmentaltools.spatiotemporal.indicators.exceedance_to_nonexceedance_ratio

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

Compute ratio of exceedance area to non-exceedance area.

Calculates the ratio between the fraction of area exceeding each threshold and the fraction not exceeding it. This indicator (AEAN - Area Exceeding to Area Non-exceeding) becomes large when exceedances are prevalent and approaches zero when exceedances are rare.

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.

  • area_ratios (np.ndarray) – Ratio of exceedance area to non-exceedance area for each threshold.

Notes

The exceedance to non-exceedance ratio is computed as:

\[AEAN(t) = \frac{RAEH(t)}{1 - RAEH(t)} = \frac{N_e}{N - N_e}\]

where \(N_e\) is the number of points exceeding the threshold and \(N\) is the total number of points.

The ratio approaches infinity as the exceedance fraction approaches 1, and equals 0 when no points exceed the threshold.

Examples

>>> import numpy as np
>>> data = np.random.beta(2, 5, 1000) * 10
>>> thresholds, ratios = exceedance_to_nonexceedance_ratio(data)

Warning

Returns infinity for thresholds where all points exceed (100% exceedance).