environmentaltools.spatiotemporal.indicators.functional_area_loss

environmentaltools.spatiotemporal.indicators.functional_area_loss(data_cube, threshold, t_start, t_end)[source]

Calculate functional area loss between two time points.

Compares functional areas (defined by threshold exceedance) between two time points to quantify spatial losses. This is useful for assessing habitat loss, service area degradation, or similar applications.

Parameters:

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

  • threshold (float) – Threshold defining functional status.

  • t_start (int) – Time indices to compare.

  • t_end (int) – Time indices to compare.

Returns:

  • loss_map (np.ndarray) – Binary map of loss areas (1 = loss occurred, 0 = no loss).

  • area_start, area_end (int) – Number of functional cells at start and end times.

Notes

A cell experiences functional loss if it was above threshold at t_start but below threshold at t_end. The analysis identifies which specific areas have lost functionality between the two time points.

Examples

>>> import numpy as np
>>> data_cube = np.random.random((100, 25, 25))
>>> loss_map, area_start, area_end = functional_area_loss(data_cube, 0.5, 10, 90)
>>> print(f"Area lost: {loss_map.sum()} cells")