elbow_helper.smoothing module

Phase 2 — the smoothing scale-space.

Generates a grid of odd smoothing windows (always including 1 = no smoothing) and applies a centered Gaussian smoother with reflected boundaries, implemented in pure NumPy (no scipy.ndimage).

Author

Warith Harchaoui, <warithmetics@deraison.ai>

elbow_helper.smoothing.signal_and_noise(y, config)

Split y into a smooth signal and noise of the curve’s own scale.

The signal is a lightly smoothed copy of the observed curve, so every replicate keeps the shape actually measured. The noise is the smoother’s residual, rescaled so its standard deviation matches robust_sigma_from_diffs(), the successive-difference estimate of the per-sample noise. The rescaling is what makes the bandwidth a shape choice rather than a noise-level choice: whatever curvature the smoother leaves behind, the perturbation injected into the replicates is always the size of the noise the data actually carry.

This replaces fitting the accepted broken line and resampling its residuals. On a smoothly bending curve those residuals are dominated by the broken line’s own misfit rather than by noise – on a 784-point PCA scree spectrum they had a standard deviation of 0.054 against a true noise level of 0.00013, a 400-fold inflation – so the replicates were curves far noisier than anything observed and the knee went undetected in a fifth to a third of them. The failure grew with how sharply the curve bent, i.e. with how clear the elbow was, which is how a strong elbow ended up reported as BOOTSTRAP_UNSTABLE.

Parameters:

• y (numpy.ndarray) – The observed (scaled) curve.

• config (RobustKneeConfig) – Supplies bootstrap_signal_window.

Returns:

(signal, residuals), both the length of y.

Return type:

tuple of (numpy.ndarray, numpy.ndarray)

elbow_helper.smoothing.smooth_curve(y, window, method='gaussian')

Smooth y with a centered kernel and reflected boundaries.

Parameters:

• y (numpy.ndarray) – The signal to smooth.

• window (int) – Approximate support width; window <= 1 returns y unchanged.

• method (str, optional) – "gaussian" (default) or "moving_average" (a baseline).

Returns:

The smoothed signal, same length as y.

Return type:

numpy.ndarray

elbow_helper.smoothing.smoothing_grid(n, config)

Odd smoothing windows for n samples, sorted ascending, deduplicated.

Parameters:

• n (int) – Number of samples in the curve.

• config (RobustKneeConfig) – smoothing_fractions are multiplied by n to size the windows.

Returns:

Distinct odd window widths, always starting with 1.

Return type:

list of int