ImpKMeans

ImpKMeans is an improved version of the K-Means clustering algorithm, designed to automatically determine high-quality initial centroids using:

• Multivariate Kernel Density Estimation (KDE)
• KD-Tree–based radius suppression
• Mode-seeking peak extraction

Motivation

K-Means often performs poorly when its initial centroids are chosen randomly. The paper shows that selecting centroids from KDE-based density peaks and filtering them with a KD-Tree radius rule leads to more accurate and stable clustering. ImpKMeans implements this idea to provide a simple, effective improvement over standard K-Means initialization.

🚀 Features

• KDE-based high-density region detection
• Intelligent centroid selection via KD-Tree radius filtering
• Deterministic behavior with random_state
• Fully compatible with scikit-learn API (fit, fit_predict, predict, get_params, set_params)
• Lightweight and fast

📦 Installation

Install directly from PyPI:

pip install impkmeans

Basic Usage

from sklearn.datasets import load_iris
from impkmeans import ImpKMeans
from sklearn.metrics.cluster import adjusted_rand_score

# Load dataset
data = load_iris()
X, y = data.data, data.target

model = ImpKMeans(k=7, r=0.7245, random_state=42)
labels = model.fit_predict(X)

ARI=adjusted_rand_score(y, labels)
print("Adjusted Rand Index = %0.4f"%ARI)

Cite

If you use the code in your works, please cite the paper given below:

Şenol, A. (2024). Impkmeans: An improved version of the k-means algorithm, by determining 
optimum initial centroids, based on multivariate kernel density estimation and kd-tree. 
Acta Polytechnica Hungarica, 21(2), 111-131.

@article{csenol2024impkmeans,
  title={Impkmeans: An improved version of the k-means algorithm, by determining optimum initial centroids, based on multivariate kernel density estimation and kd-tree},
  author={{\c{S}}enol, Ali},
  journal={Acta Polytechnica Hungarica},
  volume={21},
  number={2},
  pages={111--131},
  year={2024}
}

License

This project is licensed under the MIT License. See the LICENSE file for details.