Metadata-Version: 2.4
Name: toc-cluster
Version: 0.1.0
Summary: Trust Orbit Computation: clustering with confidence
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: scikit-learn>=1.0
Requires-Dist: scipy>=1.7
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# toc-cluster

**Trust Orbit Computation** — a clustering algorithm that tells you not just which cluster each point belongs to, but *how confident* that assignment is.

## Install

```bash
pip install toc-cluster
```

## Quick Start

```python
from toc import TOC
import numpy as np

X = np.random.randn(1000, 50)   # your data, shape (n_samples, n_features)

model = TOC(n_clusters=5)
model.fit(X)

print(model.labels_)          # cluster label for every point, shape (1000,)
print(model.states_)          # 'MERGE', 'ORBIT', or 'ESCAPE' per point
print(model.orbit_percent_)   # ORBIT% per cluster — measures boundary ambiguity
model.summary()               # print full results table
```

## The Three States

| State | Meaning | What it tells you |
|-------|---------|-------------------|
| MERGE | Confidently inside a cluster | High-quality assignment |
| ORBIT | Genuinely between clusters | Boundary — assignment uncertain |
| ESCAPE | Outlier | Far from any cluster structure |

## Why Use TOC Instead of K-Means?

K-Means assigns every point with equal confidence. TOC tells you which assignments are confident (MERGE) and which are uncertain (ORBIT).

**On the Samusik CyTOF benchmark** (514,386 cells, 24 populations):
- K-Means: ARI 0.597
- FlowSOM (current standard): ARI 0.730
- **TOC: ARI 0.907**

**On PBMC 10k scRNA-seq** (11,922 cells, 14 cell types):
- K-Means: ARI 0.684
- scVI + Leiden (deep learning): ARI 0.730
- **TOC: ARI 0.891**

## When to Use TOC

TOC works best when:
- IntrD (intrinsic dimensionality) > 10
- N/K (average points per cluster) > 150
- Data is preprocessed (normalized, PCA-reduced)

Not recommended for: raw count scRNA-seq, small tabular datasets, graph-structured data.

## GPU Support

TOC automatically uses GPU if CUDA is available. No code changes needed.

```python
# Same code works on CPU and GPU
model = TOC(n_clusters=5)
model.fit(X)   # uses GPU automatically if available
```

## ORBIT% — The Novel Output

ORBIT% per cluster measures how many of a cluster's members sit at the boundary with other clusters. High ORBIT% = ambiguous cluster. Low ORBIT% = well-defined cluster.

Example from human bone marrow (263,159 cells):
- MPP-MyLy (multipotent progenitor): 89.4% ORBIT — between myeloid and lymphoid lineages
- Plasma Cell (terminally differentiated): 0.9% ORBIT — most distinct cell type

TOC recovered the known haematopoietic hierarchy from geometry alone.

## Citation

[Paper link — coming soon]

## License

MIT
