Metadata-Version: 2.4
Name: atlas-place
Version: 1.0.0
Summary: Phylogenetic placement via BiosphereAtlas hyperbolic coordinates
Project-URL: Homepage, https://github.com/sentry-bio/atlas-place
Author: Sentry Bio Inc.
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,biosphere-atlas,coordinate-native,hyperbolic-geometry,phylogenetics,placement
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Requires-Dist: numpy>=1.24
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: local
Requires-Dist: atlas-core>=1.0.0; extra == 'local'
Requires-Dist: biopython>=1.80; extra == 'local'
Requires-Dist: torch>=2.0; extra == 'local'
Requires-Dist: tqdm; extra == 'local'
Description-Content-Type: text/markdown

# atlas-place

**Phylogenetic placement via BiosphereAtlas hyperbolic coordinates.**

Drop-in replacement for pplacer / GTDB-Tk `classify_wf`. Every query
sequence gets a BiosphereAtlas (r, θ) coordinate and a conformal
three-zone decision (accept / escalate / fallback) with formal coverage
guarantees.

## How it works

```
sequence → embedding → nearest-prototype → calibrated placement
```

1. **Encode**: DNA sequence → Poincaré ball embedding via BiosphereCodec
2. **Index**: O(log n) nearest-prototype lookup via hyperbolic VP-tree
3. **Place**: Ranked candidates with geodesic distance and margin
4. **Calibrate**: Conformal prediction → three-zone decision with coverage guarantee P(correct) ≥ 1−ε

## Quick start

```python
from atlas_place import place_sequences, ReferenceDB

ref = ReferenceDB.load("reference.pkl")
results = place_sequences("input.fasta", ref)

for r in results:
    print(f"{r.sequence_id}\t{r.best_placement.taxon_id}\t{r.zone}\t{r.confidence:.3f}")
```

## CLI

```bash
# Basic placement
atlas-place place input.fasta -r reference.pkl -o placements.tsv

# V13 checkpoint placement (end-to-end FASTA -> embedding)
atlas-place place input.fasta -r reference.pkl \
  --model /zfs_raid/SentryBio/working/checkpoints/v13_living_geometry/best.pt \
  --tokenizer /zfs_raid/SentryBio/working/inference_data/bpe_vocab.json \
  --device cuda

# pplacer-compatible output
atlas-place place input.fasta -r reference.pkl --format jplace -o placements.jplace

# Hierarchical mode (top-down through ranks)
atlas-place place input.fasta -r reference.pkl --mode hierarchical

# Reference database info
atlas-place info -r reference.pkl

# Build reference DB from manifest + V13 checkpoint
atlas-place build-ref \
  --manifest /zfs_raid/SentryBio/working/v10_1_tokenized/v10_1_manifest.csv \
  --model /zfs_raid/SentryBio/working/checkpoints/v13_living_geometry/best.pt \
  --tokenizer /zfs_raid/SentryBio/working/inference_data/bpe_vocab.json \
  --split train \
  --rank family \
  --device cuda \
  --output v13_reference_family.pkl
```

## Output columns

| Column | Description |
|--------|-------------|
| `sequence_id` | Query identifier |
| `classification` | Best-match taxon |
| `rank` | Taxonomic rank of best match |
| `lineage` | Full lineage string (`;`-separated) |
| `distance` | Geodesic distance to nearest prototype |
| `margin` | Gap between 1st and 2nd nearest (discrimination signal) |
| `zone` | Conformal zone: `accept` / `escalate` / `fallback` |
| `confidence` | Calibrated placement confidence ∈ [0, 1] |
| `prediction_set_size` | Conformal prediction set size (1 = singleton) |
| `atlas_r` | Hyperbolic radial coordinate (distance from LUCA) |
| `atlas_theta` | Angular coordinate in BiosphereAtlas (r, θ) space |
| `n_candidates` | Number of candidate placements returned |

## Three-zone decisions

| Zone | Condition | Meaning |
|------|-----------|---------|
| **accept** | A ≤ q_accept | High-confidence singleton placement |
| **escalate** | q_accept < A ≤ q_fallback | Prediction set of plausible taxa |
| **fallback** | A > q_fallback | Abstain — escalate to coarser rank |

The nonconformity score A combines nearest distance, margin, and
evolutionary depth:

```
A = d_best − η·margin + ρ·r_evolutionary
```

Conformal quantiles use finite-sample correction:
`q = ⌈(n+1)(1−ε)⌉ / n`

## Geometry

All operations use the Poincaré ball model with curvature κ = 1.247
(Fenn & Fenn 2025). Ball radius R = 1/√κ ≈ 0.896.

The coordinate system is shared with atlas-chimera and atlas-hplg:
- **r** = hyperbolic distance from origin (LUCA)
- **θ** = angular coordinate (phylogenetic direction)

## Architecture

```
atlas_place/
├── hyperbolic.py    # Poincaré ball geometry (κ=1.247)
├── reference.py     # Reference database (prototype store + taxonomy)
├── index.py         # VP-tree + brute-force spatial index
├── placer.py        # Core nearest-prototype placement engine
├── calibrator.py    # Conformal calibration (three-zone decisions)
├── encoder.py       # BiosphereCodec/V13 wrapper (+ k-mer dev proxy)
├── place.py         # Main pipeline orchestration
├── build_reference.py # Manifest -> reference prototype builder
├── io.py            # FASTA/TSV/JSON/.jplace I/O
└── cli.py           # Command-line interface
```

## Installation

```bash
pip install atlas-place
```

With atlas-hplg integration:
```bash
pip install atlas-place[hplg]
```

## Requirements

- Python ≥ 3.9
- PyTorch ≥ 2.0
- NumPy ≥ 1.24
- BioPython ≥ 1.80

## License

MIT — Sentry Bio Inc.
