toad.postprocessing.stats.time

Classes

TimeStats(toad, var)

Class containing functions for calculating time-related statistics for clusters, such as start time, peak time, etc.

class toad.postprocessing.stats.time.TimeStats(toad, var)

Bases: object

Class containing functions for calculating time-related statistics for clusters, such as start time, peak time, etc.

all_stats(cluster_id)

Return all cluster stats

Return type:

dict

compute_transition_time(cluster_ids=None, shift_threshold=0.25)

Computes the transition time for each grid cell.

This method identifies the time point of maximum rate of change (peak shift) for each spatial location in the data. It uses the absolute value of shifts to detect both positive and negative transitions.

Parameters:

• cluster_ids (int | list[int] | None) – Optional integer or list of integers specifying which cluster IDs to analyze. If None, analyzes all clusters. If specified, only analyzes grid cells belonging to the given cluster(s).

• shift_threshold – Optional float specifying the minimum absolute shift value that should be considered a valid transition. Defaults to 0.5. Grid cells with maximum shift values below this threshold will be marked as having no transition (NaN).

Returns:

xarray DataArray containing the transition time for each grid cell. Grid cells with no detected transition will contain NaN values. The output has the same spatial dimensions as the input shifts data.

Return type:

DataArray

Note

The transition time is determined by finding the time index where the absolute value of the shifts reaches its maximum for each grid cell. This corresponds to the point of most rapid change in the underlying data.

For grid cells where the maximum absolute shift value is below shift_threshold, or where no clear transition is detected, NaN values will be returned.

duration(cluster_id)

Return duration of the cluster in time.

Parameters:

cluster_id – ID of the cluster to calculate duration for.

Returns:

Duration of the cluster. If the original dataset uses cftime format,

the duration is returned in seconds.

Return type:

float

duration_timesteps(cluster_id)

Return duration of the cluster in timesteps.

Return type:

int

end(cluster_id)

Return the end time of the cluster.

Return type:

float | datetime

end_timestep(cluster_id)

Return the end index of the cluster

Return type:

int

iqr(cluster_id, lower_quantile, upper_quantile)

Get start and end time of the specified interquantile range of the cluster temporal density.

Parameters:

• cluster_id – ID of the cluster

• lower_quantile (float) – Lower bound of the interquantile range (0-1)

• upper_quantile (float) – Upper bound of the interquantile range (0-1)

Returns:

Start time and end time of the interquantile range in original time format

Return type:

tuple

iqr_50(cluster_id)

Get start and end time of the 50% interquantile range of the cluster temporal density

Return type:

tuple[float, float]

iqr_68(cluster_id)

Get start and end time of the 68% interquantile range of the cluster temporal density

Return type:

tuple[float, float]

iqr_90(cluster_id)

Get start and end time of the 90% interquantile range of the cluster temporal density

Return type:

tuple[float, float]

mean(cluster_id)

Return mean time value of the cluster.

Return type:

float | datetime

median(cluster_id)

Return median time of the cluster.

Return type:

float | datetime

membership_peak(cluster_id)

Return the time of the largest cluster temporal density.

If there’s a plateau at the maximum value, returns the center of the plateau.

Return type:

float | datetime

membership_peak_density(cluster_id)

Return the largest cluster temporal density

Return type:

float

start(cluster_id)

Return the start time of the cluster.

Return type:

float | datetime

start_timestep(cluster_id)

Return the start index of the cluster

Return type:

float

std(cluster_id)

Return standard deviation of the time of the cluster.

Return type:

float

steepest_gradient(cluster_id)

Return the time of the steepest gradient of the median cluster timeseries

Return type:

float | datetime

steepest_gradient_timestep(cluster_id)

Return the index of the steepest gradient of the mean cluster timeseries inside the cluster time bounds

Return type:

float