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.5, shift_direction='both')

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.

Parameters:

• cluster_ids (int | list[int] | range | 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 (float) – 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).

• shift_direction (Literal['both', 'positive', 'negative'] | str) – Sign of shifts to retain when locating the global peak per grid cell. Options are "both", "positive", and "negative" (same convention as toad.clustering.compute_clusters()). Defaults to "both".

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

Shifts are restricted to the requested sign before locating the global peak per grid cell via toad.utils.shift_selection_utils._peak_global_for_ts() (middle of any maximum-|shift| plateau), so e.g. shift_direction="negative" returns the timing of the largest negative shift.

Grid cells with no peak above shift_threshold in the requested direction return NaN.

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 | datetime64

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 | datetime | datetime64, float | datetime | datetime64]

iqr_68(cluster_id)

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

Return type:

tuple[float | datetime | datetime64, float | datetime | datetime64]

iqr_90(cluster_id)

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

Return type:

tuple[float | datetime | datetime64, float | datetime | datetime64]

mean(cluster_id)

Return mean time value of the cluster.

Return type:

float | datetime | datetime64

mean_shift_magnitude(cluster_id)

Alias for value_change(aggregation=”mean”).

Return type:

float

median(cluster_id)

Median model time while the cluster mask is active anywhere in space.

This summarises the cluster’s temporal footprint in the 3D cluster mask (equivalent to median_activity_time()). It is not the median per-cell peak shift time; for that, use pooled_median_transition_time().

Return type:

float | datetime | datetime64

median_activity_time(cluster_id)

Median model time while the cluster exists anywhere in space.

See median() for details.

Return type:

float | datetime | datetime64

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 | datetime64

membership_peak_density(cluster_id)

Return the largest cluster temporal density

Return type:

float

pooled_median_transition_time(cluster_id, shift_threshold=0.5)

Median of per-cell peak-shift times within the cluster.

Each grid cell contributes one transition time: the model time of maximum |shift| above shift_threshold (same field as compute_transition_time()). This pools all cells in the cluster, analogous to pooled_median_shift_time in Aggregation.consensus_summary().

Parameters:

• cluster_id (int)

• shift_threshold (float)

Return type:

float | datetime | datetime64

pooled_std_transition_time(cluster_id, shift_threshold=0.5)

Sample standard deviation of per-cell peak-shift times in the cluster.

Parameters:

• cluster_id (int)

• shift_threshold (float)

Return type:

float

start(cluster_id)

Return the start time of the cluster.

Return type:

float | datetime | datetime64

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 (largest rate of change, up or down) of the median cluster timeseries.

Return type:

float | datetime | datetime64

steepest_gradient_timestep(cluster_id)

Return the index of the steepest gradient (largest rate of change, up or down) of the median cluster timeseries inside the cluster time bounds.

Return type:

float

summary(cluster_ids=None, shift_threshold=0.5)

Per-cluster table of activity-time vs pooled transition-time summaries.

Returns one row per cluster with:

• median_activity_time — median timestep while the cluster mask is active anywhere in space (median_activity_time()).

• pooled_median_transition_time / pooled_std_transition_time — median and sample std of per-cell peak-shift times (pooled over all cells), matching the spirit of pooled_* columns in Aggregation.consensus_summary().

• n_transition_cells — number of cells with a finite transition time.

• start / end — first and last timestep with any cluster member.

Parameters:

• cluster_ids (int | list[int] | range | None)

• shift_threshold (float)

Return type:

DataFrame

value_at_end(cluster_id, aggregation='median')

Return aggregated cluster value at the end timestep.

Parameters:

aggregation (str)

Return type:

float

value_at_iqr_90_end(cluster_id, aggregation='median')

Return aggregated cluster value at the upper iqr_90 bound.

Parameters:

aggregation (str)

Return type:

float

value_at_iqr_90_start(cluster_id, aggregation='median')

Return aggregated cluster value at the lower iqr_90 bound.

Parameters:

aggregation (str)

Return type:

float

value_at_start(cluster_id, aggregation='median')

Return aggregated cluster value at the start timestep.

Parameters:

aggregation (str)

Return type:

float

value_change(cluster_id, aggregation='median')

Return signed aggregated value change across full span (end - start).

Parameters:

aggregation (str)

Return type:

float

value_change_iqr_90(cluster_id, aggregation='median')

Return signed aggregated value change across iqr_90 bounds (upper - lower).

Parameters:

aggregation (str)

Return type:

float