minimap2 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad687f9f6addf8de0a913d8b3b230539a42f76ce32f77b24576dda10118e3a07
-  data.tar.gz: 853c9994378f2441ad9dbaff0966a97812a3f7708a5b6516391d150f9c70b558
+  metadata.gz: '09e4267638f072ee219b2af3ef1afd3938c3a6d02f5370aa9454b25b871652b7'
+  data.tar.gz: ab035c12eb6d6bda353ffab1b5f5923ec8327fea9a4552259b01b02523b7f934
 SHA512:
-  metadata.gz: 916210eb2b7ab42f1d81cc9873f6bfa5ca2c9b1084ba63c9dc62f6301c54940115fc36e5b2fc63afbec33a60a18fb632bb8ae3e533009a4b47de619d7a026321
-  data.tar.gz: 82435ffd47931e66ab1b99c6d85b2d8413d6cf9fb3152f984857b708e988f09b96a4380ae37d76f3f90c5a10a5300c7b891adc0d161dff4414d6aa2d277b1fc7
+  metadata.gz: 8f24c1f2d8e07e1be825fbc2a67049d378c1e1d5f3d23312d474e796fa7968b7d85b58b061226dbf4a14e637c27708667a5737da246e4874f03cadf9df4f013e
+  data.tar.gz: 5e92b4c08e02416b0385c9a5a6b6c7b46381469ae70447fea80a9269a06e1ac11155a06de3d3a4a97995880f542d8adf9cd6063afa2c133be474644dd6d3245f

data/README.md

@@ -1,28 +1,33 @@
 # 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)
+[![The MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Docs Latest](https://img.shields.io/badge/docs-stable-blue.svg)](https://rubydoc.info/gems/minimap2)
 
 :dna: [minimap2](https://github.com/lh3/minimap2) - the long-read mapper - for [Ruby](https://github.com/ruby/ruby)
 
 ## Installation
 
-You need to install it 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. 
+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. 
+
+Build
 
 ```sh
 git clone --recurse-submodules https://github.com/kojix2/ruby-minimap2
 cd ruby-minimap2
 bundle install
 bundle exec rake minimap2:build
-bundle exec rake install
 ```
 
-You can run tests to see if the installation was successful. 
+Install
 
 ```
-bundle exec rake test
+bundle exec rake install
 ```
 
+Ruby-minimap2 is tested on Ubuntu and macOS. 
+
 ## Quick Start
 
 ```ruby
@@ -37,40 +42,115 @@ seq = aligner.seq("MT_human", 100, 200)
 # mapping
 aligner.align(seq) do |h|
   pp h.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"}
 end
 ```
 
-## APIs
+## APIs Overview
 
-See
-* [Mappy: Minimap2 Python Binding](https://github.com/lh3/minimap2/tree/master/python)
+See the [RubyDoc.info document](https://rubydoc.info/gems/minimap2) for details.
 
 ```markdown
 * Minimap2 module
+  - fastx_read
+  - revcomp
+
   * Aligner class
+    * attributes
+      - index
+      - idx_opt
+      - map_opt
+    * methods
+      - new(path, preset: nil)
+      - align
+
   * 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
+    * methods
+      - to_h
+      - to_s
+
+  * FFI module
+    * IdxOpt class
+    * MapOpt class
 ```
 
+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.
+
+* [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, which also provides a way to access some C structs such as IdxOpt and MapOpt.
+
 ## Development
 
+Fork your repository and clone.
+
 ```sh
 git clone --recurse-submodules https://github.com/kojix2/ruby-minimap2
 # git clone https://github.com/kojix2/ruby-minimap2
 # cd ruby-minimap2
 # git submodule update -i
+```
+
+Build.
+
+```sh
 cd ruby-minimap2
-bundle install
+bundle install # Install dependent packages including Ruby-FFI
 bundle exec rake minimap2:build
+```
+
+Run tests.
+
+```
 bundle exec rake test
 ```
 
 ## Contributing
 
-ruby-minimap2 is a library under development and there are many points to be improved. 
-If you improve the source code, please feel free to send us your pull request. 
-Typo corrections are also welcome. 
+ruby-minimap2 is a library under development and there are many points to be improved. Please feel free to send us your pull request. 
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kojix2/ruby-minimap2.
+* [Report bugs](https://github.com/kojix2/ruby-minimap2/issues)
+* Fix bugs and [submit pull requests](https://github.com/kojix2/ruby-minimap2/pulls)
+* Write, clarify, or fix documentation
+* Suggest or add new features
+* Create tools based on ruby-minimap2
+* Update minimap2 in github submodule
 
 ## License
 

data/lib/minimap2.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 # dependencies
-require "ffi"
+require 'ffi'
 
 # bit fields
-require_relative "minimap2/ffi_helper"
+require_relative 'minimap2/ffi_helper'
 
 # modules
-require_relative "minimap2/aligner"
-require_relative "minimap2/alignment"
-require_relative "minimap2/version"
+require_relative 'minimap2/aligner'
+require_relative 'minimap2/alignment'
+require_relative 'minimap2/version'
 
 # Minimap2 mapper for long read sequences
 # https://github.com/lh3/minimap2
@@ -22,15 +22,15 @@ module Minimap2
     attr_accessor :ffi_lib
   end
 
-  lib_name = ::FFI.map_library_name("minimap2")
-  self.ffi_lib = if ENV["MINIMAPDIR"]
-                   File.expand_path(lib_name, ENV["MINIMAPDIR"])
+  lib_name = ::FFI.map_library_name('minimap2')
+  self.ffi_lib = if ENV['MINIMAPDIR']
+                   File.expand_path(lib_name, ENV['MINIMAPDIR'])
                  else
                    File.expand_path("../vendor/#{lib_name}", __dir__)
                  end
 
   # friendlier error message
-  autoload :FFI, "minimap2/ffi"
+  autoload :FFI, 'minimap2/ffi'
 
   # methods from mappy
   class << self

data/lib/minimap2/aligner.rb

@@ -2,10 +2,34 @@
 
 module Minimap2
   class Aligner
-    attr_reader :index_options, :map_options, :index
+    attr_reader :idx_opt, :map_opt, :index
+
+    # 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.
+    # @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.
+    # @param min_chain_score [Integer] minimum chaing score.
+    # @param min_dp_score
+    # @param bw [Integer] chaining and alignment band width.
+    # @param best_n [Integer] max number of alignments to return.
+    # @param n_threads [Integer] number of indexing threads.
+    # @param fn_idx_out [String] name of file to which the index is written.
+    #   This parameter has no effect if seq is set.
+    # @param max_frag_len [Integer]
+    # @param extra_flags [Integer] additional flags defined in minimap.h.
+    # @param scoring [Array] scoring system.
+    #   It is a tuple/list consisting of 4, 6 or 7 positive integers.
+    #   The first 4 elements specify match scoring, mismatch penalty, gap open and gap extension penalty.
+    #   The 5th and 6th elements, if present, set long-gap open and long-gap extension penalty.
+    #   The 7th sets a mismatch penalty involving ambiguous bases.
 
     def initialize(
-      fn_idx_in, # FIXME
+      fn_idx_in = nil,
+      seq: nil,
       preset: nil,
       k: nil,
       w: nil,
@@ -18,76 +42,81 @@ module Minimap2
       fn_idx_out: nil,
       max_frag_len: nil,
       extra_flags: nil,
-      seq: nil,
       scoring: nil
     )
 
-      @index_options = FFI::IdxOpt.new
-      @map_options = FFI::MapOpt.new
+      @idx_opt = FFI::IdxOpt.new
+      @map_opt = FFI::MapOpt.new
 
-      if preset
-        FFI.mm_set_opt(preset, index_options, map_options)
-      else
-        # set the default options
-        FFI.mm_set_opt(0, index_options, map_options)
-      end
+      r = FFI.mm_set_opt(preset, idx_opt, map_opt)
+      raise ArgumentError, "Unknown preset name: #{preset}" if r == -1
 
       # always perform alignment
-      map_options[:flag] |= 4
-      index_options[:batch_size] = 0x7fffffffffffffff
+      map_opt[:flag] |= 4
+      idx_opt[:batch_size] = 0x7fffffffffffffff
 
       # override preset options
-      index_options[:k] = k if k
-      index_options[:w] = w if w
-      map_options[:min_cnt] = min_cnt if min_cnt
-      map_options[:min_chain_score] = min_chain_score if min_chain_score
-      map_options[:min_dp_max] = min_dp_score if min_dp_score
-      map_options[:bw] = bw if bw
-      map_options[:best_n] = best_n if best_n
-      map_options[:max_frag_len] = max_frag_len if max_frag_len
-      map_options[:flag] |= extra_flags if extra_flags
+      idx_opt[:k] = k if k
+      idx_opt[:w] = w if w
+      map_opt[:min_cnt] = min_cnt if min_cnt
+      map_opt[:min_chain_score] = min_chain_score if min_chain_score
+      map_opt[:min_dp_max] = min_dp_score if min_dp_score
+      map_opt[:bw] = bw if bw
+      map_opt[:best_n] = best_n if best_n
+      map_opt[:max_frag_len] = max_frag_len if max_frag_len
+      map_opt[:flag] |= extra_flags if extra_flags
       if scoring && scoring.size >= 4
-        map_options[:a] = scoring[0]
-        map_options[:b] = scoring[1]
-        map_options[:q] = scoring[2]
-        map_options[:e] = scoring[3]
-        map_options[:q2] = map_options.q
-        map_options[:e2] = map_options.e
+        map_opt[:a] = scoring[0]
+        map_opt[:b] = scoring[1]
+        map_opt[:q] = scoring[2]
+        map_opt[:e] = scoring[3]
+        map_opt[:q2] = map_opt.q
+        map_opt[:e2] = map_opt.e
         if scoring.size >= 6
-          map_options[:q2] = scoring[4]
-          map_options[:e2] = scoring[5]
-          map_options[:sc_ambi] = scoring[6] if scoring.size >= 7
+          map_opt[:q2] = scoring[4]
+          map_opt[:e2] = scoring[5]
+          map_opt[:sc_ambi] = scoring[6] if scoring.size >= 7
         end
       end
 
-      if seq
-        @index = FFI.mappy_idx_seq(
-          index_options.w, index_options.k, index_options & 1,
-          index_options.bucket_bits, seq, seq.size
-        )
-        FFI.mm_mapopt_update(map_options, index)
-        map_options.mid_occ = 1000 # don't filter high-occ seeds
-      else
-        reader = FFI.mm_idx_reader_open(fn_idx_in, index_options, fn_idx_out)
+      if fn_idx_in
+        warn "Since fn_idx_in is specified, the seq argument will be ignored." if seq
+        reader = FFI.mm_idx_reader_open(fn_idx_in, idx_opt, fn_idx_out)
 
         # The Ruby version raises an error here
         raise "Cannot open : #{fn_idx_in}" if reader.null?
 
         @index = FFI.mm_idx_reader_read(reader, n_threads)
         FFI.mm_idx_reader_close(reader)
-        FFI.mm_mapopt_update(map_options, index)
+        FFI.mm_mapopt_update(map_opt, index)
         FFI.mm_idx_index_name(index)
+      elsif seq
+        @index = FFI.mappy_idx_seq(
+          idx_opt[:w], idx_opt[:k], idx_opt[:flag] & 1,
+          idx_opt[:bucket_bits], seq, seq.size
+        )
+        FFI.mm_mapopt_update(map_opt, index)
+        map_opt[:mid_occ] = 1000 # don't filter high-occ seeds
       end
     end
 
-    # FIXME: naming
-    def destroy
+    # Explicitly releases the memory of the index object.
+    def free_index
       FFI.mm_idx_destroy(index) unless index.null?
     end
 
-    # NOTE: Name change: map -> align
-    # In the Ruby language, the name map means iterator.
-    # The original name is map, but here I use the method name align.
+    # @param seq [String]
+    # @param seq2 [String]
+    # @param buf [FFI::TBuf]
+    # @param cs [true, false]
+    # @param md [true, false]
+    # @param max_frag_len [Integer]
+    # @param extra_flags [Integer]
+    # @note Name change: map -> align
+    #   In the Ruby language, the name map means iterator.
+    #   The original name is map, but here I use the method name align.
+    # @note The use of Enumerator is being considered. The method names may change again.
+
     def align(
       seq, seq2 = nil,
       buf: nil,
@@ -99,14 +128,14 @@ module Minimap2
 
       return if index.null?
 
-      map_options.max_frag_len = max_frag_len if max_frag_len
-      map_options.flag |= extra_flags if extra_flags
+      map_opt.max_frag_len = max_frag_len if max_frag_len
+      map_opt.flag |= extra_flags if extra_flags
 
       buf ||= FFI::TBuf.new
       km = FFI.mm_tbuf_get_km(buf)
       n_regs_ptr = ::FFI::MemoryPointer.new :int
 
-      ptr = FFI.mm_map_aux(index, seq, seq2, n_regs_ptr, buf, map_options)
+      ptr = FFI.mm_map_aux(index, seq, seq2, n_regs_ptr, buf, map_opt)
       n_regs = n_regs_ptr.read_int
 
       regs = Array.new(n_regs) { |i| FFI::Reg1.new(ptr + i * FFI::Reg1.size) }
@@ -124,13 +153,13 @@ module Minimap2
           # convert the 32-bit CIGAR encoding to Ruby array
           cigar = c.map { |x| [x >> 4, x & 0xf] }
 
-          _cs = ""
+          _cs = ''
           if cs
             l_cs_str = FFI.mm_gen_cs(km, cs_str, m_cs_str, @index, regs[i], seq, 1)
             _cs = cs_str.read_pointer.read_string(l_cs_str)
           end
 
-          _md = ""
+          _md = ''
           if md
             l_cs_str = FFI.mm_gen_md(km, cs_str, m_cs_str, @index, regs[i], seq)
             _md = cs_str.read_pointer.read_string(l_cs_str)
@@ -149,6 +178,11 @@ module Minimap2
       end
     end
 
+    # retrieve a subsequence from the index.
+    # @params name
+    # @params start
+    # @params stop
+
     def seq(name, start = 0, stop = 0x7fffffff)
       lp = ::FFI::MemoryPointer.new(:int)
       s = FFI.mappy_fetch_seq(index, name, start, stop, lp)
@@ -158,10 +192,12 @@ module Minimap2
       s.read_string(l)
     end
 
+    # k-mer length, no larger than 28
     def k
       index[:k]
     end
 
+    # minimizer window size, no larger than 255
     def w
       index[:w]
     end

data/lib/minimap2/alignment.rb

@@ -1,13 +1,57 @@
 # frozen_string_literal: true
 
 module Minimap2
+  # Alignment result
+  #
+  # @!attribute ctg
+  #   @return [String] name of the reference sequence the query is mapped to.
+  # @!attribute ctg_len
+  #   @return [Integer] total length of the reference sequence.
+  # @!attribute r_st
+  #   @return [Integer] start positions on the reference.
+  # @!attribute r_en
+  #   @return [Integer] end positions on the reference.
+  # @!attribute strand
+  #   @return [Integer] +1 if on the forward strand; -1 if on the reverse strand.
+  # @!attribute trans_strand
+  #   @return [Integer] transcript strand.
+  #     +1 if on the forward strand; -1 if on the reverse strand; 0 if unknown.
+  # @!attribute blen
+  #   @return [Integer] length of the alignment, including both alignment matches and gaps
+  #      but excluding ambiguous bases.
+  # @!attribute mlen
+  #   @return [Integer] length of the matching bases in the alignment,
+  #     excluding ambiguous base matches.
+  # @!attribute nm
+  #   @return [Integer] number of mismatches, gaps and ambiguous poistions in the alignment.
+  # @!attribute primary
+  #   @return [Integer] if the alignment is primary (typically the best and the first to generate)
+  # @!attribute q_st
+  #   @return [Integer] start positions on the query.
+  # @!attribute q_en
+  #   @return [Integer] end positions on the query.
+  # @!attribute mapq
+  #   @return [Integer] mapping quality.
+  # @!attribute cigar
+  #   @return [Array] CIGAR returned as an array of shape (n_cigar,2).
+  #     The two numbers give the length and the operator of each CIGAR operation.
+  # @!attribute read_num
+  #   @return [Integer] read number that the alignment corresponds to;
+  #     1 for the first read and 2 for the second read.
+  # @!attribute cs
+  #   @return [String] the cs tag.
+  # @!attribute md
+  #   @return [String] the MD tag as in the SAM format.
+  #     It is an empty string unless the md argument is applied when calling Aligner#align.
+  # @!attribute cigar_str
+  #   @return [String] CIGAR string.
+
   class Alignment
     def self.keys
       %i[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]
     end
 
-    # Read only
     attr_reader(*keys)
 
     def initialize(h, cigar, cs = nil, md = nil)
@@ -29,7 +73,7 @@ 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 + 'MIDNSH'[x[1]] }.join
     end
 
     def primary?
@@ -42,19 +86,19 @@ module Minimap2
 
     def to_s
       strand = if @strand.positive?
-                 "+"
+                 '+'
                elsif @strand.negative?
-                 "-"
+                 '-'
                else
-                 "?"
+                 '?'
                end
-      tp = @primary != 0 ? "tp:A:P" : "tp:A:S"
+      tp = @primary != 0 ? 'tp:A:P' : 'tp:A:S'
       ts = if @trans_strand.positive?
-             "ts:A:+"
+             'ts:A:+'
            elsif @trans_strand.negative?
-             "ts:A:-"
+             'ts:A:-'
            else
-             "ts:A:."
+             'ts:A:.'
            end
       a = [@q_st, @q_en, strand, @ctg, @ctg_len, @r_st, @r_en,
            @mlen, @blen, @mapq, tp, ts, "cg:Z:#{@cigar_str}"]

data/lib/minimap2/ffi.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # bit fields
-require_relative "ffi_helper"
+require_relative 'ffi_helper'
 
 module Minimap2
   # Native APIs
@@ -22,6 +22,6 @@ module Minimap2
   end
 end
 
-require_relative "ffi/constants"
-require_relative "ffi/functions"
-require_relative "ffi/mappy"
+require_relative 'ffi/constants'
+require_relative 'ffi/functions'
+require_relative 'ffi/mappy'

data/lib/minimap2/ffi/functions.rb

@@ -6,15 +6,15 @@ module Minimap2
       :mm_set_opt_raw, :mm_set_opt,
       [:pointer, IdxOpt.by_ref, MapOpt.by_ref],
       :int
-    
+
     private_class_method :mm_set_opt_raw
-    
+
     def self.mm_set_opt(preset, io, mo)
-      if preset == 0
-        ptr = ::FFI::Pointer.new(:int, 0)
-      else
-        ptr = ::FFI::MemoryPointer.from_string(preset.to_s)
-      end
+      ptr = if preset
+              ::FFI::MemoryPointer.from_string(preset.to_s)
+            else
+              ::FFI::Pointer.new(:int, 0)
+            end
       mm_set_opt_raw(ptr, io, mo)
     end
 

data/lib/minimap2/ffi/mappy.rb

@@ -38,7 +38,7 @@ module Minimap2
         :seq,            KString,
         :qual,           KString,
         :last_char,      :int,
-        :f,              :pointer # FIXME: KStream
+        :f,              :pointer # KStream
     end
 
     attach_function \
@@ -88,7 +88,7 @@ module Minimap2
 
     attach_function \
       :mappy_idx_seq,
-      %i[int int int int pointer int],
+      %i[int int int int string int],
       Idx.by_ref
 
     attach_function \

data/lib/minimap2/ffi_helper.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "ffi"
+require 'ffi'
 
 module FFI
   class BitStruct < Struct

data/lib/minimap2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Minimap2
-  VERSION = "0.0.1"
+  VERSION = '0.0.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minimap2
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - kojix2
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-04 00:00:00.000000000 Z
+date: 2021-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -112,7 +112,6 @@ 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