Install & Compatibility
Where this runs
tested against v2.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
build_error
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 22.4s · import 6.433s · 555MB
441MB installed
● package 441MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mapclassify
✓ import mapclassify as mc
The standard convention is to import mapclassify as 'mc'.
Quantiles
✓ mc.Quantiles
✗ mapclassify.Quantiles
Typically accessed via the aliased import `mc`.
NaturalBreaks
✓ mc.NaturalBreaks
✗ mapclassify.NaturalBreaks
Typically accessed via the aliased import `mc`.
FisherJenks
✓ mc.FisherJenks
✗ mapclassify.FisherJenks
Typically accessed via the aliased import `mc`. Numba is recommended for performance.
This quickstart demonstrates how to generate sample data, apply two common classification schemes (Quantiles and Fisher-Jenks), and inspect their bin edges and class assignments. It then visualizes the results using the `plot_legendgram` method, which requires `matplotlib` for execution. Ensure `mapclassify[plotting]` is installed for the visualization part.
import numpy as np
import mapclassify as mc
import matplotlib.pyplot as plt
# Generate some sample data
np.random.seed(42)
data = np.random.rand(100) * 100
# Apply a classification scheme (e.g., Quantiles)
classifier_q = mc.Quantiles(data, k=5)
print(f"Quantiles Classifier (k={classifier_q.k}):")
print(f"Bin edges: {classifier_q.bins}")
print(f"Class assignments for first 5 values: {classifier_q.yb[:5]}\n")
# Apply another scheme (e.g., Natural Breaks / Fisher-Jenks)
classifier_fj = mc.FisherJenks(data, k=5)
print(f"Fisher-Jenks Classifier (k={classifier_fj.k}):")
print(f"Bin edges: {classifier_fj.bins}")
print(f"Class assignments for first 5 values: {classifier_fj.yb[:5]}\n")
# Visualize the classification with a legendgram
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))
classifier_q.plot_legendgram(ax=ax1, cmap='viridis', title='Quantiles Legendgram')
classifier_fj.plot_legendgram(ax=ax2, cmap='plasma', title='Fisher-Jenks Legendgram')
plt.tight_layout()
plt.show()
Errors
Common errors & fixes
No module named 'mapclassify.api'
This error occurs because the `mapclassify.api` module was removed in version 2.0 of mapclassify. The API structure changed significantly, consolidating core functionality under the main `mapclassify` namespace.
fixUpdate your import statements to directly import from `mapclassify`. For example, change `import mapclassify.api as mc` to `import mapclassify` and then access classifiers directly (e.g., `mapclassify.Quantiles(y)`).
ImportError: The 'mapclassify' package (>= 2.4.0) is required to use the 'scheme' keyword.
This error typically arises when using the `scheme` keyword with `geopandas.plot()` while an older version of `mapclassify` (less than 2.4.0) is installed or if `mapclassify` is not installed at all, which `geopandas` often uses internally for classification schemes.
fixEnsure `mapclassify` is installed and updated to a compatible version. Run `pip install --upgrade mapclassify` or `conda install -c conda-forge mapclassify` to get the latest version.
AttributeError: module 'mapclassify' has no attribute 'Fisher_Jenks'
This error indicates that you are trying to access a classifier using an outdated or incorrect naming convention. In newer versions of `mapclassify`, classifier names are typically camel-cased (e.g., `FisherJenks` instead of `Fisher_Jenks`).
fixAdjust the classifier name to its correct camel-case form as per the current API. For instance, change `mapclassify.Fisher_Jenks` to `mapclassify.FisherJenks`. Refer to the `mapclassify` documentation for the exact names of supported classifiers.
ValueError: Invalid scheme: 'some_scheme_name'\nScheme must be in the set: {'quantiles', 'equal_interval', ...}
This error occurs when the string passed to the `scheme` parameter (e.g., in `geopandas.plot(scheme='...')` or `mapclassify.classify(scheme='...')`) does not match any of the recognized classification scheme names supported by the `mapclassify` library.
fixCheck the available scheme names in the error message or the `mapclassify` documentation and ensure your `scheme` argument uses one of the valid strings (e.g., 'quantiles', 'equalinterval', 'naturalbreaks'). Pay attention to casing and underscores/spaces.
ValueError: Data must be 1-dimensional
This error occurs when you provide a multi-dimensional array or a data structure that cannot be interpreted as a single sequence of values (e.g., a DataFrame with multiple columns) to a `mapclassify` function that expects a 1-dimensional input array for classification.
fixEnsure the input data `y` passed to a `mapclassify` classifier is a 1-dimensional NumPy array or a pandas Series. If you have multiple columns, select a single column for classification, e.g., `mapclassify.Quantiles(df['column_name'])`.
Upgrade
Version history
2.11.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
numpyrequiredFundamental for numerical operations and array handling.
scipyrequiredRequired for statistical functions used in some classification schemes.
pandasrequiredOften used for data handling, though not strictly required for core classification.
matplotliboptionalNecessary for plotting functions like `plot_legendgram` and `plot` methods on classification objects.
numbaoptionalEnhances performance for computationally intensive algorithms like FisherJenks.