Skip to main content

Compute Natural Breaks (Fisher-Jenks algorithm)

Project description

Compute “natural breaks” (Fisher-Jenks algorithm) on list / tuple / array / numpy.ndarray of integers/floats.

The algorithm implemented by this library is also sometimes referred to as Fisher-Jenks algorithm, Jenks Optimisation Method or Fisher exact optimization method. This is a deterministic method to calculate the optimal class boundaries.

Intended compatibility: CPython 3.6+

Wheels are provided via PyPI for Windows / MacOS / Linux users - Also available on conda-forge channel for Anaconda users.

Version Anaconda-Server Badge Build status GH PyPI download month


Two ways of using jenkspy are available:

  • by using the jenks_breaks function which takes as input a list / tuple / array.array / numpy.ndarray of integers or floats and returns a list of values that correspond to the limits of the classes (starting with the minimum value of the series - the lower bound of the first class - and ending with its maximum value - the upper bound of the last class).

>>> import jenkspy
>>> import json

>>> with open('tests/test.json', 'r') as f:
...     # Read some data from a JSON file
...     data = json.loads(
>>> jenkspy.jenks_breaks(data, n_classes=5) # Asking for 5 classes
[0.0028109620325267315, 2.0935479691252112, 4.205495140049607, 6.178148351609707, 8.09175917180255, 9.997982932254672]
# ^                      ^                    ^                 ^                  ^                 ^
# Lower bound            Upper bound          Upper bound       Upper bound        Upper bound       Upper bound
# 1st class              1st class            2nd class         3rd class          4th class         5th class
# (Minimum value)                                                                                    (Maximum value)
  • by using the JenksNaturalBreaks class that is inspired by scikit-learn classes.

The .fit and .group behavior is slightly different from jenks_breaks, by accepting value outside the range of the minimum and maximum value of breaks_, retaining the input size. It means that fit and group will use only the inner_breaks_. All value below the min bound will be included in the first group and all value higher than the max bound will be included in the last group.

>>> from jenkspy import JenksNaturalBreaks

>>> x = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

>>> jnb = JenksNaturalBreaks(4) # Asking for 4 clusters

>>> # Create the clusters according to values in 'x'
>>> print(jnb.labels_) # Labels for fitted data
... print(jnb.groups_) # Content of each group
... print(jnb.breaks_) # Break values (including min and max)
... print(jnb.inner_breaks_) # Inner breaks (ie breaks_[1:-1])
[0 0 0 1 1 1 2 2 2 3 3 3]
[array([0, 1, 2]), array([3, 4, 5]), array([6, 7, 8]), array([ 9, 10, 11])]
[0.0, 2.0, 5.0, 8.0, 11.0]
[2.0, 5.0, 8.0]

>>> print(jnb.predict(15)) # Predict the group of a value

>>> print(jnb.predict([2.5, 3.5, 6.5])) # Predict the group of several values
[1 1 2]

>>> print([2.5, 3.5, 6.5])) # Group the elements into there groups
[array([], dtype=float64), array([2.5, 3.5]), array([6.5]), array([], dtype=float64)]


  • From pypi

pip install jenkspy
  • From source

git clone
cd jenkspy/
python install
  • For anaconda users

conda install -c conda-forge jenkspy

Requirements :

  • Numpy

  • Only for building from source: C compiler, Python C headers and optionally Cython.

Motivation :

  • Making a painless installing C extension so it could be used more easily as a dependency in an other package (and so learning how to build wheels using appveyor / travis at first - now it uses GitHub Actions).

  • Getting the break values! (and fast!). No fancy functionality provided, but contributions/forks/etc are welcome.

  • Other python implementations are currently existing but not as fast or not available on PyPi.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jenkspy-0.3.3.tar.gz (154.8 kB view hashes)

Uploaded source

Built Distributions

jenkspy-0.3.3-cp311-cp311-win_amd64.whl (177.5 kB view hashes)

Uploaded cp311

jenkspy-0.3.3-cp310-cp310-win_amd64.whl (178.2 kB view hashes)

Uploaded cp310

jenkspy-0.3.3-cp39-cp39-win_amd64.whl (179.2 kB view hashes)

Uploaded cp39

jenkspy-0.3.3-cp38-cp38-win_amd64.whl (179.3 kB view hashes)

Uploaded cp38

jenkspy-0.3.3-cp37-cp37m-win_amd64.whl (178.8 kB view hashes)

Uploaded cp37

jenkspy-0.3.3-cp36-cp36m-win_amd64.whl (188.1 kB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page