toad.utils.cluster_consensus_utils

Functions

consensus_shift_time_distribution(td, ...[, ...])	Per-consensus-cluster event-time samples used to build summary shift columns.
consensus_shift_time_distributions(td, ...)	Plotting-friendly transition-time samples grouped by consensus cluster id.
infer_stitch_meridian(dataset, spatial_dims)	Return True when the native grid spans nearly all longitudes with a wrapped seam.
label_field_shift_time_distributions(td, ...)	Plotting-friendly transition-time samples grouped by cluster id in one label field.
label_field_shift_time_samples(td, da_labels)	Event-time of each spacetime cell with a non-noise label (one clustering, any kind).
resolve_stitch_meridian(setting, *, dataset, ...)	Resolve stitch_meridian from False, True, or "auto".

toad.utils.cluster_consensus_utils.consensus_shift_time_distribution(td, da_clusters, spatial_dims=None, time_dim=None)

Per-consensus-cluster event-time samples used to build summary shift columns.

Each sample is the numeric time coordinate at a spacetime voxel where both the consensus label and the input cluster_var are non-noise (>= 0) at the same (time, y, x). Dilated-only support or events at different timesteps on the same grid cell do not contribute.

This is stricter than Aggregation.consensus_extraction_mask_2d(), which collapses over time so that consensus at one timestep and an input cluster at another can still define the same spatial cell — that looser rule is for extracting full time series, not for timing statistics here.

Dataset (when clusterings exist):

• spatial_mean_transition_time / spatial_median_transition_time / spatial_std_transition_time — per (consensus_cluster_id, cluster_var) over the matching voxels above.

Summary table mapping:

• median_median_shift_time — median over cluster_var of spatial_median.

• std_median_shift_time — std over cluster_var of spatial_median.

• median_std_shift_time / std_std_shift_time — same for spatial_std.

• pooled_median_shift_time / pooled_std_shift_time — median and sample std of all transition_time rows for that id in the long dataframe.

Long DataFrame: columns consensus_cluster_id, cluster_var, transition_time (one row per matching voxel; the same (y, x) may appear multiple times at different timesteps).

Parameters:

• td (Any) – TOAD instance with cluster_vars and shifts.

• da_clusters (DataArray) – Time-resolved consensus clusters from Aggregation.compute_consensus().

• spatial_dims (Tuple[str, str] | None) – Grid dimension names; default tuple(td.space_dims).

• time_dim (str | None) – Time dimension of da_clusters if 3D; default td.time_dim when that dimension is present.

Returns:

(dataset, dataframe). If there are no cluster variables or no positive consensus labels, returns an empty Dataset and an empty DataFrame with the expected columns.

Return type:

tuple[Dataset, DataFrame]

toad.utils.cluster_consensus_utils.consensus_shift_time_distributions(td, da_clusters, spatial_dims=None, time_dim=None, *, distribution_result=None, source_input_cluster_var=None)

Plotting-friendly transition-time samples grouped by consensus cluster id.

This is a convenience wrapper around consensus_shift_time_distribution(). It aggregates the returned long-form dataframe across all input cluster_var values and returns one 1D numpy array per consensus cluster, suitable for violin plots or histograms.

The samples match the values underlying the summary shift columns. In spacetime mode this means a spatial cell can contribute multiple times if it appears in the same consensus component at multiple timesteps.

Parameters:

• distribution_result (tuple[Dataset, DataFrame] | None) – If provided, must be a value already returned from consensus_shift_time_distribution() for the same td, da_clusters, and options; the inner call is skipped (avoids duplicate work when both the dataset and grouped arrays are needed).

• source_input_cluster_var (str | None) – If set, keep only rows whose cluster_var column equals this name (one input clustering’s events for each consensus id).

• td (Any)

• da_clusters (DataArray)

• spatial_dims (Tuple[str, str] | None)

• time_dim (str | None)

Return type:

dict[int, ndarray]

toad.utils.cluster_consensus_utils.infer_stitch_meridian(dataset, spatial_dims)

Return True when the native grid spans nearly all longitudes with a wrapped seam.

Parameters:

• dataset (Dataset)

• spatial_dims (Tuple[str, str])

Return type:

bool

toad.utils.cluster_consensus_utils.label_field_shift_time_distributions(td, da_labels, spatial_dims=None, time_dim=None)

Plotting-friendly transition-time samples grouped by cluster id in one label field.

Pooled the same way as consensus_shift_time_distributions() (one array per id). In spacetime, the same cell can appear at multiple times if the cluster footprint spans several timesteps.

Parameters:

• td (Any)

• da_labels (DataArray)

• spatial_dims (Tuple[str, str] | None)

• time_dim (str | None)

Return type:

dict[int, ndarray]

toad.utils.cluster_consensus_utils.label_field_shift_time_samples(td, da_labels, spatial_dims=None, time_dim=None)

Event-time of each spacetime cell with a non-noise label (one clustering, any kind).

For each point where da_labels >= 0, records the numeric numeric_time_value at that timestep. Same time-coordinate convention as consensus_shift_time_distribution() for the consensus case (event times at labelled voxels), but without intersecting with other cluster maps—use a single 3D label field (e.g. a normal *cluster variable on td or consensus labels with one logical map if passed manually).

Parameters:

• td (Any) – TOAD instance (time coordinate, space_dims).

• da_labels (DataArray) – 3D cluster labels, (time, y, x) (or with time_dim as below).

• spatial_dims (Tuple[str, str] | None) – Defaults to tuple(td.space_dims).

• time_dim (str | None) – Defaults to td.time_dim when that dimension is present on da_labels.

Returns:

Long-form DataFrame with columns cluster_id, transition_time.

Return type:

DataFrame

toad.utils.cluster_consensus_utils.resolve_stitch_meridian(setting, *, dataset, spatial_dims)

Resolve stitch_meridian from False, True, or "auto".

Parameters:

• setting (bool | Literal['auto'])

• dataset (Dataset)

• spatial_dims (Tuple[str, str])

Return type:

bool