kmodes Clustering Library

Warnings

• breaking Dropped support for missing values (np.NaN) in the input matrix (X) starting from version 0.11.1, following scikit-learn's approach. Users must now handle missing data manually by imputation or removal.
  Fix: Pre-process your data to handle `np.NaN` values (e.g., fill with a specific category for categorical features, or remove rows) before passing to `kmodes`.
• breaking Python 3.4 support was dropped in version 0.10.2. Official support for Python 3.10 was added in 0.12.0. Ensure your Python environment is compatible (Python 3.6+ is generally safe).
  Fix: Upgrade your Python environment to at least 3.6. For full compatibility with the latest features, Python 3.10 or newer is recommended.
• breaking The minimum `scikit-learn` version was upgraded to 0.22 in kmodes version 0.11.0. Older `scikit-learn` versions may cause compatibility issues or `AttributeError`.
  Fix: Upgrade your `scikit-learn` library to version 0.22 or newer: `pip install --upgrade scikit-learn`.
• gotcha When using `KPrototypes`, one or more of your numerical feature columns may contain string values, leading to `TypeError: '<' not supported between instances of 'str' and 'float'`.
  Fix: Ensure that all numerical columns are consistently typed as numeric (e.g., `float` or `int`) before passing them to `KPrototypes`. Convert string representations of numbers to their proper numeric types.
• gotcha For `KPrototypes`, you must explicitly specify which column indices are categorical using the `categorical` argument. If not provided, it assumes all are numerical, or can raise an error if mixed data types are present without specification.
  Fix: Pass a list of categorical column indices to the `categorical` parameter during `KPrototypes` initialization, e.g., `KPrototypes(..., categorical=[0, 2, 5])`.
• gotcha A `ModuleNotFoundError` (e.g., `No module named 'kmodes.kmodes'`) can occur if your working Python file is named `kmodes.py`, as it might shadow the installed `kmodes` package.
  Fix: Rename your local Python script to something other than `kmodes.py` (e.g., `my_script.py`) to avoid module name conflicts.
• gotcha Encountering `ValueError: Clustering algorithm could not initialize` is often an indication that the data and chosen parameters (e.g., `n_clusters`, `init` method) are not suitable. It's not necessarily a bug.
  Fix: Consider reducing the number of clusters, cleaning or normalizing your data, exploring different initialization methods, or ensuring sufficient data density for the chosen cluster count.

Install

• pip install kmodes Install with pip

Imports

• KModes

  from kmodes.kmodes import KModes

• KPrototypes

  from kmodes.kprototypes import KPrototypes

Quickstart

Demonstrates basic usage of the KModes algorithm for clustering purely categorical data. Initialize the KModes estimator, fit it to your data, and retrieve the cluster assignments and centroids.

import numpy as np
from kmodes.kmodes import KModes

# Generate random categorical data (e.g., 100 samples, 10 features, 20 unique categories per feature)
data = np.random.choice(20, (100, 10))

# Initialize KModes with 4 clusters, Huang initialization, 5 initialization runs
km = KModes(n_clusters=4, init='Huang', n_init=5, verbose=1)

# Fit the model and predict clusters
clusters = km.fit_predict(data)

# Print the cluster centroids
print("Cluster Centroids:\n", km.cluster_centroids_)
print("Assigned Clusters:\n", clusters[:10]) # Display first 10 assigned clusters