minimap2 0.0.4 → 0.2.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ef413b53423059804163320f8d5cd9ca0366fa7473603b06a857c109b99395
-  data.tar.gz: 64cdc52d1961e793f9dc0a966c9f63f357aa3992c4cf8f3341d1cd64c0eea01a
+  metadata.gz: 4bd850f529cb82950c16581735bdd74f232e0ef3490e5cb5b6f7045faa1fe696
+  data.tar.gz: 40d00cf14886a35f831b593d541cf9e72f8e5cf07d87be31116c215799449f62
 SHA512:
-  metadata.gz: cf3a7c4294279f7a79a6f931f50c243f72b17658a69f4e6eec13e8584b61d503a6da164be3b01ca81cb52679d893efd903ac41387ec418f43c016e392d027ed4
-  data.tar.gz: 4cac45c87e639ec4b698990e80e9a64aad902a368f44e35223a31ce162eeafa46137b06faa99b345f8e57a99cce4b9e39bb2959dd29d8a5c09d746439431df21
+  metadata.gz: 669bd6d5a4eb0dc37f12ee4c0f9653bfe76afec70b8d592e291269cb97b90b493b398b8d68ebacb64ba2ce28187a32a32fdb3fb77ef070023ffa27983f479929
+  data.tar.gz: 12c2fd1ace06a7e6a1734cb27f09091851f3fe917714156b27a003a168815dbef83eabc00c56c701bdcd5f982db873346bca375b3e8f05764b7fb797d2d5c898

data/README.md

@@ -1,4 +1,4 @@
-# Minimap2
+# ruby-minimap2
 
 [![Gem Version](https://img.shields.io/gem/v/minimap2?color=brightgreen)](https://rubygems.org/gems/minimap2)
 [![CI](https://github.com/kojix2/ruby-minimap2/workflows/CI/badge.svg)](https://github.com/kojix2/ruby-minimap2/actions)
@@ -12,7 +12,7 @@
 
 ## Installation
 
-You need to install ruby-minimap2 from the source code. Because you need to build minimap2 and create a shared library. Open your terminal and type the following commands in order. 
+Open your terminal and type the following commands in order. You need to build minimap2 on your own because you need to create a shared library that contains cmappy functions.
 
 Build
 
@@ -29,7 +29,7 @@ Install
 bundle exec rake install
 ```
 
-Ruby-minimap2 is tested on Ubuntu and macOS. 
+Ruby-minimap2 is [tested on Ubuntu and macOS](https://github.com/kojix2/ruby-minimap2/actions). 
 
 ## Quick Start
 
@@ -37,99 +37,119 @@ Ruby-minimap2 is tested on Ubuntu and macOS.
 require "minimap2"
 ```
 
-create aligner
+Create aligner
 
 ```ruby
 aligner = Minimap2::Aligner.new("minimap2/test/MT-human.fa")
 ```
 
-retrieve a subsequence from the index
+Retrieve a subsequence from the index
 
 ```ruby
 seq = aligner.seq("MT_human", 100, 200)
 ```
 
-mapping
+Mapping
 
 ```ruby
 hits = aligner.align(seq)
-pp hits[0].to_h
-# {:ctg          => "MT_human",
-#  :ctg_len      => 16569,
-#  :r_st         => 100,
-#  :r_en         => 200,
-#  :strand       => 1,
-#  :trans_strand => 0,
-#  :blen         => 100,
-#  :mlen         => 100,
-#  :nm           => 0,
-#  :primary      => 1,
-#  :q_st         => 0,
-#  :q_en         => 100,
-#  :mapq         => 60,
-#  :cigar        => [[100, 0]],
-#  :read_num     => 1,
-#  :cs           => "",
-#  :md           => "",
-#  :cigar_str    => "100M"}
+pp hits[0]
+```
+
+```
+=> 
+#<Minimap2::Alignment:0x000055fe18223f50
+ @blen=100,
+ @cigar=[[100, 0]],
+ @cigar_str="100M",
+ @cs="",
+ @ctg="MT_human",
+ @ctg_len=16569,
+ @mapq=60,
+ @md="",
+ @mlen=100,
+ @nm=0,
+ @primary=1,
+ @q_en=100,
+ @q_st=0,
+ @r_en=200,
+ @r_st=100,
+ @read_num=1,
+ @strand=1,
+ @trans_strand=0>
 ```
 
 ## APIs Overview
 
-See the [RubyDoc.info document](https://rubydoc.info/gems/minimap2) for details.
+API is based on [Mappy](https://github.com/lh3/minimap2/tree/master/python), the official Python binding for Minimap2. 
+
+Note: `Aligner#map` has been changed to `aligne`, because `map` means iterator in Ruby.
 
 ```markdown
 * Minimap2 module
-  - fastx_read
-  - revcomp
+  - fastx_read                  Read fasta/fastq file.
+  - revcomp                     Reverse complement sequence.
 
   * Aligner class
     * attributes
-      - index
-      - idx_opt
-      - map_opt
+      - index                   Returns the value of attribute index.
+      - idx_opt                 Returns the value of attribute idx_opt.
+      - map_opt                 Returns the value of attribute map_opt.
     * methods
-      - new(path, preset: nil)
-      - align
+      - new(path, preset: nil)  Create a new aligner. (presets: sr, map-pb, map-out, map-hifi, splice, asm5, etc.)
+      - align                   Maps and returns alignments.
+      - seq                     Retrieve a subsequence from the index.
 
   * Alignment class
     * attributes
-      - ctg
-      - ctg_len
-      - r_st
-      - r_en
-      - strand
-      - trans_strand
-      - blen
-      - mlen
-      - nm
-      - primary
-      - q_st
-      - q_en
-      - mapq
-      - cigar
-      - read_num
-      - cs
-      - md
-      - cigar_str
+      - ctg                     Returns name of the reference sequence the query is mapped to.
+      - ctg_len                 Returns total length of the reference sequence.
+      - r_st                    Returns start positions on the reference.
+      - r_en                    Returns end positions on the reference.
+      - strand                  Returns +1 if on the forward strand; -1 if on the reverse strand.
+      - trans_strand            Returns transcript strand. +1 if on the forward strand; -1 if on the reverse strand; 0 if unknown.
+      - blen                    Returns length of the alignment, including both alignment matches and gaps but excluding ambiguous bases.
+      - mlen                    Returns length of the matching bases in the alignment, excluding ambiguous base matches.
+      - nm                      Returns number of mismatches, gaps and ambiguous poistions in the alignment.
+      - primary                 Returns if the alignment is primary (typically the best and the first to generate).
+      - q_st                    Returns start positions on the query.
+      - q_en                    Returns end positions on the query.
+      - mapq                    Returns mapping quality.
+      - cigar                   Returns CIGAR returned as an array of shape (n_cigar,2). The two numbers give the length and the operator of each CIGAR operation.
+      - read_num                Returns read number that the alignment corresponds to; 1 for the first read and 2 for the second read.
+      - cs                      Returns the cs tag.
+      - md                      Returns the MD tag as in the SAM format. It is an empty string unless the md argument is applied when calling Aligner#align.
+      - cigar_str               Returns CIGAR string.
     * methods
-      - to_h
-      - to_s
+      - to_h                    Convert Alignment to hash.
+      - to_s                    Convert to the PAF format without the QueryName and QueryLength columns.
 
-  * FFI module
-    * IdxOpt class
-    * MapOpt class
+  ## FFI module
+    * IdxOpt class              Indexing options.
+    * MapOpt class              Mapping options.
 ```
 
-The ruby-minimap2 API is compliant with mappy, the official Python binding for Minimap2. However, there are a few differences. For example, the `map` method has been renamed to `align` since map is the common name for iterators in Ruby.
+This is not all. See the [RubyDoc.info documentation](https://rubydoc.info/gems/minimap2/) for more details.
 
-* [Mappy: Minimap2 Python Binding](https://github.com/lh3/minimap2/tree/master/python)
+ruby-minimap2 is built on top of [Ruby-FFI](https://github.com/ffi/ffi). 
+Native functions can be called from the FFI module. FFI also provides the way to access some C structs.
 
-ruby-minimap2 is built on top of [Ruby-FFI](https://github.com/ffi/ffi). Native functions can be called from the FFI module, which also provides a way to access some C structs such as IdxOpt and MapOpt.
+```ruby
+aligner.idx_opt.members
+# => [:k, :w, :flag, :bucket_bits, :mini_batch_size, :batch_size]
+aligner.kds_opt.values
+# => [15, 10, 0, 14, 50000000, 9223372036854775807]
+aligner.idx_opt[:k]
+# => 15
+aligner.idx_opt[:k] = 14
+aligner.idx_opt[:k]
+# => 14
+```
 
 ## Development
 
-Fork your repository and clone.
+Fork your repository.
+then clone.
 
 ```sh
 git clone --recursive https://github.com/kojix2/ruby-minimap2
@@ -138,7 +158,7 @@ git clone --recursive https://github.com/kojix2/ruby-minimap2
 # git submodule update -i
 ```
 
-Build.
+Build Minimap2 and Mappy.
 
 ```sh
 cd ruby-minimap2
@@ -146,6 +166,13 @@ bundle install # Install dependent packages including Ruby-FFI
 bundle exec rake minimap2:build
 ```
 
+A shared library will be created in the vendor directory.
+
+```
+└── vendor
+   └── libminimap2.so
+```
+
 Run tests.
 
 ```
@@ -166,3 +193,7 @@ ruby-minimap2 is a library under development and there are many points to be imp
 ## License
 
 [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgements
+
+I would like to thank Heng Li for making Minimap2, and all the readers who read the README to the end.

data/lib/minimap2.rb

@@ -34,7 +34,7 @@ module Minimap2
 
   # methods from mappy
   class << self
-    # read fasta/fastq file
+    # Read fasta/fastq file.
     # @param [String] file_path
     # @param [Boolean] read_comment If false or nil, the comment will not be read.
     # @yield [name, seq, qual, comment]
@@ -57,7 +57,7 @@ module Minimap2
       FFI.mm_fastx_close(ks)
     end
 
-    # reverse complement sequence
+    # Reverse complement sequence.
     # @param [String] seq
     # @return [string] seq
 
@@ -68,7 +68,7 @@ module Minimap2
       FFI.mappy_revcomp(l, bseq)
     end
 
-    # set verbosity level
+    # Set verbosity level.
     # @param [Integer] level
 
     def verbose(level = -1)

data/lib/minimap2/aligner.rb

@@ -4,11 +4,21 @@ module Minimap2
   class Aligner
     attr_reader :idx_opt, :map_opt, :index
 
-    # Create a new aligner
+    # Create a new aligner.
     #
     # @param fn_idx_in [String] index or sequence file name.
     # @param seq [String] a single sequence to index.
     # @param preset [String] minimap2 preset.
+    #   * map-pb : PacBio CLR genomic reads
+    #   * map-ont : Oxford Nanopore genomic reads
+    #   * map-hifi : PacBio HiFi/CCS genomic reads (v2.19 or later)
+    #   * asm20 : PacBio HiFi/CCS genomic reads (v2.18 or earlier)
+    #   * sr : short genomic paired-end reads
+    #   * splice : spliced long reads (strand unknown)
+    #   * splice:hq : Final PacBio Iso-seq or traditional cDNA
+    #   * asm5 : intra-species asm-to-asm alignment
+    #   * ava-pb : PacBio read overlap
+    #   * ava-ont : Nanopore read overlap
     # @param k [Integer] k-mer length, no larger than 28.
     # @param w [Integer] minimizer window size, no larger than 255.
     # @param min_cnt [Integer] mininum number of minimizers on a chain.
@@ -101,6 +111,7 @@ module Minimap2
     end
 
     # Explicitly releases the memory of the index object.
+
     def free_index
       FFI.mm_idx_destroy(index) unless index.null?
     end
@@ -184,10 +195,10 @@ module Minimap2
       alignments
     end
 
-    # retrieve a subsequence from the index.
-    # @params name
-    # @params start
-    # @params stop
+    # Retrieve a subsequence from the index.
+    # @param name
+    # @param start
+    # @param stop
 
     def seq(name, start = 0, stop = 0x7fffffff)
       lp = ::FFI::MemoryPointer.new(:int)

data/lib/minimap2/alignment.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Minimap2
-  # Alignment result
+  # Alignment result.
   #
   # @!attribute ctg
   #   @return [String] name of the reference sequence the query is mapped to.
@@ -73,17 +73,21 @@ module Minimap2
       @cs           = cs
       @md           = md
 
-      @cigar_str = cigar.map { |x| x[0].to_s + 'MIDNSH'[x[1]] }.join
+      @cigar_str = cigar.map { |x| x[0].to_s + FFI::CIGAR_STR[x[1]] }.join
     end
 
     def primary?
       @primary == 1
     end
 
+    # Convert Alignment to hash.
+
     def to_h
       self.class.keys.map { |k| [k, __send__(k)] }.to_h
     end
 
+    # Convert to the PAF format without the QueryName and QueryLength columns.
+
     def to_s
       strand = if @strand.positive?
                  '+'

data/lib/minimap2/ffi/constants.rb

@@ -34,6 +34,7 @@ module Minimap2
     NO_END_FLT     = 0x10000000
     HARD_MLEVEL    = 0x20000000
     SAM_HIT_ONLY   = 0x40000000
+    RMQ            = 0x80000000 # LL
 
     HPC            = 0x1
     NO_SEQ         = 0x2
@@ -43,6 +44,8 @@ module Minimap2
 
     MAX_SEG        = 255
 
+    CIGAR_STR      = 'MIDNSHP=XB'
+
     # emulate 128-bit integers
     class MM128 < ::FFI::Struct
       layout \

data/lib/minimap2/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Minimap2
-  VERSION = '0.0.4'
+  # Minimap2-2.21 (r1071).
+  VERSION = '0.2.21'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minimap2
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.2.21
 platform: ruby
 authors:
 - kojix2
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-27 00:00:00.000000000 Z
+date: 2021-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -112,6 +112,7 @@ files:
 - lib/minimap2/ffi/mappy.rb
 - lib/minimap2/ffi_helper.rb
 - lib/minimap2/version.rb
+- vendor/libminimap2.so
 homepage: https://github.com/kojix2/ruby-minimap2
 licenses:
 - MIT