Skip to content

sgam.disturbance

sgam.disturbance

Disturbance detection module for SGAM.

This module provides functionality to identify disturbance events (such as harvest, fire, or pest damage) based on rapid declines in GPP and LAI.

Functions:

Classes:

  • Disturbances –

    Identify disturbance events and compute their severity.

Disturbances 

Disturbances(growing_season_limit: float, disturbance_threshold: float)

Disturbance event detector.

Identifies disturbance events based on rapid declines in GPP and LAI during the growing season. Disturbances include events such as harvest, fire, pest damage, or other biomass-removing events.

Attributes:

  • growing_season_limit –

    Minimum temperature (°C) defining the growing season. Days with temperature above this threshold are considered within the growing season and eligible for disturbance detection.

  • disturbance_threshold –

    Fractional decline threshold (0-1). A disturbance event is detected when both GPP and LAI decline by more than this fraction in a single day.

Example

disturbances = Disturbances(growing_season_limit=15.0, disturbance_threshold=0.3) temperature = np.array([20.0, 20.0, 20.0, 20.0]) gpp = np.array([5.0, 5.0, 1.0, 1.0]) lai = np.array([1.0, 1.0, 0.2, 0.2]) result = disturbances.forward(temperature, gpp, lai)

Initialize the Disturbances detector.

Parameters:

  • growing_season_limit (float) –

    Minimum temperature (°C) defining the growing season.

  • disturbance_threshold (float) –

    Fractional decline threshold (0-1) for detecting disturbances.

__call__ 

__call__(temperature: NDArray[float64], gpp: NDArray[float64], lai: NDArray[float64], aggregate: bool = False) -> NDArray[float64]

Identify disturbance events and compute their severity.

This is an alias for forward.

Parameters:

  • temperature (NDArray[float64]) –

    Daily temperature values (°C).

  • gpp (NDArray[float64]) –

    Daily GPP values (gC m⁻² day⁻¹).

  • lai (NDArray[float64]) –

    Daily LAI values (m² m⁻²).

  • aggregate (bool, default: False ) –

    If True, aggregate daily results to weekly timesteps.

Returns:

  • NDArray[float64] –

    Disturbance severity as a fraction of biomass lost (0-1).

forward 

forward(temperature: NDArray[float64], gpp: NDArray[float64], lai: NDArray[float64], aggregate: bool = False) -> NDArray[float64]

Identify disturbance events and compute their severity.

A disturbance event is detected when all three conditions are met: 1. Temperature exceeds the growing season threshold 2. GPP declines by more than the disturbance threshold (fraction) 3. LAI declines by more than the disturbance threshold (fraction)

Note: Input data should be at DAILY timestep.

Parameters:

  • temperature (NDArray[float64]) –

    Daily temperature values (°C).

  • gpp (NDArray[float64]) –

    Daily GPP values (gC m⁻² day⁻¹).

  • lai (NDArray[float64]) –

    Daily LAI values (m² m⁻²).

  • aggregate (bool, default: False ) –

    If True, aggregate daily results to weekly timesteps by taking the maximum within each 7-day window. If False (default), return daily values.

Returns:

  • NDArray[float64] –

    Disturbance severity as a fraction of biomass lost (0-1).

  • NDArray[float64] –

    Non-disturbance days have value 0.

  • NDArray[float64] –

    If aggregate=True, values are weekly; otherwise daily.

aggregate_to_weekly 

aggregate_to_weekly(daily_severity: NDArray[float64]) -> NDArray[float64]

Aggregate daily disturbance severity to weekly timesteps.

Takes the maximum daily severity observed within each 7-day window. If the input length is not a multiple of 7, it is padded with zeros.

Parameters:

  • daily_severity (NDArray[float64]) –

    Array of daily disturbance severity values.

Returns:

  • NDArray[float64] –

    Array of weekly maximum disturbance severity values.