htslib 0.3.0 → 0.3.2

data/lib/hts/bam/mpileup.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    # High-level mpileup iterator over multiple BAM/CRAM inputs
+    class Mpileup
+      include Enumerable
+
+      # Usage:
+      #   HTS::Bam::Mpileup.open([bam1, bam2], region: "chr1:1-100") do |mpl|
+      #     mpl.each { |cols| ... }
+      #   end
+      def self.open(*args, **kw)
+        m = new(*args, **kw)
+        return m unless block_given?
+
+        begin
+          yield m
+        ensure
+          m.close
+        end
+        m
+      end
+
+      # Normalize inputs to HTS::Bam instances
+      # Accepts array of HTS::Bam or filenames (String)
+      def initialize(inputs, region: nil, beg: nil, end_: nil, maxcnt: nil, overlaps: false)
+        raise ArgumentError, "inputs must be non-empty" if inputs.nil? || inputs.empty?
+
+        @owned_bams = [] # Bams we opened here; will be closed on close
+        @bams = inputs.map do |x|
+          case x
+          when HTS::Bam
+            x
+          when String
+            b = HTS::Bam.open(x)
+            @owned_bams << b
+            b
+          else
+            raise ArgumentError, "Unsupported input type: #{x.class}"
+          end
+        end
+
+        n = @bams.length
+        @iters       = []
+        @data_blocks = [] # per-input packed pointers kept alive
+
+        # Prepare optional region iterators for each input
+        @bams.each_with_index do |bam, i|
+          itr = nil
+          if region && beg.nil? && end_.nil?
+            raise "Index required for region mpileup" unless bam.index_loaded?
+
+            itr = HTS::LibHTS.sam_itr_querys(bam.instance_variable_get(:@idx), bam.header.struct, region)
+            raise "Failed to query region on input ##{i}: #{region}" if itr.null?
+          elsif region && beg && end_
+            raise "Index required for region mpileup" unless bam.index_loaded?
+
+            tid = bam.header.get_tid(region)
+            itr = HTS::LibHTS.sam_itr_queryi(bam.instance_variable_get(:@idx), tid, beg, end_)
+            raise "Failed to query region on input ##{i}: #{region} #{beg} #{end_}" if itr.null?
+          elsif beg || end_
+            raise ArgumentError, "beg and end_ must be specified together"
+          end
+          @iters << itr
+        end
+
+        # Build per-input packed pointer blocks so C passes them back to the callback.
+        # Layout per input: [0] hts_fp (htsFile*), [1] hdr_struct (bam_hdr_t*), [2] itr (hts_itr_t* or NULL)
+        ptr_size = FFI.type_size(:pointer)
+        data_array = FFI::MemoryPointer.new(:pointer, n)
+        @bams.each_with_index do |bam, i|
+          hts_fp     = bam.instance_variable_get(:@hts_file)
+          hdr_struct = bam.header.struct
+          itr        = @iters[i]
+          block = FFI::MemoryPointer.new(:pointer, 3)
+          block.put_pointer(0 * ptr_size, hts_fp)
+          block.put_pointer(1 * ptr_size, hdr_struct)
+          block.put_pointer(2 * ptr_size, itr && !itr.null? ? itr : FFI::Pointer::NULL)
+          @data_blocks << block
+          data_array.put_pointer(i * ptr_size, block)
+        end
+        # Keep the array of per-input blocks alive while the C side holds on to them
+        @data_array = data_array
+
+        @cb = FFI::Function.new(:int, %i[pointer pointer]) do |data, b|
+          # Unpack pointers from the per-input block
+          hts_fp     = data.get_pointer(0 * ptr_size)
+          hdr_struct = data.get_pointer(1 * ptr_size)
+          itr        = data.get_pointer(2 * ptr_size)
+          # HTSlib contract: return same as sam_itr_next/sam_read1 (>= 0 on success, -1 on EOF, < -1 on error)
+          if itr && !itr.null?
+            HTS::LibHTS.sam_itr_next(hts_fp, itr, b)
+          else
+            HTS::LibHTS.sam_read1(hts_fp, hdr_struct, b)
+          end
+        end
+
+        @iter = HTS::LibHTS.bam_mplp_init(n, @cb, @data_array)
+        raise "bam_mplp_init failed" if @iter.null?
+
+        HTS::LibHTS.bam_mplp_set_maxcnt(@iter, maxcnt) if maxcnt
+        return unless overlaps
+
+        rc = HTS::LibHTS.bam_mplp_init_overlaps(@iter)
+        raise "bam_mplp_init_overlaps failed" if rc < 0
+      end
+
+      # Yields an array of Pileup::PileupColumn (one per input) for each position
+      def each
+        return to_enum(__method__) unless block_given?
+
+        n = @bams.length
+        tid_ptr = FFI::MemoryPointer.new(:int)
+        pos_ptr = FFI::MemoryPointer.new(:long_long)
+        n_ptr   = FFI::MemoryPointer.new(:int, n)
+        plp_ptr = FFI::MemoryPointer.new(:pointer, n)
+        plp1_size = HTS::LibHTS::BamPileup1.size
+        headers   = @bams.map(&:header)
+
+        while HTS::LibHTS.bam_mplp64_auto(@iter, tid_ptr, pos_ptr, n_ptr, plp_ptr) > 0
+          tid = tid_ptr.read_int
+          pos = pos_ptr.read_long_long
+
+          counts = n_ptr.read_array_of_int(n)
+          plp_arr = plp_ptr.read_array_of_pointer(n)
+
+          cols = Array.new(n)
+          i = 0
+          while i < n
+            c = counts[i]
+            if c <= 0 || plp_arr[i].null?
+              cols[i] = HTS::Bam::Pileup::PileupColumn.new(tid: tid, pos: pos, alignments: [])
+            else
+              base_ptr = plp_arr[i]
+              aligns = Array.new(c)
+              j = 0
+              while j < c
+                e_ptr = base_ptr + (j * plp1_size)
+                entry = HTS::LibHTS::BamPileup1.new(e_ptr)
+                aligns[j] = HTS::Bam::Pileup::PileupRecord.new(entry, headers[i])
+                j += 1
+              end
+              cols[i] = HTS::Bam::Pileup::PileupColumn.new(tid: tid, pos: pos, alignments: aligns)
+            end
+            i += 1
+          end
+
+          yield cols
+        end
+
+        self
+      end
+
+      def close
+        if @iter && !@iter.null?
+          HTS::LibHTS.bam_mplp_destroy(@iter)
+          @iter = FFI::Pointer::NULL
+        end
+        @iters.each do |itr|
+          HTS::LibHTS.hts_itr_destroy(itr) if itr && !itr.null?
+        end
+        @iters.clear
+        # Keep references to callback and data blocks to prevent GC
+        @_keepalive = [@cb, @data_array, *@data_blocks]
+        # Close owned bams opened by this object
+        @owned_bams.each do |b|
+          b.close
+        rescue StandardError
+        end
+        @owned_bams.clear
+      end
+    end
+  end
+end

data/lib/hts/bam/pileup.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    # High-level pileup iterator for a single SAM/BAM/CRAM
+    class Pileup
+      include Enumerable
+
+      # Usage:
+      #   HTS::Bam::Pileup.open(bam, region: "chr1:1-100") do |pl|
+      #     pl.each { |col| ... }
+      #   end
+      def self.open(*args, **kw)
+        pu = new(*args, **kw)
+        return pu unless block_given?
+
+        begin
+          yield pu
+        ensure
+          pu.close
+        end
+        pu
+      end
+
+      # A column at a reference position with pileup alignments
+      PileupColumn = Struct.new(:tid, :pos, :alignments, keyword_init: true) do
+        def depth
+          alignments.length
+        end
+      end
+
+      # A wrapper of one bam_pileup1_t entry
+      class PileupRecord
+        def initialize(entry, header)
+          @entry  = entry
+          @header = header
+          @record = nil
+        end
+
+        # Return Bam::Record. On the first call, duplicate the underlying bam1_t (bam_dup1)
+        # so the record becomes safe to keep beyond the current pileup step. Subsequent calls
+        # return the cached Bam::Record instance.
+        # NOTE: Without duplication, bam1_t memory may be reused by HTSlib on the next step.
+        def record
+          return @record if @record
+
+          # Normalize to a raw pointer and duplicate to obtain owned memory.
+          b_ptr = @entry[:b].is_a?(FFI::Pointer) ? @entry[:b] : @entry[:b].to_ptr
+          dup_ptr = HTS::LibHTS.bam_dup1(b_ptr)
+          raise "bam_dup1 failed" if dup_ptr.null?
+
+          # Build a Bam::Record backed by the duplicated bam1_t.
+          @record = HTS::Bam::Record.new(@header, dup_ptr)
+        end
+
+        def query_position
+          @entry[:qpos]
+        end
+
+        def indel
+          @entry[:indel]
+        end
+
+        def del?
+          @entry[:is_del] == 1
+        end
+
+        def head?
+          @entry[:is_head] == 1
+        end
+
+        def tail?
+          @entry[:is_tail] == 1
+        end
+
+        def refskip?
+          @entry[:is_refskip] == 1
+        end
+      end
+
+      # Create a Pileup iterator
+      # @param bam [HTS::Bam]
+      # @param region [String, nil] Optional region string (requires index)
+      # @param beg [Integer, nil] Optional begin when using tid/beg/end form
+      # @param end_ [Integer, nil] Optional end when using tid/beg/end form
+      # @param maxcnt [Integer, nil] Max per-position depth (capped)
+      def initialize(bam, region: nil, beg: nil, end_: nil, maxcnt: nil)
+        @bam    = bam
+        @header = bam.header
+        @itr    = nil
+        @cb     = nil
+        @plp    = nil
+
+        # Optional region iterator
+        if region && beg.nil? && end_.nil?
+          raise "Index file is required to use region pileup." unless bam.index_loaded?
+
+          @itr = HTS::LibHTS.sam_itr_querys(bam.instance_variable_get(:@idx), @header.struct, region)
+          raise "Failed to query region: #{region}" if @itr.null?
+        elsif region && beg && end_
+          raise "Index file is required to use region pileup." unless bam.index_loaded?
+
+          tid = @header.get_tid(region)
+          @itr = HTS::LibHTS.sam_itr_queryi(bam.instance_variable_get(:@idx), tid, beg, end_)
+          raise "Failed to query region: #{region} #{beg} #{end_}" if @itr.null?
+        elsif beg || end_
+          raise ArgumentError, "beg and end_ must be specified together"
+        end
+
+        # Build the auto callback for bam_plp_init (micro-optimized)
+        # - Hoist ivar/constant lookups out of the callback to reduce per-call overhead.
+        # - Specialize callbacks to avoid branching in the hot path.
+        hts_fp     = @bam.instance_variable_get(:@hts_file)
+        hdr_struct = @header.struct
+        itr_local  = @itr
+
+        @cb = if itr_local && !itr_local.null?
+                FFI::Function.new(:int, %i[pointer pointer]) do |_data, b|
+                  # HTSlib contract: return same as sam_itr_next (>= 0 on success, -1 on EOF, < -1 on error)
+                  HTS::LibHTS.sam_itr_next(hts_fp, itr_local, b)
+                end
+              else
+                FFI::Function.new(:int, %i[pointer pointer]) do |_data, b|
+                  # HTSlib contract: return same as sam_read1 (>= 0 on success, -1 on EOF, < -1 on error)
+                  HTS::LibHTS.sam_read1(hts_fp, hdr_struct, b)
+                end
+              end
+
+        @plp = HTS::LibHTS.bam_plp_init(@cb, nil)
+        raise "bam_plp_init failed" if @plp.null?
+
+        HTS::LibHTS.bam_plp_set_maxcnt(@plp, maxcnt) if maxcnt
+      end
+
+      def each
+        return to_enum(__method__) unless block_given?
+
+        tid_ptr = FFI::MemoryPointer.new(:int)
+        pos_ptr = FFI::MemoryPointer.new(:long_long) # hts_pos_t
+        n_ptr   = FFI::MemoryPointer.new(:int)
+
+        # Micro-optimizations:
+        # - Compute constant struct size once
+        # - Hoist header reference outside the loop
+        plp1_size    = HTS::LibHTS::BamPileup1.size
+        header_local = @header
+
+        loop do
+          base_ptr = HTS::LibHTS.bam_plp64_auto(@plp, tid_ptr, pos_ptr, n_ptr)
+
+          # When base_ptr is NULL, check n to distinguish EOF (n == 0) from error (n < 0)
+          if base_ptr.null?
+            n = n_ptr.read_int
+            raise "HTSlib pileup error (bam_plp64_auto)" if n < 0
+
+            break
+          end
+
+          tid = tid_ptr.read_int
+          pos = pos_ptr.read_long_long
+          n   = n_ptr.read_int
+
+          # Construct alignment entries with minimal allocations
+          if n.zero?
+            alignments = []
+          else
+            alignments = Array.new(n)
+            i = 0
+            while i < n
+              e_ptr = base_ptr + (i * plp1_size)
+              entry = HTS::LibHTS::BamPileup1.new(e_ptr)
+              alignments[i] = PileupRecord.new(entry, header_local)
+              i += 1
+            end
+          end
+
+          yield PileupColumn.new(tid: tid, pos: pos, alignments: alignments)
+        end
+
+        self
+      end
+
+      def reset
+        HTS::LibHTS.bam_plp_reset(@plp) if @plp && !@plp.null?
+      end
+
+      def close
+        if @plp && !@plp.null?
+          HTS::LibHTS.bam_plp_destroy(@plp)
+          @plp = FFI::Pointer::NULL
+        end
+        if @itr && !@itr.null?
+          HTS::LibHTS.hts_itr_destroy(@itr)
+          @itr = FFI::Pointer::NULL
+        end
+        # Keep @cb referenced by instance to avoid GC during iteration.
+        @cb
+      end
+    end
+  end
+end

data/lib/hts/bam/record.rb

@@ -326,6 +326,13 @@ module HTS
         end
       end
 
+      # Get base modification information from MM/ML tags
+      # @param auto_parse [Boolean] If true (default), parse lazily on first access
+      # @return [BaseMod] Base modification object
+      def base_mod(auto_parse: true)
+        BaseMod.new(self, auto_parse: auto_parse)
+      end
+
       # TODO: add a method to get the auxiliary fields as a hash.
 
       # TODO: add a method to set the auxiliary fields.
@@ -352,8 +359,13 @@ module HTS
       private
 
       def initialize_copy(orig)
+        super
         @header = orig.header
-        @bam = LibHTS.bam_dup1(orig.struct)
+        # Deep-copy underlying bam1_t to detach from original buffer
+        dup_bam1 = LibHTS.bam_dup1(orig.struct)
+        raise "bam_dup1 failed" if dup_bam1.null?
+
+        @bam1 = dup_bam1
       end
     end
   end

data/lib/hts/bam.rb

@@ -7,7 +7,9 @@ require_relative "bam/header"
 require_relative "bam/cigar"
 require_relative "bam/flag"
 require_relative "bam/record"
-# require_relative "bam/pileup"
+require_relative "bam/base_mod"
+require_relative "bam/pileup"
+require_relative "bam/mpileup"
 # require_relative "bam/pileup_entry"
 
 module HTS
@@ -160,7 +162,7 @@ module HTS
 
       position = tell
       ary = map { |r| r.aux(tag) }
-      seek(position)
+      seek(position) if position
       ary
     end
 
@@ -194,6 +196,13 @@ module HTS
       self
     end
 
+    # Iterate alignment records in this file.
+    #
+    # Performance and memory semantics:
+    # - copy: false (default) reuses a single Record instance and its underlying bam1_t buffer.
+    #   The yielded Record MUST NOT be stored beyond the block; its content will be overwritten
+    #   by the next iteration. If you need to retain it, call `rec = rec.dup`.
+    # - copy: true yields a fresh Record per iteration (deep-copied via bam_dup1). Slower, safe to keep.
     def each(copy: false, &block)
       if copy
         each_record_copy(&block)
@@ -202,23 +211,65 @@ module HTS
       end
     end
 
+    # Iterate records in a genomic region or multiple regions.
+    # See {#each} for copy semantics. When copy: false, the yielded Record is reused and should not be stored.
+    #
+    # @param region [String, Array<String>] Region specification(s)
+    #   - Single region: "chr1:100-200" or "chr1" with beg/end parameters
+    #   - Multiple regions: ["chr1:100-200", "chr2:500-600", ...]
+    # @param beg [Integer, nil] Start position (used with single string region)
+    # @param end_ [Integer, nil] End position (used with single string region)
+    # @param copy [Boolean] Whether to deep-copy records (see {#each})
+    #
+    # @example Single region query
+    #   bam.query("chr1:100-200") { |r| puts r.qname }
+    #   bam.query("chr1", 100, 200) { |r| puts r.qname }
+    #
+    # @example Multi-region query
+    #   bam.query(["chr1:100-200", "chr2:500-600"]) { |r| puts r.qname }
     def query(region, beg = nil, end_ = nil, copy: false, &block)
       check_closed
       raise "Index file is required to call the query method." unless index_loaded?
 
-      if beg && end_
-        tid = header.get_tid(region)
-        queryi(tid, beg, end_, copy:, &block)
-      elsif beg.nil? && end_.nil?
-        querys(region, copy:, &block)
+      case region
+      when Array
+        raise ArgumentError, "beg and end_ cannot be used with array of regions" if beg || end_
+
+        query_regions(region, copy:, &block)
+      when String
+        if beg && end_
+          tid = header.get_tid(region)
+          queryi(tid, beg, end_, copy:, &block)
+        elsif beg.nil? && end_.nil?
+          querys(region, copy:, &block)
+        else
+          raise ArgumentError, "beg and end_ must be specified together"
+        end
       else
-        raise ArgumentError, "beg and end_ must be specified together"
+        raise ArgumentError, "region must be String or Array"
       end
     end
 
-    # def pileup
-    #   Pileup.new(self)
-    # end
+    # Pileup iterator over this file. Optional region can be specified.
+    # When a block is given, uses RAII-style and ensures the iterator is closed at block end.
+    # Without a block, returns an Enumerator over a live Pileup instance; caller should close when done.
+    #
+    # @param region [String, nil] region string like "chr1:100-200"
+    # @param beg [Integer, nil]
+    # @param end_ [Integer, nil]
+    # @param maxcnt [Integer, nil] cap on depth per position
+    def pileup(region = nil, beg = nil, end_: nil, maxcnt: nil, &block)
+      check_closed
+      if block_given?
+        Pileup.open(self, region:, beg:, end_: end_, maxcnt: maxcnt) do |piter|
+          piter.each(&block)
+        end
+        self
+      else
+        piter = Pileup.new(self, region:, beg:, end_: end_, maxcnt: maxcnt)
+        piter.to_enum(:each)
+      end
+    end
 
     private
 
@@ -238,6 +289,17 @@ module HTS
       end
     end
 
+    # Multi-region query implementation
+    def query_regions(regions, copy: false, &block)
+      if copy
+        query_regions_copy(regions, &block)
+      else
+        query_regions_reuse(regions, &block)
+      end
+    end
+
+    # Internal: yield a single reused Record over the entire file.
+    # The underlying bam1_t is mutated on each iteration for speed.
     def each_record_reuse
       check_closed
       # Each does not always start at the beginning of the file.
@@ -250,6 +312,7 @@ module HTS
       self
     end
 
+    # Internal: yield deep-copied Records so callers may retain them safely.
     def each_record_copy
       check_closed
       return to_enum(__method__) unless block_given?
@@ -301,6 +364,7 @@ module HTS
       self
     end
 
+    # Internal: reused-Record iterator over a query iterator.
     def query_reuse_yield(qiter)
       bam1 = LibHTS.bam_init1
       record = Record.new(header, bam1)
@@ -323,5 +387,27 @@ module HTS
     ensure
       LibHTS.hts_itr_destroy(qiter)
     end
+
+    # Multi-region query using sequential single-region queries
+    # Note: This is a fallback implementation. Ideally we would use sam_itr_regarray
+    # but there seem to be issues with the multi-region iterator in the current setup.
+    def query_regions_reuse(regions, &block)
+      return to_enum(__method__, regions) unless block_given?
+
+      regions.each do |region|
+        querys_reuse(region, &block)
+      end
+      self
+    end
+
+    # Multi-region query with copied Records using sequential queries
+    def query_regions_copy(regions, &block)
+      return to_enum(__method__, regions) unless block_given?
+
+      regions.each do |region|
+        querys_copy(region, &block)
+      end
+      self
+    end
   end
 end