elbow_helper.numerics module

Small NumPy-only numerical primitives shared across the pipeline.

These replace the handful of scipy / scikit-learn calls the plan reached for (Spearman correlation, robust noise, peak prominence, Theil-Sen slope, OLS + BIC) so the package keeps to a numpy-only core.

Author

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

elbow_helper.numerics.bic(rss, n, n_params)

Bayesian information criterion for a Gaussian OLS fit.

BIC = n * ln(RSS / n) + k * ln(n) with k = n_params + 1 (the extra parameter is the noise variance). Lower is better.

Parameters:

• rss (float) – Residual sum of squares.

• n (int) – Number of data points.

• n_params (int) – Number of regression parameters (not counting the noise variance).

Returns:

The BIC score; lower is better.

Return type:

float

elbow_helper.numerics.ols_rss(design, y)

Ordinary least squares fit; return (coefficients, residual_sum_sq).

Parameters:

• design (numpy.ndarray) – Design matrix, one row per sample.

• y (numpy.ndarray) – Target values, one per row of design.

Returns:

The fitted coefficients and the residual sum of squares.

Return type:

tuple of (numpy.ndarray, float)

elbow_helper.numerics.peak_prominence(signal, index)

Topographic prominence of the peak at index.

Implements the standard definition (as in scipy.signal.peak_prominences) directly: descend from the peak on both sides until the signal rises above the peak (or an array end is reached), take the highest valley on each side, and return the peak height above the higher of the two valleys.

Parameters:

• signal (numpy.ndarray) – The curve the peak lives on (here, the difference curve).

• index (int) – Index of the peak.

Returns:

The peak’s prominence (>= 0).

Return type:

float

elbow_helper.numerics.rankdata(a)

Rank values with ties averaged (scipy.stats.rankdata semantics).

Parameters:

a (numpy.ndarray) – One-dimensional array of values to rank.

Returns:

Ranks, 1-indexed, ties resolved to the average rank of their group.

Return type:

numpy.ndarray

elbow_helper.numerics.robust_sigma_from_diffs(y)

Robust noise estimate from first differences.

Uses the MAD of successive differences, scaled by 1.4826 (consistency with the normal) and by 1/sqrt(2) because differencing two independent samples inflates the variance twofold.

Parameters:

y (numpy.ndarray) – The (scaled) signal.

Returns:

Estimated per-sample standard deviation.

Return type:

float

elbow_helper.numerics.spearman(x, y)

Spearman rank correlation coefficient between x and y.

Parameters:

• x (numpy.ndarray) – Equal-length arrays to correlate.

• y (numpy.ndarray) – Equal-length arrays to correlate.

Returns:

Spearman’s rho, in [-1, 1]; 0.0 if either array is constant.

Return type:

float

elbow_helper.numerics.theil_sen_slope(x, y)

Theil-Sen robust slope: the median of all pairwise slopes.

Parameters:

• x (numpy.ndarray) – Equal-length arrays.

• y (numpy.ndarray) – Equal-length arrays.

Returns:

The median of (y_j - y_i) / (x_j - x_i) over all pairs i < j with distinct x; nan when fewer than two distinct x values are available.

Return type:

float