Metadata-Version: 2.5
Name: chameleon-cluster
Version: 0.1.1
Summary: CHAMELEON hierarchical clustering using dynamic modeling
Project-URL: Homepage, https://github.com/oszypczy/pychameleon
Project-URL: Documentation, https://chameleon-cluster.readthedocs.io
Project-URL: Repository, https://github.com/oszypczy/pychameleon
Project-URL: Issues, https://github.com/oszypczy/pychameleon/issues
Author-email: Oliwier Szypczyn <oliwier.szypczyn@tenvalleys.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chameleon,clustering,data-mining,hierarchical-clustering,unsupervised-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Requires-Dist: pymetis>=2025.2
Requires-Dist: scikit-learn>=1.6
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: mypy>=1.7; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: matplotlib>=3.7; extra == 'docs'
Requires-Dist: numpydoc>=1.8; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.16; extra == 'docs'
Requires-Dist: sphinx>=8.0; extra == 'docs'
Provides-Extra: experiments
Requires-Dist: jupyter>=1.0; extra == 'experiments'
Requires-Dist: nbconvert>=7.0; extra == 'experiments'
Requires-Dist: nbstripout>=0.7; extra == 'experiments'
Requires-Dist: notebook>=7.0; extra == 'experiments'
Requires-Dist: pandas>=2.0; extra == 'experiments'
Requires-Dist: pyyaml>=6.0; extra == 'experiments'
Requires-Dist: seaborn>=0.13; extra == 'experiments'
Requires-Dist: tqdm>=4.65; extra == 'experiments'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == 'viz'
Description-Content-Type: text/markdown

# pychameleon

[![PyPI](https://img.shields.io/pypi/v/chameleon-cluster)](https://pypi.org/project/chameleon-cluster/)
[![CI](https://github.com/oszypczy/pychameleon/actions/workflows/ci.yml/badge.svg)](https://github.com/oszypczy/pychameleon/actions/workflows/ci.yml)
[![Docs](https://readthedocs.org/projects/chameleon-cluster/badge/?version=latest)](https://chameleon-cluster.readthedocs.io)

**Documentation:** https://chameleon-cluster.readthedocs.io

Implementation of the CHAMELEON hierarchical clustering algorithm ([Karypis, Han, Kumar, 1999](https://glaros.dtc.umn.edu/gkhome/fetch/papers/chameleonCOMPUTER99.pdf)) with a scikit-learn compatible API.

CHAMELEON discovers clusters of arbitrary shapes, densities, and sizes by using a two-phase approach:

1. **Phase I**: partition a k-nearest-neighbor graph into many small sub-clusters via [METIS](https://www.cs.umn.edu/~metis).
2. **Phase II**: agglomeratively merge sub-clusters using **dynamic modeling** — decisions consider each cluster's internal inter-connectivity and closeness, not a fixed global threshold.

## Installation

```bash
uv add chameleon-cluster        # with uv
# or
pip install chameleon-cluster   # with pip
```

The distribution is named `chameleon-cluster`; the import name is `pychameleon`.

> **Windows:** the `pymetis` dependency has no Windows wheels on PyPI. Install it
> from conda-forge first (`conda install -c conda-forge pymetis`), then
> `pip install chameleon-cluster`.

## Quick start

```python
import numpy as np
from pychameleon import Chameleon

X = np.random.rand(500, 2)

model = Chameleon(n_clusters=5, k_nn=10, min_cluster_size=0.025, alpha=2.0)
labels = model.fit_predict(X)

print(f"Found {model.n_clusters_} clusters, labels: {np.unique(labels)}")
```

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `n_clusters` | `8` | Target number of final clusters |
| `k_nn` | `10` | Number of neighbors in the k-NN graph |
| `min_cluster_size` | `0.025` | Minimum Phase-I sub-cluster size (fraction of `n` if `< 1`, else absolute count) |
| `alpha` | `2.0` | Exponent for relative closeness in the merge score: `RI · RC^alpha` |

## Development

```bash
git clone https://github.com/oszypczy/pychameleon.git
cd pychameleon
uv sync --all-extras

uv run pytest           # tests + coverage
uv run ruff check .     # lint
uv run mypy src/        # type check
```

## References

- Karypis, G., Han, E.-H., & Kumar, V. (1999). *Chameleon: hierarchical clustering using dynamic modeling*. Computer, 32(8), 68–75.
- Karypis, G., & Kumar, V. (1998). *A fast and high quality multilevel scheme for partitioning irregular graphs*. SIAM J. Sci. Comput., 20(1), 359–392.

## License

MIT
