README.md
1[](https://github.com/lh3/minimap2/releases)
2[](https://anaconda.org/bioconda/minimap2)
3[](https://pypi.python.org/pypi/mappy)
4[](https://github.com/lh3/minimap2/actions)
5## <a name="started"></a>Getting Started
6```sh
7git clone https://github.com/lh3/minimap2
8cd minimap2 && make
9# long sequences against a reference genome
10./minimap2 -a test/MT-human.fa test/MT-orang.fa > test.sam
11# create an index first and then map
12./minimap2 -x map-ont -d MT-human-ont.mmi test/MT-human.fa
13./minimap2 -a MT-human-ont.mmi test/MT-orang.fa > test.sam
14# use presets (no test data)
15./minimap2 -ax map-pb ref.fa pacbio.fq.gz > aln.sam # PacBio CLR genomic reads
16./minimap2 -ax map-ont ref.fa ont.fq.gz > aln.sam # Oxford Nanopore genomic reads
17./minimap2 -ax map-hifi ref.fa pacbio-ccs.fq.gz > aln.sam # PacBio HiFi/CCS genomic reads (v2.19 or later)
18./minimap2 -ax asm20 ref.fa pacbio-ccs.fq.gz > aln.sam # PacBio HiFi/CCS genomic reads (v2.18 or earlier)
19./minimap2 -ax sr ref.fa read1.fa read2.fa > aln.sam # short genomic paired-end reads
20./minimap2 -ax splice ref.fa rna-reads.fa > aln.sam # spliced long reads (strand unknown)
21./minimap2 -ax splice -uf -k14 ref.fa reads.fa > aln.sam # noisy Nanopore Direct RNA-seq
22./minimap2 -ax splice:hq -uf ref.fa query.fa > aln.sam # Final PacBio Iso-seq or traditional cDNA
23./minimap2 -ax splice --junc-bed anno.bed12 ref.fa query.fa > aln.sam # prioritize on annotated junctions
24./minimap2 -cx asm5 asm1.fa asm2.fa > aln.paf # intra-species asm-to-asm alignment
25./minimap2 -x ava-pb reads.fa reads.fa > overlaps.paf # PacBio read overlap
26./minimap2 -x ava-ont reads.fa reads.fa > overlaps.paf # Nanopore read overlap
27# man page for detailed command line options
28man ./minimap2.1
29```
30
31## Table of Contents
32
33- [Getting Started](#started)
34- [Users' Guide](#uguide)
35 - [Installation](#install)
36 - [General usage](#general)
37 - [Use cases](#cases)
38 - [Map long noisy genomic reads](#map-long-genomic)
39 - [Map long mRNA/cDNA reads](#map-long-splice)
40 - [Find overlaps between long reads](#long-overlap)
41 - [Map short accurate genomic reads](#short-genomic)
42 - [Full genome/assembly alignment](#full-genome)
43 - [Advanced features](#advanced)
44 - [Working with >65535 CIGAR operations](#long-cigar)
45 - [The cs optional tag](#cs)
46 - [Working with the PAF format](#paftools)
47 - [Algorithm overview](#algo)
48 - [Getting help](#help)
49 - [Citing minimap2](#cite)
50- [Developers' Guide](#dguide)
51- [Limitations](#limit)
52
53## <a name="uguide"></a>Users' Guide
54
55Minimap2 is a versatile sequence alignment program that aligns DNA or mRNA
56sequences against a large reference database. Typical use cases include: (1)
57mapping PacBio or Oxford Nanopore genomic reads to the human genome; (2)
58finding overlaps between long reads with error rate up to ~15%; (3)
59splice-aware alignment of PacBio Iso-Seq or Nanopore cDNA or Direct RNA reads
60against a reference genome; (4) aligning Illumina single- or paired-end reads;
61(5) assembly-to-assembly alignment; (6) full-genome alignment between two
62closely related species with divergence below ~15%.
63
64For ~10kb noisy reads sequences, minimap2 is tens of times faster than
65mainstream long-read mappers such as BLASR, BWA-MEM, NGMLR and GMAP. It is more
66accurate on simulated long reads and produces biologically meaningful alignment
67ready for downstream analyses. For >100bp Illumina short reads, minimap2 is
68three times as fast as BWA-MEM and Bowtie2, and as accurate on simulated data.
69Detailed evaluations are available from the [minimap2 paper][doi] or the
70[preprint][preprint].
71
72### <a name="install"></a>Installation
73
74Minimap2 is optimized for x86-64 CPUs. You can acquire precompiled binaries from
75the [release page][release] with:
76```sh
77curl -L https://github.com/lh3/minimap2/releases/download/v2.24/minimap2-2.24_x64-linux.tar.bz2 | tar -jxvf -
78./minimap2-2.24_x64-linux/minimap2
79```
80If you want to compile from the source, you need to have a C compiler, GNU make
81and zlib development files installed. Then type `make` in the source code
82directory to compile. If you see compilation errors, try `make sse2only=1`
83to disable SSE4 code, which will make minimap2 slightly slower.
84
85Minimap2 also works with ARM CPUs supporting the NEON instruction sets. To
86compile for 32 bit ARM architectures (such as ARMv7), use `make arm_neon=1`. To
87compile for for 64 bit ARM architectures (such as ARMv8), use `make arm_neon=1
88aarch64=1`.
89
90Minimap2 can use [SIMD Everywhere (SIMDe)][simde] library for porting
91implementation to the different SIMD instruction sets. To compile using SIMDe,
92use `make -f Makefile.simde`. To compile for ARM CPUs, use `Makefile.simde`
93with the ARM related command lines given above.
94
95### <a name="general"></a>General usage
96
97Without any options, minimap2 takes a reference database and a query sequence
98file as input and produce approximate mapping, without base-level alignment
99(i.e. coordinates are only approximate and no CIGAR in output), in the [PAF format][paf]:
100```sh
101minimap2 ref.fa query.fq > approx-mapping.paf
102```
103You can ask minimap2 to generate CIGAR at the `cg` tag of PAF with:
104```sh
105minimap2 -c ref.fa query.fq > alignment.paf
106```
107or to output alignments in the [SAM format][sam]:
108```sh
109minimap2 -a ref.fa query.fq > alignment.sam
110```
111Minimap2 seamlessly works with gzip'd FASTA and FASTQ formats as input. You
112don't need to convert between FASTA and FASTQ or decompress gzip'd files first.
113
114For the human reference genome, minimap2 takes a few minutes to generate a
115minimizer index for the reference before mapping. To reduce indexing time, you
116can optionally save the index with option **-d** and replace the reference
117sequence file with the index file on the minimap2 command line:
118```sh
119minimap2 -d ref.mmi ref.fa # indexing
120minimap2 -a ref.mmi reads.fq > alignment.sam # alignment
121```
122***Importantly***, it should be noted that once you build the index, indexing
123parameters such as **-k**, **-w**, **-H** and **-I** can't be changed during
124mapping. If you are running minimap2 for different data types, you will
125probably need to keep multiple indexes generated with different parameters.
126This makes minimap2 different from BWA which always uses the same index
127regardless of query data types.
128
129### <a name="cases"></a>Use cases
130
131Minimap2 uses the same base algorithm for all applications. However, due to the
132different data types it supports (e.g. short vs long reads; DNA vs mRNA reads),
133minimap2 needs to be tuned for optimal performance and accuracy. It is usually
134recommended to choose a preset with option **-x**, which sets multiple
135parameters at the same time. The default setting is the same as `map-ont`.
136
137#### <a name="map-long-genomic"></a>Map long noisy genomic reads
138
139```sh
140minimap2 -ax map-pb ref.fa pacbio-reads.fq > aln.sam # for PacBio CLR reads
141minimap2 -ax map-ont ref.fa ont-reads.fq > aln.sam # for Oxford Nanopore reads
142```
143The difference between `map-pb` and `map-ont` is that `map-pb` uses
144homopolymer-compressed (HPC) minimizers as seeds, while `map-ont` uses ordinary
145minimizers as seeds. Emperical evaluation suggests HPC minimizers improve
146performance and sensitivity when aligning PacBio CLR reads, but hurt when aligning
147Nanopore reads.
148
149#### <a name="map-long-splice"></a>Map long mRNA/cDNA reads
150
151```sh
152minimap2 -ax splice:hq -uf ref.fa iso-seq.fq > aln.sam # PacBio Iso-seq/traditional cDNA
153minimap2 -ax splice ref.fa nanopore-cdna.fa > aln.sam # Nanopore 2D cDNA-seq
154minimap2 -ax splice -uf -k14 ref.fa direct-rna.fq > aln.sam # Nanopore Direct RNA-seq
155minimap2 -ax splice --splice-flank=no SIRV.fa SIRV-seq.fa # mapping against SIRV control
156```
157There are different long-read RNA-seq technologies, including tranditional
158full-length cDNA, EST, PacBio Iso-seq, Nanopore 2D cDNA-seq and Direct RNA-seq.
159They produce data of varying quality and properties. By default, `-x splice`
160assumes the read orientation relative to the transcript strand is unknown. It
161tries two rounds of alignment to infer the orientation and write the strand to
162the `ts` SAM/PAF tag if possible. For Iso-seq, Direct RNA-seq and tranditional
163full-length cDNAs, it would be desired to apply `-u f` to force minimap2 to
164consider the forward transcript strand only. This speeds up alignment with
165slight improvement to accuracy. For noisy Nanopore Direct RNA-seq reads, it is
166recommended to use a smaller k-mer size for increased sensitivity to the first
167or the last exons.
168
169Minimap2 rates an alignment by the score of the max-scoring sub-segment,
170*excluding* introns, and marks the best alignment as primary in SAM. When a
171spliced gene also has unspliced pseudogenes, minimap2 does not intentionally
172prefer spliced alignment, though in practice it more often marks the spliced
173alignment as the primary. By default, minimap2 outputs up to five secondary
174alignments (i.e. likely pseudogenes in the context of RNA-seq mapping). This
175can be tuned with option **-N**.
176
177For long RNA-seq reads, minimap2 may produce chimeric alignments potentially
178caused by gene fusions/structural variations or by an intron longer than the
179max intron length **-G** (200k by default). For now, it is not recommended to
180apply an excessively large **-G** as this slows down minimap2 and sometimes
181leads to false alignments.
182
183It is worth noting that by default `-x splice` prefers GT[A/G]..[C/T]AG
184over GT[C/T]..[A/G]AG, and then over other splicing signals. Considering
185one additional base improves the junction accuracy for noisy reads, but
186reduces the accuracy when aligning against the widely used SIRV control data.
187This is because SIRV does not honor the evolutionarily conservative splicing
188signal. If you are studying SIRV, you may apply `--splice-flank=no` to let
189minimap2 only model GT..AG, ignoring the additional base.
190
191Since v2.17, minimap2 can optionally take annotated genes as input and
192prioritize on annotated splice junctions. To use this feature, you can
193```sh
194paftools.js gff2bed anno.gff > anno.bed
195minimap2 -ax splice --junc-bed anno.bed ref.fa query.fa > aln.sam
196```
197Here, `anno.gff` is the gene annotation in the GTF or GFF3 format (`gff2bed`
198automatically tests the format). The output of `gff2bed` is in the 12-column
199BED format, or the BED12 format. With the `--junc-bed` option, minimap2 adds a
200bonus score (tuned by `--junc-bonus`) if an aligned junction matches a junction
201in the annotation. Option `--junc-bed` also takes 5-column BED, including the
202strand field. In this case, each line indicates an oriented junction.
203
204#### <a name="long-overlap"></a>Find overlaps between long reads
205
206```sh
207minimap2 -x ava-pb reads.fq reads.fq > ovlp.paf # PacBio CLR read overlap
208minimap2 -x ava-ont reads.fq reads.fq > ovlp.paf # Oxford Nanopore read overlap
209```
210Similarly, `ava-pb` uses HPC minimizers while `ava-ont` uses ordinary
211minimizers. It is usually not recommended to perform base-level alignment in
212the overlapping mode because it is slow and may produce false positive
213overlaps. However, if performance is not a concern, you may try to add `-a` or
214`-c` anyway.
215
216#### <a name="short-genomic"></a>Map short accurate genomic reads
217
218```sh
219minimap2 -ax sr ref.fa reads-se.fq > aln.sam # single-end alignment
220minimap2 -ax sr ref.fa read1.fq read2.fq > aln.sam # paired-end alignment
221minimap2 -ax sr ref.fa reads-interleaved.fq > aln.sam # paired-end alignment
222```
223When two read files are specified, minimap2 reads from each file in turn and
224merge them into an interleaved stream internally. Two reads are considered to
225be paired if they are adjacent in the input stream and have the same name (with
226the `/[0-9]` suffix trimmed if present). Single- and paired-end reads can be
227mixed.
228
229Minimap2 does not work well with short spliced reads. There are many capable
230RNA-seq mappers for short reads.
231
232#### <a name="full-genome"></a>Full genome/assembly alignment
233
234```sh
235minimap2 -ax asm5 ref.fa asm.fa > aln.sam # assembly to assembly/ref alignment
236```
237For cross-species full-genome alignment, the scoring system needs to be tuned
238according to the sequence divergence.
239
240### <a name="advanced"></a>Advanced features
241
242#### <a name="long-cigar"></a>Working with >65535 CIGAR operations
243
244Due to a design flaw, BAM does not work with CIGAR strings with >65535
245operations (SAM and CRAM work). However, for ultra-long nanopore reads minimap2
246may align ~1% of read bases with long CIGARs beyond the capability of BAM. If
247you convert such SAM/CRAM to BAM, Picard and recent samtools will throw an
248error and abort. Older samtools and other tools may create corrupted BAM.
249
250To avoid this issue, you can add option `-L` at the minimap2 command line.
251This option moves a long CIGAR to the `CG` tag and leaves a fully clipped CIGAR
252at the SAM CIGAR column. Current tools that don't read CIGAR (e.g. merging and
253sorting) still work with such BAM records; tools that read CIGAR will
254effectively ignore these records. It has been decided that future tools
255will seamlessly recognize long-cigar records generated by option `-L`.
256
257**TL;DR**: if you work with ultra-long reads and use tools that only process
258BAM files, please add option `-L`.
259
260#### <a name="cs"></a>The cs optional tag
261
262The `cs` SAM/PAF tag encodes bases at mismatches and INDELs. It matches regular
263expression `/(:[0-9]+|\*[a-z][a-z]|[=\+\-][A-Za-z]+)+/`. Like CIGAR, `cs`
264consists of series of operations. Each leading character specifies the
265operation; the following sequence is the one involved in the operation.
266
267The `cs` tag is enabled by command line option `--cs`. The following alignment,
268for example:
269```txt
270CGATCGATAAATAGAGTAG---GAATAGCA
271|||||| |||||||||| |||| |||
272CGATCG---AATAGAGTAGGTCGAATtGCA
273```
274is represented as `:6-ata:10+gtc:4*at:3`, where `:[0-9]+` represents an
275identical block, `-ata` represents a deletion, `+gtc` an insertion and `*at`
276indicates reference base `a` is substituted with a query base `t`. It is
277similar to the `MD` SAM tag but is standalone and easier to parse.
278
279If `--cs=long` is used, the `cs` string also contains identical sequences in
280the alignment. The above example will become
281`=CGATCG-ata=AATAGAGTAG+gtc=GAAT*at=GCA`. The long form of `cs` encodes both
282reference and query sequences in one string. The `cs` tag also encodes intron
283positions and splicing signals (see the [minimap2 manpage][manpage-cs] for
284details).
285
286#### <a name="paftools"></a>Working with the PAF format
287
288Minimap2 also comes with a (java)script [paftools.js](misc/paftools.js) that
289processes alignments in the PAF format. It calls variants from
290assembly-to-reference alignment, lifts over BED files based on alignment,
291converts between formats and provides utilities for various evaluations. For
292details, please see [misc/README.md](misc/README.md).
293
294### <a name="algo"></a>Algorithm overview
295
296In the following, minimap2 command line options have a dash ahead and are
297highlighted in bold. The description may help to tune minimap2 parameters.
298
2991. Read **-I** [=*4G*] reference bases, extract (**-k**,**-w**)-minimizers and
300 index them in a hash table.
301
3022. Read **-K** [=*200M*] query bases. For each query sequence, do step 3
303 through 7:
304
3053. For each (**-k**,**-w**)-minimizer on the query, check against the reference
306 index. If a reference minimizer is not among the top **-f** [=*2e-4*] most
307 frequent, collect its the occurrences in the reference, which are called
308 *seeds*.
309
3104. Sort seeds by position in the reference. Chain them with dynamic
311 programming. Each chain represents a potential mapping. For read
312 overlapping, report all chains and then go to step 8. For reference mapping,
313 do step 5 through 7:
314
3155. Let *P* be the set of primary mappings, which is an empty set initially. For
316 each chain from the best to the worst according to their chaining scores: if
317 on the query, the chain overlaps with a chain in *P* by **--mask-level**
318 [=*0.5*] or higher fraction of the shorter chain, mark the chain as
319 *secondary* to the chain in *P*; otherwise, add the chain to *P*.
320
3216. Retain all primary mappings. Also retain up to **-N** [=*5*] top secondary
322 mappings if their chaining scores are higher than **-p** [=*0.8*] of their
323 corresponding primary mappings.
324
3257. If alignment is requested, filter out an internal seed if it potentially
326 leads to both a long insertion and a long deletion. Extend from the
327 left-most seed. Perform global alignments between internal seeds. Split the
328 chain if the accumulative score along the global alignment drops by **-z**
329 [=*400*], disregarding long gaps. Extend from the right-most seed. Output
330 chains and their alignments.
331
3328. If there are more query sequences in the input, go to step 2 until no more
333 queries are left.
334
3359. If there are more reference sequences, reopen the query file from the start
336 and go to step 1; otherwise stop.
337
338### <a name="help"></a>Getting help
339
340Manpage [minimap2.1][manpage] provides detailed description of minimap2
341command line options and optional tags. The [FAQ](FAQ.md) page answers several
342frequently asked questions. If you encounter bugs or have further questions or
343requests, you can raise an issue at the [issue page][issue]. There is not a
344specific mailing list for the time being.
345
346### <a name="cite"></a>Citing minimap2
347
348If you use minimap2 in your work, please cite:
349
350> Li, H. (2018). Minimap2: pairwise alignment for nucleotide sequences.
351> *Bioinformatics*, **34**:3094-3100. [doi:10.1093/bioinformatics/bty191][doi]
352
353## <a name="dguide"></a>Developers' Guide
354
355Minimap2 is not only a command line tool, but also a programming library.
356It provides C APIs to build/load index and to align sequences against the
357index. File [example.c](example.c) demonstrates typical uses of C APIs. Header
358file [minimap.h](minimap.h) gives more detailed API documentation. Minimap2
359aims to keep APIs in this header stable. File [mmpriv.h](mmpriv.h) contains
360additional private APIs which may be subjected to changes frequently.
361
362This repository also provides Python bindings to a subset of C APIs. File
363[python/README.rst](python/README.rst) gives the full documentation;
364[python/minimap2.py](python/minimap2.py) shows an example. This Python
365extension, mappy, is also [available from PyPI][mappypypi] via `pip install
366mappy` or [from BioConda][mappyconda] via `conda install -c bioconda mappy`.
367
368## <a name="limit"></a>Limitations
369
370* Minimap2 may produce suboptimal alignments through long low-complexity
371 regions where seed positions may be suboptimal. This should not be a big
372 concern because even the optimal alignment may be wrong in such regions.
373
374* Minimap2 requires SSE2 instructions on x86 CPUs or NEON on ARM CPUs. It is
375 possible to add non-SIMD support, but it would make minimap2 slower by
376 several times.
377
378* Minimap2 does not work with a single query or database sequence ~2
379 billion bases or longer (2,147,483,647 to be exact). The total length of all
380 sequences can well exceed this threshold.
381
382* Minimap2 often misses small exons.
383
384
385
386[paf]: https://github.com/lh3/miniasm/blob/master/PAF.md
387[sam]: https://samtools.github.io/hts-specs/SAMv1.pdf
388[minimap]: https://github.com/lh3/minimap
389[smartdenovo]: https://github.com/ruanjue/smartdenovo
390[longislnd]: https://www.ncbi.nlm.nih.gov/pubmed/27667791
391[gaba]: https://github.com/ocxtal/libgaba
392[ksw2]: https://github.com/lh3/ksw2
393[preprint]: https://arxiv.org/abs/1708.01492
394[release]: https://github.com/lh3/minimap2/releases
395[mappypypi]: https://pypi.python.org/pypi/mappy
396[mappyconda]: https://anaconda.org/bioconda/mappy
397[issue]: https://github.com/lh3/minimap2/issues
398[k8]: https://github.com/attractivechaos/k8
399[manpage]: https://lh3.github.io/minimap2/minimap2.html
400[manpage-cs]: https://lh3.github.io/minimap2/minimap2.html#10
401[doi]: https://doi.org/10.1093/bioinformatics/bty191
402[smide]: https://github.com/nemequ/simde
403[unimap]: https://github.com/lh3/unimap
404
){kind=link}
){kind=link}
){kind=link}
){kind=link}