htslib 0.2.9 → 0.3.1

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,6 +7,10 @@ require_relative "bam/header"
 require_relative "bam/cigar"
 require_relative "bam/flag"
 require_relative "bam/record"
+require_relative "bam/base_mod"
+require_relative "bam/pileup"
+require_relative "bam/mpileup"
+# require_relative "bam/pileup_entry"
 
 module HTS
   # A class for working with SAM, BAM, CRAM files.
@@ -30,7 +34,7 @@ module HTS
     def initialize(file_name, mode = "r", index: nil, fai: nil, threads: nil,
                    build_index: false)
       if block_given?
-        message = "HTS::Bam.new() dose not take block; Please use HTS::Bam.open() instead"
+        message = "HTS::Bam.new() does not take block; Please use HTS::Bam.open() instead"
         raise message
       end
 
@@ -44,6 +48,17 @@ module HTS
 
       raise Errno::ENOENT, "Failed to open #{@file_name}" if @hts_file.null?
 
+      # Auto-detect and set reference for CRAM files
+      if fai.nil? && @file_name.end_with?(".cram")
+        # Try to find reference file in the same directory
+        base_name = File.basename(@file_name, ".cram")
+        dir_name = File.dirname(@file_name)
+        potential_ref = File.join(dir_name, "#{base_name}.fa")
+
+        # For remote URLs, assume reference exists; for local files, check existence
+        fai = potential_ref if @file_name.start_with?("http") || File.exist?(potential_ref)
+      end
+
       if fai
         r = LibHTS.hts_set_fai_filename(@hts_file, fai)
         raise "Failed to load fasta index: #{fai}" if r < 0
@@ -67,7 +82,7 @@ module HTS
       else
         warn "Create index for #{@file_name}"
       end
-      case LibHTS.sam_index_build3(@file_name, index_name, min_shift, (@nthreads || threads))
+      case LibHTS.sam_index_build3(@file_name, index_name, min_shift, @nthreads || threads)
       when 0 # successful
       when -1 then raise "indexing failed"
       when -2 then raise "opening #{@file_name} failed"
@@ -95,7 +110,7 @@ module HTS
     end
 
     def close
-      LibHTS.hts_idx_destroy(@idx) if @idx&.null?
+      LibHTS.hts_idx_destroy(@idx) if @idx && !@idx.null?
       @idx = nil
       super
     end
@@ -141,13 +156,13 @@ module HTS
     alias isize insert_size
     alias mpos mate_pos
 
-    # FXIME: experimental
+    # FIXME: experimental
     def aux(tag)
       check_closed
 
       position = tell
       ary = map { |r| r.aux(tag) }
-      seek(position)
+      seek(position) if position
       ary
     end
 
@@ -181,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)
@@ -189,17 +211,63 @@ 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, "region must be String or Array"
+      end
+    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
-        raise ArgumentError, "beg and end_ must be specified together"
+        piter = Pileup.new(self, region:, beg:, end_: end_, maxcnt: maxcnt)
+        piter.to_enum(:each)
       end
     end
 
@@ -221,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.
@@ -233,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?
@@ -284,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)
@@ -306,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

data/lib/hts/bcf.rb

@@ -30,7 +30,7 @@ module HTS
     def initialize(file_name, mode = "r", index: nil, threads: nil,
                    build_index: false)
       if block_given?
-        message = "HTS::Bcf.new() dose not take block; Please use HTS::Bcf.open() instead"
+        message = "HTS::Bcf.new() does not take block; Please use HTS::Bcf.open() instead"
         raise message
       end
 
@@ -62,7 +62,7 @@ module HTS
       else
         warn "Create index for #{@file_name}"
       end
-      case LibHTS.bcf_index_build3(@file_name, index_name, min_shift, (@nthreads || threads))
+      case LibHTS.bcf_index_build3(@file_name, index_name, min_shift, @nthreads || threads)
       when 0 # successful
       when -1 then raise "indexing failed"
       when -2 then raise "opening #{@file_name} failed"
@@ -90,7 +90,7 @@ module HTS
     end
 
     def close
-      LibHTS.hts_idx_destroy(@idx) unless @idx&.null?
+      LibHTS.hts_idx_destroy(@idx) if @idx && !@idx.null?
       @idx = nil
       super
     end
@@ -215,13 +215,20 @@ module HTS
       raise "query is only available for BCF files" unless file_format == "bcf"
       raise "Index file is required to call the query method." unless index_loaded?
 
-      if beg && end_
-        tid = header.name2id(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 must not be specified when region is an Array" unless beg.nil? && end_.nil?
+
+        query_regions(region, copy:, &block)
       else
-        raise ArgumentError, "beg and end must be specified together"
+        if beg && end_
+          tid = header.name2id(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
       end
     end
 
@@ -243,6 +250,14 @@ module HTS
       end
     end
 
+    def query_regions(regions, copy: false, &block)
+      if copy
+        query_regions_copy(regions, &block)
+      else
+        query_regions_reuse(regions, &block)
+      end
+    end
+
     def queryi_reuse(tid, beg, end_, &block)
       return to_enum(__method__, tid, beg, end_) unless block_given?
 
@@ -263,6 +278,15 @@ module HTS
       self
     end
 
+    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
+
     def query_reuse_yield(qiter)
       bcf1 = LibHTS.bcf_init
       record = Record.new(header, bcf1)
@@ -299,6 +323,15 @@ module HTS
       self
     end
 
+    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
+
     def query_copy_yield(qiter)
       loop do
         bcf1 = LibHTS.bcf_init

data/lib/hts/faidx.rb

@@ -21,7 +21,7 @@ module HTS
 
     def initialize(file_name)
       if block_given?
-        message = "HTS::Faidx.new() dose not take block; Please use HTS::Faidx.open() instead"
+        message = "HTS::Faidx.new() does not take block; Please use HTS::Faidx.open() instead"
         raise message
       end
 

data/lib/hts/hts.rb

@@ -13,7 +13,7 @@ module HTS
           check_closed
           position = tell
           ary = map(&name)
-          seek(position)
+          seek(position) if position
           ary
         end
       end

data/lib/hts/libhts/constants.rb

@@ -4,7 +4,6 @@ module HTS
   # Module for working with C HTSlib.
   module LibHTS
     typedef :int64, :hts_pos_t
-    typedef :pointer, :bam_plp_auto_f
 
     # kstring
 
@@ -158,7 +157,7 @@ module HTS
         :specific,          :pointer
     end
 
-    class HtsIdx < FFI::Struct # FIXME: ManagedStruct
+    class HtsIdx < FFI::Struct
       layout \
         :fmt,            :int,
         :min_shift,      :int,
@@ -189,9 +188,9 @@ module HTS
           :n_unmapped,   :uint64
         )
 
-      def self.release(ptr)
-        LibHTS.hts_idx_destroy(ptr) unless ptr.null?
-      end
+      # def self.release(ptr)
+      #   LibHTS.hts_idx_destroy(ptr) unless ptr.null?
+      # end
     end
 
     class HtsReglist < FFI::Struct
@@ -352,6 +351,36 @@ module HTS
       end
     end
 
+    # Internal: Non-owning view of bam1_t used when the pointer is managed by HTSlib
+    # (e.g., pileup/mpileup). This struct mirrors the layout of bam1_t and MUST NOT
+    # free memory on GC. Do not expose publicly; use only for read-only access.
+    class Bam1View < FFI::Struct
+      layout \
+        :core,           Bam1Core,
+        :id,             :uint64,
+        :data,           :pointer, # uint8_t
+        :l_data,         :int,
+        :m_data,         :uint32,
+        :_mempolicy,     :uint32 # bit_fields
+    end
+
+    # Base modification structure
+    class HtsBaseMod < FFI::Struct
+      layout \
+        :modified_base,   :int,
+        :canonical_base,  :int,
+        :strand,          :int,
+        :qual,            :int
+    end
+
+    # Base modification state (opaque pointer)
+    # Use AutoPointer since the structure is opaque and we only need custom release.
+    class HtsBaseModState < FFI::AutoPointer
+      def self.release(ptr)
+        LibHTS.hts_base_mod_state_free(ptr) unless ptr.null?
+      end
+    end
+
     typedef :pointer, :bam_plp
     typedef :pointer, :bam_mplp
 
@@ -364,7 +393,7 @@ module HTS
 
     class BamPileup1 < FFI::BitStruct
       layout \
-        :b,              Bam1.ptr,
+        :b,              :pointer,
         :qpos,           :int32,
         :indel,          :int,
         :level,          :int,
@@ -379,6 +408,10 @@ module HTS
                  :is_refskip, 1,
                  :_reserved,  1,
                  :aux,        27
+
+      # def self.release(ptr)
+      #   LibHTS.bam_plp_destroy(ptr) unless ptr.null?
+      # end
     end
 
     class TbxConf < FFI::Struct