elbow_helper.clustering module

Phase 5 — persistence clustering, uniqueness, and scale selection.

Groups candidate knees that recur at nearby locations across the smoothing scales and sensitivities, measures how persistent each group is, rejects the ambiguous multi-knee case, and picks the smallest stable smoothing scale of the winning cluster.

Author

Warith Harchaoui, <warith.harchaoui@deraison.ai>

elbow_helper.clustering.cluster_candidates(candidates, prepared, config)[source]

Cluster candidates by location and score each cluster’s persistence.

Parameters:

candidates (list of KneeCandidate) – Candidates that already passed the basic filters.
prepared (PreparedCurve) – The curve (for the total candidate count and window grid).
config (RobustKneeConfig) – cluster_tolerance and the persistence thresholds.

Returns:

Clusters sorted by support (descending), each flagged persistent.

Return type:

list of CandidateCluster

elbow_helper.clustering.select_unique_cluster(clusters, config)[source]

Pick the single dominant persistent cluster, or explain the abstention.

Parameters:

clusters (list of CandidateCluster) – All clusters (sorted by support).
config (RobustKneeConfig) – secondary_support_frac and min_dominance_ratio.

Returns:

(cluster, None) on success, or (None, reason_code) when there is no persistent cluster or the winner is not clearly dominant.

Return type:

tuple