bio-genome-assembly-long-read-assembly

What this skill does

## Version Compatibility

Reference examples tested with: Flye 2.9+, Canu 2.2+, NextDenovo 2.5+, Shasta 0.11+, Raven 1.8+, wtdbg2 2.5+, miniasm 0.3+, minimap2 2.26+, purge_dups 1.2+, Porechop_ABI 0.5+, Trycycler 0.5+.

Before using code patterns, verify installed versions match. If versions differ:
- CLI: `<tool> --version` then `<tool> --help` to confirm flags

Two behaviors are version-dependent and load-bearing: Flye `--genome-size` became optional (auto-estimated) and `--scaffold` flipped OFF by default in recent releases - confirm against the installed Flye. Shasta `--config` names are dated and chemistry-specific (e.g. `Nanopore-R10-Fast-Nov2022`) - list with `shasta --command listConfigurations` rather than hard-coding one. Canu read-type flag spellings and `correctedErrorRate` defaults changed across major versions. If a command errors, introspect the installed tool and adapt rather than retrying.

# Long-Read Assembly (Noisy Reads)

**"Assemble a genome from Nanopore/PacBio-CLR long reads"** -> Build a contiguous de novo assembly whose input mode matches the basecaller error regime, then hand off to polishing because the raw consensus is contiguous but not yet accurate.
- CLI: `flye --nano-hq reads.fq.gz --out-dir out -t 16` (modern ONT R10/Dorado), `canu -p asm -d out genomeSize=4.6m -nanopore reads.fq.gz` (thorough), `wtdbg2 -x ont -g 4.6m -i reads.fq.gz -fo asm && wtpoa-cns -i asm.ctg.lay.gz -fo asm.fa` (fast draft)

## The Single Most Important Modern Insight -- The Basecaller Era Picks the Flag, and the Assembly Is Only Half-Done Until Polished

Two load-bearing facts no assembler README states:

1. **The basecaller era dictates the input flag, and a mismatch silently wrecks the assembly while the report looks finished.** Noisy long reads are not one error regime: ONT R9.4.1+Guppy is ~5-10% error, ONT R10.4.1+Dorado SUP is Q20+ (~1-2%), PacBio CLR is ~10-15%. Each assembler has separate modes tuned to each (Flye `--nano-raw` / `--nano-hq` / `--pacbio-raw`). The dangerous direction is **telling the assembler the reads are noisier than they are** - feeding R10/Dorado data to `--nano-raw` makes Flye treat real repeat-copy and allele differences as noise and **over-collapse** them. The result is *fewer contigs and a HIGHER N50* as the assembly gets *worse* - the most dangerous failure mode because the headline metric improved and nothing crashes. The chemistry/kit/basecaller model is an assembly *parameter*, not optional metadata; if it is unknown, the flag cannot be chosen and the assembly is uninterpretable - find out, do not guess.

2. **The bottleneck flipped from contiguity to consensus accuracy.** A raw noisy-long-read assembly emits a FASTA with a spectacular N50 that *looks* finished, but per-base accuracy is often Q20-Q30 (one error every ~100-1000 bp). The dominant ONT error is the **indel**, especially in homopolymers, and a single indel frameshifts a protein - so a contiguous assembly can have every gene model broken. Contiguity and correctness are orthogonal axes; N50 is blind to QV. The assembler is the **halfway point**: the deliverable is a *polished* assembly with a *measured* QV (Merqury), not a high-N50 FASTA. Flye does one internal polishing round and stops - that is not "polished." Hand off to assembly-polishing and assembly-qc.

## Tool Taxonomy

| Tool | Citation | Paradigm | When |
|------|----------|----------|------|
| Flye | Kolmogorov 2019 *Nat Biotechnol* | repeat graph (disjointigs -> explicit repeat structure) | the fast general-purpose default; bacteria -> eukaryote |
| Canu | Koren 2017 *Genome Res* | correct -> trim -> assemble (OLC, MHAP) | maximum single-assembler quality; slow, grid-oriented |
| NextDenovo | Hu 2024 *Genome Biol* | correct (NextCorrect) -> string-graph (NextGraph) | large/repetitive plant and animal genomes; contiguity-first |
| Shasta | Shafin 2020 *Nat Biotechnol* | run-length-encoded marker graph | ONT human-scale, speed/cost critical |
| Raven | Vaser & Sikic 2021 *Nat Comput Sci* | OLC string graph, near parameter-free | fast simple draft; common Trycycler input |
| wtdbg2 | Ruan & Li 2020 *Nat Methods* | fuzzy de Bruijn graph (+ mandatory wtpoa-cns) | fastest, lowest RAM; lowest accuracy -> polish hard |
| miniasm | Li 2016 *Bioinformatics* | string-graph layout, NO consensus | layout demo / pipeline component only; output = raw read error |
| Trycycler / Autocycler | Wick 2021 *Genome Biol* / Wick 2025 | consensus of multiple independent assemblies | bacterial reliability; catches single-assembler structural errors |
| purge_dups | Guan 2020 *Bioinformatics* | read-depth + self-alignment | remove haplotig false-duplication from a diploid primary |

PacBio CLR (`--pacbio-raw`) is legacy - superseded by HiFi for all new PacBio work; treat CLR support as maintenance for archival data, do not recommend generating new CLR.

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| ONT R10.4.1 / Dorado HAC-SUP, any genome | Flye `--nano-hq` | modern default mode; matches the Q20+ error regime |
| ONT R9.4.1 SUP (Guppy5+/Dorado) | Flye `--nano-hq --read-error 0.05` | hq mode with the error floor raised to R9-SUP |
| ONT R9.4.1 legacy fast/HAC | Flye `--nano-raw` | the genuinely-noisy mode; do not use on R10 |
| PacBio CLR (archival) | Flye `--pacbio-raw` or Canu `-pacbio` | legacy noisy mode; polish hard (arrow/GCpp) |
| Bacterial isolate, want a *correct* finished genome | Trycycler (interactive) / Autocycler (automated) | consensus across assemblers; fixes structural errors polishing can't |
| Large repetitive plant/animal, contiguity-first | NextDenovo | memory-efficient, top contiguity on big genomes |
| ONT human-scale, speed-critical | Shasta `--config <era-matched>` | RLE marker graph; human genomes in days |
| Quick draft / compute is the bottleneck | wtdbg2 or Raven | fastest; accept lower accuracy then polish |
| PacBio HiFi (Q30+, CCS) | -> hifi-assembly | hifiasm phased haplotypes; wrong tool here |
| After assembling (always) | -> assembly-polishing then assembly-qc | raw consensus is low-QV; not finished until polished + QV-measured |
| Reads not yet QC'd / unknown chemistry | -> long-read-sequencing/long-read-qc, long-read-sequencing/basecalling | garbage-in caps the assembly; basecaller model sets the flag |
| Genome size / coverage unknown | GenomeScope2 on accurate short reads (not raw ONT) | k-mer histograms from noisy reads inflate unique k-mers |

## Flye (the default)

```bash
flye --nano-hq reads.fq.gz --out-dir out -t 16                              # ONT R10 / Dorado SUP
flye --nano-hq reads.fq.gz --read-error 0.05 --out-dir out -t 16            # ONT R9 SUP
flye --nano-raw reads.fq.gz --out-dir out -t 16                             # legacy ONT R9 fast/HAC
flye --pacbio-raw reads.fq.gz --out-dir out -t 16                           # PacBio CLR (legacy)
flye --nano-hq reads.fq.gz --genome-size 3g --asm-coverage 40 -o out -t 32  # large genome: use longest 40x for initial assembly
```

`--genome-size` is optional in recent Flye (auto-estimated) but **required when paired with `--asm-coverage`**, which downsamples to the longest N-coverage of reads for the initial disjointig step (cuts runtime/RAM on deep large-genome data; the rest are still used). `--iterations` defaults to 1 polishing round (`0` to skip); `--keep-haplotypes` retains alt bubble paths for diploid awareness; `--meta` is metaFlye for uneven-coverage communities (-> metagenome-assembly). Output: `assembly.fasta`, `assembly_info.txt` (per-contig length/coverage/circularity), `assembly_graph.gfa`.

## Canu (thorough), wtdbg2 / Raven (fast), miniasm (layout only)

```bash
canu -p asm -d out genomeSize=4.6m -nanopore reads.fq.gz useGrid=false maxThreads=16   # correct->trim->assemble
wtdbg2 -x ont -g 4.6m -t 16 -i reads.fq.gz -fo asm && wtpoa-cns -t 16 -i asm.ctg.lay.gz -fo asm.ctg.fa  # consensus step is MANDATORY
raven -t 16 reads.fq.gz > asm.fasta