Metadata-Version: 2.4
Name: fdc
Version: 1.17
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=1.21
Requires-Dist: scikit-learn>=1.0
Requires-Dist: scipy>=1.7
Requires-Dist: clustering-benchmarks>=1.1 ; extra == 'benchmark'
Requires-Dist: tabulate>=0.9 ; extra == 'benchmark'
Requires-Dist: matplotlib>=3.4 ; extra == 'benchmark'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8 ; extra == 'dev'
Requires-Dist: matplotlib>=3.4 ; extra == 'plotting'
Provides-Extra: benchmark
Provides-Extra: dev
Provides-Extra: plotting
License-File: LICENSE.rst
Summary: Fast Density Clustering in low-dimension
Author-email: Alexandre Day <alexandre.day1@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://alexandreday.github.io/
Project-URL: Repository, https://github.com/alexandreday/fast_density_clustering

# fdc — Fast Density Clustering

A Python package for clustering low-dimensional data using kernel density maps and density graphs.
Ships with a Rust extension for 2–3x acceleration out of the box.

## Features

- **No cluster count required** — automatically discovers the number of clusters
- **Non-convex clusters** — handles crescents, rings, and other complex shapes
- **Multiscale** — works with varying densities and population sizes
- **Fast** — O(n log n) time, O(n) memory via KD-tree search
- **Rust-accelerated** — optional native extension for 2–3x speedup (pre-built wheels for Linux, macOS, Windows)
- **Two parameters** — neighborhood size (auto) and noise threshold (eta)

## Installation

```bash
pip install fdc
```

Pre-built wheels include the Rust extension. Falls back to pure Python if no wheel is available.

## Quick start

```python
from fdc import FDC
from sklearn.datasets import make_blobs
from sklearn.preprocessing import StandardScaler

X, y = make_blobs(n_samples=5000, n_features=2, centers=10)
X = StandardScaler().fit_transform(X)

model = FDC(eta=0.5)
model.fit(X)
print(f"Found {len(model.idx_centers)} clusters")
```

## Performance vs C-backed competitors (100K points, 2D)

| Algorithm | Runtime |
|---|---|
| **FDC (Rust)** | **1.8s** |
| FDC (Python) | 4.8s |
| DBSCAN (sklearn/C) | 23.7s |
| HDBSCAN (sklearn/C) | 61.8s |

## Links

- [GitHub](https://github.com/alexandreday/fast_density_clustering)
- [Examples](https://github.com/alexandreday/fast_density_clustering/tree/master/example)

## Citation

```bibtex
@article{mehta2018high,
  title={A high-bias, low-variance introduction to Machine Learning for physicists},
  author={Mehta, Pankaj and Bukov, Marin and Wang, Ching-Hao and Day, Alexandre GR and Richardson, Clint and Fisher, Charles K and Schwab, David J},
  journal={arXiv preprint arXiv:1803.08823},
  year={2018}
}
```

## License

MIT

