Metadata-Version: 2.4
Name: atlas-chimera
Version: 0.5.0
Summary: Reference-free chimera detection for metagenomic assemblies and long-read amplicons
Project-URL: Homepage, https://biosphereatlas.com
Project-URL: Repository, https://github.com/sentry-bio/atlas-chimera
Project-URL: Documentation, https://biosphereatlas.com/docs/chimera
Project-URL: API, https://api.biosphereatlas.com
Author-email: "Sentry Bio, Inc." <research@sentry.bio>
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,biosphere-atlas,chimera-detection,hyperbolic-geometry,long-read,metagenomics,poincare-ball
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: httpx>=0.24
Requires-Dist: joblib>=1.2
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: local
Requires-Dist: geoopt>=0.5.0; extra == 'local'
Requires-Dist: torch>=2.0; extra == 'local'
Requires-Dist: tqdm; extra == 'local'
Description-Content-Type: text/markdown

# 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](https://github.com/torognes/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:

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

### Standalone CLI against api.biosphereatlas.com

```bash
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:

```bash
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

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

`samplesheet.csv`:

```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

```bibtex
@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`.
