kmodes

What it is and what it does

kmodes provides Python implementations of k-modes and k-prototypes clustering, specialized for categorical and mixed data types. Unlike k-means, which clusters numerical data by Euclidean distance, k-modes clusters categorical variables by counting matching categories between points. k-prototypes extends this to handle datasets with both numerical and categorical features. The library mirrors scikit-learn's clustering API, making it familiar to users of that ecosystem.

The package relies on numpy for computation and supports parallel execution via joblib for multiple initialization runs. It includes initialization strategies such as Huang's method and density-based approaches. All runtime dependencies (numpy, scikit-learn, scipy, joblib) are standard data-science libraries with low installation friction.

Use it for:

• Cluster customer records with mixed demographic (categorical) and behavioral (numerical) attributes.
• Segment product categories or survey responses where most features are discrete or nominal.
• Analyze categorical genomic or medical data where Euclidean distance is not meaningful.
• Reduce dimensionality or find patterns in text-encoded or one-hot-encoded feature sets.
• Benchmark or compare k-modes results against k-means on datasets with predominantly categorical features.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Implements k-modes and k-prototypes clustering algorithms for categorical and mixed numerical/categorical data, with a scikit-learn-compatible interface.

Yes, if you need to cluster categorical or mixed-type data and want a scikit-learn-compatible interface. The low install friction and permissive license make it a straightforward choice. However, the dormant maintenance status (last release 2022-09-06) warrants checking compatibility with your current numpy and scikit-learn versions before committing to production use.

Install

kmodes on PyPI

pip install kmodes

uv add kmodes

poetry add kmodes

Installing kmodes

Before you install

Low friction install with standard dependencies (numpy, scikit-learn, scipy, joblib). Maintenance is dormant—last release was 2022-09-06, though the repository remains active with recent commits and no archived status.

License in practice

MIT license permits commercial and private use with minimal restrictions; you must include the license text in distributions.

Quickstart

pip install kmodes

import numpy as np
from kmodes.kmodes import KModes

data = np.random.choice(20, (100, 10))
km = KModes(n_clusters=4, init='Huang', n_init=5, verbose=1)
clusters = km.fit_predict(data)

Input data must have consistent data types within columns; NaN values are not accepted and must be handled before clustering.

Verify before relying

• Whether the dormant maintenance status affects compatibility with current numpy/scikit-learn versions.
• Performance characteristics and scalability limits for large datasets relative to alternatives.

Package facts

Evidence: kmodes-0.12.2-py2.py3-none-any.whl

Tags

More Scientific/Engineering packages

Further reading