Mapclassify

Warnings

• breaking 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`.
  Fix: Upgrade Python to 3.11+ or pin `mapclassify` to `<2.9.0` in your project dependencies.
• gotcha When working with `FisherJenks` classification, `numba` is highly recommended for performance, especially with large datasets. Without it, the algorithm can be significantly slower.
  Fix: Install `numba` as an optional dependency: `pip install mapclassify[all]` or `pip install numba`.
• gotcha 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.
  Fix: Upgrade to `mapclassify>=2.8.1` to ensure correct handling of NaN values.
• deprecated 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.
  Fix: Consider using `splot` or direct `matplotlib`/`seaborn` for visualization in conjunction with mapclassify, as these are now the more actively integrated options.
• gotcha 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.
  Fix: Upgrade to `mapclassify>=2.10.0` to leverage the new `Colormap` and `cmap` detection features for improved visualization control.

Install

• pip install mapclassify Core installation
• pip install mapclassify[plotting] With plotting dependencies (e.g., matplotlib, seaborn)
• pip install mapclassify[all] All optional dependencies (e.g., numba, geopandas)

Imports

• mapclassify

  import mapclassify as mc

  The standard convention is to import mapclassify as 'mc'.
• Quantiles

  mc.Quantiles

  Typically accessed via the aliased import `mc`.
• NaturalBreaks

  mc.NaturalBreaks

  Typically accessed via the aliased import `mc`.
• FisherJenks

  mc.FisherJenks

  Typically accessed via the aliased import `mc`. Numba is recommended for performance.

Quickstart

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()