{"id":8245,"library":"jenkspy","title":"jenkspy","description":"Jenkspy is a Python library providing a fast implementation of the Fisher-Jenks algorithm for computing 'natural breaks'. It's designed for 1-dimensional clustering on lists, tuples, arrays, or NumPy ndarrays of integers/floats to determine optimal class boundaries. Widely used in cartography and data analysis, the library is currently at version 0.4.1 and is actively maintained with recent updates.","status":"active","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/mthh/jenkspy.git","tags":["geospatial","data-analysis","clustering","statistics","natural-breaks","fisher-jenks"],"install":[{"cmd":"pip install jenkspy","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Mandatory dependency for numerical operations, required since version 0.3.0.","package":"numpy","optional":false}],"imports":[{"wrong":"from jenkspy import jenks_breaks # While functional, direct import is less common in examples and can lead to naming conflicts.","symbol":"jenks_breaks","correct":"import jenkspy\nbreaks = jenkspy.jenks_breaks(data, n_classes=5)"},{"symbol":"JenksNaturalBreaks","correct":"from jenkspy import JenksNaturalBreaks\nclassifier = JenksNaturalBreaks(n_classes=5)"}],"quickstart":{"code":"import jenkspy\nimport random\n\n# Generate some sample data\ndata = [random.uniform(0, 100) for _ in range(100)]\n\n# Compute natural breaks with 5 classes using the function API\nbreaks_func = jenkspy.jenks_breaks(data, n_classes=5)\nprint(f\"Jenks breaks (function API): {breaks_func}\")\n\n# Alternatively, use the scikit-learn inspired class API\nfrom jenkspy import JenksNaturalBreaks\nclassifier = JenksNaturalBreaks(n_classes=5)\nclassifier.fit(data)\n\n# Get the breaks and group labels\nbreaks_class = classifier.breaks_\ngroups = classifier.groups_ # Groups elements into corresponding class indices\n\nprint(f\"Jenks breaks (class API): {breaks_class}\")\nprint(f\"First 10 group labels: {groups[:10]}\")\n","lang":"python","description":"This quickstart demonstrates both the functional (`jenks_breaks`) and object-oriented (`JenksNaturalBreaks`) ways to compute natural breaks. The functional approach directly returns the break points, while the class-based API provides a scikit-learn-like interface with `fit` and `groups_` methods for more complex workflows."},"warnings":[{"fix":"Replace `nb_class` with `n_classes` in your function calls. E.g., `jenkspy.jenks_breaks(data, n_classes=5)`.","message":"The `nb_class` parameter for `jenks_breaks` was renamed to `n_classes` in version 0.3.0 to align with scikit-learn conventions. Using `nb_class` in newer versions will raise an error.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Ensure `numpy` is installed: `pip install numpy`.","message":"NumPy became a mandatory dependency starting from version 0.3.0. Installations without NumPy will fail or raise import errors.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Filter out or handle non-finite values in your data, and ensure NumPy arrays are 1-dimensional before passing them to `jenkspy` functions or classes.","message":"Attempting to compute breaks on data containing non-finite values (NaN, Inf) or a non-one-dimensional NumPy array will now raise an error instead of a warning (since 0.2.3).","severity":"breaking","affected_versions":">=0.2.3"},{"fix":"Ensure that `n_classes` is less than or equal to the number of unique values in your dataset. Consider pre-processing your data to count unique elements.","message":"If the requested `n_classes` is greater than the number of unique values in the input data, `jenkspy` will raise an exception (since 0.4.1).","severity":"gotcha","affected_versions":">=0.4.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Convert your pandas Series to a NumPy array before passing it to `jenkspy`: `jenkspy.jenks_breaks(my_series.to_numpy(), n_classes=...)`.","cause":"The `jenkspy.jenks_breaks` function does not natively support pandas Series objects; it expects standard Python lists, tuples, or NumPy arrays.","error":"TypeError: 'KeyError' or other issues when passing pandas Series directly."},{"fix":"Install a C compiler. On Debian/Ubuntu: `sudo apt-get update && sudo apt-get install build-essential`. On macOS, install Xcode Command Line Tools: `xcode-select --install`. For Windows, consider installing the Microsoft Visual C++ Build Tools or using `conda install -c conda-forge jenkspy`.","cause":"Jenkspy uses C extensions for performance. This error indicates that a C compiler (like GCC) is not found on your system, which is required to compile these extensions if pre-built wheels are not available for your platform/Python version.","error":"error: 'x86_64-linux-gnu-gcc': No such file or directory during installation."}]}