atlas-place 1.0.0

Phylogenetic placement via BiosphereAtlas hyperbolic coordinates

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

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

# 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

pip install atlas-place

With atlas-hplg integration:

pip install atlas-place[hplg]

Requirements

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

License

MIT — Sentry Bio Inc.