Repository files navigation

A rust FFI library forminimap2. In development! Feedback appreciated!

minimap2-sys is the raw FFI bindings to minimap2. minimap2 is the more opinionated, rusty version.

minimap2 ="0.1.23+minimap2.2.28"

Also seeFeatures

Tested with rustc 1.82.0 and nightly. So probably a good idea to upgrade before running. But let me know if you run into pain points with older versions and will try to fix.

Create an Aligner

letmut aligner =Aligner::builder().map_ont().with_threads(8).with_cigar().with_index("ReferenceFile.fasta",None).expect("Unable to build index");

Align a sequence:

let seq:Vec<u8> =b"ACTGACTCACATCGACTACGACTACTAGACACTAGACTATCGACTACTGACATCGA";let alignment = aligner.map(&seq,false,false,None,None,Some(b"My Sequence Name")).expect("Unable to align");

All minimap2 presets should be available (seefunctions section):

let aligner =map_ont();let aligner =asm20();

Note Each preset overwrites different arguments. Using multiple at a time is not technically supported, but will work. Results unknown. So be careful!It's equivalent to running minimap2 -x map_ont -x short ...

MapOpts andIdxOpts can be customized with Rust's struct pattern, as well as applying mapping settings. Inspired bybevy.

letmut aligner:Aligner<PresetSet> =Aligner::builder().map_ont();aligner.mapopt.seed =42;aligner.mapopt.best_n =1;aligner.idxopt.k =21;self.mapopt.flag |=MM_F_COPY_COMMENTasi64;// Setting a flag. If you do this frequently, open an [issue](https://github.com/jguhlin/minimap2-rs/issues/new) asking for an ergonomic function!self.idxopt.flag |=MM_I_HPCasi32;

Seefull list of options below.

There are two working examples directly in this repo. In both instances below, 64 is the number of threads to allocate.

Channel-based multi-threading

cargo run --example channels -- reference_genome.fasta reads.fasta 64

Rayon-based multi-threading

cargo run --example rayon -- reference_genome.fasta reads.fasta 64

Depending on your needs you can probably do just fine with Rayon. But for very large implementations, interactivity, or limited memory, using channels may be the way to go.

There is a binary called "fakeminimap2" which demonstrates basic usage and multithreading using channels or rayon. You can find itin this repo for an example. It it much more fully featured example, with an output interface, some mouse support, and interaction.

Alignment functions return aMapping struct. TheAlignment struct is only returned when theAligner is created using.with_cigar().

A very simple example would be:

letmut file = std::fs::File::open(query_file);letmut reader =BufReader::new(reader);letmut fasta =Fasta::from_buffer(&mut reader)for seqin reader{let seq = seq.unwrap();let alignment:Vec<Mapping> = aligner.map(&seq.sequence.unwrap(),false,false,None,None,None).expect("Unable to align");println!("{:?}", alignment);}

There is a map_file function that works on an entire file, but it is not-lazy and thus not suitable for large files. It may be removed in the future or moved to a separate lib.

let mappings:Result<Vec<Mapping>> = aligner.map_file("query.fa",false,false);

Multithreading is supported, for implementation example seefakeminimap2. Minimap2 also supports threading itself, and will use a minimum of 3 cores for building the index. Multithreading for mapping is left to the end-user.

Adjust the number of threads used to build the index:

letmut aligner =Aligner::builder().map_ont().with_index_threads(8);

Thisappears to work. Seefakeminimap2 for full implementation.

use rayon::prelude::*;let results = sequences.par_iter().map(|seq|{    aligner.map(seq.as_bytes(),false,false,None,None,None).unwrap()}).collect::<Vec<_>>();

Also works. Otherwise directly cloning the aligner will Arc clone the internal index.

The following crate features are available:

• map-file - Enables the ability to map a file directly to a reference. Enabled by deafult
• htslib - Provides an interface to minimap2 that returns rust_htslib::Records
• simde - Enables SIMD Everywhere library in minimap2
• zlib-ng - Enables the use of zlib-ng for faster compression
• curl - Enables curl for htslib
• static - Builds minimap2 as a static library
• sse2only - Builds minimap2 with only SSE2 support

Map-file is adefault feature and enabled unless otherwise specified.

Create anissue if you need any of the following:

• setting mismatch penalty for base transitionsminimap 2.27 release notes
• Generate ds tags to indicate uncertainty in indels

Potentially others. Please create an issue!

Follow theseinstructions.

In brief, using bash shell:

docker pull messense/rust-musl-cross:x86_64-muslalias rust-musl-builder='docker run --rm -it -v "$(pwd)":/home/rust/src messense/rust-musl-cross:x86_64-musl'rust-musl-builder cargo build --release

Minimap2 is tested on x86_64 and aarch64 (arm64). Other platforms may work, please open an issue if minimap2 compiles but minimap2-rs does not.

• htslib -Success
• simde -Success

• Chopper - Long read trimming and filtering
• mappy-rs - Drop-in multi-threaded replacement for python's mappy
• HiFiHLA - HLA star-calling tool for PacBio HiFi data
• STRdust - Tandem repeat genotyper for long reads
• oarfish - transcript quantification from long-read RNA-seq data
• lrge - Long Read-based Genome size Estimation from overlaps

• Iterator interface for map_file
• -sys Possible to decouple from pthread?

Please cite the appropriate minimap2 papers if you use this in your work, as well as this library.

... coming soon ...

Li, H. (2018). Minimap2: pairwise alignment for nucleotide sequences.Bioinformatics,34:3094-3100. [doi:10.1093/bioinformatics/bty191][doi]

and/or:

Li, H. (2021). New strategies to improve minimap2 alignment accuracy.Bioinformatics,37:4572-4574. [doi:10.1093/bioinformatics/btab705][doi2]

Seecustomization for how to use these.

These can be set with helper functions. Please see the docs for IdxOpt and MapOpt.

These can be set with helper functions. Please see the docs for IdxOpt and MapOpt.

SeeCHANGELOG.md