atlas-chimera 0.5.0

Reference-free chimera detection for metagenomic assemblies and long-read amplicons

atlas-chimera

Reference-free chimera detection for metagenomic contigs and long-read amplicons.

atlas-chimera detects chimeric sequences by analyzing geometric consistency of sliding-window embeddings in the BiosphereAtlas Poincaré manifold. v0.5 uses a pure-API inference path — per-window encoding via Atlas v8.4+compact2 (:8003 /predict) and KESTREL v8.4 (:8002 /classify) — with a pre-trained logistic regression head on 26-d geometric features.

TEST F1 = 0.886 on the cross-phylum 3000bp contig benchmark (v0.5, Atlas v8.4+compact2, P=0.870 R=0.903 at T=0.300). Marginally below the v0.4 number (F1 = 0.898 on Atlas v9) — the ~0.01 gap is the cost of aligning the encoder with the v1.0 production path (see CHANGELOG.md for the v0.4 errata where earlier docs quoted a 0.905 CV F1 where they should have used TEST F1).

Still the only working ref-free tool in this regime (vsearch UCHIME_ref structurally fails due to maxseqlength=50000).

---

When to use this tool

✅ Intended use:

• Per-contig chimera QC for metagenomic assemblies (SPAdes, megahit, metaSPAdes output) before binning
• Long-read 16S/ITS/18S full-length amplicons (PacBio HiFi, Nanopore 1.5kb)
• Metagenome-assembled genome (MAG) screening — detect chimeric contigs that would contaminate MAGs
• Any genomic sequence ≥ 1500bp where reference-free detection is valuable (novel environments, non-model organisms)

❌ NOT recommended for:

• Short-read 16S amplicons (<500bp) — use UCHIME/UCHIME3 via vsearch. The encoder has a sharp length cliff below 250bp.
• Regimes where UCHIME works (16S, amplicon, abundant reference) — UCHIME achieves F1 = 0.99 there; we don't compete.

atlas-chimera is complementary to UCHIME and GUNC, not a replacement.

---

Quick start

Via the unified sentry-bio/atlas pipeline (recommended)

atlas-chimera is one module in the larger coordinate-native pipeline. The easiest way to use it is via that pipeline's pre-built container, which also runs atlas-place using the same coordinate frame:

nextflow run sentry-bio/atlas -profile docker \
  --input samples.csv --analysis chimera \
  --atlas_api_key $ATLAS_API_KEY

Standalone CLI against api.biosphereatlas.com

pip install atlas-chimera==0.5.0

atlas-chimera contigs.fa \
  --output chimeras.tsv \
  --summary summary.json \
  --api-url https://api.biosphereatlas.com \
  --api-key $ATLAS_API_KEY

Standalone CLI against a local Atlas + KESTREL container

If you've pulled the sentry-bio/atlas container and have Atlas on :8003 and KESTREL on :8002 locally:

atlas-chimera contigs.fa \
  --output chimeras.tsv \
  --summary summary.json \
  --api-url http://127.0.0.1:8003 \
  --kestrel-url http://127.0.0.1:8002 \
  --api-key $ATLAS_API_KEY

Via Nextflow

nextflow run sentry-bio/atlas-chimera \
  -profile docker \
  --input samplesheet.csv \
  --outdir results

samplesheet.csv:

sample,fasta
soil_assembly,/path/to/soil_contigs.fa
gut_assembly,/path/to/gut_contigs.fa

Outputs go to results/atlaschimera/{sample}/:

• {sample}.chimeras.tsv — per-sequence chimera calls + scores
• {sample}.nonchimeras.fa — clean sequences (feed into binning)
• {sample}.chimeric_reads.fa — flagged sequences (for manual review)
• {sample}.summary.json — counts, runtime, config

---

Output format

chimeras.tsv:

column	meaning
sequence_id	FASTA header (first token)
is_chimera	1 = chimeric, 0 = clean
probability	Ensemble classifier probability [0, 1]
score	Raw chimera score (changepoint strength)
length	Sequence length in bp
n_windows	Number of overlapping windows analyzed

---

How it works

1. Window the sequence: 400 bp sliding windows with 150 bp stride (defaults)
2. Embed each window via HTTP:
   • Atlas v8.4+compact2 (:8003 /predict, 129-d tangent, paid-tier API key)
   • KESTREL v8.4 (:8002 /classify, 129-d coords)
3. Extract 13 geometric features per encoder (cp_2state, cp_3state, block-A/B consistency, centroid distance, pairwise stats)
4. Concatenate to 26 features and apply the shipped logistic regression classifier
5. Call chimera if probability exceeds the bundled threshold (T = 0.300, selected on a stratified held-out slice — see CHANGELOG.md)

See BENCHMARK_REPORT.md for the v0.4 benchmark methodology (numbers there are the historical v0.4 record; current v0.5 shipping numbers are at the top of this README and in CHANGELOG.md).

---

Performance

v0.5 is API-bound, not compute-bound. Throughput scales with the Atlas + KESTREL servers:

• Against api.biosphereatlas.com: ~5 sequences/sec with 8 parallel workers (default)
• Against a local sentry-bio/atlas container (same GPU as the public API): similar throughput, no network latency
• Local machine needs only enough RAM for the classifier + feature matrix (~100 MB for 10K contigs)

No GPU required on the client. The Atlas server does the PyTorch work.

---

Known limitations

1. Encoder length cliff at ~250 bp: windows below this produce meaningless embeddings. Sequences under 500 bp will be reported as no-call.
2. Cross-phylum chimeras are easiest to detect; cross-family within-phylum is harder (signal compresses).
3. Transition windows spanning the breakpoint are intrinsically ambiguous; oracle accuracy on these is only 62%.
4. F1 ceiling at ~0.90 is structural across multiple independent approaches (encoder fine-tuning, KESTREL swap, feature engineering, learned aggregator, length scaling). See BENCHMARK_REPORT.md for the complete ceiling investigation and future research directions that could plausibly break it.

---

Benchmarks

Full benchmark methodology, numbers, and reproducibility info in BENCHMARK_REPORT.md.

Summary:

Regime	atlas-chimera v0.5 F1	atlas-chimera v0.4 F1	vsearch UCHIME_ref F1
16S 250bp (Edgar 2011)	~0.55	~0.55	0.841
16S 1500bp (held-out family)	~0.855	0.855	0.988
Genomic contigs 3000bp (cross-phylum)	0.886	0.898	0.000 (tool broken in regime)
Genomic contigs 6000bp (cross-phylum)	—	0.881	— (length scaling does not help)

v0.5 ships against Atlas v8.4+compact2 (v1.0 production encoder); v0.4 was against Atlas v9. The ~0.01 F1 difference on the primary benchmark is the cost of coordinate-frame alignment with atlas-place; everything else is within noise.

---

Citation

@software{atlas_chimera_2026,
  author = {Fenn, R. and Fenn, A.},
  title  = {atlas-chimera: Reference-free chimera detection via hyperbolic sequence embeddings},
  year   = {2026},
  url    = {https://github.com/sentry-bio/atlas-chimera},
  note   = {v0.5.0}
}

Underlying geometry: Fenn, R. & Fenn, A. (2025). Evolution as Active Geometry: A Universal Curvature Constant. bioRxiv.

---

License

MIT. See LICENSE.