KlusterFudge

A Python library for clustering categorical data using the K-Modes algorithm. It supports multiple initialization methods and distance metrics, optimized with numba for performance.

Documentation | PyPI

Features

• Algorithms: K-Modes clustering for categorical data
• GPU Acceleration: Optional PyTorch-based GPU acceleration via KModesGPU
• Distance Metrics: Hamming, Jaccard, and NG dissimilarity measures
• Initialization: Random, Huang, and Cao methods
• Optimization: CPU operations accelerated with numba, GPU operations with PyTorch
• Integration: Supports all ArrayLikes (numpy arrays, pandas DataFrames, lists, etc.)

Installation

Install KlusterFudge via pip:

pip install kluster-fudge

Or install from source:

git clone https://github.com/ethqnol/KlusterFudge.git
cd KlusterFudge
pip install .

GPU Acceleration (Optional)

For GPU acceleration, install PyTorch:

pip install torch

See PyTorch installation guide for CUDA/ROCm support.

Quick Start

import pandas as pd
from kluster_fudge import KModes

# 1. Load Data
df = pd.DataFrame({
    'color': ['red', 'blue', 'red', 'green', 'blue', 'green'],
    'size': ['small', 'large', 'small', 'large', 'medium', 'medium'],
    'shape': ['circle', 'square', 'circle', 'square', 'triangle', 'triangle']
})

# 2. Initialize Model
model = KModes(
    n_clusters=2, 
    init_method='cao', 
    dist_metric='hamming', 
    random_state=42
)

# 3. Fit and Predict
clusters = model.fit_predict(df)
print("Cluster Labels:", clusters)

GPU Acceleration

For large datasets, use KModesGPU for significant speedups (unless using NG dissimilarity):

from kluster_fudge import KModesGPU
import numpy as np

# Large dataset
X = np.random.randint(0, 10, size=(100000, 20))

# GPU model (auto-detects CUDA/MPS/CPU)
model_gpu = KModesGPU(n_clusters=5, n_init=5, random_state=42)
model_gpu.fit(X)

# 3-6x faster than CPU on typical datasets

Performance: On a 100k sample dataset, GPU achieves ~3.2x speedup on Apple Silicon (MPS) and up to 6x on CUDA GPUs.

Comparisons & Benchmarks

See benchmarks/benchmark_metrics.py

(Run on 5000 samples, 20 features, 10 categories)

License

MIT License