elbow_helper.metrics module

Phase 4 — per-candidate metrics and basic rejection filters.

Given a raw KneeCandidate (location + the difference curve it came from), attach its prominence, local-noise estimate, prominence-to-noise ratio and boundary distance, then decide whether it clears the cheap structural filters before any expensive stability analysis.

Author

Warith Harchaoui, <warithmetics@deraison.ai>

elbow_helper.metrics.evaluate_candidate(candidate, y_difference, threshold_index, y_scaled)[source]

Fill in a candidate’s prominence, noise, ratio and boundary distance.

Parameters:

  • candidate (KneeCandidate) – The candidate to annotate (mutated in place and returned).

  • y_difference (numpy.ndarray) – The difference curve the candidate was found on.

  • threshold_index (int) – Index of the generating peak on y_difference.

  • y_scaled (numpy.ndarray) – The (unsmoothed) scaled signal, for the robust noise estimate.

Returns:

The same object, with metric fields populated.

Return type:

KneeCandidate

elbow_helper.metrics.passes_basic_filters(candidate, n, config)[source]

Return True iff a candidate survives the cheap structural filters.

Sets candidate.rejected to a reason code when it fails. Rejections: within the boundary margin, too few points on one side, within half a smoothing window of an end, weak prominence, or weak prominence-to-noise.

The boundary margin is the wider of boundary_margin (a fraction of the range) and boundary_min_samples (a count), because the two things it guards against scale differently – see the field comments on RobustKneeConfig. Taken as a fraction alone it silently got stricter the longer the curve was, and on a long one it did worse than miss an early knee: it rejected the knee at its true position while keeping the drifted copy the coarse smoothing scales put further in. A 200-point curve whose plateau begins at index 11 had candidates at 11, 13, 14, 15 and 18 all thrown out as boundary artefacts, and the cluster that survived to be reported sat at 21.

Parameters:
Returns:

Whether the candidate passes.

Return type:

bool