minimap2 0.2.31.0 → 1.2.31.0

data/lib/minimap2/aligner.rb

@@ -1,389 +1,72 @@
 # frozen_string_literal: true
 
 module Minimap2
+  # Builds or loads a minimap2 index and maps sequences against it.
+  #
+  # Calls on the same Aligner are thread-safe and serialized. Different Aligner
+  # instances can map concurrently.
+  #
+  # @!method initialize(path = nil, seq: nil, preset: nil, k: nil, w: nil, min_cnt: nil, min_chain_score: nil, min_dp_score: nil, bw: nil, bw_long: nil, best_n: nil, n_threads: 3, fn_idx_out: nil, max_frag_len: nil, extra_flags: nil, scoring: nil, sc_ambi: nil, max_chain_skip: nil, batch_size: nil)
+  #   Creates an aligner from a FASTA/FASTQ/index file or one in-memory sequence.
+  #   @param path [String, nil] sequence or index file
+  #   @param seq [String, nil] single sequence to index when path is nil
+  #   @param preset [String, Symbol, nil] minimap2 preset such as map-ont, map-pb, map-hifi, sr, splice, or asm5
+  #   @param k [Integer, nil] k-mer length in the range 1..28
+  #   @param w [Integer, nil] minimizer window size in the range 1..255
+  #   @param min_cnt [Integer, nil] minimum number of minimizers on a chain
+  #   @param min_chain_score [Integer, nil] minimum chaining score
+  #   @param min_dp_score [Integer, nil] minimum DP alignment score
+  #   @param bw [Integer, nil] chaining and alignment bandwidth
+  #   @param bw_long [Integer, nil] bandwidth for long-gap rechaining
+  #   @param best_n [Integer, nil] maximum number of alignments to return
+  #   @param n_threads [Integer] number of indexing threads
+  #   @param fn_idx_out [String, nil] path at which to write the generated index
+  #   @param max_frag_len [Integer, nil] maximum fragment length
+  #   @param extra_flags [Integer, nil] additional minimap2 mapping flags
+  #   @param scoring [Array<Integer>, nil] four, six, or seven scoring values
+  #   @param sc_ambi [Integer, nil] score for ambiguous bases
+  #   @param max_chain_skip [Integer, nil] maximum chain-skip count
+  #   @param batch_size [Integer, nil] index batch size; small values create a multipart index
+  #   @raise [ArgumentError] if a preset, k, or w is invalid
+  #   @raise [Minimap2::Error] if the index cannot be initialized or lacks sequence data
+  #
+  # @!method align(seq, seq2 = nil, name: nil, cs: false, ds: false, md: false, max_frag_len: nil, extra_flags: nil)
+  #   Maps one sequence or a paired sequence.
+  #   @param seq [String] query sequence
+  #   @param seq2 [String, nil] paired query sequence
+  #   @param name [String, nil] query name stored in Alignment; defaults to "*"
+  #   @param cs [Boolean] generate the cs tag
+  #   @param ds [Boolean] generate the ds tag
+  #   @param md [Boolean] generate the MD tag
+  #   @param max_frag_len [Integer, nil] per-call maximum fragment length
+  #   @param extra_flags [Integer, nil] per-call additional mapping flags
+  #   @return [Array<Alignment>] alignments, or an empty array when no index or hit is available
+  #
+  # @!method seq(name, start = 0, stop = 0x7fffffff)
+  #   Retrieves a subsequence from the index. By default, reads to the end of the sequence.
+  #   @return [String, nil] an ASCII-8BIT sequence, or nil if unavailable
+  #
+  # @!method k
+  #   @return [Integer] minimizer k-mer length
+  #   @raise [Minimap2::Error] if no index is available
+  #
+  # @!method w
+  #   @return [Integer] minimizer window size
+  #   @raise [Minimap2::Error] if no index is available
+  #
+  # @!method n_seq
+  #   @return [Integer] number of sequences across all index parts
+  #
+  # @!method seq_names
+  #   Returns names in index order, including duplicate names.
+  #   @return [Array<String>] UTF-8 sequence names
+  #
+  # @!method index?
+  #   @return [Boolean] whether a live index is available
+  #
+  # @!method free_index
+  #   Releases every native index owned by this object. Calling it repeatedly is safe.
+  #   @return [nil]
   class Aligner
-    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.
-    #   * 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] minimum number of minimizers on a chain.
-    # @param min_chain_score [Integer] minimum chain score.
-    # @param min_dp_score
-    # @param bw [Integer] chaining and alignment band width. (initial chaining and extension)
-    # @param bw_long [Integer] chaining and alignment band width (RMQ-based rechaining and closing gaps)
-    # @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 = nil,
-      seq: nil,
-      preset: nil,
-      k: nil,
-      w: nil,
-      min_cnt: nil,
-      min_chain_score: nil,
-      min_dp_score: nil,
-      bw: nil,
-      bw_long: nil,
-      best_n: nil,
-      n_threads: 3,
-      fn_idx_out: nil,
-      max_frag_len: nil,
-      extra_flags: nil,
-      scoring: nil,
-      sc_ambi: nil,
-      max_chain_skip: nil,
-      batch_size: nil
-    )
-      @idx_opt = FFI::IdxOpt.new
-      @map_opt = FFI::MapOpt.new
-
-      r = FFI.mm_set_opt(preset, idx_opt, map_opt)
-      raise ArgumentError, "Unknown preset name: #{preset}" if r == -1
-
-      # always perform alignment
-      map_opt[:flag] |= 4
-
-      # Keep a large batch_size by default (mappy-compatible behavior) to avoid
-      # splitting indexes unless explicitly requested.
-      idx_opt[:batch_size] = 0x7fffffffffffffff
-      idx_opt[:batch_size] = batch_size if batch_size
-
-      # override preset options
-      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[:bw_long] = bw_long if bw_long
-      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_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_opt[:q2] = scoring[4]
-          map_opt[:e2] = scoring[5]
-          map_opt[:sc_ambi] = scoring[6] if scoring.size >= 7
-        end
-      end
-      map_opt[:sc_ambi] = sc_ambi if sc_ambi
-      map_opt[:max_chain_skip] = max_chain_skip if max_chain_skip
-
-      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?
-
-        @indexes = []
-        begin
-          loop do
-            idx = FFI.mm_idx_reader_read(reader, n_threads)
-            break if idx.nil? || idx.null?
-
-            # Initialize sequence name index for each part
-            FFI.mm_idx_index_name(idx)
-            @indexes << idx
-          end
-        ensure
-          FFI.mm_idx_reader_close(reader)
-        end
-
-        raise "Failed to read index parts from: #{fn_idx_in}" if @indexes.empty?
-
-        # Keep backward-compatible accessor for a single index
-        @index = @indexes[0]
-        FFI.mm_mapopt_update(map_opt, 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
-        )
-        @indexes = [@index]
-        FFI.mm_mapopt_update(map_opt, index)
-        map_opt[:mid_occ] = 1000 # don't filter high-occ seeds
-      else
-        @indexes = []
-        @index = FFI::Idx.new(::FFI::Pointer::NULL)
-      end
-    end
-
-    # Explicitly releases the memory of the index object.
-
-    def free_index
-      indexes = @indexes
-      if indexes && !indexes.empty?
-        indexes.each do |idx|
-          FFI.mm_idx_destroy(idx) unless idx.nil? || idx.null?
-        end
-      elsif defined?(@index) && !@index.nil? && !@index.null?
-        FFI.mm_idx_destroy(@index)
-      end
-    ensure
-      @indexes = []
-      @index = FFI::Idx.new(::FFI::Pointer::NULL)
-    end
-
-    # @param seq [String]
-    # @param seq2 [String]
-    # @param buf [FFI::TBuf]
-    # @param cs [true, false]
-    # @param ds [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.
-    # @return [Array] alignments
-
-    def align(
-      seq, seq2 = nil,
-      name: nil,
-      buf: nil,
-      cs: false,
-      ds: false,
-      md: false,
-      max_frag_len: nil,
-      extra_flags: nil
-    )
-      return if index.null?
-      return if (map_opt[:flag] & 4).zero? && (index[:flag] & 2).zero?
-
-      orig_map_opt_bytes = map_opt.to_ptr.read_bytes(FFI::MapOpt.size)
-      orig_best_n = map_opt[:best_n]
-
-      owned_buf = false
-      if buf.nil?
-        buf = FFI.mm_tbuf_init
-        owned_buf = true
-      end
-
-      km = FFI.mm_tbuf_get_km(buf)
-      alignments = []
-
-      idx_parts = @indexes
-      idx_parts = [index] if idx_parts.nil? || idx_parts.empty?
-
-      begin
-        idx_parts.each do |idx_part|
-          next if idx_part.nil? || idx_part.null?
-
-          # Update options for this specific index part
-          FFI.mm_mapopt_update(map_opt, idx_part)
-
-          # Per-call options (do not leak across calls)
-          map_opt[:flag] |= 4
-          map_opt[:best_n] = orig_best_n
-          map_opt[:max_frag_len] = max_frag_len if max_frag_len
-          map_opt[:flag] |= extra_flags if extra_flags
-
-          n_regs_ptr = ::FFI::MemoryPointer.new :int
-          regs_ptr = FFI.mm_map_aux(idx_part, name, seq, seq2, n_regs_ptr, buf, map_opt)
-          n_regs = n_regs_ptr.read_int
-
-          next if regs_ptr.nil? || regs_ptr.null? || n_regs <= 0
-
-          regs = Array.new(n_regs) do |i|
-            FFI::Reg1.new(regs_ptr + i * FFI::Reg1.size)
-          end
-
-          hit = FFI::Hit.new
-
-          cs_buf_ptr = nil
-          m_cs_ptr = nil
-          if cs || ds || md
-            cs_buf_ptr = ::FFI::MemoryPointer.new(:pointer)
-            cs_buf_ptr.write_pointer(::FFI::Pointer::NULL)
-            m_cs_ptr = ::FFI::MemoryPointer.new(:int)
-            m_cs_ptr.write_int(0)
-          end
-
-          i = 0
-          begin
-            while i < n_regs
-              FFI.mm_reg2hitpy(idx_part, regs[i], hit)
-
-              c = hit[:cigar32].read_array_of_uint32(hit[:n_cigar32])
-              cigar = c.map { |x| [x >> 4, x & 0xf] } # 32-bit CIGAR encoding -> Ruby array
-
-              _cs = ""
-              _ds = ""
-              _md = ""
-              if cs || ds || md
-                cur_seq = hit[:seg_id] > 0 && seq2 ? seq2 : seq
-
-                if cs
-                  l_cs_str = FFI.mm_gen_cs(km, cs_buf_ptr, m_cs_ptr, idx_part, regs[i], cur_seq, 1)
-                  cs_ptr = cs_buf_ptr.read_pointer
-                  _cs = cs_ptr.null? || l_cs_str <= 0 ? "" : cs_ptr.read_string(l_cs_str)
-                end
-
-                if ds
-                  l_cs_str = FFI.mm_gen_ds(km, cs_buf_ptr, m_cs_ptr, idx_part, regs[i], cur_seq, 1)
-                  cs_ptr = cs_buf_ptr.read_pointer
-                  _ds = cs_ptr.null? || l_cs_str <= 0 ? "" : cs_ptr.read_string(l_cs_str)
-                end
-
-                if md
-                  l_cs_str = FFI.mm_gen_md(km, cs_buf_ptr, m_cs_ptr, idx_part, regs[i], cur_seq)
-                  cs_ptr = cs_buf_ptr.read_pointer
-                  _md = cs_ptr.null? || l_cs_str <= 0 ? "" : cs_ptr.read_string(l_cs_str)
-                end
-              end
-
-              alignments << Alignment.new(hit, cigar, _cs, _ds, _md)
-
-              FFI.mm_free_reg1(regs[i])
-              i += 1
-            end
-          ensure
-            while i < n_regs
-              FFI.mm_free_reg1(regs[i])
-              i += 1
-            end
-
-            if cs_buf_ptr
-              cs_ptr = cs_buf_ptr.read_pointer
-              FFI.mappy_free(cs_ptr) unless cs_ptr.nil? || cs_ptr.null?
-            end
-
-            # Free the mm_map/mm_map_aux return value array itself
-            FFI.mappy_free(regs_ptr) unless regs_ptr.nil? || regs_ptr.null?
-          end
-        end
-      ensure
-        FFI.mm_tbuf_destroy(buf) if owned_buf
-
-        # Restore map_opt to the state before this call
-        map_opt.to_ptr.put_bytes(0, orig_map_opt_bytes)
-      end
-
-      if orig_best_n && orig_best_n > 0 && alignments.length > orig_best_n
-        alignments.sort_by! do |aln|
-          [
-            aln.primary? ? 1 : 0,
-            aln.mapq,
-            aln.mlen,
-            aln.blen,
-            -aln.nm
-          ]
-        end
-        alignments.reverse!
-        alignments = alignments.take(orig_best_n)
-      end
-
-      alignments
-    end
-
-    # Retrieve a subsequence from the index.
-    # @param name
-    # @param start
-    # @param stop
-
-    def seq(name, start = 0, stop = 0x7fffffff)
-      return if index.null?
-      return if (map_opt[:flag] & 4).zero? && (index[:flag] & 2).zero?
-
-      idx_parts = @indexes
-      idx_parts = [index] if idx_parts.nil? || idx_parts.empty?
-
-      idx_parts.each do |idx_part|
-        next if idx_part.nil? || idx_part.null?
-
-        lp = ::FFI::MemoryPointer.new(:int)
-        s = FFI.mappy_fetch_seq(idx_part, name, start, stop, lp)
-        l = lp.read_int
-        if l == 0
-          FFI.mappy_free(s) unless s.nil? || s.null?
-          next
-        end
-
-        begin
-          return s.read_string(l)
-        ensure
-          FFI.mappy_free(s) unless s.nil? || s.null?
-        end
-      end
-
-      nil
-    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
-
-    def n_seq
-      return 0 if index.null?
-
-      indexes = @indexes
-      return index[:n_seq] if indexes.nil? || indexes.empty?
-
-      indexes.sum { |idx| idx.nil? || idx.null? ? 0 : idx[:n_seq] }
-    end
-
-    def seq_names
-      return [] if index.null?
-
-      indexes = @indexes
-      indexes = [index] if indexes.nil? || indexes.empty?
-
-      names = []
-      seen = {}
-      indexes.each do |idx|
-        next if idx.nil? || idx.null?
-
-        ptr = idx[:seq].to_ptr
-        idx[:n_seq].times do |i|
-          name = FFI::IdxSeq.new(ptr + i * FFI::IdxSeq.size)[:name]
-          next if seen[name]
-
-          seen[name] = true
-          names << name
-        end
-      end
-      names
-    end
   end
 end

data/lib/minimap2/alignment.rb

@@ -3,6 +3,10 @@
 module Minimap2
   # Alignment result.
   #
+  # @!attribute qname
+  #   @return [String] query sequence name.
+  # @!attribute qlen
+  #   @return [Integer] query sequence length.
   # @!attribute ctg
   #   @return [String] name of the reference sequence the query is mapped to.
   # @!attribute ctg_len
@@ -39,24 +43,27 @@ module Minimap2
   #   @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.
+  #   @return [String, nil] the cs tag.
   # @!attribute ds
-  #   @return [String] the ds tag.
+  #   @return [String, nil] the ds 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.
+  #   @return [String, nil] the MD tag as in the SAM format.
   # @!attribute cigar_str
   #   @return [String] CIGAR string.
 
   class Alignment
+    CIGAR_STR = "MIDNSHP=XB"
+
     def self.keys
-      %i[ctg ctg_len r_st r_en strand trans_strand blen mlen nm primary
+      %i[qname qlen ctg ctg_len r_st r_en strand trans_strand blen mlen nm primary
          q_st q_en mapq cigar read_num cs ds md cigar_str]
     end
 
     attr_reader(*keys)
 
     def initialize(h, cigar, cs = nil, ds = nil, md = nil)
+      @qname        = h[:qname]
+      @qlen         = h[:qlen]
       @ctg          = h[:ctg]
       @ctg_len      = h[:ctg_len]
       @r_st         = h[:ctg_start]
@@ -76,7 +83,7 @@ module Minimap2
       @ds           = ds
       @md           = md
 
-      @cigar_str = cigar.map { |x| x[0].to_s + FFI::CIGAR_STR[x[1]] }.join
+      @cigar_str = cigar.map { |x| x[0].to_s + CIGAR_STR[x[1]] }.join
     end
 
     def primary?
@@ -89,7 +96,7 @@ module Minimap2
       self.class.keys.map { |k| [k, __send__(k)] }.to_h
     end
 
-    # Convert to the PAF format without the QueryName and QueryLength columns.
+    # Convert to the PAF format.
 
     def to_s
       strand = if @strand > 0
@@ -107,7 +114,7 @@ module Minimap2
            else
              "ts:A:."
            end
-      a = [@q_st, @q_en, strand, @ctg, @ctg_len, @r_st, @r_en,
+      a = [@qname, @qlen, @q_st, @q_en, strand, @ctg, @ctg_len, @r_st, @r_en,
            @mlen, @blen, @mapq, tp, ts, "cg:Z:#{@cigar_str}"]
       a << "cs:Z:#{@cs}" unless @cs.nil? || @cs.empty?
       a << "ds:Z:#{@ds}" unless @ds.nil? || @ds.empty?

data/lib/minimap2/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Minimap2
-  VERSION = "0.2.31.0"
+  # <binding major>.<minimap2 major>.<minimap2 minor>.<binding patch>
+  VERSION = "1.2.31.0"
 end