elbow_helper.preprocessing module

Phase 1 — cleaning, robust normalization, and global-shape screening.

Turns raw (x, y) into a PreparedCurve on the unit square or raises Abstain with a reason code when the data are unusable or globally incompatible with the requested curve/direction.

Author

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

exception elbow_helper.preprocessing.Abstain(reason, **diagnostics)[source]

Bases: Exception

Internal control-flow signal carrying a reason code and diagnostics.

Parameters:

  • reason (str) – A Reason code explaining the abstention.

  • **diagnostics – Arbitrary supporting values, exposed to callers via diagnostics.

elbow_helper.preprocessing.infer_curve_direction(x_norm, y_scaled)[source]

Infer (curve, direction) from a cleaned, normalized curve.

direction is the sign of the Spearman correlation between x_norm and y_scaled: positive means increasing, negative means decreasing. curve is read off the sign of the (lightly smoothed) curve’s average signed deviation from the chord connecting its first and last point: a curve lying above its chord is concave (the mathematical definition, e.g. a square-root-shaped knee); a curve lying below its chord is convex (e.g. a k-means inertia elbow). Both reads are direction-agnostic, so they combine independently into all four concave/convex x increasing/decreasing cases.

Parameters:

  • x_norm (numpy.ndarray) – A cleaned, normalized curve on the unit square.

  • y_scaled (numpy.ndarray) – A cleaned, normalized curve on the unit square.

Returns:

(curve, direction), each one of the values accepted by prepare_curve().

Return type:

tuple of (str, str)

elbow_helper.preprocessing.prepare_curve(x, y, curve, direction, config)[source]

Clean, sort, deduplicate, normalize, and screen a curve.

Parameters:

  • x (array-like) – Raw input coordinates of equal length.

  • y (array-like) – Raw input coordinates of equal length.

  • curve (str or None) – "concave" or "convex" (passed through to the locator). If None, inferred from the data via infer_curve_direction().

  • direction (str or None) – "increasing" or "decreasing". If None, inferred from the data via infer_curve_direction().

  • config (RobustKneeConfig) – Thresholds; min_samples, min_spearman_abs and max_direction_violation_rate are consulted here.

Returns:

The normalized curve plus inverse-transform metadata, with curve and direction resolved to the actual values used (never None).

Return type:

PreparedCurve

Raises:

Abstain – With INVALID_INPUT, INSUFFICIENT_DATA, ZERO_RANGE or INCOMPATIBLE_GLOBAL_SHAPE when the data cannot be processed.

elbow_helper.preprocessing.prepare_curve_unconstrained(x, y, min_samples)[source]

Clean, sort, deduplicate and normalize a curve with no shape assumption.

Used by elbow_helper.robust_knees(): a multi-breakpoint search has no single global curve/direction to check against (segments may alternate slope sign freely), so this skips the shape-compatibility gate in prepare_curve() entirely. curve/direction on the returned PreparedCurve are set to "n/a" and unused.

Parameters:

  • x (array-like) – The raw curve.

  • y (array-like) – The raw curve.

  • min_samples (int) – Minimum number of points required after cleaning.

Returns:

The cleaned, normalized curve, ready for candidate search.

Return type:

PreparedCurve

Raises:

Abstain – With INVALID_INPUT, INSUFFICIENT_DATA or ZERO_RANGE.