Skip to content

README

Jump to bottom
genomewalker edited this page Feb 26, 2026 · 8 revisions

AMBER — Ancient Metagenomic BinnER

License: MIT GitHub release CI

AMBER bins metagenomic contigs from ancient DNA (aDNA) samples. Unlike general-purpose binners that treat all coverage signal as equally informative, AMBER models post-mortem DNA damage and fragment length degradation explicitly, learning contig embeddings that are robust to the mixed ancient/modern DNA signal common in paleogenomic assemblies.

The problem: ancient DNA breaks metagenomic binning

Standard binners (MetaBAT2, SemiBin2, COMEBin) rely on two signals: tetranucleotide frequency (genomic composition) and coverage depth (co-abundance across samples). Both are distorted in ancient DNA:

  1. Damage-induced composition shift. Post-mortem deamination converts cytosines to uracil (read as T) at fragment termini [Briggs et al. 2007]. C→T at 5′ and G→A at 3′ change the apparent tetranucleotide composition of every contig, pushing damaged and undamaged contigs of the same genome apart in composition space.

  2. Fragment length bias in coverage. Ancient reads are short (~50–150 bp) while modern reads are longer (~150–300 bp). Short reads map more ambiguously and cover terminal regions of contigs differently, making coverage profiles systematically different between ancient and modern genomes even at equal abundance.

  3. Mixed ancient/modern populations. Many paleogenomic assemblies contain reads from both ancient (damaged) DNA and modern (undamaged) DNA — from environmental contamination, recent organisms in the same sediment, or microbes that colonised the sample post-deposition. A binner unaware of this mixture conflates ancient and modern strains of the same species into a single bin, or splits a single ancient genome across multiple bins.

AMBER addresses all three by learning damage-aware embeddings and providing an EM-based deconvolution subcommand that separates ancient from modern reads before or after binning.

How AMBER works

AMBER pipeline overview

1. Feature extraction

For each contig (minimum 2,500 bp), AMBER extracts a 157-dimensional feature vector:

Features Dims Description
Encoder 128 Self-supervised InfoNCE (COMEBin-style)
Damage profile 10 C→T rates at 5′ pos 1–5; G→A rates at 3′ pos 1–5
Decay parameters 2 λ₅, λ₃ (exponential damage decay constants)
Fragment length 2 Mean and std dev of aligned read lengths
Damage coverage 2 Coverage ratio and effective N from damaged vs undamaged reads
Mismatch spectrum 4 T→C, A→G and other mismatch rates
CGR entropy 9 Multi-scale chaos game representation entropy/occupancy slopes

See aDNA Features for the full mathematical derivation of each dimension.

2. Damage-aware contrastive learning

AMBER trains a contig encoder using InfoNCE [Oord et al. 2018] with substring augmentation (COMEBin-style). Two random substrings of the same contig form a positive pair; all other contigs in the batch are negatives. The standard InfoNCE loss is:

$$\mathcal{L}_{\text{InfoNCE}} = -\frac{1}{|B|} \sum_{i} \log \frac{\exp(\text{sim}(z_i, z_i^+)/\tau)}{\sum_{j \neq i} \exp(\text{sim}(z_i, z_j)/\tau)}$$

AMBER extends this with damage-aware negative weighting: negatives from contigs with incompatible damage signatures (one ancient, one modern) are downweighted in the denominator by a factor w ∈ [w_min, 1]:

$$w_{ij} = 1 - \lambda_{\text{att}} \cdot c_i c_j \cdot (1 - f_{\text{compat}}(i, j))$$

where c_i = n_{eff,i} / (n_{eff,i} + n_0) is confidence from effective read depth, and f_compat is a symmetric damage compatibility score based on terminal C→T rates and p_ancient. This prevents the encoder from learning to use damage state as a separating feature (which would merge co-occurring modern+ancient contigs), while still forming a meaningful embedding for composition and coverage signals.

3. Quality-guided Leiden clustering

After encoding, AMBER builds a kNN graph (HNSW approximate nearest neighbours) and clusters it with Leiden [Traag et al. 2019] using a three-phase quality refinement:

  • Phase 1 — SCG-guided Leiden. Edges between contigs sharing single-copy marker genes (SCGs) are penalised before clustering: w′ = w · exp(−3 · n_shared_markers). This pre-separates contigs from different genomes that happen to have similar embeddings.

  • Phase 2 — Contamination splitting. Bins with excess SCG duplication (dup_excess > 0) are re-clustered at 3× resolution on their subgraph and split if total duplication decreases.

  • Phase 3 — Near-HQ rescue. Bins at 75–90% estimated completeness recruit kNN neighbours that carry missing SCG markers, accepting a contig only if none of its markers are already in the target bin (no duplication risk).

Resolution is swept over [0.5, 5.0] with 25 random seeds; the configuration maximising a composite SCG quality score (strict-HQ > pre-HQ > MQ > completeness) is retained.

4. Partition consensus and resolve

Multiple independent AMBER runs (with different encoder seeds) can be aggregated by amber resolve. It builds a co-binning affinity graph: each pair of contigs that appears in the same bin in any run receives an edge of weight proportional to the fraction of runs in which they co-bin. Leiden is re-run on this affinity graph to produce a consensus binning that is more stable than any individual run.

Installation

Requirements

  • C++17 compiler (GCC 9+)
  • CMake ≥ 3.18
  • HTSlib ≥ 1.15
  • Eigen3
  • OpenMP

All dependencies are available via conda:

conda env create -f environment.yml
conda activate amber

Build (no GPU — works anywhere)

git clone https://github.com/genomewalker/amber.git
cd amber
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

All subcommands work except amber bin, which requires LibTorch for neural network training.

Enabling amber bin — CPU (no GPU required)

conda install pytorch cpuonly -c pytorch
cmake -DAMBER_USE_TORCH=ON -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

CPU training is ~5–10× slower than GPU but produces identical results.

Enabling amber bin — GPU (CUDA 12)

conda install pytorch pytorch-cuda=12.1 -c pytorch -c nvidia
cmake -DAMBER_USE_TORCH=ON -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

Note: GPU builds must be compiled on a node with CUDA libraries available.

Install system-wide

cmake --install build --prefix /usr/local

Quick start

Minimum input

  • Contigs FASTA (assembled metagenome, e.g. from MEGAHIT or metaSPAdes)
  • BAM file (reads mapped to contigs, indexed)
  • HMM marker file (auxiliary/bacar_marker.hmm, included in repo)

Binning (3 restarts, 25 Leiden seeds — recommended)

amber bin \
    --contigs contigs.fa \
    --bam alignments.bam \
    --hmm auxiliary/bacar_marker.hmm \
    --encoder-seed 42 \
    --random-seed 1006 \
    --resolution 5.0 \
    --bandwidth 0.2 \
    --partgraph-ratio 50 \
    --encoder-restarts 3 \
    --leiden-restarts 25 \
    --threads 16 \
    --output bins/

Aggregate 3 replicate runs

amber resolve \
    --runs run1/run.abin run2/run.abin run3/run.abin \
    --output consensus_bins/ \
    --threads 16

Separate ancient from modern reads

amber deconvolve \
    --contigs reference.fa \
    --bam alignments.bam \
    --output deconvolve/ \
    --threads 16

Per-bin damage statistics (post-hoc)

amber damage \
    --bam alignments.bam \
    --bins bins/ \
    --output damage_stats.tsv \
    --threads 16

Subcommands

Command Description
amber bin Bin contigs with damage-aware contrastive learning (requires LibTorch)
amber resolve Consensus binning from multiple independent runs
amber deconvolve Separate ancient and modern DNA via EM on damage + fragment length
amber damage Compute per-bin aDNA damage statistics from BAM
amber chimera Detect chimeric contigs and misassemblies
amber seeds Generate SCG marker seeds for binning

For subcommand help: amber <command> --help

See Command Reference for all flags.

Key parameters for amber bin

Parameter Default Description
--encoder-seed 42 Random seed for neural network training
--random-seed 1006 Random seed for Leiden clustering
--resolution 5.0 Leiden resolution parameter (higher = more, smaller bins)
--bandwidth 0.2 kNN edge kernel bandwidth
--partgraph-ratio 50 Partition graph density ratio
--encoder-restarts 3 Independent encoder training restarts for consensus kNN
--leiden-restarts 25 Leiden random seed restarts per resolution
--epochs 100 Training epochs
--threads 1 CPU threads
--min-length 2500 Minimum contig length (bp)
--damage-infonce on Enable damage-aware InfoNCE negative weighting

Best validated configuration (KapK sediment data, 11 HQ bins reproducible):

--encoder-seed 42 --random-seed 1006 --resolution 5.0 --bandwidth 0.2 --partgraph-ratio 50

EM deconvolution (amber deconvolve)

AMBER models each read as arising from one of two populations — ancient (high terminal damage, short fragment) or modern (low damage, longer fragment) — using an EM algorithm:

E-step: For each read r and reference contig c, compute soft assignment:

$$p_{\text{ancient}}(r) = \frac{\pi_a \cdot P(\text{damage}_r \mid \text{ancient}) \cdot P(l_r \mid \text{ancient})}{\pi_a \cdot P(\cdot \mid \text{ancient}) + \pi_m \cdot P(\cdot \mid \text{modern})}$$

The damage likelihood is a product over terminal C→T and G→A positions using the exponential damage model δ(p) = d · e^{−λp}. The length likelihood uses fitted log-normal distributions for fragment lengths.

M-step: Update mixture fraction π and distribution parameters from soft counts.

Outputs two consensus FASTA sequences (ancient and modern) called against the reference, plus a per-position uncertainty file and optional BAM of modern-classified reads.

See Methods and Model for the full derivation.

Output files

File Description
bins/bin.*.fa One FASTA per bin
bins/amber_summary.tsv Bin-level statistics (size, SCG completeness, contamination)
bins/damage_per_bin.tsv Per-bin damage profile (C→T, G→A, λ, p_ancient)
run.abin Binary run archive for amber resolve
deconvolve/ancient_consensus.fa Ancient-population consensus FASTA
deconvolve/modern_consensus.fa Modern-population consensus FASTA
deconvolve/deconv_uncertainty.tsv Per-position posterior uncertainty

See Output Formats for schema details.

Validation

Use CheckM2 to assess bin quality:

checkm2 predict -i bins/ -o bins/checkm2 -x fa --threads 16
awk -F'\t' 'NR>1 && $2>=90 && $3<5' bins/checkm2/quality_report.tsv | wc -l  # HQ count

A high-quality (HQ) bin has ≥90% completeness and <5% contamination [MIMAG standard, Bowers et al. 2017].

Citation

Fernandez-Guerra A et al. (2025) Ancient metagenomics reveals microbial community dynamics in Holocene lake sediments. bioRxiv doi: 10.1101/2023.06.10.544454

References

  • Briggs AW et al. (2007) Patterns of damage in genomic DNA sequences from a Neandertal. PNAS 104:14616–21.
  • Bowers RM et al. (2017) Minimum information about a single amplified genome (MISAG) and a metagenome-assembled genome (MIMAG) of bacteria and archaea. Nature Biotechnology 35:725–731.
  • Oord A van den et al. (2018) Representation Learning with Contrastive Predictive Coding. arXiv 1807.03748.
  • Traag VA et al. (2019) From Louvain to Leiden: guaranteeing well-connected communities. Scientific Reports 9:5233.
  • Wang Z et al. (2023) COMEBin allows effective binning of metagenomic contigs using coverage multi-view encoder. Nature Communications 15:1119.

License

MIT — see LICENSE.

Clone this wiki locally