toc-cluster 0.1.0

Trust Orbit Computation: clustering with confidence

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

pip install toc-cluster

Quick Start

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.

# 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