bio-genome-assembly-metagenome-assembly

What this skill does

## Version Compatibility

Reference examples tested with: Flye 2.9+, SPAdes 3.15+ (metaSPAdes), MEGAHIT 1.2+, hifiasm-meta 0.3+, metaMDBG 1.0+, MetaBAT2 2.15+, MaxBin 2.2.7+, CONCOCT 1.1+, SemiBin 2.0+, VAMB 4.1+, DAS_Tool 1.1.6+, CheckM2 1.0+, GUNC 1.0+, GTDB-Tk 2.4+, inStrain 1.7+, minimap2 2.26+, samtools 1.19+.

Before using code patterns, verify installed versions match. If versions differ:
- CLI: `<tool> --version` then `<tool> --help` to confirm flags
- Python: `pip show <package>` then `help(module.function)` to check signatures

GTDB-Tk results track the reference-package RELEASE (e.g. R214 vs R220); the DB release MUST match the GTDB-Tk binary or classification silently fails. CheckM2 and GUNC each download their own DIAMOND DB. SemiBin2's pretrained `--environment` models are versioned. If code throws an error, introspect the installed tool and adapt rather than retrying.

# Metagenome Assembly

**"Assemble genomes from my metagenome"** -> Co-assemble a community at uneven, strain-mixed coverage, then bin the contigs into a set of consensus population genomes (MAGs) and QC each against MIMAG. The deliverable is MAGs, not a single assembly.
- CLI: `flye --meta --nano-hq reads.fq` (ONT), `spades.py --meta -1 R1.fq -2 R2.fq` or `megahit -1 R1.fq -2 R2.fq` (Illumina), `hifiasm_meta`/`metaMDBG` (HiFi); then binners -> `DAS_Tool` -> `checkm2 predict` + `gunc run` + `gtdbtk classify_wf`

## The Single Most Important Modern Insight -- A Metagenome Is Not a Genome; the Assembler Cannot Assume Uniform Coverage

Every isolate assembler is built on the premise that the true sequence sits at roughly one depth, so a coverage drop or spike signals a repeat or an error. In a community that premise is false by construction: an abundant species at 500x and a rare one at 3x are both real. Running plain SPAdes/Unicycler or single-genome Flye on a community treats the abundance spread and strain bubbles as errors to "fix" and produces garbage. Use `--meta` modes. Three consequences cascade:

1. **A MAG is a population consensus, not an organism's genome.** Co-occurring strains differing by <1% ANI become bubbles the assembler collapses into one consensus path -- a sequence that may match no actual cell in the sample. A 99%-complete circular MAG is still the consensus of the dominant strain; minority-strain accessory genome is averaged away. Treat every per-strain, per-allele, or pangenome claim from a single consensus MAG as suspect until read-level microdiversity (inStrain) or strain-aware assembly confirms it.
2. **The deliverable is a community of MAGs, not one assembly -- a community has no N50.** N50 is dominated by whichever few abundant genomes assembled well and says nothing about the community; a "better N50" assembly can have recovered fewer genomes. Report MAG count split by MIMAG tier (HQ/medium/low) and community fraction binned. Bigger total assembly size is not better -- it can mean more chimeras and strain-fragmentation.
3. **Modern practice is multi-binner -> consolidate -> CheckM2 + GUNC -> GTDB-Tk.** Never trust one binner; run several (each weights composition vs coverage differently and recovers a partially-different genome set), reconcile with DAS_Tool, then QC every bin with CheckM2 AND GUNC (completeness lies about chimeras) before classifying against the MIMAG 90%/5% bar. HiFi/long reads are the single biggest quality jump: they span the conserved rRNA operons and strain bubbles short reads shred, yielding complete, circular, genuinely-HQ MAGs.

## Assembler Taxonomy

| Tool | Citation | Mechanism / role | When |
|------|----------|------------------|------|
| metaFlye | Kolmogorov 2020 *Nat Methods* | repeat-graph long-read meta-assembler (`--meta` mandatory) | ONT/CLR community de novo; polish after |
| metaSPAdes | Nurk 2017 *Genome Res* | strain-aware multi-k de Bruijn (`spades.py --meta`) | Illumina, contiguity priority; ONE paired library only |
| MEGAHIT | Li 2015 *Bioinformatics* | succinct de Bruijn, low-memory | huge/complex Illumina co-assemblies, soil; lower contiguity |
| hifiasm-meta | Feng 2022 *Nat Methods* | strain-resolved HiFi string graph | PacBio HiFi communities; keeps strains apart |
| metaMDBG | Benoit 2024 *Nat Biotechnol* | minimizer de Bruijn for HiFi | HiFi; often ~2x the HQ circular MAGs, low RAM |
| OPERA-MS | Bertrand 2019 *Nat Biotechnol* | short-read meta scaffolded by long reads | hybrid short + long |

## Binner Taxonomy

| Binner | Citation | Signal | When |
|--------|----------|--------|------|
| MetaBAT2 | Kang 2019 *PeerJ* | tetranucleotide freq (TNF) + coverage, parameter-free | fast default workhorse (`-m 1500`) |
| MaxBin2 | Wu 2016 *Bioinformatics* | EM over TNF + marker genes + coverage | single/few samples |
| CONCOCT | Alneberg 2014 *Nat Methods* | GMM on composition+coverage of cut-up contigs | many samples; 4-step pipeline, not one command |
| SemiBin2 | Pan 2023 *Bioinformatics* | self-supervised contrastive deep learning | current SOTA; short + long; pretrained env models |
| VAMB | Nissen 2021 *Nat Biotechnol* | variational autoencoder of coabundance + k-mer | multi-sample; separates close strains |
| DAS_Tool | Sieber 2018 *Nat Microbiol* | dereplicate-aggregate-score across binners (consolidation) | ALWAYS run; non-redundant set beats any single binner |

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Illumina, complex/huge/soil, low RAM | MEGAHIT `--presets meta-sensitive` | succinct dBG fits in memory; multi-library |
| Illumina, contiguity priority, tractable size | metaSPAdes (`spades.py --meta`) | strain-aware repeat resolution; merge libraries first (one paired lib only) |
| ONT-only community | metaFlye `--meta --nano-hq` -> polish | repeat-graph meta mode; ONT needs polishing -> assembly-polishing |
| PacBio HiFi community | hifiasm-meta or metaMDBG | complete circular strain-resolved MAGs; fixes rRNA collapse |
| Hybrid short + long | OPERA-MS | short-read meta scaffolded with long reads |
| Recover MAGs (any assembly) | >=2-3 binners -> DAS_Tool -> CheckM2 + GUNC -> GTDB-Tk | ensemble beats one binner; chimera + taxonomy gates |
| Only ONE sample | composition-only binning, expect weak bins | differential coverage needs multiple samples; add samples, not tuning |
| Multiple samples available | map ALL samples to each assembly for binning depth | differential-coverage is the strongest binning signal |
| Strain-level question | -> inStrain on reads mapped to MAGs | consensus MAGs blur strains; needs read-level microdiversity |
| Read-based taxonomy / rare biosphere | -> metagenomics/kraken-classification | assembly is blind below the abundance-detection limit |
| Reads not QC'd / host-contaminated | -> long-read-sequencing/long-read-qc | remove host reads vs a T2T reference before assembly |
| MAG contamination forensics | -> contamination-detection | detailed CheckM2/GUNC interpretation |

## metaFlye (ONT / Long Reads)

```bash
flye --meta --nano-hq ont.fastq.gz --out-dir flye_out -t 32
#   --meta        uneven-coverage metagenome mode (REQUIRED for communities)
#   read-type flag (mutually exclusive): --nano-hq (Guppy5+/Q20) | --nano-raw (older) |
#       --pacbio-hifi | --pacbio-raw (CLR)
# outputs: assembly.fasta, assembly_graph.gfa, assembly_info.txt (circularity flag in col 'circ.')
```
ONT contigs are contiguous but error-prone (indels in homopolymers); polish before downstream use (-> assembly-polishing; medaka needs the matching basecaller model). HiFi usually needs no polishing.

## metaSPAdes / MEGAHIT (Illumina)

```bash
# metaSPAdes -- contiguity priority; exactly ONE paired library
spades.py --meta -1 R1.fastq.gz -2 R2.fastq.gz -o spades_out -t 32 -m 500
#   -m memory cap in GB (SPAdes aborts if exceeded); -k auto by default
# outputs: contigs.fasta, scaffolds.fasta

# MEGAHIT -- huge/low-RAM; accepts comma-separated multiple libraries
megahit -1 a1.fq.gz,b1.fq.gz -2 a2.fq.gz,b2.fq.gz -o megahit_out -t 32 \