minimap2 Documentation

The mapeval command evaluates mapped SAM/PAF files. It is typically used with simulated reads converted via pbsim2fq (for MAF) or mason2fq (for SAM).

Output includes:

• Q lines: Quality threshold, number of reads with mapping quality $\ge$ threshold, number of wrong mappings, accumulative mapping error rate, and accumulative number of mapped reads.
• U line: Number of unmapped reads (if present in SAM).

Before using Minimap2, be aware of the following technical constraints:

Hardware Requirements

• x86 CPUs: Requires SSE2 instructions.
• ARM CPUs: Requires NEON instructions.
• While non-SIMD support is possible, it significantly reduces performance.

Sequence Constraints

• Maximum Sequence Length: A single query or database sequence cannot be approximately 2 billion bases or longer (specifically, the limit is 2,147,483,647 bases). However, the total length of all sequences combined can exceed this limit.

Alignment Limitations

• Low-complexity regions: Minimap2 may produce suboptimal alignments in long, low-complexity regions because seed positions may be suboptimal.
• Exons: Minimap2 may occasionally miss small exons.

To speed up mapping, you can create an index file (.mmi) first and then use that index for subsequent mapping tasks.

1. Create the index:

./minimap2 -x map-ont -d MT-human-ont.mmi test/MT-human.fa

2. Map using the index:

./minimap2 -a MT-human-ont.mmi test/MT-orang.fa > test.sam

Direct-RNA reads are noisier and stranded. Use a shorter k-mer (-k14) for sensitivity and the -uf flag to force mapping to the forward transcript strand only. The --splice-flank=no option is also recommended for SIRV data.

minimap2 -ax splice -k14 -uf SIRV_E2.fa SIRV_ont-drna.fa > aln.sam

To install minimap2, clone the repository and build it using make.

# install minimap2
git clone https://github.com/lh3/minimap2
cd minimap2 && make

Mappy is a Python binding for minimap2. It requires zlib. You can install it via pip or by building it from the source repository.

Using pip:

pip install --user mappy

Building from source (requires Cython):

git clone https://github.com/lh3/minimap2
cd minimap2
python setup.py install

To install the minimap2 executables and the companion paftools.js script, download the release tarball, extract it, and add the directory to your PATH.

# install minimap2 executables
curl -L https://github.com/lh3/minimap2/releases/download/v2.31/minimap2-2.31_x64-linux.tar.bz2 | tar jxf -
cp minimap2-2.31_x64-linux/{minimap2,k8,paftools.js} .
export PATH="$PATH:"`pwd`                               # put the current directory on PATH

# download example datasets
curl -L https://github.com/lh3/minimap2/releases/download/v2.10/cookbook-data.tgz | tar zxf -

Precompiled Binaries (x86-64 Linux)

You can download and extract precompiled binaries using curl and tar:

curl -L https://github.com/lh3/minimap2/releases/download/v2.31/minimap2-2.31_x64-linux.tar.bz2 | tar -jxvf -
./minimap2-2.31_x64-linux/minimap2

Compiling from Source

Requires a C compiler, GNU make, and zlib development files.

• Standard build: make
• Disable SSE4 (slower): make sse2only=1 (useful if compilation errors occur)
• 32-bit ARM (e.g., ARMv7): make arm_neon=1
• 64-bit ARM (e.g., ARMv8): make arm_neon=1 aarch64=1
• Using SIMDe (for various SIMD instruction sets): make -f Makefile.simde (combine with ARM flags as needed)

Use the asm20 preset for cross-species alignment where divergence is up to 10%.

Presets available:

• asm5: divergence < 1%
• asm10: divergence ~2%
• asm20: divergence < 10%

To call variants from the alignment, pipe the sorted PAF output to paftools.js call.

Use the ava presets to find overlaps within the same dataset for assembly.

• For PacBio: use ava-pb.
• For Nanopore: use ava-ont. It is recommended to set a minimum overlap length with -r (e.g., -r 10000) to improve contiguity.