elbow_helper.explain module

Human-readable detail lines for every abstention, in English or French.

A Reason code says which gate closed. It does not say whether the curve is hopeless or merely noisy, and those call for opposite responses: measure more finely, or stop looking. A user who reads NO_PERSISTENT_CLUSTER and nothing else has no way to tell the two apart.

Every gate in the pipeline is a number against a threshold, and both are in hand the moment it closes. These renderers put them in the sentence: what was measured, what it had to clear, and – where the quantity is a position – in the caller’s own x units rather than the normalized ones the gate works in. The result rides along as NoClearKnee.detail and as diagnostics["detail"]; the Reason code itself is untouched, so anything matching on it keeps working.

The sentences are assembled from _STRINGS, the same shape elbow_helper.plotting uses for its chrome text, and the language comes from RobustKneeConfig.language. Phrasing lives here rather than in each consumer because the logic that decides which clauses apply – which of four persistence gates failed, whether held-out error fell short or rose – is the part worth writing once. A presentation layer that only had the reason code would have to re-derive all of it to say anything more specific than the code itself.

Author

Warith Harchaoui, <warithmetics@deraison.ai>

elbow_helper.explain.detail_for(reason, prepared, config, *, seg=None, boot=None, null=None)[source]

Render the detail for a pipeline-stage abstention.

Parameters:

  • reason (str) – The Reason code being explained.

  • prepared (PreparedCurve or None) – The prepared curve, when the stage had one.

  • config (RobustKneeConfig) – The thresholds in force, and the language.

  • seg (optional) – Whichever stage’s evidence produced reason.

  • boot (optional) – Whichever stage’s evidence produced reason.

  • null (optional) – Whichever stage’s evidence produced reason.

Returns:

A detail sentence, or "" when the reason needs no elaboration.

Return type:

str

elbow_helper.explain.explain_bootstrap(boot, prepared, config)[source]

Say which bootstrap stability check the knee failed.

Parameters:
Returns:

One sentence naming the checks that failed.

Return type:

str

elbow_helper.explain.explain_candidates(candidates, prepared, config)[source]

Say why no candidate survived the cheap structural filters.

Parameters:

  • candidates (list of KneeCandidate) – Every candidate generated, each carrying the rejected code the filter that killed it left behind.

  • prepared (PreparedCurve) – For reporting distances in the caller’s x units.

  • config (RobustKneeConfig) – The thresholds the candidates were measured against, and the language.

Returns:

One sentence naming the dominant rejection and its margin.

Return type:

str

elbow_helper.explain.explain_clusters(clusters, reason, prepared, config)[source]

Say why no single cluster of candidates could be accepted.

Parameters:

  • clusters (list of CandidateCluster) – Every cluster found, persistent or not.

  • reason (str) – The Reason code being explained.

  • prepared (PreparedCurve) – For reporting locations in the caller’s x units.

  • config (RobustKneeConfig) – The persistence and uniqueness thresholds, and the language.

Returns:

One sentence naming the failed gates and their margins.

Return type:

str

elbow_helper.explain.explain_insufficient(n, min_samples, language='en')[source]

Say how far short of min_samples the curve fell.

Takes min_samples and language rather than a config because the cleaning stage that raises this runs before any config-wide state is in scope.

Parameters:

  • n (int) – Usable points found after cleaning.

  • min_samples (int) – The configured minimum.

  • language (str, optional) – "en" (default) or "fr".

Returns:

A detail sentence naming the shortfall and the way past it.

Return type:

str

elbow_helper.explain.explain_null(null, config)[source]

Say how often a knee-free curve would have looked this convincing.

Parameters:
Returns:

One sentence putting the p-value against its threshold.

Return type:

str

elbow_helper.explain.explain_segment(seg, prepared, config)[source]

Say why the two-line model did not beat the one-line model.

Parameters:

  • seg (SegmentEvidence) – The confirmation stage’s measurements.

  • prepared (PreparedCurve) – Unused here; kept so every renderer takes the same arguments.

  • config (RobustKneeConfig) – The confirmation thresholds, and the language.

Returns:

One sentence naming the criteria that fell short.

Return type:

str

elbow_helper.explain.explain_shape(spearman, violation, config)[source]

Say which global-shape screen the curve failed.

Parameters:

  • spearman (float) – The measured rank correlation.

  • violation (float) – The measured direction-violation rate.

  • config (RobustKneeConfig) – The screen’s thresholds, and the language.

Returns:

One sentence naming the screens that failed.

Return type:

str