Statistics¶

cluster_stats ¶

Cluster population statistics and frame assignments.

assign_clusters(dataset: Dataset, labels: ndarray) -> None

Attach cluster labels to frame records in a dataset.

Parameters:

Name	Type	Description	Default
`dataset`	`Dataset`	Dataset whose frames will be updated in place.	required
`labels`	`ndarray`	Cluster label per frame, shape `(n_frames,)`.	required

Raises:

Type	Description
`ValueError`	If label count does not match the number of frames.

compute_cluster_stats(dataset: Dataset) -> ClusterStats

Compute per-cluster populations and frame lists.

Parameters:

Name	Type	Description	Default
`dataset`	`Dataset`	Dataset with cluster assignments on each frame record.	required

Returns:

Type	Description
`dict`	Mapping from `cluster_id` to population and frame list.

Raises:

Type	Description
`ValueError`	If any frame lacks a cluster assignment.

sort_clusters_by_population(cluster_stats: ClusterStats, ascending: bool = True) -> List[int]

Return cluster IDs sorted by population.

Parameters:

Name	Type	Description	Default
`cluster_stats`	`dict`	Per-cluster statistics from :func:`compute_cluster_stats`.	required
`ascending`	`bool`	If `True`, smallest populations first.	`True`

Returns:

Type	Description
`list of int`	Sorted cluster IDs.

cluster_stats_to_rows(cluster_stats: ClusterStats) -> List[Dict[str, int]]

Convert cluster statistics to flat rows for CSV export.

Parameters:

Name	Type	Description	Default
`cluster_stats`	`dict`	Per-cluster statistics.	required

Returns:

Type	Description
`list of dict`	Rows with keys `cluster_id` and `population`.