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 (array-like) – x values.
y (array-like) – y values.
S (float) – 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 (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.
knee_y (float) – The y value of the knee point.
norm_knee (float) – The normalized x value of the knee point.
norm_knee_y (float) – The normalized y value of the knee point.
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).
elbow_y (float) – The y value of the knee point (elbow and knee are interchangeable).
norm_elbow – The normalized x value of the knee point (elbow and knee are interchangeable).
norm_elbow_y (float) – The normalized y value of the knee point (elbow and knee are interchangeable).
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_elbowss_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: Optional[Tuple[int, int]] = 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)
Returns:	NoReturn

KneeLocator.plot_knee_normalized(figsize: Optional[Tuple[int, int]] = 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)
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)