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)
-
static