API Reference
There are two classes in kneed: KneeLocator identifies the knee/elbow point(s) and and DataGenerator creates synthetic x and y numpy arrays to explore kneed.
KneeLocator
- class kneed.knee_locator.KneeLocator(x: Iterable[float], y: Iterable[float], S: float = 1.0, curve: str = 'concave', direction: str = 'increasing', interp_method: str = 'interp1d', online: bool = False, polynomial_degree: int = 7)
Once instantiated, this class attempts to find the point of maximum curvature on a line. The knee is accessible via the .knee attribute.
- Parameters:
x (1D array of shape (number_of_y_values,) or list) – x values, must be the same length as y.
y (1D array of shape (number_of_y_values,) or list) – y values, must be the same length as x.
S (float) – Sensitivity, the number of minimum number of data points below the local distance maximum before calling a knee. The original paper suggests default of 1.0
curve (str) – If ‘concave’, algorithm will detect knees. If ‘convex’, it will detect elbows.
direction (str) – one of {“increasing”, “decreasing”}
interp_method (str) – one of {“interp1d”, “polynomial”}
online (bool) – kneed will correct old knee points if True, will return first knee if False
polynomial_degree (int) – The degree of the fitting polynomial. Only used when interp_method=”polynomial”. This argument is passed to numpy polyfit deg parameter.
- Variables:
x (array-like) – x values.
y (array-like) – y values.
S (integer) – Sensitivity, original paper suggests default of 1.0
curve (str) – If ‘concave’, algorithm will detect knees. If ‘convex’, it will detect elbows.
direction (str) – one of {“increasing”, “decreasing”}
interp_method (str) – one of {“interp1d”, “polynomial”}
online (str) – kneed will correct old knee points if True, will return first knee if False
polynomial_degree (int) – The degree of the fitting polynomial. Only used when interp_method=”polynomial”. This argument is passed to numpy polyfit deg parameter.
N (integer) – The number of x values in the
all_knees (set) – A set containing all the x values of the identified knee points.
all_norm_knees (set) – A set containing all the normalized x values of the identified knee points.
all_knees_y (list) – A list containing all the y values of the identified knee points.
all_norm_knees_y (list) – A list containing all the normalized y values of the identified knee points.
Ds_y (numpy array) – The y values from the fitted spline.
x_normalized (numpy array) – The normalized x values.
y_normalized (numpy array) – The normalized y values.
x_difference (numpy array) – The x values of the difference curve.
y_difference (numpy array) – The y values of the difference curve.
maxima_indices (numpy array) – The indices of each of the maxima on the difference curve.
maxima_indices – The indices of each of the maxima on the difference curve.
x_difference_maxima (numpy array) – The x values from the difference curve where the local maxima are located.
y_difference_maxima (numpy array) – The y values from the difference curve where the local maxima are located.
minima_indices (numpy array) – The indices of each of the minima on the difference curve.
minima_indices – The indices of each of the minima on the difference curve.
x_difference_minima (numpy array) – The x values from the difference curve where the local minima are located.
y_difference_minima (numpy array) – The y values from the difference curve where the local minima are located.
Tmx (numpy array) – The y values that correspond to the thresholds on the difference curve for determining the knee point.
knee (float) – The x value of the knee point. None if no knee/elbow was detected.
knee_y (float) – The y value of the knee point. None if no knee/elbow was detected
norm_knee (float) – The normalized x value of the knee point. None if no knee/elbow was detected
norm_knee_y (float) – The normalized y value of the knee point. None if no knee/elbow was detected
all_knees – The x values of all the identified knee points.
all_knees_y – The y values of all the identified knee points.
all_norm_knees – The normalized x values of all the identified knee points.
all_norm_knees_y – The normalized y values of all the identified knee points.
elbow (float) – The x value of the elbow point (elbow and knee are interchangeable). None if no knee/elbow was detected
elbow_y (float) – The y value of the knee point (elbow and knee are interchangeable). None if no knee/elbow was detected
norm_elbow – The normalized x value of the knee point (elbow and knee are interchangeable). None if no knee/elbow was detected
norm_elbow_y (float) – The normalized y value of the knee point (elbow and knee are interchangeable). None if no knee/elbow was detected
all_elbows (set) – The x values of all the identified knee points (elbow and knee are interchangeable).
all_elbows_y – The y values of all the identified knee points (elbow and knee are interchangeable).
all_norm_elbows (set) – The normalized x values of all the identified knee points (elbow and knee are interchangeable).
all_norm_elbows_y – The normalized y values of all the identified knee points (elbow and knee are interchangeable).
Plotting methods
There are two methods for basic visualizations of the knee/elbow point(s).
- KneeLocator.plot_knee(figsize: Tuple[int, int] | None = None, title: str = 'Knee Point', xlabel: str | None = None, ylabel: str | None = None)
Plot the curve and the knee, if it exists
- Parameters:
figsize – Optional[Tuple[int, int] The figure size of the plot. Example (12, 8)
title – str Title of the visualization, defaults to “Knee Point”
xlabel – Optional[str] X-axis label
ylabel – Optional[str] y-axis label
- Returns:
NoReturn
- KneeLocator.plot_knee_normalized(figsize: Tuple[int, int] | None = None, title: str = 'Normalized Knee Point', xlabel: str | None = None, ylabel: str | None = None)
Plot the normalized curve, the difference curve (x_difference, y_normalized) and the knee, if it exists.
- Parameters:
figsize – Optional[Tuple[int, int] The figure size of the plot. Example (12, 8)
title – str Title of the visualization, defaults to “Normalized Knee Point”
xlabel – Optional[str] X-axis label
ylabel – Optional[str] y-axis label
- Returns:
NoReturn
DataGenerator
- class kneed.data_generator.DataGenerator
Generate synthetic data to work with kneed.
- static bumpy() Tuple[Iterable[float], Iterable[float]]
Generate a sample function with local minima/maxima.
- Returns:
tuple(x, y)
- static concave_decreasing() Tuple[Iterable[float], Iterable[float]]
Generate a sample decreasing concave function.
- Returns:
tuple(x, y)
- static concave_increasing() Tuple[Iterable[float], Iterable[float]]
Generate a sample increasing concave function.
- Returns:
tuple(x, y)
- static convex_decreasing() Tuple[Iterable[float], Iterable[float]]
Generate a sample decreasing convex function.
- Returns:
tuple(x, y)
- static convex_increasing() Tuple[Iterable[float], Iterable[float]]
Generate a sample increasing convex function.
- Returns:
tuple(x, y)
- static figure2() Tuple[Iterable[float], Iterable[float]]
Recreate the values in figure 2 from the original kneedle paper.
- Returns:
tuple(x, y)
- static noisy_gaussian(mu: float = 50, sigma: float = 10, N: int = 100, seed=42) Tuple[Iterable[float], Iterable[float]]
Recreate NoisyGaussian from the orignial kneedle paper.
- Parameters:
mu – The mean value to build a normal distribution around
sigma – The standard deviation of the distribution.
N – The number of samples to draw from to build the normal distribution.
seed – An integer to set the random seed.
- Returns:
tuple(x, y)