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)