Metadata-Version: 2.4
Name: drasc
Version: 0.1.0
Summary: Density-Ratio Adaptive Spectral Clustering: a scikit-learn-compatible clustering estimator.
Author-email: Saikiran Gogineni <goginenisaikiran31677@gmail.com>
License: MIT
Keywords: clustering,spectral-clustering,machine-learning,unsupervised-learning,scikit-learn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: scikit-learn>=1.1
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# DRASC — Density-Ratio Adaptive Spectral Clustering

A small, dependency-light, **scikit-learn-compatible** clustering estimator.

DRASC builds a sparse k-nearest-neighbour graph with a self-tuning (per-point
adaptive) bandwidth, down-weights edges that bridge regions of very different
density via a density-ratio term raised to the power `gamma`, and then runs
normalized spectral clustering on the resulting graph.

## Installation

```bash
pip install drasc
```

Or from a local checkout:

```bash
pip install .
```

Requires Python ≥ 3.9 and `numpy`, `scipy`, `scikit-learn` (installed
automatically).

## Quick start

```python
from sklearn.datasets import load_wine
from sklearn.preprocessing import StandardScaler
from drasc import DRASC

X = StandardScaler().fit_transform(load_wine().data)

model = DRASC(n_clusters=3)
labels = model.fit_predict(X)
```

Because it follows the scikit-learn estimator API, it works with `Pipeline`,
`GridSearchCV`, and the `sklearn.metrics` clustering scores:

```python
from sklearn.pipeline import make_pipeline
from sklearn.metrics import adjusted_rand_score

pipe = make_pipeline(StandardScaler(), DRASC(n_clusters=3))
labels = pipe.fit_predict(X)
```

## Parameters

| Parameter      | Default | Description |
|----------------|---------|-------------|
| `n_clusters`   | —       | Number of clusters to form (required, ≥ 2). |
| `n_neighbors`  | `None`  | Graph neighbours; `None` → `max(10, ceil(2·log2 n))`. |
| `gamma`        | `2.0`   | Density-ratio exponent. `0` disables reweighting. |
| `random_state` | `0`     | Seed for the final k-means step. |
| `n_init`       | `30`    | k-means initializations on the embedding. |
| `n_jobs`       | `-1`    | Parallel jobs for the neighbour search. |

## Fitted attributes

- `labels_` — cluster label per sample.
- `embedding_` — row-normalized spectral embedding `(n_samples, n_clusters)`.
- `eigengap_` — relative eigengap at the `n_clusters` boundary, useful for
  selecting `n_clusters` / `gamma` / `n_neighbors`.

## Tips

- **Standardize your features first** (e.g. `StandardScaler`). DRASC uses
  Euclidean distances, so feature scales matter.
- For high-dimensional data, reduce with PCA before clustering.
- Sweep `eigengap_` over candidate settings to pick hyperparameters without
  labels.

## License

MIT
