Manual Reference Pages - minimap2 (1) (original) (raw)

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). At present, it works efficiently with query sequences from a few kilobases to ~100 megabases in length at a error rate ~15%. Minimap2 outputs in the PAF or the SAM format.

-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.
-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.
--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.
-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.
--dual=yes|no
Ifno, 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.
--rmq-inner NUM
Apply full dynamic programming for anchors within distance_NUM_ [1000].
--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. 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.
--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.
--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.
--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]
--no-pairing
Treat two reads in a pair as independent reads. The mate related fields in SAM are still properly populated.
--no-hash-name
Produce the same alignment for identical sequences regardless of their sequence names.
-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.
-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.
-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].
--pe-ind-chain
For paired-end short reads, perform chaining for each end independently. By default, minimap2 chains the two ends together.
--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 preceding base 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 junction accuracy 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 minimap2 on SIRV data, please add--splice-flank=no to the command line.
--spsc FILE Splice scores []. Each line consists of five fields: 1) contig, 2) offset, 3) ‘+’ or ‘-’, 4) ‘D’ or ‘A’, and 5) score, where offset is the number of bases before a splice junction, ‘D’ indicates the line corresponds to a donor site and ‘A’ for an acceptor site. A positive score suggests the junction is preferred and a negative score suggests the junction is not preferred.
--junc-pen INT
Penalty for a position not in FILE specified by--spsc [5]. Effective with--spsc but not--junc-bed.
--junc-bed FILE
Gene annotations in the BED12 format (aka 12-column BED), or intron positions in 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 [9]. Effective with--junc-bed but not--spsc.
--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. This option is only effective with--splice. It helps to avoid tiny terminal exons. [6]
--no-end-flt
Don’t filter seeds towards the ends of chains before performing base-level alignment.
--cap-sw-mem NUM
Skip alignment if the DP matrix size is above_NUM_. Set 0 to disable [100m].
--cap-kalloc NUM
Free thread-local kalloc memory reservoir if after the alignment the size of the reservoir above_NUM_. Set 0 to disable [500m].
-a Generate CIGAR and output alignments in the SAM format. Minimap2 outputs in PAF by default.
-o FILE Output alignments to_FILE_ [stdout].
-Q Ignore base quality in the input file.
-L Write CIGAR with >65535 operators at the CG tag. Older tools are unable to convert alignments with >65535 CIGAR ops to BAM. This option makes minimap2 SAM compatible with older tools. Newer tools recognizes 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 output.
-c Generate CIGAR. In PAF, the CIGAR is written to the ‘cg’ custom tag.
--cs[=STR]
Output thecs tag.STR can be either_short_ or_long_. If no_STR_ 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.
--secondary-seq
In SAM output, show query sequences for secondary alignments.
--seed INT Integer seed for randomizing equally best hits. Minimap2 hashes_INT_ and read name when choosing between equally best hits. [11]
-t INT Number of threads [3]. Minimap2 uses at most three threads when indexing target sequences, and uses up to_INT_+1 threads when mapping (the extra thread is for I/O, which is frequently idle and takes 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/O thread may become the bottleneck. Apply this option to use one thread for input and 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 large_NUM_ helps load balancing in the 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 the reference name fields are 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 version number to stdout

Minimap2 outputs mapping positions in the Pairwise mApping Format (PAF) by default. PAF is a TAB-delimited text format with each line consisting of at least 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 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. PAF may optionally have additional fields in the 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 (with approximate CIGAR strings)
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 query_AND_ 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