elbow_helper.types module

Result and intermediate data types for the robust knee detector.

The public contract is a tagged union: elbow_helper.robust_knee() always returns either a ClearKnee or a NoClearKnee, both subclasses of KneeResult, so callers must handle abstention explicitly. Every NoClearKnee carries a machine-readable Reason code plus a diagnostics dict; every ClearKnee carries the full evidence chain.

Author

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

class elbow_helper.types.BootstrapEvidence(passes, detection_rate, ci90, ci90_width, primary_cluster_rate, secondary_cluster_rate, median_shift, knees, reason=None)[source]

Bases: object

Stability of the detected knee across residual-bootstrap replicates.

Parameters:
passes

Whether the detection rate, CI width and cluster-rate checks passed.

Type:

bool

detection_rate

Fraction of bootstrap replicates in which a knee was redetected.

Type:

float

ci90

The 5th-95th percentile interval of redetected locations, data units.

Type:

tuple of float

ci90_width

Width of ci90, in normalized x units.

Type:

float

primary_cluster_rate

Fraction of redetections in the dominant location cluster.

Type:

float

secondary_cluster_rate

Fraction of redetections in the next-largest location cluster.

Type:

float

median_shift

Shift between the observed knee and the median redetected location.

Type:

float

knees

The redetected knee locations, one per successful replicate.

Type:

list of float

reason

A Reason code if a check failed, None otherwise.

Type:

str, optional

ci90: Tuple[float, float]
ci90_width: float
detection_rate: float
knees: List[float]
median_shift: float
passes: bool
primary_cluster_rate: float
reason: str | None = None
secondary_cluster_rate: float
class elbow_helper.types.CandidateCluster(median_knee, mad, members, n_windows, consecutive_scales, sensitivity_support, neighbor_shift, support, support_frac, median_prominence, median_noise_prominence_ratio, persistent=False, stable_window=None)[source]

Bases: object

A group of candidates at nearby knee locations across the scale space.

Parameters:
median_knee

Median normalized location of the cluster’s members.

Type:

float

mad

Median absolute deviation of the members’ locations.

Type:

float

members

The candidates in this cluster.

Type:

list of KneeCandidate

n_windows

Number of distinct smoothing windows represented.

Type:

int

consecutive_scales

Longest run of consecutive smoothing scales the cluster spans.

Type:

int

sensitivity_support

Fraction of distinct sensitivities represented.

Type:

float

neighbor_shift

Largest jump in per-window median location between adjacent windows.

Type:

float

support

Number of member candidates.

Type:

int

support_frac

support divided by the total candidate count.

Type:

float

median_prominence

Median prominence across members.

Type:

float

median_noise_prominence_ratio

Median noise-prominence ratio across members.

Type:

float

persistent

Whether this cluster cleared the persistence gates.

Type:

bool

stable_window

Smallest smoothing window meeting the sensitivity-support threshold, set only when persistent is True.

Type:

int, optional

consecutive_scales: int
mad: float
median_knee: float
median_noise_prominence_ratio: float
median_prominence: float
members: List[KneeCandidate]
n_windows: int
neighbor_shift: float
persistent: bool = False
sensitivity_support: float
stable_window: int | None = None
support: int
support_frac: float
class elbow_helper.types.ClearKnee(reason, diagnostics=<factory>, knee_x=0.0, knee_x_norm=0.0, knee_index=0, ci90=(0.0, 0.0), detection_rate=0.0, smoothing_window=1, sensitivity=1.0, prominence=0.0, slope_contrast=0.0, bic_improvement=0.0, null_p_value=1.0)[source]

Bases: KneeResult

A knee accepted by every stage of the pipeline, with uncertainty.

Parameters:
knee_x

The detected knee, in the caller’s original data units.

Type:

float

knee_x_norm

The detected knee, normalized to [0, 1].

Type:

float

knee_index

Index of the knee on the cleaned, sorted curve.

Type:

int

ci90

90% bootstrap interval for the knee location, data units.

Type:

tuple of float

detection_rate

Fraction of bootstrap replicates in which the knee was redetected.

Type:

float

smoothing_window, sensitivity

The scale-space setting that produced the winning candidate.

Type:

int, float

prominence

Topographic prominence of the winning candidate’s peak.

Type:

float

slope_contrast

Normalized Theil-Sen slope contrast across the knee.

Type:

float

bic_improvement

BIC improvement of the broken line over a single line.

Type:

float

null_p_value

Monte-Carlo p-value from the no-knee null test.

Type:

float

bic_improvement: float = 0.0
ci90: Tuple[float, float] = (0.0, 0.0)
detection_rate: float = 0.0
knee_index: int = 0
knee_x: float = 0.0
knee_x_norm: float = 0.0
null_p_value: float = 1.0
prominence: float = 0.0
sensitivity: float = 1.0
slope_contrast: float = 0.0
smoothing_window: int = 1
class elbow_helper.types.InvalidKnees(reason, diagnostics=<factory>)[source]

Bases: MultiKneeResult

Preprocessing failed: the input could not be searched at all.

Parameters:
class elbow_helper.types.KneeCandidate(knee_x_norm, knee_index, window, sensitivity, prominence=0.0, local_noise=0.0, noise_prominence_ratio=0.0, boundary_distance=0.0, rejected=None)[source]

Bases: object

A single knee-candidate hit at one (smoothing window, sensitivity) setting.

Parameters:
knee_x_norm

Candidate location, normalized x.

Type:

float

knee_index

Index of the candidate on the (smoothed) curve.

Type:

int

window

Smoothing window that produced this candidate.

Type:

int

sensitivity

Sensitivity S that produced this candidate.

Type:

float

prominence

Topographic prominence of the peak (see peak_prominence()).

Type:

float

local_noise

Robust noise estimate of the (unsmoothed) curve.

Type:

float

noise_prominence_ratio

prominence / local_noise.

Type:

float

boundary_distance

Distance from the candidate to the nearer curve endpoint.

Type:

float

rejected

A Reason code if this candidate failed a basic filter, None if it passed.

Type:

str, optional

boundary_distance: float = 0.0
knee_index: int
knee_x_norm: float
local_noise: float = 0.0
noise_prominence_ratio: float = 0.0
prominence: float = 0.0
rejected: str | None = None
sensitivity: float
window: int
class elbow_helper.types.KneeEstimate(x, x_norm, index, slope_left, slope_right, fwer_p_value=None)[source]

Bases: object

One accepted breakpoint from elbow_helper.robust_knees().

Segments are independent (discontinuous) OLS lines, not the continuous broken-line model ClearKnee uses; slope_left/slope_right are each segment’s own fitted slope, in data units and need not agree at the breakpoint.

Parameters:
x

The breakpoint, in the caller’s original data units.

Type:

float

x_norm

The breakpoint, normalized to [0, 1].

Type:

float

index

Index of the breakpoint on the cleaned, sorted curve.

Type:

int

slope_left, slope_right

Each neighbouring segment’s own fitted slope, data units.

Type:

float

fwer_p_value

The sequential FWER test’s p-value for this breakpoint, None when the FWER gate was not run (require_fwer_confirmation=False).

Type:

float, optional

fwer_p_value: float | None = None
index: int
slope_left: float
slope_right: float
x: float
x_norm: float
class elbow_helper.types.KneeResult(reason, diagnostics=<factory>)[source]

Bases: object

Base class for the tagged union returned by robust_knee().

Parameters:
diagnostics: Dict
property is_clear: bool

True for ClearKnee, False for NoClearKnee.

reason: str
class elbow_helper.types.Knees(reason, diagnostics=<factory>, knees=<factory>)[source]

Bases: MultiKneeResult

A valid multi-knee result: zero or more accepted breakpoints.

Unlike NoClearKnee, an empty knees list here is not an abstention: it is the pipeline’s confident conclusion that the data has no real breakpoint, having survived the same search and false-positive gates a nonempty result would have to survive.

Parameters:
property k: int

Number of accepted breakpoints.

knees: List[KneeEstimate]
class elbow_helper.types.MultiKneeResult(reason, diagnostics=<factory>)[source]

Bases: object

Base class for the tagged union returned by elbow_helper.robust_knees().

Parameters:
diagnostics: Dict
property is_valid: bool

True for Knees, False for InvalidKnees.

reason: str
class elbow_helper.types.NoClearKnee(reason, diagnostics=<factory>)[source]

Bases: KneeResult

An explicit abstention: no knee is strong enough to report.

Parameters:
class elbow_helper.types.NullEvidence(passes, p_value, observed_statistic, null_replicates, reason=None)[source]

Bases: object

Search-adjusted Monte-Carlo test against a no-knee null model.

Parameters:

  • passes (bool)

  • p_value (float)

  • observed_statistic (tuple)

  • null_replicates (int)

  • reason (str | None)

passes

Whether p_value cleared config.max_null_p_value.

Type:

bool

p_value

The Monte-Carlo p-value, finite-sample corrected.

Type:

float

observed_statistic

The observed test statistic, as computed on the real data.

Type:

tuple

null_replicates

Number of null replicates the p-value was computed from.

Type:

int

reason

A Reason code if the check failed, None otherwise.

Type:

str, optional

null_replicates: int
observed_statistic: tuple
p_value: float
passes: bool
reason: str | None = None
class elbow_helper.types.PreparedCurve(x_norm, y_scaled, n, x_lo, x_hi, y_lo, y_hi, curve, direction, spearman, violation_rate)[source]

Bases: object

A cleaned, sorted, normalized curve plus inverse-transform metadata.

Parameters:
x_norm, y_scaled

The curve on the unit square: x linearly scaled to [0, 1] and y robustly scaled (5th/95th percentile) and clipped to [0, 1].

Type:

numpy.ndarray

n

Number of retained samples.

Type:

int

x_lo, x_hi

Original x-range, used to map a normalized knee back to data units.

Type:

float

y_lo, y_hi

Robust y-limits used for scaling (inverse transform for y).

Type:

float

curve, direction

The caller-supplied curve orientation.

Type:

str

spearman

Spearman rank correlation between x and y.

Type:

float

violation_rate

Fraction of lightly-smoothed first differences that move against direction.

Type:

float

curve: str
denormalize_x(x_norm)[source]

Map a normalized x back to original data units.

Parameters:

x_norm (float) – A location in [0, 1].

Returns:

The corresponding location in the caller’s original data units.

Return type:

float

direction: str
n: int
spearman: float
violation_rate: float
x_hi: float
x_lo: float
x_norm: ndarray
y_hi: float
y_lo: float
y_scaled: ndarray
class elbow_helper.types.Reason[source]

Bases: object

Stable, machine-readable abstention (and status) reason codes.

ALL_CANDIDATES_WEAK = 'ALL_CANDIDATES_WEAK'
BOOTSTRAP_MULTIMODAL = 'BOOTSTRAP_MULTIMODAL'
BOOTSTRAP_UNSTABLE = 'BOOTSTRAP_UNSTABLE'
BOUNDARY_KNEE = 'BOUNDARY_KNEE'
CLEAR_KNEE = 'CLEAR_KNEE'
INCOMPATIBLE_GLOBAL_SHAPE = 'INCOMPATIBLE_GLOBAL_SHAPE'
INSUFFICIENT_DATA = 'INSUFFICIENT_DATA'
INTERNAL_NUMERICAL_FAILURE = 'INTERNAL_NUMERICAL_FAILURE'
INVALID_INPUT = 'INVALID_INPUT'
KNEES_FOUND = 'KNEES_FOUND'
MULTIPLE_PLAUSIBLE_KNEES = 'MULTIPLE_PLAUSIBLE_KNEES'
NO_KNEE_CANDIDATES = 'NO_KNEE_CANDIDATES'
NO_PERSISTENT_CLUSTER = 'NO_PERSISTENT_CLUSTER'
NULL_NOT_REJECTED = 'NULL_NOT_REJECTED'
SEGMENTED_MODEL_NOT_BETTER = 'SEGMENTED_MODEL_NOT_BETTER'
WEAK_SLOPE_CHANGE = 'WEAK_SLOPE_CHANGE'
ZERO_RANGE = 'ZERO_RANGE'
class elbow_helper.types.SegmentEvidence(passes, slope_contrast, m_left, m_right, bic_improvement, cv_improvement, reason=None)[source]

Bases: object

Slope-contrast and broken-line vs single-line model comparison.

Parameters:
passes

Whether the slope, CV and BIC checks all passed.

Type:

bool

slope_contrast

Normalized contrast between the left and right Theil-Sen slopes.

Type:

float

m_left, m_right

The robust slopes on either side of the candidate knee.

Type:

float

bic_improvement

BIC of the single line minus BIC of the broken line (higher favors the broken line).

Type:

float

cv_improvement

Fractional reduction in blocked cross-validated SSE from using the broken line instead of the single line.

Type:

float

reason

A Reason code if a check failed, None otherwise.

Type:

str, optional

bic_improvement: float
cv_improvement: float
m_left: float
m_right: float
passes: bool
reason: str | None = None
slope_contrast: float