Bio Genome Assembly Hifi Assembly

Version Compatibility

Reference examples tested with: hifiasm 0.25.0+, yak 0.1+, verkko 2.3+, gfatools 0.5+, meryl 1.4+.

Before using code patterns, verify installed versions match. If versions differ:

• CLI: <tool> --version then <tool> --help to confirm flags

hifiasm output filenames AND the default purge level are version-dependent: confirm the .bp.*/.dip.* prefixes and -l defaults against hifiasm --help and the man page for the installed build before scripting around them. The k-mer-size convention also matters more than the binary version: hifiasm/yak trio uses k=31; verkko/Merqury hap-mers commonly use k=30 - mixing them silently produces garbage hap-mer matching. If a command errors, introspect the installed tool and adapt rather than retrying.

HiFi Assembly

"Assemble a diploid genome from HiFi reads" -> Build two cleanly phased haplotypes (not one mosaic primary) from accurate long reads, choosing the phasing mechanism from the sample type and available data, and validate phasing with k-mer QC the headline metrics cannot see.

• CLI: hifiasm -o prefix -t 32 reads.hifi.fq.gz (HiFi-only), --h1/--h2 (Hi-C), -1/-2 *.yak (trio); verkko --hifi ... --nano ... (T2T)

The Single Most Important Modern Insight -- A Primary Assembly Is a Mosaic Chimera, Not a Haplotype

A "primary assembly" is not a genome that exists in any cell. At every heterozygous block the assembler picks one allele, and which one it picks switches arbitrarily from block to block - so the primary is a stitched chimera: maternal here, paternal there, matching no gamete, no parent, no individual. It is a fine haploid representation for "roughly where is gene X" and a terrible substrate for anything allele-aware (phased variant calling, allele-specific expression, HLA/KIR typing, compound-heterozygote analysis). HiFi's combination of length AND ~Q30 accuracy made phased diploid assembly routine, so the field's deliverable shifted from one collapsed reference to two phased haplotypes (and onward to the pangenome: each HPRC node is a per-sample phased diploid assembly, Liao 2023 Nature 617:312).

The killer corollary: the thing that is wrong with a mosaic - that it is a haplotype mix - is exactly the thing none of the metrics people check can see. A switch error does not break a contig (N50 unchanged), delete a gene (BUSCO unchanged), or introduce a wrong base (QV unchanged - both alleles are real sequence, just assigned to the wrong haplotype). Switch errors and haplotype mosaicism are structurally invisible to N50, BUSCO, and even base-level QV. Only k-mer/trio QC - Merqury hap-mer blob plots and switch/hamming error against parental k-mers - can see them. "Reported N50 and BUSCO but no switch/hamming or hap-mer plot" means the phasing was never validated. Subtle trap: the HiFi-only .bp.hap1/hap2 are partially phased (locally phased, switch errors between blocks) - "hap1" in a filename does NOT certify global phasing; the phasing data supplied (trio or Hi-C) does.

Tool Taxonomy

Decision Tree by Scenario

hifiasm Invocations (the fragile commands - run as written)

# HiFi-only (default): primary mosaic + PARTIALLY-phased hap1/hap2
hifiasm -o prefix -t 32 reads.hifi.fq.gz

# Hi-C phased (no parents) - Cheng 2022; global phasing
hifiasm -o prefix -t 32 --h1 hic_R1.fq.gz --h2 hic_R2.fq.gz reads.hifi.fq.gz

# Trio phased (gold standard) - build parental k-mer DBs first (k=31)
yak count -k31 -b37 -t16 -o pat.yak paternal_R1.fq.gz paternal_R2.fq.gz
yak count -k31 -b37 -t16 -o mat.yak maternal_R1.fq.gz maternal_R2.fq.gz
hifiasm -o prefix -t 32 -1 pat.yak -2 mat.yak reads.hifi.fq.gz

# Inbred / homozygous / mole: DISABLE purging or real duplications are deleted
hifiasm -o prefix -t 32 -l0 reads.hifi.fq.gz

# Unbalanced haplotype sizes: pin the homozygous-coverage peak read off the k-mer histogram
hifiasm -o prefix -t 32 --hom-cov 38 reads.hifi.fq.gz

# Ultralong ONT toward T2T (combine with Hi-C or trio for phasing)
hifiasm -o prefix -t 32 --ul ul_ont.fq.gz reads.hifi.fq.gz

Key flags: -l purge level (0 none, 1 light, 2/3 aggressive; default 3 in HiFi-only, 0 in trio); --h1/--h2 Hi-C R1/R2; -1/-2 paternal/maternal yak DBs; --ul ultralong ONT; --hom-cov INT force the homozygous-coverage peak; --n-hap INT ploidy (default 2); --primary emit primary + alternate (a_ctg) instead of dual hap1/hap2.

Output Filenames: the .bp. vs .dip. Convention (read the prefix, it encodes the mode)

The prefix is not cosmetic - it tells how the assembly was phased:

• .bp. ("balanced phasing") = HiFi-only OR Hi-C mode. prefix.bp.p_ctg.gfa (the mosaic primary), prefix.bp.hap1.p_ctg.gfa/prefix.bp.hap2.p_ctg.gfa (the two haplotypes - partially phased in HiFi-only, fully phased with Hi-C). Also prefix.bp.r_utg.gfa/p_utg.gfa (unitig graphs).
• .dip. ("diploid") = trio mode. prefix.dip.hap1.p_ctg.gfa (paternal/hap1), prefix.dip.hap2.p_ctg.gfa (maternal/hap2).
• --primary mode: prefix.p_ctg.gfa (primary) + prefix.a_ctg.gfa (alternate). The alternate is incomplete by construction (only heterozygous loci produce alt contigs).
• Reusable binaries prefix.ec.bin/ovlp.*.bin let a re-run with different -l/phasing skip error-correction.

People grep hap1.p_ctg and are confused when a trio run made dip.hap1.p_ctg and a Hi-C run made bp.hap1.p_ctg. Verify the actual emitted names against the installed version.

GFA Is Not FASTA (extract S lines before anything downstream)

hifiasm and verkko emit assembly graphs (GFA), and downstream tools want FASTA. Contig sequences live in GFA S (segment) lines:

gfatools gfa2fa prefix.bp.hap1.p_ctg.gfa > hap1.fa          # preferred
awk '/^S/{print ">"$2"\n"$3}' prefix.bp.hap1.p_ctg.gfa > hap1.fa   # dependency-free fallback

The graph also carries bubbles/alternate paths the FASTA throws away - keep the GFA. Verkko works internally in homopolymer-compressed coordinates (its .gfa is HPC); its final assembly.fasta is in normal space.

verkko (T2T, when the goal genuinely needs it)

T2T is a project, not a flag. Reach for verkko only when T2T completeness is the actual goal AND the data exist (deep HiFi PLUS good ultralong ONT N50 PLUS trio or Hi-C). It is slower, heavier (hundreds of CPU-hours, high RAM, Snakemake-orchestrated), and more fragile than hifiasm. CHM13 - the first T2T human - was a hydatidiform mole precisely because a mole is effectively homozygous, decoupling repeat-resolution from phasing (Nurk 2022 Science 376:44).

# Trio-phased T2T: build parental + CHILD meryl DBs (k=30), derive hap-mers, then run.
# --hap-kmers needs HAP-MER DBs (haplotype-specific k-mers), not raw parental count DBs.
meryl count k=30 paternal.fq.gz output pat.meryl
meryl count k=30 maternal.fq.gz output mat.meryl
meryl count k=30 child.fq.gz    output child.meryl
$MERQURY/trio/hapmers.sh mat.meryl pat.meryl child.meryl   # hapmers.sh takes maternal first; emits mat/pat.hapmer.meryl
verkko -d asm_out --hifi hifi.fq.gz --nano ul_ont.fq.gz \
  --hap-kmers pat.hapmer.meryl mat.hapmer.meryl trio       # paternal first -> haplotype1=paternal (matches hifiasm -1 pat)

# Hi-C-phased (no parents)
verkko -d asm_out --hifi hifi.fq.gz --nano ul_ont.fq.gz --hic1 hic_R1.fq.gz --hic2 hic_R2.fq.gz

--hifi accurate reads; --nano ultralong ONT (the spanning data, strongly recommended); --hap-kmers <hap1> <hap2> trio (argument ORDER sets which becomes haplotype1/haplotype2 - it is not inferred from biology) or --hic1/--hic2 for phasing. Outputs assembly.fasta, assembly.haplotype1.fasta, assembly.haplotype2.fasta, assembly.homopolymer-compressed.gfa. verkko-vs-hifiasm(--ul): verkko closes more chromosomes automatically at higher cost; hifiasm --ul brings much of the spanning benefit far cheaper but needs more manual finishing. Neither reaches T2T without ultralong reads.

Per-Method Failure Modes

Primary assembly used as if it were a haplotype

Trigger: running the primary .bp.p_ctg/p_ctg into an allele-aware analysis. Mechanism: the primary is a per-block haplotype mosaic. Symptom: garbage phased variant / ASE / HLA results; "best" metrics. Fix: use trio/Hi-C-phased hap1/hap2; never the primary for allele-aware work.