-
Notifications
You must be signed in to change notification settings - Fork 0
/
minimap2.1
702 lines (697 loc) · 18.6 KB
/
minimap2.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
.TH minimap2 1 "9 April 2021" "minimap2-2.18 (r1015)" "Bioinformatics tools"
.SH NAME
.PP
minimap2 - mapping and alignment between collections of DNA sequences
.SH SYNOPSIS
* Indexing the target sequences (optional):
.RS 4
minimap2
.RB [ -x
.IR preset ]
.B -d
.I target.mmi
.I target.fa
.br
minimap2
.RB [ -H ]
.RB [ -k
.IR kmer ]
.RB [ -w
.IR miniWinSize ]
.RB [ -I
.IR batchSize ]
.B -d
.I target.mmi
.I target.fa
.RE
* Long-read alignment with CIGAR:
.RS 4
minimap2
.B -a
.RB [ -x
.IR preset ]
.I target.mmi
.I query.fa
>
.I output.sam
.br
minimap2
.B -c
.RB [ -H ]
.RB [ -k
.IR kmer ]
.RB [ -w
.IR miniWinSize ]
.RB [ ... ]
.I target.fa
.I query.fa
>
.I output.paf
.RE
* Long-read overlap without CIGAR:
.RS 4
minimap2
.B -x
ava-ont
.RB [ -t
.IR nThreads ]
.I target.fa
.I query.fa
>
.I output.paf
.RE
.SH DESCRIPTION
.PP
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.
.SH OPTIONS
.SS Indexing options
.TP 10
.BI -k \ INT
Minimizer k-mer length [15]
.TP
.BI -w \ INT
Minimizer window size [2/3 of k-mer length]. A minimizer is the smallest k-mer
in a window of w consecutive k-mers.
.TP
.B -H
Use homopolymer-compressed (HPC) minimizers. An HPC sequence is constructed by
contracting homopolymer runs to a single base. An HPC minimizer is a minimizer
on the HPC sequence.
.TP
.BI -I \ NUM
Load at most
.I NUM
target bases into RAM for indexing [4G]. If there are more than
.I NUM
bases in
.IR target.fa ,
minimap2 needs to read
.I query.fa
multiple times to map it against each batch of target sequences.
.I NUM
may be ending with k/K/m/M/g/G. NB: mapping quality is incorrect given a
multi-part index.
.TP
.B --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
.B -a
or
.BR -c .
When base-level alignment is not requested, this option is automatically applied.
.TP
.BI -d \ FILE
Save the minimizer index of
.I target.fa
to
.I 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. When an index file is
provided as the target sequences, options
.BR -H ,
.BR -k ,
.BR -w ,
.B -I
will be effectively overridden by the options stored in the index file.
.TP
.BI --alt \ FILE
List of ALT contigs [null]
.TP
.BI --alt-drop \ FLOAT
Drop ALT hits by
.I FLOAT
fraction when ranking and computing mapping quality [0.15]
.SS Mapping options
.TP 10
.BI -f \ FLOAT | INT1 [, INT2 ]
If fraction, ignore top
.I FLOAT
fraction of most frequent minimizers [0.0002]. If integer,
ignore minimizers occuring more than
.I INT1
times.
.I INT2
is only effective in the
.B --sr
or
.B -xsr
mode, which sets the threshold for a second round of seeding.
.TP
.BI --min-occ-floor \ INT
Force minimap2 to always use k-mers occurring
.I INT
times or less [0]. In effect, the max occurrence threshold is set to
the
.RI max{ INT ,
.BR -f }.
.TP
.BI -g \ INT
Stop chain enlongation if there are no minimizers within
.IR INT -bp
[10000].
.TP
.BI -r \ INT
Bandwidth used in chaining and DP-based alignment [500]. This option
approximately controls the maximum gap size.
.TP
.BI -n \ INT
Discard chains consisting of
.RI < INT
number of minimizers [3]
.TP
.BI -m \ INT
Discard chains with chaining score
.RI < INT
[40]. Chaining score equals the approximate number of matching bases minus a
concave gap penalty. It is computed with dynamic programming.
.TP
.B -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.
.TP
.B -P
Retain all chains and don't attempt to set primary chains. Options
.B -p
and
.B -N
have no effect when this option is in use.
.TP
.BR --dual = yes | no
If
.BR no ,
skip query-target pairs wherein the query name is lexicographically greater
than the target name [yes]
.TP
.B -X
Equivalent to
.RB ' -DP
.BR --dual = no
.BR --no-long-join '.
Primarily used for all-vs-all read overlapping.
.TP
.BI -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
.BR -M ),
the chain with a lower score is secondary to the chain with a higher score.
If the ratio of the scores is below
.IR FLOAT ,
the secondary chain will not be outputted or extended with DP alignment later.
This option has no effect when
.B -X
is applied.
.TP
.BI -N \ INT
Output at most
.I INT
secondary alignments [5]. This option has no effect when
.B -X
is applied.
.TP
.BI -G \ NUM
Maximum gap on the reference (effective with
.BR -xsplice / --splice ).
This option also changes the chaining and alignment band width to
.IR NUM .
Increasing this option slows down spliced alignment. [200k]
.TP
.BI -F \ NUM
Maximum fragment length (aka insert size; effective with
.BR -xsr / --frag = yes )
[800]
.TP
.BI -M \ FLOAT
Mark as secondary a chain that overlaps with a better chain by
.I FLOAT
or more of the shorter chain [0.5]
.TP
.B --hard-mask-level
Honor option
.B -M
and disable a heurstic to save unmapped subsequences and disables
.BR --mask-len .
.TP
.BI --mask-len \ NUM
Keep an alignment if dropping it leaves an unaligned region on query longer than
.IR INT
[inf]. Effective without
.BR --hard-mask-level .
.TP
.BI --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
.I INT
to a large number to switch off this heurstics.
.TP
.BI --max-chain-iter \ INT
Check up to
.I INT
partial chains during chaining [5000]. This is a heuristic to avoid quadratic
time complexity in the worst case.
.TP
.BI --chain-gap-scale \ FLOAT
Scale of gap cost during chaining [1.0]
.TP
.B --no-long-join
Disable the long gap patching heuristic. When this option is applied, the
maximum alignment gap is mostly controlled by
.BR -r .
.TP
.BI --lj-min-ratio \ FLOAT
Fraction of query sequence length required to bridge a long gap [0.5]. A
smaller value helps to recover longer gaps, at the cost of more false gaps.
.TP
.B --splice
Enable the splice alignment mode.
.TP
.B --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.
.TP
.BI --split-prefix \ STR
Prefix to create temporary files. Typically used for a multi-part index.
.TP
.BR --frag = no | yes
Whether to enable the fragment mode [no]
.TP
.B --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.
.TP
.B --rev-only
Only map to the reverse complement strand of the reference sequences.
.TP
.BR --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]
.TP
.B --no-pairing
Treat two reads in a pair as independent reads. The mate related fields in SAM
are still properly populated.
.SS Alignment options
.TP 10
.BI -A \ INT
Matching score [2]
.TP
.BI -B \ INT
Mismatching penalty [4]
.TP
.BI -O \ INT1[,INT2]
Gap open penalty [4,24]. If
.I INT2
is not specified, it is set to
.IR INT1 .
.TP
.BI -E \ INT1[,INT2]
Gap extension penalty [2,1]. A gap of length
.I k
costs
.RI min{ O1 + k * E1 , O2 + k * E2 }.
In the splice mode, the second gap penalties are not used.
.TP
.BI -C \ INT
Cost for a non-canonical GT-AG splicing (effective with
.BR --splice )
[0]
.TP
.BI -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
.IR 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
.IR INT1 .
Decrease
.I INT2
to find small inversions at the cost of performance and false positives.
Increase
.I INT1
to improves the contiguity of alignment at the cost of poor alignment in the
middle.
.TP
.BI -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.
.TP
.BI -u \ CHAR
How to find canonical splicing sites GT-AG -
.BR f :
transcript strand;
.BR b :
both strands;
.BR n :
no attempt to match GT-AG [n]
.TP
.BI --end-bonus \ INT
Score bonus when alignment extends to the end of the query sequence [0].
.TP
.BI --score-N \ INT
Score of a mismatch involving ambiguous bases [1].
.TP
.BR --splice-flank = yes | no
Assume the next base to a
.B GT
donor site tends to be A/G (91% in human and 92% in mouse) and the preceding
base to a
.B AG
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
.BR --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
.B --splice-flank=no
to the command line.
.TP
.BR --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'
[].
.TP
.BR --junc-bonus \ INT
Score bonus for a splice donor or acceptor found in annotation (effective with
.BR --junc-bed )
[9].
.TP
.BI --end-seed-pen \ INT
Drop a terminal anchor if
.IR s <log( g )+ INT ,
where
.I s
is the local alignment score around the anchor and
.I g
the length of the terminal gap in the chain. This option is only effective
with
.BR --splice .
It helps to avoid tiny terminal exons. [6]
.TP
.B --no-end-flt
Don't filter seeds towards the ends of chains before performing base-level
alignment.
.TP
.BI --cap-sw-mem \ NUM
Skip alignment if the DP matrix size is above
.IR NUM .
Set 0 to disable [0].
.SS Input/output options
.TP 10
.B -a
Generate CIGAR and output alignments in the SAM format. Minimap2 outputs in PAF
by default.
.TP
.BI -o \ FILE
Output alignments to
.I FILE
[stdout].
.TP
.B -Q
Ignore base quality in the input file.
.TP
.B -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.
.TP
.BI -R \ STR
SAM read group line in a format like
.B @RG\\\\tID:foo\\\\tSM:bar
[].
.TP
.B -y
Copy input FASTA/Q comments to output.
.TP
.B -c
Generate CIGAR. In PAF, the CIGAR is written to the `cg' custom tag.
.TP
.BI --cs[= STR ]
Output the
.B cs
tag.
.I STR
can be either
.I short
or
.IR long .
If no
.I STR
is given,
.I short
is assumed. [none]
.TP
.B --MD
Output the MD tag (see the SAM spec).
.TP
.B --eqx
Output =/X CIGAR operators for sequence match/mismatch.
.TP
.B -Y
In SAM output, use soft clipping for supplementary alignments.
.TP
.BI --seed \ INT
Integer seed for randomizing equally best hits. Minimap2 hashes
.I INT
and read name when choosing between equally best hits. [11]
.TP
.BI -t \ INT
Number of threads [3]. Minimap2 uses at most three threads when indexing target
sequences, and uses up to
.IR INT +1
threads when mapping (the extra thread is for I/O, which is frequently idle and
takes little CPU time).
.TP
.B -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.
.TP
.BI -K \ NUM
Number of bases loaded into memory to process in a mini-batch [500M].
Similar to option
.BR -I ,
K/M/G/k/m/g suffix is accepted. A large
.I NUM
helps load balancing in the multi-threading mode, at the cost of increased
memory.
.TP
.BR --secondary = yes | no
Whether to output secondary alignments [yes]
.TP
.BI --max-qlen \ NUM
Filter out query sequences longer than
.IR NUM .
.TP
.B --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.
.TP
.B --sam-hit-only
In SAM, don't output unmapped reads.
.TP
.B --version
Print version number to stdout
.SS Preset options
.TP 10
.BI -x \ STR
Preset []. This option applies multiple options at the same time. It should be
applied before other options because options applied later will overwrite the
values set by
.BR -x .
Available
.I STR
are:
.RS
.TP 8
.B map-pb
PacBio/Oxford Nanopore read to reference mapping
.RB ( -Hk19 )
.TP
.B map-ont
Slightly more sensitive for Oxford Nanopore to reference mapping
.RB ( -k15 ).
For PacBio reads, HPC minimizers consistently leads to faster performance and
more sensitive results in comparison to normal minimizers. For Oxford Nanopore
data, normal minimizers are better, though not much. The effectiveness of HPC
is determined by the sequencing error mode.
.TP
.B asm5
Long assembly to reference mapping
.RB ( -k19
.B -w19 -A1 -B19 -O39,81 -E3,1 -s200 -z200 -N50
.BR --min-occ-floor=100 ).
Typically, the alignment will not extend to regions with 5% or higher sequence
divergence. Only use this preset if the average divergence is far below 5%.
.TP
.B asm10
Long assembly to reference mapping
.RB ( -k19
.B -w19 -A1 -B9 -O16,41 -E2,1 -s200 -z200 -N50
.BR --min-occ-floor=100 ).
Up to 10% sequence divergence.
.TP
.B asm20
Long assembly to reference mapping
.RB ( -k19
.B -w10 -A1 -B4 -O6,26 -E2,1 -s200 -z200 -N50
.BR --min-occ-floor=100 ).
Up to 20% sequence divergence.
.TP
.B ava-pb
PacBio all-vs-all overlap mapping
.RB ( -Hk19
.B -Xw5 -m100 -g10000 --max-chain-skip
.BR 25 ).
.TP
.B ava-ont
Oxford Nanopore all-vs-all overlap mapping
.RB ( -k15
.B -Xw5 -m100 -g10000 -r2000 --max-chain-skip
.BR 25 ).
Similarly, the major difference from
.B ava-pb
is that this preset is not using HPC minimizers.
.TP
.B splice
Long-read spliced alignment
.RB ( -k15
.B -w5 --splice -g2000 -G200k -A1 -B2 -O2,32 -E1,0 -C9 -z200 -ub --junc-bonus=9
.BR --splice-flank=yes ).
In the splice mode, 1) long deletions are taken as introns and represented as
the
.RB ` N '
CIGAR operator; 2) long insertions are disabled; 3) deletion and insertion gap
costs are different during chaining; 4) the computation of the
.RB ` ms '
tag ignores introns to demote hits to pseudogenes.
.TP
.B splice:hq
Long-read splice alignment for PacBio CCS reads
.RB ( -xsplice
.B -C5 -O6,24
.BR -B4 ).
.TP
.B sr
Short single-end reads without splicing
.RB ( -k21
.B -w11 --sr --frag=yes -A2 -B8 -O12,32 -E2,1 -r50 -p.5 -N20 -f1000,5000 -n2 -m20
.B -s40 -g200 -2K50m --heap-sort=yes
.BR --secondary=no ).
.RE
.SS Miscellaneous options
.TP 10
.B --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 the
multi-threading mode.
.TP
.B --print-qname
Print query names to stderr, mostly to see which query is crashing minimap2.
.TP
.B --print-seeds
Print seed positions to stderr, for debugging only.
.SH OUTPUT FORMAT
.PP
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:
.TS
center box;
cb | cb | cb
r | c | l .
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)
.TE
.PP
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:
.TS
center box;
cb | cb | cb
r | c | l .
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
.TE
.PP
The
.B cs
tag encodes difference sequences in the short form or the entire query
.I AND
reference sequences in the long form. It consists of a series of operations:
.TS
center box;
cb | cb |cb
r | l | l .
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
.TE
.SH LIMITATIONS
.TP 2
*
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.
.TP
*
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.
.SH SEE ALSO
.PP
miniasm(1), minimap(1), bwa(1).