environmentaltools.spatiotemporal.indicators.threshold_exceedance_frequency

environmentaltools.spatiotemporal.indicators.threshold_exceedance_frequency(data_cube, threshold)[source]

Calculate frequency of threshold exceedance for each spatial cell.

Computes how many times each spatial location exceeds a given threshold across the time dimension. This provides a measure of temporal persistence of exceedance conditions.

Parameters:

  • data_cube (np.ndarray) – 3D array with shape (time, lat, lon) containing spatiotemporal data.

  • threshold (float or np.ndarray) – Fixed threshold value or 2D array of spatially-varying thresholds with shape (lat, lon).

Returns:

freq_map – 2D map showing number of times threshold is exceeded at each location.

Return type:

np.ndarray

Notes

For a fixed threshold, exceedance is computed as data_cube > threshold. For spatially-varying thresholds, each spatial cell is compared against its corresponding threshold value.

The frequency map provides insight into which areas are most prone to threshold exceedances over time.

Examples

>>> import numpy as np
>>> data_cube = np.random.exponential(2, (100, 20, 20))
>>> freq_map = threshold_exceedance_frequency(data_cube, threshold=3.0)
>>> print(f"Max exceedances: {freq_map.max()}")