Metadata-Version: 2.4
Name: pipnn
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: scikit-learn>=1.2
Requires-Dist: pynndescent>=0.5 ; extra == 'bench'
Requires-Dist: faiss-cpu>=1.8 ; extra == 'bench'
Requires-Dist: matplotlib>=3.5 ; extra == 'bench'
Requires-Dist: h5py>=3.6 ; extra == 'bench'
Requires-Dist: faiss-cpu>=1.8 ; extra == 'faiss'
Requires-Dist: scanpy>=1.10 ; extra == 'scanpy'
Requires-Dist: anndata>=0.9 ; extra == 'scanpy'
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: scanpy>=1.10 ; extra == 'test'
Requires-Dist: pynndescent>=0.5 ; extra == 'test'
Provides-Extra: bench
Provides-Extra: faiss
Provides-Extra: scanpy
Provides-Extra: test
License-File: LICENSE
Summary: Fast graph-based approximate nearest-neighbor indexing for single-cell / scanpy — a Rust implementation of the PiPNN method
Keywords: nearest-neighbors,knn,ann,approximate-nearest-neighbors,single-cell,scanpy,vector-search,hnsw,rust,bioinformatics
Author: Ian Driver
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/iandriver/pipnn-scanpy
Project-URL: Issues, https://github.com/iandriver/pipnn-scanpy/issues
Project-URL: Paper, https://arxiv.org/abs/2602.21247
Project-URL: Repository, https://github.com/iandriver/pipnn-scanpy

# pipnn

Fast, graph-based approximate-nearest-neighbor indexing for building the k-NN
graph in single-cell / `scanpy` workflows — a Rust implementation (with PyO3
bindings) of the **PiPNN** method. It plugs into `scanpy` as a drop-in
`sc.pp.neighbors` backend and also exposes a small standalone API. It builds the
graph quickly at recall close to exact, and scales to tens of millions of cells.

> Independent implementation of the PiPNN algorithm. Please cite the paper:
> Tobias Rubel, Richard Wen, Laxman Dhulipala, Lars Gottesbüren, Rajesh Jayaram,
> Jakub Łącki. *PiPNN: Ultra-Scalable Graph-Based Nearest Neighbor Indexing.*
> [arXiv:2602.21247](https://arxiv.org/abs/2602.21247)

## Install

```bash
uv pip install pipnn      # or: pip install pipnn
```

Prebuilt wheels for Linux (x86_64, aarch64), macOS (arm64, x86_64), and Windows
(x86_64); Python 3.9+. No Rust toolchain needed to install.

## Quickstart

**As a scanpy backend** (drop-in for the default neighbor step):

```python
import scanpy as sc
from pipnn import PiPNNTransformer

sc.pp.neighbors(adata, n_neighbors=15, use_rep="X_pca",
                transformer=PiPNNTransformer())
# then sc.tl.umap / sc.tl.leiden as usual
```

**Standalone** (just the k-NN graph):

```python
import numpy as np
from pipnn import self_knn_graph

X = np.random.default_rng(0).normal(size=(100_000, 50)).astype("float32")
indices, distances = self_knn_graph(X, n_neighbors=15)
# indices, distances: shape (n, k+1), self edge first, sorted by distance
```

## What it does

- Produces the exact-distance k-NN graph `scanpy` expects — a scipy CSR of shape
  `(n, n)` with `k+1` entries per row, the self edge first.
- `euclidean` (default, matches scanpy on PCA space) and `cosine` metrics.
- Parallel Rust build; deterministic given a fixed `random_state`.
- Optional comparison backends under `pipnn.contrib` behind the same transformer
  API: a native `HnswTransformer`, `FaissTransformer` (`pip install pipnn[faiss]`),
  and `GlassTransformer` (pyglass).

## Benchmarks & source

Full benchmarks — SIFT, and the Tahoe-100M single-cell atlas from 1M to 10M cells
(build time, recall, and peak memory vs FAISS, pyglass, and pynndescent) — plus
development notes and the comparison harness, are in the repository:

**https://github.com/iandriver/pipnn-scanpy**

MIT licensed.

