/ kneed Public

Knee point detection in Python 📈

# arvkevi/kneed

## Folders and files

NameName
Last commit message
Last commit date

# kneed

Knee-point detection in Python

This repository is an attempt to implement the kneedle algorithm, published here. Given a set of `x` and `y` values, `kneed` will return the knee point of the function. The knee point is the point of maximum curvature.

## Installation

`kneed` has been tested with Python 3.7, 3.8, 3.9, and 3.10.

anaconda

`\$ conda install -c conda-forge kneed`

pip

```\$ pip install kneed # To install only knee-detection algorithm
\$ pip install kneed[plot] # To also install plotting functions for quick visualizations```

Clone from GitHub

```\$ git clone https://github.com/arvkevi/kneed.git && cd kneed
\$ pip install -e .```

## Usage

These steps introduce how to use `kneed` by reproducing Figure 2 from the manuscript.

### Input Data

The `DataGenerator` class is only included as a utility to generate sample datasets.

Note: `x` and `y` must be equal length arrays.

```from kneed import DataGenerator, KneeLocator

x, y = DataGenerator.figure2()

print([round(i, 3) for i in x])
print([round(i, 3) for i in y])

[0.0, 0.111, 0.222, 0.333, 0.444, 0.556, 0.667, 0.778, 0.889, 1.0]
[-5.0, 0.263, 1.897, 2.692, 3.163, 3.475, 3.696, 3.861, 3.989, 4.091]```

### Find Knee

The knee (or elbow) point is calculated simply by instantiating the `KneeLocator` class with `x`, `y` and the appropriate `curve` and `direction`.
Here, `kneedle.knee` and/or `kneedle.elbow` store the point of maximum curvature.

```kneedle = KneeLocator(x, y, S=1.0, curve="concave", direction="increasing")

print(round(kneedle.knee, 3))
0.222

print(round(kneedle.elbow, 3))
0.222```

The knee point returned is a value along the `x` axis. The `y` value at the knee can be identified:

```print(round(kneedle.knee_y, 3))
1.897```

### Visualize

The `KneeLocator` class also has two plotting functions for quick visualizations. Note that all (x, y) are transformed for the normalized plots

```# Normalized data, normalized knee, and normalized distance curve.
kneedle.plot_knee_normalized()```

```# Raw data and knee.
kneedle.plot_knee()```

## Documentation

Documentation of the parameters and a full API reference can be found here.

## Interactive

An interactive streamlit app was developed to help users explore the effect of tuning the parameters. There are two sites where you can test out kneed by copy-pasting your own data:

You can also run your own version -- head over to the source code for ikneed.

## Contributing

Contributions are welcome, please refer to CONTRIBUTING to learn more about how to contribute.

## Citation

Finding a “Kneedle” in a Haystack: Detecting Knee Points in System Behavior Ville Satopa † , Jeannie Albrecht† , David Irwin‡ , and Barath Raghavan§ †Williams College, Williamstown, MA ‡University of Massachusetts Amherst, Amherst, MA § International Computer Science Institute, Berkeley, CA

Knee point detection in Python 📈

## Releases 27

Remove more warnings Latest
Jul 9, 2023