Picture an online shop that wants to sort its customers into groups of look-alikes: the bargain hunters, the Sunday regulars, the big-basket buyers. An algorithm called k-means does that sorting, on one condition: you tell it in advance how many groups to form. Two groups? The sorting stays coarse. Ten? Each group gets so small it no longer means anything. The right number is somewhere in between.
A curve will point it out. Across the bottom, the number of groups tried. Up the side, a measure of the disorder left inside the groups. The curve dives at first, because each added group soaks up a lot of disorder, then it flattens out, because extra groups barely help anymore. The same diminishing-returns silhouette shows up when you ask when a model should stop training, or at what budget an advertising channel saturates. The point where the curve stops paying off goes by an anatomical name: the elbow or knee1. Before it, every extra unit earns its keep. Past it, you are just insisting.
Finding that point looks easy. Yet an elbow detector always answers something. Hand it a perfect straight line and it gives you an elbow. Hand it pure noise and it gives you another one.
elbow-helper asks harder questions. Is this elbow clear? Is it the only one? Does it stay put when you smooth the curve a little? Does it come back if you rerun the computation? And above all: could a curve with no elbow at all have produced the same thing by chance? One bad answer is all it takes: the tool abstains and says why. Try it while you read: at deraison.ai/elbow-helper, paste a curve into your browser and the answer arrives with its evidence well before this article ends.
The classic case: a k-means inertia curve, with the number of clusters along the bottom. k-means sorts points into a number of clusters fixed in advance. Its inertia is the sum of the distances from each point to the center of its cluster. The plot shows the detected elbow, its bootstrap interval (explained below) and, beside it, the evidence in figures.
A point with no error bar
Proposing a location is something existing methods do very well, starting with the Kneedle algorithm that everyone refers to2. But they never say how much they believe it: you get a point, with no error bar, no probability, no right to stay silent. On a noisy curve, that lone point invites over-reading. You pick four clusters, size a system's fast memory, stop an experiment. Three decisions resting on an accident of noise.
Faced with a blurry scan, a radiologist holds back from a diagnosis. The report says the image supports no conclusion and asks for another one. A statistical program facing a noisy curve does well to show the same restraint and conclude only what the data allows. The radiologist, though, exercises judgment. The program applies thresholds fixed once and for all: it gains in predictability and loses in subtlety.
elbow-helper therefore set itself one priority: avoid false elbows, even at the cost of staying silent more often. The program that calls it receives one of two answers and nothing else, a ClearKnee or a NoClearKnee. A clear elbow arrives with its position, its range and its evidence in figures. The aim is a range that encloses the true position in roughly nine cases out of ten. So far only the test family of curves confirms it. A refusal arrives with a code a machine can read, saying why the tool kept quiet. The tool never falls back quietly to a doubtful estimate: abstention is an answer the calling program handles and cannot work around.
The tools already available come in three groups:
- The elbow hunters:
kneed3,kneebow4, Yellowbrick's visualizer5. They always answer with a point and have no way of saying "there is nothing here". - The changepoint libraries,
ruptures6 foremost. They are excellent, but they answer a different question: how many breaks in a signal? Returns that shrink do not concern them. - The judgment left to a human looking at the plot, or to a language model. That judgment does not reproduce.
elbow-helper's closest relative falls outside those three groups: the R package segmented7 starts from the same idea. Saying there is an elbow means saying how sure you are. Yet staying silent when the evidence is missing remains rare, in segmented as in the three groups. That silence is elbow-helper's main contribution. The comparison comes with numbers: the ratings table and the map summarizing its eleven criteria wait further down, just before the tool's limits.
Eight releases, from v0.1.0 to v0.1.7, are published on PyPI, the public index pip install pulls Python libraries from. Code gets turned away until the 85 automated tests pass on Python 3.12 and the style checker stops complaining. Once a week, the suite runs again on all four supported Python versions, 3.10 through 3.13. Between them, those 85 tests cover 96% of the package's lines.
A mathematical note typeset in LaTeX proves every formula in the package with a worked example: ELBOW.pdf, with LIKELIHOOD.pdf alongside. Both exist in English and in French and stay in step with the code.
From raw curve to candidate
First, the housekeeping. Invalid points get dropped, the x values get sorted and deduplicated, both scales get brought back between 0 and 1. The rescaling anchors itself on the 5th and 95th percentiles instead of the lowest and highest points. The 5th percentile is the value below which 5% of the points fall, the 95th the one below which 95% of them fall. One outlier, however wild, therefore cannot squash the whole curve against an edge.
Then comes a first shape check. Does the curve keep rising, or keep falling, with no change of direction? We then call it monotone. A Spearman correlation8 answers that by looking at the order of the values and ignoring their size. A second check looks at the gaps and confirms the verdict. A curve with no clear trend gets turned away on the spot, before anyone looks for an elbow.
The program reads the curve's direction from the sign of the trend, unless you want to force it. Hollow or domed? It stretches a chord between the first and last points, then looks at which side the curve passes. Above the chord, a dome. Below, a bowl. All four cases (domed or hollow, rising or falling) are therefore covered without your having to name the shape. If you do give it, yours wins.
The curve is clean and its direction known. What are we looking for? Take a square-root curve, rising fast then settling down. Draw the straight line joining its two ends, then subtract it from the curve. A bump remains, zero at departure and arrival, tallest where the curve pulls furthest from that line. The top of that bump is the elbow. Once the data is brought between 0 and 1, the line joining the ends becomes the diagonal, where height equals horizontal position. Subtracting it therefore means taking away from each point its own x value:
The local maxima of that difference, the points higher than their immediate neighbors, are the candidates. A sensitivity threshold then decides whether a peak deserves the name of elbow or is a mere wiggle. The candidate must dominate its neighborhood by a margin proportional to a parameter \(S\). The bar to clear is written T:
Start from the height of the peak and take away a margin: the sensitivity parameter times the mean gap between two neighboring x values. Raise \(S\) and the margin widens: the peak has to tower higher. The whole search then runs again over a grid of smoothing windows and sensitivities. A candidate that moves from one setting to the next is out. A real elbow stays put when you blur the curve a little. An accident of noise disappears.
That peak search has authors: it is Kneedle2, described by Satopää, Albrecht, Irwin and Raghavan in 2011. Here it is rewritten from scratch in NumPy. The way it walks the curve, the orientation table and the sensitivity threshold closely follow Kevin Arvai's kneed library3. That library is BSD licensed and credited in the repository. elbow-helper runs without it. Its contribution comes next, with what it demands of a candidate before agreeing to call it an elbow.
First demand: the slope has to change clearly enough that three stray points could not have manufactured the change. A Theil-Sen estimator9 measures it. The usual method, least squares, looks for the line that makes the sum of squared gaps as small as possible. One wild value weighs very heavily there, since its gap gets squared. Theil-Sen goes another way: it computes the slope of every pair of points, then takes the middle value, the median. A few wild points can scream all they like, the median does not hear them.
Now for the model itself. A real elbow breaks the slope: one straight line up to the point \(k\), a different slope after it. The broken line has to be one piece, with no jump. One function does the job, flat at zero before \(k\), rising steadily after:
The letters a and b describe an ordinary line, its starting height and its slope. The term with the max stays at zero until the break, then grows steadily. The whole story of the elbow plays out in the coefficient \(c\): past the break, the slope becomes b plus \(c\). If it is zero, we are back to a straight line with no elbow. The further \(c\) gets from zero, the sharper the slope breaks at \(k\).
The broken line then faces the plain line on two grounds. On the first, blocked cross-validation10, we hide part of the curve, then see whether the model guesses what was hidden. We take out whole stretches instead of isolated points, because an isolated point is far too easy to guess from its neighbors. On the second, a score compares the two models while accounting for their complexity. Building that score first requires saying what "fits better" means.
Measuring surprise: likelihood
Suppose the model is true. If it fits the data well, what we observe is no surprise: that is the idea of likelihood. Computing it takes a model of the randomness. Observed points always land a little off the theoretical curve. The gap is Gaussian noise, the bell-curve randomness that many small errors produce when they add up. Each gap is drawn without regard to the others, with a typical size written \(\sigma\). Every observation then gets a probability density, a number saying how expected that value was. A point landing close to the proposed curve gets a large number, a point landing far away a small one.
Textbooks multiply those numbers together, across the \(n\) points. That product raises a practical problem: multiplying \(n\) numbers all smaller than one gives a result that collapses at speed as \(n\) grows. Take 0.9. Multiplied by itself 80 times, it gives about two ten-thousandths. Multiplied 800 times, it gives a number with thirty-six zeros after the decimal point before its first significant digit. How, then, do you compare a curve of 80 points with a curve of 800?
elbow-helper's way out is the likelihood per observation: multiply the \(n\) numbers, then take the \(n\)-th root, which amounts to an average. The number of points stops weighing in. In the formula below, θ stands for the model's settings, σ² for the square of the noise's typical size, p for each point's density and E for an average across all the points:
Both ways of writing it say the same thing: averaging the logarithms of the densities and coming back through the exponential amounts to taking that root of the raw likelihood. With bell-curve noise, everything simplifies in one stroke. All that remains is the mean squared error (MSE), the average of the squared gaps between the observed points and the fitted curve:
The first factor depends on the noise alone. The exponential depends on the fit and falls when the MSE rises. Take the natural logarithm, which undoes that exponential without residue.
Look at that line. The first term knows nothing about the model's settings. The second contains the MSE with a minus sign. At fixed noise, making the mean squared error as small as possible therefore means making the likelihood as large as possible. We learn least squares as a geometric recipe. We learn maximum likelihood as a statistical principle. They are one and the same operation, seen from two sides!
Scaled up to the whole sample, with the noise's size estimated by the MSE itself, this log-likelihood simplifies. Multiplied by minus two, it becomes \(n\) times the logarithm of the MSE, plus a constant. That is the fit term of every criterion that follows. The mathematical note ELBOW.pdf builds that bridge step by step. Comparing two models on that fit alone would be rigged from the start: a model with more dials always clings closer to the data, right up to hugging the noise itself. So we charge for the dials. The BIC family of scores11, where BIC stands for Bayesian Information Criterion, starts from the likelihood and adds a penalty proportional to the number of dials spent. The elbow costs dials. It has to pay them back in fit, or else the plain line wins.
How do we make all of this readable for a human? The reflex would be \(R^2\), the textbook fit score. It sets the model's error against that of a lazy student who always answers the mean of the observations. It is 1 for a perfect fit, 0 for "no better than answering the mean". The trouble is that the mean is the fixed value that minimizes the error: among dumb answers, it is the best possible opponent. Beaten by the lazy student, an \(R^2\) drops below zero. elbow-helper picks a frankly bad opponent instead: the observed value that, answered everywhere, predicts all the others worst.
For each observed value, compute the average error you would make by answering it everywhere. The value producing the largest error becomes the reference. The quality score compares our error to that one. It is 1 for a perfect fit and 0 for a fit as bad as that worst fixed value. Since this reference is always worse than the mean, falling below zero becomes far harder than with an \(R^2\).
That number prints in the figure's legend, beside three others. They are the detection probability, the \(p\)-value from the next section and a weight comparing the two models. That weight is the odds between the elbow model and the plain line, computed from the BIC gap12. Those odds apply only when you have many observations. To see a probability there, you would first have to decide how much you trust each of the two models. The data here says nothing about that. So it is taken for what it is: a weight comparing two models.
Two trials against chance
A model can win that duel on the data we have and still be a whim of the noise. Two trials guard against it. The first is called the bootstrap13, after the expression about pulling yourself up by your own bootstraps. You have one dataset? Make others out of it. Take the fitted model away from the curve and the gaps remain. Shuffle those gaps like a deck of cards, then paste them back onto the model. Each copy looks like what you would have observed had chance drawn differently. The whole search starts over on every copy. The verdict: the elbow must come back to the same place in at least 90% of the copies, with a tight range.
The second trial, the plain-line test, attacks the problem from the other side. Two hundred straight lines with the same noise level are simulated, a thousand for a validation-grade run. Then we count how often chance alone produces evidence as strong as the evidence observed.
That number is the \(p\)-value, one of the most misread quantities in statistics. It does not give the probability that there is no elbow. It says the opposite: supposing there is none, how often would chance alone manufacture evidence this convincing? Take a \(p\)-value of 0.01: a pure straight line manages it once in a hundred tries. That is little, so we keep the elbow. It is not zero: out of a hundred curves with no elbow at all, one would still clear this bar.
Why go through simulation? Because if there is no elbow, its position does not exist. The classical tests then lose the reference they normally lean on14. So the candidate has two bars to clear:
On the left, the share of copies where the elbow comes back, at least 90%. On the right, how often a line with no elbow does as well, at most 1%. Only a candidate that clears all those gates becomes a ClearKnee. That case file prints next to the curve, on the diagnostic figure. On abstention, it switches to a refusal state: curve greyed out, reason displayed, marker gone so as not to suggest more certainty than there is.
Low noise. The dashed line marks the confirmed slope change, at x = 0.463. The true break is at 0.5: the gap is discretization, since the tool answers with one of the supplied points.
The next figure shows the same curve, with the same break underneath. Only the noise has grown.
The same shape under high noise. The break goes unconfirmed, so the figure draws no marker: the abstention shows at a glance.
A code for every refusal
Abstaining is an answer in its own right, with a name, and nothing like failing in silence. The function returns one of two objects and nothing else, which forces the calling program to check which one before going on. On one curve at two noise levels, the two answers print like this:
>>> from elbow_helper import robust_knee >>> robust_knee(x, y) # noise of standard deviation 0.02 ClearKnee(knee_x=0.3038, ci90=(0.3038, 0.3418), detection_rate=0.98, null_p=0.00498) >>> robust_knee(x, y_noisy) # same elbow, ten times the noise NoClearKnee(reason='INCOMPATIBLE_GLOBAL_SHAPE')
The first answer reads without documentation: elbow at 0.304, range from 0.304 to 0.342, elbow found again in 98% of the copies, a probability of five in a thousand that a straight line with no elbow would do as well. The second stays silent on position. It does so on purpose: at that noise level the curve no longer even passes the shape check, its trend being too faint.
Every refusal comes with a stable code, readable by a machine as much as by a human. Those codes form a list settled in advance, fifteen reasons and not one more. A dashboard can therefore count its abstentions and learn whether its curves are too short, too noisy or simply ambiguous.
| Returned code | What it says |
|---|---|
| Data preparation | |
| INVALID_INPUT | the inputs are unusable: mismatched lengths, no finite value, an unknown shape requested. |
| INSUFFICIENT_DATA | the curve has fewer points than the minimum, twenty by default, too few for the later trials to mean anything. |
| ZERO_RANGE | the x axis does not vary: every point sits at the same place. |
| INCOMPATIBLE_GLOBAL_SHAPE | the curve does not have the shape announced or has no trend clear enough to infer one. |
| Candidate search | |
| NO_KNEE_CANDIDATES | the difference curve has no peak at all, at any smoothing scale. |
| ALL_CANDIDATES_WEAK | peaks exist, all drowned in the local noise. |
| BOUNDARY_KNEE | the best candidate hugs one end of the curve, where nothing tells an elbow from an edge effect. |
| NO_PERSISTENT_CLUSTER | no candidate comes back to the same place when the smoothing scale changes. |
| MULTIPLE_PLAUSIBLE_KNEES | two elbows are equally defensible: answering would amount to a coin flip. |
| Statistical confirmation | |
| WEAK_SLOPE_CHANGE | the slope, measured through the Theil-Sen median, changes too little to deserve the word elbow. |
| SEGMENTED_MODEL_NOT_BETTER | the broken line fails to beat the plain line, on blocked cross-validation or on the BIC. |
| BOOTSTRAP_UNSTABLE | the elbow comes back in only a minority of the bootstrap copies. |
| BOOTSTRAP_MULTIMODAL | it comes back often, but at two distinct places depending on the copy. |
| NULL_NOT_REJECTED | a straight line with no elbow, under the same noise, would too easily produce evidence this strong. |
| INTERNAL_NUMERICAL_FAILURE | a computation failed: the package says so instead of returning a doubtful number. |
The fifteen refusal codes, in the order the pipeline can meet them.
A refusal also says what to do. INSUFFICIENT_DATA asks for more points. BOOTSTRAP_MULTIMODAL hints that there may be two elbows rather than none, which points to the plural search described below. NULL_NOT_REJECTED says the curve is pretty, but that noise alone would account for it.
Several doors, one verdict
A detector earns its keep when you can call it from where you work. elbow-helper therefore offers the same chain through five entry points:
- The Python library suits a notebook.
- The terminal command suits a script, or those automatic checks replayed at every code change.
- The HTTP API serves a program written in a language other than Python.
- The MCP server (Model Context Protocol) serves a conversational assistant.
- The web app is for anyone who would rather install nothing.
The first four are thin layers over one shared engine. They offer the same four operations:
kneereturns an elbow with its uncertainty.elbowis the shortcut for the k-means case, where the curve is known in advance to be hollow and falling.diagnosticsreturns the figure as SVG, a drawing format that stays sharp at any size.locatorreturns the position alone, with no evidence.
What one returns, the others return too.
At install time, you choose your entry point. The engine depends on NumPy and nothing else. The network entry points are optional extras, in brackets, installed only if you use them:
$ pip install elbow-helper # library + command line $ pip install "elbow-helper[api]" # + the HTTP API $ pip install "elbow-helper[mcp]" # + the MCP server (which pulls the API in)
The library
Two functions do all the work. robust_knee takes a curve and infers its shape. robust_elbow handles the k-means case, whose shape is known in advance. The x values are optional: give only the y values and the package numbers the points from zero to n minus one.
from elbow_helper import robust_knee, robust_elbow, RobustKneeConfig
res = robust_knee(x, y) # shape and direction inferred
res = robust_elbow(k_values, inertia) # the k-means case, shape fixed
res = robust_knee(y) # implicit x: 0, 1, 2, ...
# More replays: slower, safer.
res = robust_knee(x, y, config=RobustKneeConfig(bootstrap_replicates=500,
null_replicates=1000,
random_seed=0))
if res.is_clear:
print(res.knee_x, res.ci90, res.detection_rate, res.null_p_value)
else:
print("no clear elbow:", res.reason)
Every threshold is stored in RobustKneeConfig, a structure you do not edit: you make a copy with config.with_(...). The shipped settings aim at the second of runtime rather than at the last decimal: a hundred bootstrap copies, two hundred simulated lines. For serious validation, use the values above, five to ten times slower.
The command line
It runs the same four operations and answers in JSON, a text format programs read back without ambiguity. That makes it easy to chain to the usual tools. Data comes in as comma-separated values, as a NumPy file, or as a column of a CSV table named by its number:
$ elbow-helper knee --y-values 0,0.1,0.3,0.6,0.85,0.9,0.92,0.93,0.94,0.95
{
"reason": "INSUFFICIENT_DATA",
"diagnostics": {
"curve": "auto",
"direction": "auto",
"n": 10,
"min_samples": 20
},
"is_clear": false
}
$ elbow-helper elbow --x-npy k.npy --y-npy inertia.npy
$ elbow-helper knee --y-csv measures.csv:2 --config-json '{"bootstrap_replicates": 500}'
$ elbow-helper diagnostics --x-npy k.npy --y-npy inertia.npy > diagnostics.svg
Look closely at the first command. The curve it receives looks right in every way. Any classic detector would have returned a number. Ten points, though, are too few to claim there is an elbow. The answer is therefore a documented refusal, stating how many points were supplied and how many would be needed, with no obliging estimate. The rule applies through every entry point.
The HTTP API
A server starts in one line and listens on four addresses, named after the four operations. The curve travels as JSON, and so do the settings, inside a config_overrides object. The diagnostics address returns the SVG itself, with no wrapper around it.
# uvicorn: the server that runs the Python application.
$ uvicorn elbow_helper.api:app --port 8000
$ curl -s -X POST localhost:8000/knee -H 'Content-Type: application/json' \
-d '{"x": [0, 0.0127, ...], "y": [0.0043, 0.0361, ...],
"config_overrides": {"random_seed": 0}}'
{"reason": "CLEAR_KNEE", "knee_x": 0.3038, "ci90": [0.3038, 0.3418],
"detection_rate": 0.98, "null_p_value": 0.00498, "is_clear": true,
"diagnostics": {...}} # response abridged
The MCP server
The MCP server is that same application, with the four operations declared as tools a conversational assistant can discover and call, served at /mcp:
$ uvicorn elbow_helper.mcp_server:app --port 8021 # The assistant connects to http://127.0.0.1:8021/mcp and finds # four tools there: knee, elbow, diagnostics, locator.
The point goes beyond convenience. Show a curve to an assistant: it will happily produce a plausible elbow, with nothing to contradict it. Wired to this tool, it gets a computed verdict, with its range and its \(p\)-value, or a named refusal it cannot turn into certainty.
The web app
The last entry point asks for nothing: deraison.ai/elbow-helper runs the whole pipeline in the browser, on your data, without uploading it anywhere. Paste a curve and you get the same verdict and the same diagnostic figure as through the other four doors, in English or in French.
Several elbows, one table to fill
Take three pricing tiers on a demand curve: the curve changes regime several times. The question then becomes: how many breaks and where? robust_knees, in the plural, answers it. Changing the question forces a change of model. The curve is cut into pieces, each piece gets its own straight line and a jump is allowed at the joint. We deliberately give up the single unbroken line from earlier. With it, as soon as several breaks were free to move, the cost of a partition would no longer split piece by piece: moving one break would change what its neighbors have to satisfy. With no joint imposed, each piece becomes a small independent problem. That is what makes the search fast.
First ingredient: computing the cost of one piece in a single step. Fitting a line through \(m\) points and measuring its error looks like it needs a pass over every point. Six running totals suffice instead, the number of points and these five sums:
From those come the least-squares slope b and intercept a, then the piece's error, written \(\mathrm{RSS}\) for residual sum of squares:
That last equality falls out of the least-squares equations. It says the cost of any stretch of the curve can be read off those totals, without touching the points again. For a stretch, you subtract the total at its entrance from the total at its exit. Computing those totals once takes time proportional to the number of points. Each later piece cost then comes in constant time, however long the curve is.
Second ingredient: the search itself. Trying every way to place \(k\) breaks among \(n\) points is out of reach. On a curve of a hundred points, six breaks already have more than a billion possible placements. Dynamic programming sidesteps the obstacle by building the answer from smaller answers already computed. Write \(C[k][t]\) for the lowest cost of explaining the first \(t\) points with \(k+1\) pieces:
The first equality handles the case with no cut: a single piece, whose cost reads off directly. The second reads as follows. Try every possible position \(s\) of the last cut. For each one, add two costs: the best way of explaining the first \(s\) points with one break fewer, already computed so you look it up, then the cost of the final piece, from \(s\) to \(t\). Keep the minimum.
Why is looking up a smaller answer legitimate rather than recomputing everything? Take the reasoning backwards. Suppose the best partition of the first \(t\) points has its last cut at \(s^\ast\), but its beginning is not the cheapest possible partition of that beginning. We could then swap that beginning for the cheaper one, keep the final piece as it is and get a valid partition cheaper still than the best. That is impossible. So the beginning of an optimal solution is itself optimal: Bellman's principle15.
Count the cells, on the same curve of a hundred points with six breaks. Seven rows for the number of pieces, a hundred columns for the points, at most a hundred positions to try per cell: at most 70,000 additions, where brute enumeration demanded more than a billion. Each cell also keeps an arrow to the cell it came from: follow the arrows back and you find the cuts.
Changepoint detection calls this its classic method. PELT16 starts from it and runs faster, because it abandons hopeless partitions along the way. Here it is checked against full enumeration on small inputs, rather than taken on faith.
Third ingredient: choosing the number of breaks. The more you add, the closer you cling to the data, down to the absurdity of one piece per point. A modified BIC17 settles it, with a penalty that charges for each break and also watches the length of each piece:
That formula adds three terms, for k breaks and so k+1 pieces:
- The first measures the fit: it falls when the residual sum of squares falls.
- The second charges for the breaks, at three times the logarithm of the number of points for each one.
- The third watches the lengths: each piece counts by its share of the curve, its length divided by the number of points. That share is below one, so its logarithm is negative.
The minus sign in front of that sum was not always there. A secondary source writes that term with a plus, while the original literature means to penalize uneven pieces. The package first took it as written. Tested, that plus produced the opposite of its intended effect: the term being always negative, adding it rewards uneven partitions instead of punishing them. With a minus, short and uneven pieces are properly penalized, as announced. The convention kept here is the one the tests confirm. The discrepancy is documented in the open.
One uncertainty remains: a sign that looks flipped can come from a different definition of the likelihood, a score you minimize instead of maximize or a length normalized another way. Settling it would mean setting the formulas side by side, term by term, in an appendix the repository has yet to write. What we have, then, is a measured disagreement, not a correction to the literature.
A permutation test finally confirms the winner. The curve is shuffled two hundred times: none of those shuffled versions has a real break, so almost all of them must do worse than the real fit. And since running more tests means more chances to get lucky, a Bonferroni correction tightens each test's bar in proportion to how many are run18.
One nuance separates the singular from the plural. In the plural, an empty answer is a conclusion rather than an abstention: this curve has no real break. That verdict cleared the same gates as a non-empty answer. Only a preparation problem (an invalid input, too little data, a zero range) returns an error instead of a list of breaks.
Those choices (dynamic programming over the greedy method, the minus sign, the permutation confirmation) were settled by measurement. Ten combinations were put in competition: two ways of searching times five ways of choosing how many breaks there are. Dynamic programming examines every partition. The greedy method lays its breaks down one at a time and never revisits them. Each method handled three hundred curves of a hundred points, built for the test. There are twenty-five of them for every combination of four break counts (zero to three) and three noise levels. Twenty-five times four times three, the count checks out.
The labels on the two figures below read as follows:
- DP is dynamic programming, Greedy the greedy method.
- BIC is the criterion alone, mBIC_add and mBIC_sub the two signs of the length term, plus and minus.
- ICL is a neighboring criterion that also charges for the uncertainty of the partition19.
- FWER is the permutation test with the Bonferroni correction. The acronym stands for family-wise error rate, the risk of being wrong at least once across the whole series of tests.
Probability of recovering the true number of breaks. The top five methods all rest on the dynamic program, the bottom five are their greedy twins.
In this ranking, the full search beats the greedy method every time and by a wide margin: 0.85 against 0.60 for the same criterion. The mechanism is known20: the greedy method commits early to an imperfect cut, then the cuts that follow go into repairing that error instead of describing the curve. The sign of the length term, the story told above, comes with a number too: 0.85 with the minus, 0.77 with the literature's plus. A single sign is worth eight hundredths.
That leaves the flaw this project cares about most: inventing a break where there is none. The second figure measures it on curves drawn deliberately flat.
Probability of announcing at least one break on a curve that has none. The bare BIC is wrong one time in four, the drift theory has long ascribed to it21. The subtractive form and the permutation filter are never wrong across the seventy-five curves that have no break at all.
Every method runs into the same limit. At high noise, facing three real breaks, the best method announces 1.8 on average and none recovers all three. In this hard case, the error runs toward fewer elbows rather than more. That is the direction this package accepts being wrong in. These numbers apply to that family of curves and to it alone. The repository publishes the full protocol, with the detailed table by noise level22.
A single computational dependency runs all of this, NumPy. The search algorithm was rewritten from scratch and the figure comes out stroke by stroke as SVG code, without any charting package. Every formula in the chain, from the rescaling to the permutation test, is proved step by step in the repository's mathematical note, ELBOW.pdf23. It is written intuition-first, with a worked example before every formula. Likelihood gets its own note, LIKELIHOOD.pdf24, because it owes nothing to curve fitting.
The landscape, tool by tool
Where does all of this stand? The repository rates eight ways of looking for an elbow, on eleven criteria. The rating targets the job this package does, announcing an elbow only when the evidence supports it. A tool excellent at another job is not punished for it.
| Elbow Detection Tool | Noise robustness | Shape inference | Explicit abstention | Multiple breakpoints | Significance test | Uncertainty | Model selection | Light dependencies | One-call ease | Reproducible | Published maths |
|---|---|---|---|---|---|---|---|---|---|---|---|
| elbow-helper | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ |
| kneed | ⭐️⭐️ | ⭐️⭐️ | ⭐️ | ⭐️⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ |
| ruptures | ⭐️⭐️⭐️ | ⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ |
| kneebow | ⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️ |
| KElbowVisualizer | ⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ |
| R segmented package | ⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ |
| Manual eyeballing | ⭐️ | ⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️ | ⭐️ | ⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️ | ⭐️ |
| Ask an LLM | ⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️⭐️⭐️ | ⭐️ | ⭐️⭐️ | ⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️ |
The repository's eleven criteria, from one to five stars. The highlighted row is the package this article is about.
The same table seen from above. A principal component analysis projects its eleven columns onto the two directions that best summarize them. The axes were then named by hand. elbow-helper sits alone in the precise and adaptable corner. Map drawn by Standpoint, the tool that reads a ratings table and draws its map.
- elbow-helper: the only one here that can refuse to answer. An elbow has to stay in place from one smoothing scale to the next, survive the bootstrap and beat the no-elbow model. The tool then returns either an elbow with its interval, or a named abstention code.
- kneed: the reference implementation of Kneedle, deterministic and immediate. It always returns a point, with no error bar and no way out.
- kneebow: the same geometric idea, obtained by rotating the curve. Very light on dependencies, it commits on every call.
- KElbowVisualizer: the most common way to read a k-means elbow in practice, plot it then look at it. This visualization tool, built for one curve shape, inherits scikit-learn and matplotlib.
- ruptures: the right tool when the question really is "how many breakpoints and where", with PELT and binary segmentation already in place. Diminishing returns mean nothing to it.
- R segmented package: statistically the most rigorous, with broken-line regression, standard errors, Davies test and multiple breakpoints. It asks for R and real statistical fluency.
- Manual eyeballing: a careful eye can say "I see nothing clear here", which most tools cannot. That judgment changes from one person to the next and scales poorly.
- Ask an LLM: a large language model describes a shape in words fluently and hedges when asked. It does so with no calibrated uncertainty, no checkable derivation, never the same answer twice.
What the tool assumes
The smoother assumes x values that are roughly regularly spaced: a curve sampled any which way would defeat it.
The position returned is one of the supplied points, never a value in between. With few points, the elbow can therefore land a few samples away from the truth. Half the time, on the test family of curves, the error stays under 5% of the curve's width. The simulated line and the bootstrap assume something else: noise of the same size along the whole curve and points that do not depend on each other. The variants that drop that assumption remain to be written.
Finally, the thresholds are calibrated on a documented family of curves. Demanding 90% redetections and a \(p\)-value at 1% are reasoned choices, not laws of nature. The package is at version 0.1. Its author says so: if your decision depends on it, recalibrate on your own curves. Any method working on limited data can be wrong. This one merely makes its assumptions checkable.
The refusal that helps
"No clear elbow" is real information. It keeps you from sizing a system, stopping an experiment or settling a budget on a piece of chance. A detector that knows when to stay silent serves you better than one that always answers. That displayed confidence is paid for in abstentions, a trade I stand by.
elbow-helper installs in one line, pip install elbow-helper. To try it with nothing installed, open the online sandbox: the full pipeline runs in your browser without uploading your data. The GitHub repository gathers the code, the examples, the comparison with neighboring tools and the mathematical notes. For each curve, it returns a quantified elbow or a refusal that gives its reason.
Bibliography
Here are the works this package depends on, ordered as the article uses them. Each note says what the source establishes and where it does its work here. The classics appear for the standard result they ground, the repository's own notes for their derivations and measurements.
- Thorndike, R. L. (1953). "Who belongs in the family?", Psychometrika, 18(4), 267-276. 10.1007/BF02289263 A presidential address to the Psychometric Society, commonly given as the first statement of the elbow criterion: plot a measure of spread against the number of groups and look for the bend. It sets the question this article lives on, without offering a decision rule.
- Satopää, V., Albrecht, J., Irwin, D. and Raghavan, B. (2011). "Finding a Kneedle in a Haystack: Detecting Knee Points in System Behavior", ICDCSW, IEEE. Defines the knee as the maximum gap to the chord after normalization, with a sensitivity threshold: the locator rewritten here. Its limit is in its own statement: it proposes a location, it does not say whether the knee exists.
- Arvai, K. kneed, Python library, three-clause BSD license. github.com/arvkevi/kneed The reference Python implementation of Kneedle. Its traversal logic, orientation table and sensitivity threshold guided elbow-helper's NumPy rewrite, which carries no runtime dependency on it.
- kneebow, Python library, MIT license. github.com/georg-un/kneebow Rotates the curve and takes the extremum of the rotated data. Representative of the camp that always answers with a point and can never keep quiet.
- Bengfort, B. and Bilbro, R. (2019).
"Yellowbrick: Visualizing the Scikit-Learn Model Selection Process", Journal of Open Source Software, 4(35), 1075. 10.21105/joss.01075 A
visual-diagnostics library for scikit-learn, including the
KElbowVisualizerthat plots inertia and marks an elbow. The tool aims at reading by eye, not at a quantified decision. - Truong, C., Oudre, L. and Vayatis, N.
(2020). "Selective review of offline change point detection methods", Signal Processing, 167, 107299. arxiv.org/abs/1801.00718 A review that sorts changepoint detection into three parts,
a cost function, a search method and a constraint on the number of changes; it accompanies the
ruptureslibrary. That is the frame this article's multi-elbow part inherits, on a question adjacent to, but distinct from, diminishing returns. - Muggeo, V. M. R. (2003).
"Estimating regression models with unknown break-points", Statistics in
Medicine, 22(19), 3055-3071. 10.1002/sim.1545 Estimates a breakpoint's position by successive
linearizations and returns a standard error with it, hence an interval. It is elbow-helper's
closest relative on the idea that a knee claim should carry its uncertainty; the R package
segmentedis its implementation. - Spearman, C. (1904). "The Proof and Measurement of Association between Two Things", American Journal of Psychology, 15(1), 72-101. A correlation computed on ranks rather than on values. It serves here as a shape screen, indifferent to scale and little disturbed by a few extreme points.
- Theil, H. (1950). "A Rank-Invariant Method of Linear and Polynomial Regression Analysis", Proceedings of the Royal Netherlands Academy of Sciences, 53; Sen, P. K. (1968). "Estimates of the Regression Coefficient Based on Kendall's Tau", Journal of the American Statistical Association, 63(324), 1379-1389. Together they establish the slope estimator built from the median of all pairwise slopes. It is what lets the pipeline demand a slope change without letting a handful of outliers decide the verdict.
- Arlot, S. and Celisse, A. (2010). "A survey of cross-validation procedures for model selection", Statistics Surveys, 4, 40-79. 10.1214/09-SS054 A review that carefully separates what is proved from what is merely observed about cross-validation and shows that the shape of the held-out blocks has to match the dependence in the data. That is the justification for holding out contiguous stretches here.
- Schwarz, G. (1978). "Estimating the Dimension of a Model", The Annals of Statistics, 6(2), 461-464. Establishes the BIC: a penalty equal to the number of parameters times the logarithm of the number of observations, derived as an approximation to the marginal likelihood. It is the score the broken line has to beat to earn its elbow.
- Kass, R. E. and Raftery, A. E. (1995). "Bayes Factors", Journal of the American Statistical Association, 90(430), 773-795. Gives the approximation by which a BIC gap reads as odds between two models and the interpretation scale that goes with it. It is the source of the weight the diagnostic figure's legend shows under the name posterior probability.
- Efron, B. (1979). "Bootstrap Methods: Another Look at the Jackknife", The Annals of Statistics, 7(1), 1-26. Introduces resampling as a stand-in for a sampling distribution nobody can write down. Here it is the residual noise that gets reshuffled, to measure how often and where the elbow comes back.
- Davies, R. B. (1977). "Hypothesis testing when a nuisance parameter is present only under the alternative", Biometrika, 64(2), 247-254. 10.1093/biomet/64.2.247 Treats exactly the elbow's difficulty: a parameter that exists only if the alternative hypothesis is true, here the location \(k\). The likelihood-ratio test loses its usual asymptotic distribution there, which is why the \(p\)-value is simulated rather than read off a table.
- Bellman, R. (1957). Dynamic Programming, Princeton University Press. The canonical source of the principle of optimality: the start of an optimal solution is optimal for its own sub-problem. That is what licenses the recursion used here to place several breaks.
- Killick, R., Fearnhead, P. and Eckley, I. A. (2012). "Optimal Detection of Changepoints With a Linear Computational Cost", Journal of the American Statistical Association, 107(500), 1590-1598. PELT: the same exact recursion, sped up by pruning that permanently discards partitions which have become hopeless, giving a linear cost under conditions on the penalty.
- Zhang, N. R. and Siegmund, D. O. (2007). "A Modified Bayes Information Criterion with Applications to the Analysis of Comparative Genomic Hybridization Data", Biometrics, 63(1), 22-32. Introduces the modified BIC whose extra term watches segment lengths. It is the reference whose sign, taken at face value first, had to be corrected here once its real effect was measured.
- Dunn, O. J. (1961). "Multiple Comparisons Among Means", Journal of the American Statistical Association, 56(293), 52-64. 10.1080/01621459.1961.10482090 Establishes and puts to work the inequality statistics calls Bonferroni: dividing the threshold by the number of tests bounds the risk of being wrong at least once. Used here as soon as several break counts are put to the test.
- Biernacki, C., Celeux, G. and Govaert, G. (2000). "Assessing a Mixture Model for Clustering with the Integrated Completed Likelihood", IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(7), 719-725. The ICL criterion, which adds to the BIC a penalty on the uncertainty of the assignment. A competitor in the comparison, where it reaches 0.82 accuracy and a 4% false-positive rate.
- Fryzlewicz, P. (2014). "Wild Binary Segmentation for Multiple Change-Point Detection", The Annals of Statistics, 42(6), 2243-2281. Analyzes the flaw in greedy searches, which commit to a cut too early and propagate the error and fixes it with randomly drawn intervals. This article's comparison recovers that flaw: every greedy method stays below its exhaustive twin.
- Yao, Y.-C. (1988). "Estimating the number of change-points via Schwarz' criterion", Statistics and Probability Letters, 6(3), 181-189. Studies the BIC applied to the number of changepoints and documents its tendency to keep too many. The 27% false-positive rate measured here is one instance of that, on piecewise-linear curves.
- Harchaoui, W. (2026). Multi-knee method comparison: results, research note in the elbow-helper repository. research/multiknee/RESULTS.md The full protocol behind the comparison above: ten methods, three hundred curves each, results broken down by break count and noise level, runtimes and the six conclusions drawn from them.
- Harchaoui, W. (2026). ELBOW: Noise-Robust Knee and Elbow Detection, technical note in the elbow-helper repository. doc/ELBOW-en.pdf Derives every formula in the package step by step, from normalization to the permutation test, intuition and a worked example before each one. It is the long version of everything this article compresses.
- Harchaoui, W. (2026). LIKELIHOOD, technical note in the elbow-helper repository. doc/LIKELIHOOD-en.pdf The likelihood groundwork revisited above: why the per-observation likelihood, the geometric mean of the densities, rather than the raw product and how the same construction reads on a classification model.
To close, three readings friendlier than a journal paper. My favorite AI books supply the annotated panorama the next two come from. The Elements of Statistical Learning by Hastie, Tibshirani and Friedman covers model selection and cross-validation at large. Information Theory, Inference and Learning Algorithms by MacKay traces the link between likelihood, coding and perplexity.