From 798ea0a4a3e327b4e88e9ab9582768012f2fa65c Mon Sep 17 00:00:00 2001 From: Vasimuddin Date: Fri, 26 Nov 2021 08:07:53 -0800 Subject: [PATCH] updated the readme --- README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/README.md b/README.md index 90af282..8aa7b9c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,74 @@ +## mm2-fast +### Introduction +mm2-fast is an accelerated implementation of minimap2 on modern CPUs. mm2-fast accelerates all the three major modules of minimap2: (a) seeding, (b) chaining, and (c) pairwise alignment, achieving up to 3.5x speedup over minimap2. +mm2-fast is a drop-in replacement of minimap2, providing the same functionality with the exact same output. +In the current version, all the modules are optimized using **AVX-512** vectorization. Detailed benchmark results are available in our [preprint](https://doi.org/10.1101/2021.07.21.453294). + +### System requirement +Operating System: Linux +mm2-fast was tested using g++ (GCC) 9.2.0 and icpc version 19.1.3.304 +Architecture: x86\_64 CPUs with [AVX512](https://en.wikipedia.org/wiki/AVX-512) +Memory requirement: ~30GB for human genome + +### Installation +Clone the *fast-contrib-v2.22* branch from minimap2 github page. The source code can be compiled by simple using *make* command. It only takes a few seconds. +``` +git clone --recursive https://github.com/lh3/minimap2.git -b fast-contrib-v2.22 mm2-fast +cd mm2-fast +make +``` + +### Usage +The usage of mm2-fast is same as minimap2. Here is an example of mapping ONT reads with test data. +```sh +./minimap2 -ax map-ont test/MT-human.fa test/MT-orang.fa > mm2-fast_output +``` + +### Accuracy evaluation +As mm2-fast is an accelerated version of minimap2-v2.22, the output of mm2-fast can be verified against minimap2-v2.22. Note that AVX512-based chaining in mm2-fast by default runs with a chaining parameter *max-skip=infinity* for higher chaining precision. Therefore, for correctness verification, minimap2 should run with a larger value of *max-skip* parameter. Follow the below steps to verify the accuracy of mm2-fast. +```sh +git clone https://github.com/lh3/minimap2.git -b v2.22 +cd minimap2 && make +./minimap2 -ax map-ont test/MT-human.fa test/MT-orang.fa --max-chain-skip=1000000 > minimap2_output +``` +The output generated by minimap2 and mm2-fast should match. +```sh +diff minimap2_output mm2-fast_output > diff_result +``` +The file diff\_result should show a clean-diff with the difference of 2 lines, i.e., the lines containing the command-line parameters for minimap2 and mm2-fast. + +### Advanced options +The default compilation using make applies two optimizations: AVX512 vectorized chaining and alignment, and learned-indexes based seeding is disabled by default as it requires availability of [Rust](https://en.wikipedia.org/wiki/Rust_(programming_language)). This is because the learned hash-table uses an external training library that runs on Rust. Rust is trivial to install, see https://rustup.rs/ and add its path to .bashrc file. Rust installation only takes a few seconds. Following are the steps to enable learned hash table optimization in mm2-fast: +```sh +# Start by building learned hash table index for optimized seeding module +./build_rmi.sh test/MT-human.fa map-ont ##Takes two arguments: 1. path-to-reference-seq-file 2. preset. + ##For human genome, this step should take around 20-30 minutes to finish. + +# Next, compile and run the mapping phase +make clean && make lhash=1 +./minimap2 -ax map-ont test/MT-human.fa test/MT-orang.fa > mm2-fast-lhash_output +``` +To compile mm2-fast with all optimizations turned off and switch back to default minimap2, use the following command during compilation. This could be useful for debugging. +```sh +make clean && make no_opt=1 +``` +mm2-fast includes preliminary support for AVX2 architecture. Currently, chaining step is not optimized for AVX2 but the seeding and alignment steps are available. To try mm2-fast on AVX2 systems, use the following command to compile. +```sh +make clean && make lhash=1 use_avx2=1 +``` +### Performance +We have observed up to 1.9x speedup across datasets (please refer to the paper for more details). For example, for the randomly sampled 100K reads from ["HG002\_GM24385\_1\_2\_3\_Guppy\_3.6.0\_prom.fastq.gz"](https://precision.fda.gov/challenges/10/view), minimap2 takes 92 seconds, while mm2-fast takes 54 seconds to map against the human genome on a 28 cores Intel® Xeon® Platinum 8280 CPUs. Our sampled datasets with 100K reads are available [here](https://drive.google.com/drive/folders/1131j7ejHdT7QZnjxLcTLi5qqwYcfFbuv). + +### Future Plans + + +### Citations +["Accelerating long-read analysis on modern CPUs"](https://doi.org/10.1101/2021.07.21.453294); Saurabh Kalikar, Chirag Jain, Vasimuddin Md, Sanchit Misra; BioRxiv 2021 + +--- +The original README content of minimap2 follows. + + [![GitHub Downloads](https://img.shields.io/github/downloads/lh3/minimap2/total.svg?style=social&logo=github&label=Download)](https://github.com/lh3/minimap2/releases) [![BioConda Install](https://img.shields.io/conda/dn/bioconda/minimap2.svg?style=flag&label=BioConda%20install)](https://anaconda.org/bioconda/minimap2) [![PyPI](https://img.shields.io/pypi/v/mappy.svg?style=flat)](https://pypi.python.org/pypi/mappy)