minimap2(1)

📦
version 2.27 · 5 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 minimap2 — the bestie guide 💅

minimap2(1) · part of the Bioinformatics tools family, and honestly? iconic.

✨ NAME ✨

minimap2 — mapping and alignment between collections of DNA sequences. Yeah. That's the whole job. She maps, she aligns, she slays. 🧬👑

🎀 SYNOPSIS 🎀

okay so here's the vibe, three whole modes:

* Indexing the target sequences (optional):
    minimap2 [-x preset] -d target.mmi target.fa
    minimap2 [-H] [-k kmer] [-w miniWinSize] [-I batchSize] -d
    target.mmi target.fa

* Long-read alignment with CIGAR:
    minimap2 -a [-x preset] target.mmi query.fa > output.sam
    minimap2 -c [-H] [-k kmer] [-w miniWinSize] [...]  target.fa
    query.fa > output.paf

* Long-read overlap without CIGAR:
    minimap2 -x ava-ont [-t nThreads] target.fa query.fa > output.paf

🦋 DESCRIPTION 🦋

Minimap2 is a fast sequence mapping and alignment program that can find overlaps between long noisy reads, or map long reads or their assemblies to a reference genome — optionally with detailed alignment (i.e. CIGAR). Obsessed with the "optionally", tbh.

Right now it works efficiently with query sequences from a few kilobases to ~100 megabases in length at a error rate ~15%. ~100 megabases bestie. She's built different.

Minimap2 outputs in the PAF or the SAM format. Pick your fighter. 💖

💅 OPTIONS 💅

🌸 Indexing options

  • -k INT — minimizer k-mer length [15]. The classic.
  • -w INT — minimizer window size [10]. A minimizer is the smallest k-mer in a window of w consecutive k-mers. So like, the main character k-mer of every little friend group.
  • -j INT — syncmer submer size [10]. Heads up: -j and -w will override each other — if -w is applied after -j, then -j will have no effect, and vice versa. They're fighting, basically. Only one survives. 💀
  • -H — use homopolymer-compressed (HPC) minimizers. An HPC sequence is constructed by contracting homopolymer runs to a single base, and an HPC minimizer is a minimizer on the HPC sequence. Compression era. ✨
  • -I NUM — load at most NUM target bases into RAM for indexing [8G]. If there are more than NUM bases in target.fa, minimap2 needs to read query.fa multiple times to map it against each batch of target sequences — which would create a multi-part index. NUM may be ending with k/K/m/M/g/G. Also see option --split-prefix.
NB: mapping quality is incorrect given a multi-part index. Not a vibe. Know that going in. 😭
  • --idx-no-seq — don't store target sequences in the index. It saves disk space and memory, but the index generated with this option will not work with -a or -c. When base-level alignment is not requested, this option is automatically applied. So sometimes she just does it herself, no permission needed.
  • -d FILE — save the minimizer index of target.fa to FILE [no dump]. Minimap2 indexing is fast — it can index the human genome in a couple of minutes. If even shorter startup time is desired, use this option to save the index. Indexing options are fixed in the index file. And when an index file is provided as the target sequences, options -H, -k, -w, -I will be effectively overridden by the options stored in the index file. The index ate and left no crumbs. 👑
  • --alt FILE — list of ALT contigs [null]
  • --alt-drop FLOAT — drop ALT hits by FLOAT fraction when ranking and computing mapping quality [0.15]

🔥 Mapping options

  • -f FLOAT|INT1[,INT2] — if fraction, ignore top FLOAT fraction of most frequent minimizers [0.0002]. If integer, ignore minimizers occuring more than INT1 times. INT2 is only effective in the --sr or -xsr mode, which sets the threshold for a second round of seeding. Two rounds of seeding? She's thorough. 💅
  • -U INT1[,INT2] — lower and upper bounds of k-mer occurrences [10,1000000]. The final k-mer occurrence threshold is max{INT1, min{INT2, -f}}. This option prevents excessively small or large -f estimated from the input reference. Available since r1034 and deprecating --min-occ-floor in earlier versions of minimap2. Rip to a real one.
  • --q-occ-frac FLOAT — discard a query minimizer if its occurrence is higher than FLOAT fraction of query minimizers and than the reference occurrence threshold [0.01]. Set 0 to disable. Available since r1105.
  • -e INT — sample a high-frequency minimizer every INT basepairs [500]
  • -g NUM — stop chain enlongation if there are no minimizers within NUM-bp [10k]
  • -r NUM1[,NUM2] — bandwidth for chaining and base alignment [500,20k]. NUM1 is used for initial chaining and alignment extension; NUM2 for RMQ-based re-chaining and closing gaps in alignments.
  • -n INT — discard chains consisting of <INT number of minimizers [3]
  • -m INT — discard chains with chaining score <INT [40]. Chaining score equals the approximate number of matching bases minus a concave gap penalty. It is computed with dynamic programming. Math girlie behavior, we respect it. 🧮
  • -D — if query sequence name/length are identical to the target name/length, ignore diagonal anchors. This option also reduces DP-based extension along the diagonal.
  • -P — retain all chains and don't attempt to set primary chains. Options -p and -N have no effect when this option is in use. Everyone's a main character now. ✨
  • --dual=yes|no — if no, skip query-target pairs wherein the query name is lexicographically greater than the target name [yes]
  • -X — equivalent to '-DP --dual=no --no-long-join'. Primarily used for all-vs-all read overlapping.
  • -p FLOAT — minimal secondary-to-primary score ratio to output secondary mappings [0.8]. Between two chains overlaping over half of the shorter chain (controlled by -M), the chain with a lower score is secondary to the chain with a higher score. If the ratio of the scores is below FLOAT, the secondary chain will not be outputted or extended with DP alignment later. This option has no effect when -X is applied.
  • -N INT — output at most INT secondary alignments [5]. This option has no effect when -X is applied.
  • -G NUM — maximum gap on the reference (effective with -xsplice/--splice). This option also changes the chaining and alignment band width to NUM. Increasing this option slows down spliced alignment. [200k]
  • -F NUM — maximum fragment length (aka insert size; effective with -xsr/--frag=yes) [800]
  • -M FLOAT — mark as secondary a chain that overlaps with a better chain by FLOAT or more of the shorter chain [0.5]
  • --rmq=no|yes — use the minigraph chaining algorithm [no]. The minigraph algorithm is better for aligning contigs through long INDELs. Situational queen. 🦋
  • --hard-mask-level — honor option -M and disable a heurstic to save unmapped subsequences and disables --mask-len.
  • --mask-len NUM — keep an alignment if dropping it leaves an unaligned region on query longer than INT [inf]. Effective without --hard-mask-level.
  • --max-chain-skip INT — a heuristics that stops chaining early [25]. Minimap2 uses dynamic programming for chaining, and the time complexity is quadratic in the number of seeds. This option makes minimap2 exits the inner loop if it repeatedly sees seeds already on chains. Set INT to a large number to switch off this heurstics. Escape hatch unlocked. 🚪
  • --max-chain-iter INT — check up to INT partial chains during chaining [5000]. This is a heuristic to avoid quadratic time complexity in the worst case. The worst case said "not today" and minimap2 said "bet".
  • --chain-gap-scale FLOAT — scale of gap cost during chaining [1.0]
  • --no-long-join — disable the long gap patching heuristic. When this option is applied, the maximum alignment gap is mostly controlled by -r.
  • --splice — enable the splice alignment mode. 🧬
  • --sr — enable short-read alignment heuristics. In the short-read mode, minimap2 applies a second round of chaining with a higher minimizer occurrence threshold if no good chain is found. In addition, minimap2 attempts to patch gaps between seeds with ungapped alignment. She's doing overtime fr fr.
  • --split-prefix STR — prefix to create temporary files. Typically used for a multi-part index.
  • --frag=no|yes — whether to enable the fragment mode [no]
  • --for-only — only map to the forward strand of the reference sequences. For paired-end reads in the forward-reverse orientation, the first read is mapped to forward strand of the reference and the second read to the reverse stand.
  • --rev-only — only map to the reverse complement strand of the reference sequences.
  • --heap-sort=no|yes — if yes, sort anchors with heap merge, instead of radix sort. Heap merge is faster for short reads, but slower for long reads. [no] Short-read girlies, this one's for you. 🎀
  • --no-pairing — treat two reads in a pair as independent reads. The mate related fields in SAM are still properly populated. They're not together anymore but the paperwork is still filed. 😭
  • --no-hash-name — produce the same alignment for identical sequences regardless of their sequence names. No name bias, we love to see it. 💖

⭐ Alignment options

  • -A INT — matching score [2]
  • -B INT — mismatching penalty [4]
  • -b INT — mismatching penalty for transitions [same as -B]
  • -O INT1[,INT2] — gap open penalty [4,24]. If INT2 is not specified, it is set to INT1.
  • -E INT1[,INT2] — gap extension penalty [2,1]. A gap of length k costs min{O1+k*E1,O2+k*E2}. In the splice mode, the second gap penalties are not used.
  • -J INT — splice model [1]. 0 for the original minimap2 splice model that always penalizes non-GT-AG splicing; 1 for the miniprot model that considers non-GT-AG. Option -C has no effect with the default -J1. -J0.
  • -C INT — cost for a non-canonical GT-AG splicing (effective with --splice -J0) [0].
  • -z INT1[,INT2] — truncate an alignment if the running alignment score drops too quickly along the diagonal of the DP matrix (diagonal X-drop, or Z-drop) [400,200]. If the drop of score is above INT2, minimap2 will reverse complement the query in the related region and align again to test small inversions. Minimap2 truncates alignment if there is an inversion or the drop of score is greater than INT1. Decrease INT2 to find small inversions at the cost of performance and false positives. Increase INT1 to improves the contiguity of alignment at the cost of poor alignment in the middle. Tuning era, choose your struggle. 🙈
  • -s INT — minimal peak DP alignment score to output [40]. The peak score is computed from the final CIGAR. It is the score of the max scoring segment in the alignment and may be different from the total alignment score.

okay bestie that's the indexing, mapping and alignment tea so far — but there's literally more coming, don't go anywhere 💜

  • -u CHAR — how to sniff out canonical splice sites (the GT-AG ones 💅). f = transcript strand only, b = both strands, n = don't even try to match GT-AG [n]
  • --end-bonus INT — score bonus when your alignment stretches all the way to the end of the query sequence [0].
  • --score-N INT — the score of a mismatch that involves ambiguous bases [1].
  • --splice-flank=yes|no — assume the base right after a GT donor site tends to be A/G (91% in human, 92% in mouse 😌) and the base right before an AG acceptor tends to be C/T [no]. This trend is evolutionarily conservative, all the way down to S. cerevisiae (PMID:18688272). Setting this option usually bumps junction accuracy up by several percent, so it's applied by default with --splice. BUT the SIRV control doesn't honor this trend (only ~60%), so this option reduces accuracy there. If you're benchmarking minimap2 on SIRV data, please add --splice-flank=no to the command line.
  • --junc-bed FILE — gene annotations in BED12 format (aka 12-column BED), or intron positions in 5-column BED. With this option, minimap2 prefers splicing where the annotations say. BED12 files can be converted from GTF/GFF3 with paftools.js gff2bed anno.gtf [].
  • --junc-bonus INT — score bonus for a splice donor or acceptor found in an annotation (only effective with --junc-bed) [9].
  • --end-seed-pen INT — drop a terminal anchor if s<log(g)+INT, where s is the local alignment score around the anchor and g the length of the terminal gap in the chain. Only effective with --splice. It helps you avoid tiny terminal exons [6].
  • --no-end-flt — don't filter seeds towards the ends of chains before doing base-level alignment.
  • --cap-sw-mem NUM — skip alignment if the DP matrix size is above NUM. Set to 0 to disable [100m].
  • --cap-kalloc NUM — free the thread-local kalloc memory reservoir if, after the alignment, the size of the reservoir is above NUM. Set to 0 to disable [0].

📥 Input/output options 📤

  • -a — generate CIGAR and output alignments in the SAM format. Minimap2 spits out PAF by default.
  • -o FILE — write those alignments to FILE [stdout].
  • -Q — ignore base quality in the input file.
  • -L — write CIGAR with >65535 operators at the CG tag. Older tools literally cannot convert alignments with >65535 CIGAR ops to BAM 😭. This option makes minimap2's SAM compatible with those older tools. Newer tools recognize this tag and reconstruct the real CIGAR in memory.
  • -R STR — SAM read group line in a format like @RG\tID:foo\tSM:bar [].
  • -y — copy input FASTA/Q comments to the output.
  • -c — generate CIGAR. In PAF, the CIGAR goes into the cg custom tag.
  • --cs[=STR] — output the cs tag. STR can be either short or long. If no STR is given, short is assumed. [none]
  • --MD — output the MD tag (peep the SAM spec for that one).
  • --eqx — output =/X CIGAR operators for sequence match/mismatch.
  • -Y — in SAM output, use soft clipping for supplementary alignments.
  • --secondary-seq — in SAM output, show query sequences for secondary alignments.
  • --seed INT — integer seed for randomizing equally best hits. Minimap2 hashes INT and the read name when choosing between equally best hits [11].
  • -t INT — number of threads [3]. Minimap2 uses at most three threads while indexing target sequences, and up to INT+1 threads when mapping (that extra thread is for I/O, which is frequently idle and takes barely any CPU time).
  • -2 — use two I/O threads during mapping. By default minimap2 uses one I/O thread. When I/O is slow (like piping to gzip, or reading from a slow pipe), the I/O thread can become the bottleneck. Apply this option to use one thread for input and another for output, at the cost of increased peak RAM.
  • -K NUM — number of bases loaded into memory to process in a mini-batch [500M]. Same as option -I, it accepts a K/M/G/k/m/g suffix. A large NUM helps load balancing in multi-threading mode, at the cost of increased memory.
  • --secondary=yes|no — whether to output secondary alignments [yes]
  • --max-qlen NUM — filter out query sequences longer than NUM.
  • --paf-no-hit — in PAF, output unmapped queries; the strand and reference name fields get set to *.
⚠️ Warning: some paftools.js commands may not work with such output for the moment.
  • --sam-hit-only — in SAM, don't output unmapped reads.
  • --version — print the version number to stdout

🎀 Preset options 🎀

  • -x STR — preset []. This option applies multiple options all at once. It should be applied before other options, because options applied later will overwrite the values set by -x. Available STR values are:
    • map-ont — align noisy long reads of ~10% error rate to a reference genome. This is the default mode.
    • lr:hq — align accurate long reads (error rate <1%) to a reference genome (-k19 -w19 -U50,500 -g10k). This was recommended by ONT developers for recent Nanopore reads produced with chemistry v14 that can reach ~99% accuracy. It was shown to work better for accurate Nanopore reads than map-hifi.
    • map-hifi — align PacBio high-fidelity (HiFi) reads to a reference genome (-xlr:hq -A1 -B4 -O6,26 -E2,1 -s200). It differs from lr:hq only in scoring. It has not been tested whether lr:hq would work better for PacBio HiFi reads.
    • map-pb — align older PacBio continuous long (CLR) reads to a reference genome (-Hk19). Note that this data type is effectively deprecated by HiFi. Unless you work on very old data, you probably want map-hifi or lr:hq instead.
    • map-iclr — align Illumina Complete Long Reads (ICLR) to a reference genome (-k19 -B6 -b4 -O10,50). Recommended by Illumina developers.
    • asm5 — long assembly to reference mapping (-k19 -w19 -U50,500 --rmq -r1k,100k -g10k -A1 -B19 -O39,81 -E3,1 -s200 -z200 -N50). Typically the alignment will not extend into regions with 5% or higher sequence divergence. Use this preset if the average divergence is not much higher than 0.1%.
    • asm10 — long assembly to reference mapping (-k19 -w19 -U50,500 --rmq -r1k,100k -g10k -A1 -B9 -O16,41 -E2,1 -s200 -z200 -N50). Use this if the average divergence is around 1%.
    • asm20 — long assembly to reference mapping (-k19 -w10 -U50,500 --rmq -r1k,100k -g10k -A1 -B4 -O6,26 -E2,1 -s200 -z200 -N50). Use this if the average divergence is around several percent.
    • splice — long-read spliced alignment (-k15 -w5 --splice -g2k -G200k -A1 -B2 -O2,32 -E1,0 -C9 -z200 -ub --junc-bonus=9 --cap-sw-mem=0 --splice-flank=yes). In splice mode: 1) long deletions are taken as introns and represented as the N CIGAR operator; 2) long insertions are disabled; 3) deletion and insertion gap costs are different during chaining; 4) the computation of the ms tag ignores introns to demote hits to pseudogenes.
    • splice:hq — spliced alignment for accurate long RNA-seq reads such as PacBio iso-seq (-xsplice -C5 -O6,24 -B4).
    • sr — short-read alignment without splicing (-k21 -w11 --sr --frag=yes -A2 -B8 -O12,32 -E2,1 -b0 -r100 -p.5 -N20 -f1000,5000 -n2 -m25 -s40 -g100 -2K50m --heap-sort=yes --secondary=no).
    • ava-pb — PacBio CLR all-vs-all overlap mapping (-Hk19 -Xw5 -e0 -m100).
    • ava-ont — Oxford Nanopore all-vs-all overlap mapping (-k15 -Xw5 -e0 -m100 -r2k).

🌈 Miscellaneous options 🌈

  • --no-kalloc — use the libc default allocator instead of the kalloc thread-local allocator. This debugging option is mostly used with Valgrind to detect invalid memory accesses. Minimap2 runs slower with this option, especially in multi-threading mode.
  • --print-qname — print query names to stderr, mostly so you can see which query is crashing minimap2 🙈.
  • --print-seeds — print seed positions to stderr, for debugging only.

✨ OUTPUT FORMAT ✨

Okay bestie, by default minimap2 drops mapping positions in the Pairwise mApping Format (PAF). PAF is a TAB-delimited text format, and each line has at least 12 fields. Here's the whole field menu, no gatekeeping:

  • Col 1 — string — Query sequence name
  • Col 2 — int — Query sequence length
  • Col 3 — int — Query start coordinate (0-based)
  • Col 4 — int — Query end coordinate (0-based)
  • Col 5 — char — + if query/target on the same strand; - if opposite
  • Col 6 — string — Target sequence name
  • Col 7 — int — Target sequence length
  • Col 8 — int — Target start coordinate on the original strand
  • Col 9 — int — Target end coordinate on the original strand
  • Col 10 — int — Number of matching bases in the mapping
  • Col 11 — int — Number bases, including gaps, in the mapping
  • Col 12 — int — Mapping quality (0-255 with 255 for missing)

When alignment is available, column 11 gives the total number of sequence matches, mismatches and gaps in the alignment; column 10 divided by column 11 gives the BLAST-like alignment identity. When alignment is unavailable, these two columns are approximate. Periodt.

PAF may optionally have additional fields in the SAM-like typed key-value format. Minimap2 may output the following tags:

  • tp — A — Type of aln: P/primary, S/secondary and I,i/inversion
  • cm — i — Number of minimizers on the chain
  • s1 — i — Chaining score
  • s2 — i — Chaining score of the best secondary chain
  • NM — i — Total number of mismatches and gaps in the alignment
  • MD — Z — To generate the ref sequence in the alignment
  • AS — i — DP alignment score
  • SA — Z — List of other supplementary alignments
  • ms — i — DP score of the max scoring segment in the alignment
  • nn — i — Number of ambiguous bases in the alignment
  • ts — A — Transcript strand (splice mode only)
  • cg — Z — CIGAR string (only in PAF)
  • cs — Z — Difference string
  • dv — f — Approximate per-base sequence divergence
  • de — f — Gap-compressed per-base sequence divergence
  • rl — i — Length of query regions harboring repetitive seeds

The cs tag encodes difference sequences in the short form or the entire query AND reference sequences in the long form. It consists of a series of operations:

  • = — regex [ACGTN]+ — Identical sequence (long form)
  • : — regex [0-9]+ — Identical sequence length
  • * — regex [acgtn][acgtn] — Substitution: ref to query
  • + — regex [acgtn]+ — Insertion to the reference
  • - — regex [acgtn]+ — Deletion from the reference
  • ~ — regex [acgtn]{2}[0-9]+[acgtn]{2} — Intron length and splice signal

🚧 LIMITATIONS 🚧

Not everything is perfect, and that's okay:

  • Minimap2 may produce suboptimal alignments through long low-complexity regions where seed positions may be suboptimal. This should not be a big concern because even the optimal alignment may be wrong in such regions.
  • Minimap2 requires SSE2 or NEON instructions to compile. It is possible to add non-SSE2/NEON support, but it would make minimap2 slower by several times.

👀 SEE ALSO 👀

Go read miniasm(1), minimap(1), and bwa(1), bestie. iykyk.

This manual is serving minimap2-2.27 (r1193) energy, dated 12 March 2024 — and yes, it's the minimap2(1) page. Bye bestie 💅✨🦋

📦 where this page comes from