kneed

library0.8.6pypypi✓ verified 22d ago

kneed is a Python library (current version 0.8.6) for detecting knee (also known as elbow) points in curves. It implements the Kneedle algorithm to identify the point of maximum curvature in a given set of x and y values. The library is actively maintained with regular patch releases and occasional feature updates.

ai-ml data

pip install kneed

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · KNEED

kneed

ai-mlpythonv0.8.6

Install

9.4s avg

Import

3888ms

Disk

322MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 3.978s · 319.6MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 9.4s · import 3.799s · 306MB

322MB installed

● package 322MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KneeLocator

✓ from kneed import KneeLocator

DataGenerator

✓ from kneed import DataGenerator

Utility class for generating sample data, often used in examples.

find_shape

✓ from kneed import find_shape

Helper function to automatically detect curve shape and direction.

This quickstart demonstrates how to use `KneeLocator` to find a knee point in a dataset, both by manually specifying `curve` and `direction`, and by automatically detecting them using `find_shape`. The `knee` and `knee_y` attributes provide the x and y coordinates of the detected knee point.

import numpy as np from kneed import KneeLocator, find_shape # Example 1: Basic usage with known curve type and direction x = np.arange(1, 11) y = np.array([1, 2, 3, 4, 5, 5.5, 5.6, 5.7, 5.8, 5.9]) kl = KneeLocator(x, y, curve="concave", direction="increasing") print(f"Knee at x: {kl.knee}") print(f"Corresponding y: {kl.knee_y}") # Example 2: Using find_shape for auto-detection x_auto = np.arange(1, 101) y_auto = np.sin(x_auto / 10) + np.log(x_auto) + np.random.rand(100) auto_direction, auto_curve = find_shape(x_auto, y_auto) kl_auto = KneeLocator(x_auto, y_auto, curve=auto_curve, direction=auto_direction) print(f"\nAuto-detected curve: {auto_curve}, direction: {auto_direction}") print(f"Knee at x (auto-detected): {kl_auto.knee}")

Debug

Known issues

breakingMatplotlib became an optional dependency in v0.8.0. Code calling plotting methods (e.g., `plot_knee()`, `plot_knee_normalized()`) will now raise a `ModuleNotFoundError` if Matplotlib is not installed via `pip install kneed[plot]`.

fix

Ensure Matplotlib is installed using `pip install kneed[plot]` if plotting functionality is required.

affects: >=0.8.0

breakingThe `scikit-learn` dependency was removed in v0.7.0. While `kneed` itself does not directly rely on `scikit-learn` for its core algorithm, code that implicitly expected `scikit-learn` to be installed alongside `kneed` (e.g., for K-Means clustering examples) might now fail.

fix

Explicitly install `scikit-learn` if your application requires it: `pip install scikit-learn`.

affects: >=0.7.0

breakingAs of v0.7.0, `kneed` validates the `curve` and `direction` arguments. Providing invalid string values for these parameters will now result in an error, whereas they might have been silently ignored or led to incorrect behavior in previous versions.

fix

Always use valid string values: `curve` can be 'concave' or 'convex'; `direction` can be 'increasing' or 'decreasing'.

affects: >=0.7.0

gotchaBeginning with v0.8.4 and further refined in v0.8.5, `kneed` no longer emits warnings when no knee/elbow point is found. Users who previously relied on parsing these warnings for error handling or informational purposes should update their logic.

fix

Check the `knee` attribute directly; if no knee is found, `kl.knee` will be `None`. Adjust error handling or logging based on this programmatic check instead of relying on warning messages.

affects: >=0.8.4

gotchaThe `curve` and `direction` parameters are critical for accurate knee detection. An incorrect choice (e.g., `curve='concave'` for a convex elbow, or `direction='increasing'` for a decreasing curve) will lead to incorrect or no knee detection.

fix

Carefully consider the shape and trend of your data. Use `find_shape()` for automatic detection, or plot your data to visually determine the correct parameters. Experiment with different `S` values as well.

affects: All versions

gotchaThe sensitivity parameter `S` (default `1.0`) greatly influences knee detection. Smaller `S` values detect knees more aggressively/earlier, while larger values are more conservative. Improper `S` can lead to missing a knee or identifying a false one, especially with noisy data.

fix

Experiment with different `S` values (e.g., 0.1 to 10.0) based on your data's noise level and expected knee sharpness. Consider using `interp_method='polynomial'` and `polynomial_degree` for smoother curves in noisy data.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'kneed'

The 'kneed' library is not installed in the active Python environment.

fix

pip install kneed

ImportError: cannot import name 'kneeLocator' from 'kneed'

The class name 'KneeLocator' is case-sensitive and was imported with incorrect capitalization.

fix

from kneed import KneeLocator

ModuleNotFoundError: No module named 'matplotlib'

Plotting functions in 'kneed' (e.g., plot_knee()) require 'matplotlib', which is an optional dependency and must be installed separately.

fix

pip install kneed[plot]

ValueError: Please check that the curve and direction arguments are valid.

The 'curve' or 'direction' arguments provided to KneeLocator were not among the accepted string values ('concave', 'convex' for curve; 'increasing', 'decreasing' for direction).

fix

Ensure 'curve' is 'concave' or 'convex' and 'direction' is 'increasing' or 'decreasing' (e.g., KneeLocator(x, y, curve='concave', direction='increasing')).

ValueError: `S` must be a positive float >= 1.0.

The 'S' (sensitivity) parameter was provided with a value less than 1.0, which is outside the acceptable range for the Kneedle algorithm.

fix

Ensure the 'S' parameter is set to a float value of 1.0 or greater, for example, `S=1.0` or `S=3.0`.

Upgrade

Version history

0.8.6latest on PyPI · released Mar 20, 2026

Audit

Dependencies

matplotliboptionalRequired for plotting functions within KneeLocator (e.g., plot_knee(), plot_knee_normalized()). Optional since v0.8.0.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/arvkevi/kneed ↗

packagehttps://pypi.org/project/kneed/ ↗

docshttps://kneed.readthedocs.io/en/latest/ ↗