elbow_helper.search module

The shared inner search: candidates -> filter -> cluster -> confirm.

Factored out so the main pipeline, the bootstrap replicates, and the null-test replicates all run the same detection logic. The search-adjusted test statistic (used by the null test) is a lexicographic tuple, in decreasing priority: passed model confirmation, cluster dominance, prominence-to-noise.

Author

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

class elbow_helper.search.SearchResult(detected, reason=None, knee_x_norm=None, window=None, cluster=None, segment=None, statistic=(0, 0.0, 0.0), n_candidates=0, n_filtered=0)

Bases: object

Outcome of one inner detection pass over a (prepared) curve.

Parameters:

• detected (bool)

• reason (str | None)

• knee_x_norm (float | None)

• window (int | None)

• cluster (CandidateCluster | None)

• segment (SegmentEvidence | None)

• statistic (Tuple[int, float, float])

• n_candidates (int)

• n_filtered (int)

cluster: CandidateCluster | None = None

detected: bool

knee_x_norm: float | None = None

n_candidates: int = 0

n_filtered: int = 0

reason: str | None = None

segment: SegmentEvidence | None = None

statistic: Tuple[int, float, float] = (0, 0.0, 0.0)

window: int | None = None

elbow_helper.search.run_search(prepared, config, confirm=True)

Run the full inner detection pass (no bootstrap, no null test).

Parameters:

• prepared (PreparedCurve) – The normalized curve.

• config (RobustKneeConfig) – Search thresholds.

• confirm (bool, optional) – Whether to run the segmented-model confirmation (Phase 6). The main pipeline and the null test set this True; the bootstrap sets it False for speed (it re-tests stability, not model fit).

Returns:

detected with the winning cluster and statistic or an abstention with a reason code.

Return type:

SearchResult