Manual Page - minimap2(1) (2024)

NAME

minimap2 - mapping and alignment between collections of DNA sequences

CONTENTS

Synopsis
Description
Options
Indexing options
Mapping options
Alignment options
Input/output options
Preset options
Miscellaneous options
Output Format
Limitations
See Also

SYNOPSIS

* 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:

See Also

Minimap2: pairwise alignment for nucleotide sequencesMinimap2 genome alignment tutorialNew strategies to improve minimap2 alignment accuracyAccelerating minimap2 for long-read sequencing applications on modern CPUs

minimap2-x ava-ont[-t nThreads] target.fa query.fa >output.paf

DESCRIPTION

Minimap2 is a fast sequence mapping and alignment program that can findoverlaps between long noisy reads, or map long reads or their assemblies to areference genome optionally with detailed alignment (i.e. CIGAR). At present,it works efficiently with query sequences from a few kilobases to ~100megabases in length at a error rate ~15%. Minimap2 outputs in the PAF or theSAM format.

OPTIONS

Indexing options

-k INT	Minimizer k-mer length [15]
-w INT	Minimizer window size [2/3 of k-mer length]. A minimizer is the smallest k-merin a window of w consecutive k-mers.
-H	Use hom*opolymer-compressed (HPC) minimizers. An HPC sequence is constructed bycontracting hom*opolymer runs to a single base. An HPC minimizer is a minimizeron the HPC sequence.
-I NUM	Load at mostNUM target bases into RAM for indexing [4G]. If there are more thanNUM bases intarget.fa, minimap2 needs to readquery.fa multiple times to map it against each batch of target sequences.NUM may be ending with k/K/m/M/g/G. NB: mapping quality is incorrect given amulti-part index.
--idx-no-seq
	Don’t store target sequences in the index. It saves disk space and memory butthe index generated with this option will not work with-a or-c. When base-level alignment is not requested, this option is automatically applied.
-d FILE	Save the minimizer index oftarget.fa toFILE [no dump]. Minimap2 indexing is fast. It can index the human genome in a coupleof minutes. If even shorter startup time is desired, use this option to savethe index. Indexing options are fixed in the index file. When an index file isprovided as the target sequences, options-H, -k, -w, -I will be effectively overridden by the options stored in the index file.
--alt FILE	List of ALT contigs [null]
--alt-drop FLOAT
	Drop ALT hits byFLOAT fraction when ranking and computing mapping quality [0.15]

Mapping options

-f FLOAT|INT1[,INT2]
	If fraction, ignore topFLOAT fraction of most frequent minimizers [0.0002]. If integer,ignore minimizers occuring more thanINT1 times.INT2 is only effective in the--sr or-xsr mode, which sets the threshold for a second round of seeding.
-U INT1[,INT2]
	Lower and upper bounds of k-mer occurrences [10,1000000]. The final k-mer occurrence threshold ismax{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.
--q-occ-frac FLOAT
	Discard a query minimizer if its occurrence is higher thanFLOAT 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 everyINT basepairs [500].
-g NUM	Stop chain enlongation if there are no minimizers withinNUM-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 aconcave gap penalty. It is computed with dynamic programming.
-D	If query sequence name/length are identical to the target name/length, ignorediagonal anchors. This option also reduces DP-based extension along thediagonal.
-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.
--dual=yes|no
	Ifno, skip query-target pairs wherein the query name is lexicographically greaterthan 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 belowFLOAT, 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 mostINT 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 toNUM. 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 byFLOAT or more of the shorter chain [0.5]
--rmq=no|yes
	Use the minigraph chaining algorithm [no]. The minigraph algorithm is betterfor aligning contigs through long INDELs.
--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 thanINT [inf]. Effective without--hard-mask-level.
--max-chain-skip INT
	A heuristics that stops chaining early [25]. Minimap2 uses dynamic programmingfor chaining. The time complexity is quadratic in the number of seeds. Thisoption makes minimap2 exits the inner loop if it repeatedly sees seeds alreadyon chains. SetINT to a large number to switch off this heurstics.
--max-chain-iter INT
	Check up toINT partial chains during chaining [5000]. This is a heuristic to avoid quadratictime complexity in the worst case.
--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, themaximum alignment gap is mostly controlled by-r.
--splice	Enable the splice alignment mode.
--sr	Enable short-read alignment heuristics. In the short-read mode, minimap2applies a second round of chaining with a higher minimizer occurrence thresholdif no good chain is found. In addition, minimap2 attempts to patch gaps betweenseeds with ungapped alignment.
--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-endreads in the forward-reverse orientation, the first read is mapped to forwardstrand 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 isfaster for short reads, but slower for long reads. [no]
--no-pairing
	Treat two reads in a pair as independent reads. The mate related fields in SAMare still properly populated.

Alignment options

-A INT	Matching score [2]
-B INT	Mismatching penalty [4]
-O INT1[,INT2]
	Gap open penalty [4,24]. IfINT2 is not specified, it is set toINT1.
-E INT1[,INT2]
	Gap extension penalty [2,1]. A gap of lengthk costsmin{O1+k*E1,O2+k*E2}. In the splice mode, the second gap penalties are not used.
-C INT	Cost for a non-canonical GT-AG splicing (effective with--splice) [0]
-z INT1[,INT2]
	Truncate an alignment if the running alignment score drops too quickly alongthe diagonal of the DP matrix (diagonal X-drop, or Z-drop) [400,200]. If thedrop of score is aboveINT2, minimap2 will reverse complement the query in the related region and alignagain to test small inversions. Minimap2 truncates alignment if there is aninversion or the drop of score is greater thanINT1. DecreaseINT2 to find small inversions at the cost of performance and false positives.IncreaseINT1 to improves the contiguity of alignment at the cost of poor alignment in themiddle.
-s INT	Minimal peak DP alignment score to output [40]. The peak score is computed fromthe final CIGAR. It is the score of the max scoring segment in the alignmentand may be different from the total alignment score.
-u CHAR	How to find canonical splicing sites GT-AG -f: transcript strand;b: both strands;n: no attempt to match GT-AG [n]
--end-bonus INT
	Score bonus when alignment extends to the end of the query sequence [0].
--score-N INT
	Score of a mismatch involving ambiguous bases [1].
--splice-flank=yes|no
	Assume the next base to aGT donor site tends to be A/G (91% in human and 92% in mouse) and the precedingbase to aAG acceptor tends to be C/T [no].This trend is evolutionarily conservative, all the way to S. cerevisiae(PMID:18688272). Specifying this option generally leads to higher junctionaccuracy by several percents, so it is applied by default with--splice. However, the SIRV control does not honor this trend(only ~60%). This option reduces accuracy. If you are benchmarking minimap2on SIRV data, please add--splice-flank=no to the command line.
--junc-bed FILE
	Gene annotations in the BED12 format (aka 12-column BED), or intron positionsin 5-column BED. With this option, minimap2 prefers splicing in annotations.BED12 file 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 annotation (effective with--junc-bed) [9].
--end-seed-pen INT
	Drop a terminal anchor ifs<log(g)+INT, wheres is the local alignment score around the anchor andg the length of the terminal gap in the chain. This option is only effectivewith--splice. It helps to avoid tiny terminal exons. [6]
--no-end-flt
	Don’t filter seeds towards the ends of chains before performing base-levelalignment.
--cap-sw-mem NUM
	Skip alignment if the DP matrix size is aboveNUM. Set 0 to disable [100m].
--cap-kalloc NUM
	Free thread-local kalloc memory reservoir if after the alignment the size of the reservoir aboveNUM. Set 0 to disable [0].

Input/output options

-a	Generate CIGAR and output alignments in the SAM format. Minimap2 outputs in PAFby default.
-o FILE	Output alignments toFILE [stdout].
-Q	Ignore base quality in the input file.
-L	Write CIGAR with >65535 operators at the CG tag. Older tools are unable toconvert alignments with >65535 CIGAR ops to BAM. This option makes minimap2 SAMcompatible with older tools. Newer tools recognizes this tag and reconstructthe 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 output.
-c	Generate CIGAR. In PAF, the CIGAR is written to the ‘cg’ custom tag.
--cs[=STR]
	Output thecs tag.STR can be eithershort orlong. If noSTR is given,short is assumed. [none]
--MD	Output the MD tag (see the SAM spec).
--eqx	Output =/X CIGAR operators for sequence match/mismatch.
-Y	In SAM output, use soft clipping for supplementary alignments.
--seed INT	Integer seed for randomizing equally best hits. Minimap2 hashesINT and read name when choosing between equally best hits. [11]
-t INT	Number of threads [3]. Minimap2 uses at most three threads when indexing targetsequences, and uses up toINT+1 threads when mapping (the extra thread is for I/O, which is frequently idle andtakes little CPU time).
-2	Use two I/O threads during mapping. By default, minimap2 uses one I/O thread.When I/O is slow (e.g. piping to gzip, or reading from a slow pipe), the I/Othread may become the bottleneck. Apply this option to use one thread for inputand another thread for output, at the cost of increased peak RAM.
-K NUM	Number of bases loaded into memory to process in a mini-batch [500M].Similar to option-I, K/M/G/k/m/g suffix is accepted. A largeNUM helps load balancing in the multi-threading mode, at the cost of increasedmemory.
--secondary=yes|no
	Whether to output secondary alignments [yes]
--max-qlen NUM
	Filter out query sequences longer thanNUM.
--paf-no-hit
	In PAF, output unmapped queries; the strand and the reference name fields areset to ‘*’. Warning: some paftools.js commands may not work with such outputfor the moment.
--sam-hit-only
	In SAM, don’t output unmapped reads.
--version	Print version number to stdout

Preset options

-x STR

Preset []. This option applies multiple options at the same time. It should beapplied before other options because options applied later will overwrite thevalues set by-x. AvailableSTR are: map-ont Align noisy long reads of ~10% error rate to a reference genome. This is thedefault mode. map-hifi Align PacBio high-fidelity (HiFi) reads to a reference genome(-k19 -w19 -U50,500 -g10k -A1 -B4 -O6,26 -E2,1 -s200). map-pb Align older PacBio continuous long (CLR) reads to a reference genome(-Hk19). asm5 Long assembly to reference mapping(-k19 -w19 -U50,500 --rmq -r100k -g10k -A1 -B19 -O39,81 -E3,1 -s200 -z200 -N50). Typically, the alignment will not extend to regions with 5% or higher sequencedivergence. Only use this preset if the average divergence is far below 5%. asm10 Long assembly to reference mapping(-k19 -w19 -U50,500 --rmq -r100k -g10k -A1 -B9 -O16,41 -E2,1 -s200 -z200 -N50). Up to 10% sequence divergence. asm20 Long assembly to reference mapping(-k19 -w10 -U50,500 --rmq -r100k -g10k -A1 -B4 -O6,26 -E2,1 -s200 -z200 -N50). Up to 20% sequence divergence. splice Long-read spliced alignment(-k15 -w5 --splice -g2k -G200k -A1 -B2 -O2,32 -E1,0 -b0 -C9 -z200 -ub --junc-bonus=9 --cap-sw-mem=0 --splice-flank=yes). In the splice mode, 1) long deletions are taken as introns and represented asthe‘N’ CIGAR operator; 2) long insertions are disabled; 3) deletion and insertion gapcosts are different during chaining; 4) the computation of the‘ms’ tag ignores introns to demote hits to pseudogenes. splice:hq Long-read splice alignment for PacBio CCS reads(-xsplice -C5 -O6,24 -B4). sr Short single-end reads without splicing(-k21 -w11 --sr --frag=yes -A2 -B8 -O12,32 -E2,1 -b0 -r100 -p.5 -N20 -f1000,5000 -n2 -m20 -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 memoryaccesses. Minimap2 runs slower with this option, especially in themulti-threading mode.
--print-qname
	Print query names to stderr, mostly to see which query is crashing minimap2.
--print-seeds
	Print seed positions to stderr, for debugging only.

OUTPUT FORMAT

Minimap2 outputs mapping positions in the Pairwise mApping Format (PAF) bydefault. PAF is a TAB-delimited text format with each line consisting of atleast 12 fields as are described in the following table:

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

When alignment is available, column 11 gives the total number of sequencematches, mismatches and gaps in the alignment; column 10 divided by column 11gives the BLAST-like alignment identity. When alignment is unavailable,these two columns are approximate. PAF may optionally have additional fields inthe SAM-like typed key-value format. Minimap2 may output the following tags:

Tag	Type	Description
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

Thecs tag encodes difference sequences in the short form or the entire queryAND reference sequences in the long form. It consists of a series of operations:

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

LIMITATIONS

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

SEE ALSO

miniasm(1), minimap(1), bwa(1).