{"id":5307,"library":"mapclassify","title":"Mapclassify","description":"Mapclassify provides a collection of classification schemes for choropleth maps, including standard methods like Quantiles, Equal Interval, and Natural Breaks (Jenks). It helps transform raw data into discrete classes suitable for thematic mapping. The library is actively maintained as part of the PySAL ecosystem, currently at version 2.10.0, with regular updates introducing new features and improvements.","status":"active","version":"2.10.0","language":"en","source_language":"en","source_url":"https://github.com/pysal/mapclassify","tags":["geospatial","mapping","data classification","statistics","visualization","pysal"],"install":[{"cmd":"pip install mapclassify","lang":"bash","label":"Core installation"},{"cmd":"pip install mapclassify[plotting]","lang":"bash","label":"With plotting dependencies (e.g., matplotlib, seaborn)"},{"cmd":"pip install mapclassify[all]","lang":"bash","label":"All optional dependencies (e.g., numba, geopandas)"}],"dependencies":[{"reason":"Fundamental for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Required for statistical functions used in some classification schemes.","package":"scipy","optional":false},{"reason":"Often used for data handling, though not strictly required for core classification.","package":"pandas","optional":false},{"reason":"Necessary for plotting functions like `plot_legendgram` and `plot` methods on classification objects.","package":"matplotlib","optional":true},{"reason":"Enhances performance for computationally intensive algorithms like FisherJenks.","package":"numba","optional":true}],"imports":[{"note":"The standard convention is to import mapclassify as 'mc'.","symbol":"mapclassify","correct":"import mapclassify as mc"},{"note":"Typically accessed via the aliased import `mc`.","wrong":"mapclassify.Quantiles","symbol":"Quantiles","correct":"mc.Quantiles"},{"note":"Typically accessed via the aliased import `mc`.","wrong":"mapclassify.NaturalBreaks","symbol":"NaturalBreaks","correct":"mc.NaturalBreaks"},{"note":"Typically accessed via the aliased import `mc`. Numba is recommended for performance.","wrong":"mapclassify.FisherJenks","symbol":"FisherJenks","correct":"mc.FisherJenks"}],"quickstart":{"code":"import numpy as np\nimport mapclassify as mc\nimport matplotlib.pyplot as plt\n\n# Generate some sample data\nnp.random.seed(42)\ndata = np.random.rand(100) * 100\n\n# Apply a classification scheme (e.g., Quantiles)\nclassifier_q = mc.Quantiles(data, k=5)\n\nprint(f\"Quantiles Classifier (k={classifier_q.k}):\")\nprint(f\"Bin edges: {classifier_q.bins}\")\nprint(f\"Class assignments for first 5 values: {classifier_q.yb[:5]}\\n\")\n\n# Apply another scheme (e.g., Natural Breaks / Fisher-Jenks)\nclassifier_fj = mc.FisherJenks(data, k=5)\n\nprint(f\"Fisher-Jenks Classifier (k={classifier_fj.k}):\")\nprint(f\"Bin edges: {classifier_fj.bins}\")\nprint(f\"Class assignments for first 5 values: {classifier_fj.yb[:5]}\\n\")\n\n# Visualize the classification with a legendgram\nfig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))\n\nclassifier_q.plot_legendgram(ax=ax1, cmap='viridis', title='Quantiles Legendgram')\nclassifier_fj.plot_legendgram(ax=ax2, cmap='plasma', title='Fisher-Jenks Legendgram')\n\nplt.tight_layout()\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.11+ or pin `mapclassify` to `<2.9.0` in your project dependencies.","message":"Starting with version 2.9.0, mapclassify requires Python 3.11 or newer. Projects on older Python versions will need to upgrade Python or stick to `mapclassify<2.9.0`.","severity":"breaking","affected_versions":">=2.9.0"},{"fix":"Install `numba` as an optional dependency: `pip install mapclassify[all]` or `pip install numba`.","message":"When working with `FisherJenks` classification, `numba` is highly recommended for performance, especially with large datasets. Without it, the algorithm can be significantly slower.","severity":"gotcha","affected_versions":"<2.6.1, >=2.6.1"},{"fix":"Upgrade to `mapclassify>=2.8.1` to ensure correct handling of NaN values.","message":"Versions prior to 2.8.1 had a bug in NaN handling for color arrays. While fixed, users on older versions should be aware of potential issues with missing data in visualization.","severity":"gotcha","affected_versions":"<2.8.1"},{"fix":"Consider using `splot` or direct `matplotlib`/`seaborn` for visualization in conjunction with mapclassify, as these are now the more actively integrated options.","message":"Mentions of `geoplot` were removed from the README and documentation around v2.8.0. This suggests a shift away from recommending `geoplot` for visualization within the PySAL ecosystem, possibly towards `splot` or direct `matplotlib` / `seaborn` integration.","severity":"deprecated","affected_versions":">=2.8.0"},{"fix":"Upgrade to `mapclassify>=2.10.0` to leverage the new `Colormap` and `cmap` detection features for improved visualization control.","message":"Version 2.10.0 introduced enhanced support for `Colormap` objects and `cmap` detection. If you're using custom color mapping with `plot_legendgram` or related functions, this release provides more flexible and idiomatic ways to integrate `matplotlib` colormaps.","severity":"gotcha","affected_versions":"<2.10.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}