Membership Helper

GitHub Link to Code.

Helper modules for membership plotter.

Block Optimizer Helper

Helper for optimizing cluster label sequences to plotting blocks.

Converts frame-by-frame cluster labels into contiguous blocks for efficient visualization, reducing the number of matplotlib draw calls from O(n_frames) to O(n_transitions).

class mdxplain.plots.plot_type.membership.helper.block_optimizer_helper.BlockOptimizerHelper

Helper class for optimizing cluster label sequences.

Converts sequential cluster labels into block representations (start_frame, end_frame, cluster_id) for efficient plotting.

Examples

>>> # Convert labels to blocks
>>> labels = np.array([0, 0, 0, 1, 1, 2, 2, 2])
>>> blocks = BlockOptimizerHelper.labels_to_blocks(labels)
>>> blocks
[(0, 2, 0), (3, 4, 1), (5, 7, 2)]

>>> # Single cluster
>>> labels = np.array([5, 5, 5, 5])
>>> blocks = BlockOptimizerHelper.labels_to_blocks(labels)
>>> blocks
[(0, 3, 5)]

static labels_to_blocks(labels: ndarray) → List[Tuple[int, int, int]]

Convert cluster label array to block representation.

Groups consecutive identical cluster labels into contiguous blocks for efficient plotting. Reduces draw calls from O(n_frames) to O(n_transitions).

Parameters

labelsnumpy.ndarray, shape (n_frames,): Cluster label for each frame

Returns

List[Tuple[int, int, int]]: List of (start_frame, end_frame, cluster_id) blocks. Indices are inclusive on both ends.

Examples

>>> # Three clusters with transitions
>>> labels = np.array([0, 0, 0, 1, 1, 2, 2, 2])
>>> blocks = BlockOptimizerHelper.labels_to_blocks(labels)
>>> blocks
[(0, 2, 0), (3, 4, 1), (5, 7, 2)]

>>> # With noise (-1)
>>> labels = np.array([0, 0, -1, -1, 1, 1])
>>> blocks = BlockOptimizerHelper.labels_to_blocks(labels)
>>> blocks
[(0, 1, 0), (2, 3, -1), (4, 5, 1)]

>>> # Empty array
>>> labels = np.array([])
>>> blocks = BlockOptimizerHelper.labels_to_blocks(labels)
>>> blocks
[]

Notes

Uses vectorized numpy operations for performance:

np.diff() to detect label changes
np.where() to find transition points
O(n) time complexity, minimal memory overhead