environmentaltools.spatiotemporal.indicators.permanently_affected_zone

environmentaltools.spatiotemporal.indicators.permanently_affected_zone(data_cube, threshold, persistence_ratio=0.8)[source]

Calculate permanently affected zones based on threshold exceedance persistence.

Identifies spatial areas where a variable exceeds a threshold for a specified proportion of the time period. This is useful for identifying zones of chronic impact or persistent environmental stress.

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).

  • persistence_ratio (float, optional) – Minimum proportion of time for a cell to be considered permanently affected (e.g., 0.8 means 80% of the time). Default is 0.8.

Returns:

  • mask (np.ndarray) – Binary map of permanently affected zones (True = permanently affected).

  • freq_map (np.ndarray) – Map of exceedance frequency (0-1) for each spatial location.

Notes

A location is considered permanently affected if its exceedance frequency exceeds the persistence_ratio threshold. This helps distinguish between areas with occasional versus persistent exceedances.

Examples

>>> import numpy as np
>>> data_cube = np.random.lognormal(0, 1, (365, 25, 25))  # Daily data
>>> mask, freq = permanently_affected_zone(data_cube, threshold=2.0, persistence_ratio=0.75)
>>> print(f"Permanently affected area: {mask.sum()} cells")