htslib 0.2.9 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c98f3937d65f091e9e834060f3a94578034d1bf55e7bc372e5ed388e618a6da4
-  data.tar.gz: 8e180044fef210935695bc60c0352b747b570b705f3ce9318b7538d19ddaf645
+  metadata.gz: e1bf158506931c62ffae1a524158de9fbb451796a68a7586cf788203f67a8cc4
+  data.tar.gz: d3289551dac8783cfa23f1f8d44e1b4be44b6dab3d6369f816491ceea653188f
 SHA512:
-  metadata.gz: 5324913bdbe97580fee1e54b6268f22aed2a0b84d449c8a4f62529981c82a57d6ae5cea7cc77ff1be7332425eea259bfe5daa1107b6144e36ef40bb4997dd28f
-  data.tar.gz: 7b230700951223aeda09d64fac7cca44d734d54ec03a7836c5a0fb036e552854db80b9ecaf57aa478e317c684e4712f2f03244e02474fd2ea53a4b93346d1371
+  metadata.gz: d1c316a599c2dc08e6589f980e9dd4ae6d8d6bababbfef424f35e5c25453b667bdc48570578e88a9eba142553fffb25b49ae4de54a061f99f7cbf286988ec618
+  data.tar.gz: 8529c6a02c354419dd722abc0bd6f27ec514ffe980f4b0d7014914de11551a45c4e96b803bc77255c3b423129a8743a3c39556d9d3d44ec6c6692556485379cf

data/README.md

@@ -6,6 +6,9 @@
 [![DOI](https://zenodo.org/badge/247078205.svg)](https://zenodo.org/badge/latestdoi/247078205)
 [![Docs Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://rubydoc.info/gems/htslib)
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kojix2/ruby-htslib)
+[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Fruby-htslib%2Flines)](https://tokei.kojix2.net/github/kojix2/ruby-htslib)
+
 Ruby-htslib is the [Ruby](https://www.ruby-lang.org) bindings to [HTSlib](https://github.com/samtools/htslib), a C library for high-throughput sequencing data formats. It allows you to read and write file formats commonly used in genomics, such as [SAM, BAM, VCF, and BCF](http://samtools.github.io/hts-specs/), in the Ruby language.
 
 :apple: Feel free to fork it!

data/lib/hts/bam/base_mod.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    # Base modification information from MM/ML tags
+    #
+    # This class provides access to DNA/RNA base modifications such as methylation.
+    # It wraps the htslib base modification API and provides a Ruby-friendly interface.
+    #
+    # @note BaseMod is a view object that references data in a Record.
+    #   The state is maintained in hts_base_mod_state structure.
+    class BaseMod
+      include Enumerable
+
+      class NotParsedError < StandardError; end
+
+      attr_reader :record
+
+      # Individual base modification information
+      class Modification
+        attr_reader :modified_base, :canonical_base, :strand, :qual
+
+        # @param modified_base [Integer] Modification code as char or -ChEBI
+        # @param canonical_base [Integer] Canonical base (A, C, G, T, N)
+        # @param strand [Integer] 0 or 1 for +/- strand
+        # @param qual [Integer] Quality (256*probability) or -1 if unknown
+        def initialize(modified_base:, canonical_base:, strand:, qual:)
+          @modified_base = modified_base
+          @canonical_base = canonical_base
+          @strand = strand
+          @qual = qual
+        end
+
+        # Get modification code as character or ChEBI number as string
+        # @return [String] Single character code or ChEBI number as string
+        def code
+          @modified_base > 0 ? @modified_base.chr : @modified_base.to_s
+        end
+
+        # Get canonical base as character
+        # @return [String] Single character (A, C, G, T, N)
+        def canonical
+          @canonical_base.chr
+        end
+
+        # Get likelihood as a probability (0.0-1.0)
+        # @return [Float, nil] Probability or nil if qual is -1
+        def probability
+          return nil if @qual == -1
+
+          @qual / 256.0
+        end
+
+        # Convert to hash representation
+        # @return [Hash] Hash with modification information
+        def to_h
+          {
+            modified_base: @modified_base,
+            code: code,
+            canonical_base: @canonical_base,
+            canonical: canonical,
+            strand: @strand,
+            qual: @qual,
+            probability: probability
+          }
+        end
+
+        # String representation
+        # @return [String] String representation of the modification
+        def to_s
+          if @qual >= 0
+            "#{canonical}->#{code}(#{probability.round(3)})"
+          else
+            "#{canonical}->#{code}"
+          end
+        end
+
+        # Inspect string
+        # @return [String] Inspect string
+        def inspect
+          "#<HTS::Bam::BaseMod::Modification #{self}>"
+        end
+      end
+
+      # Position-specific modification information
+      class Position
+        attr_reader :position, :modifications
+
+        # @param position [Integer] Position in query sequence
+        # @param modifications [Array<Modification>] Array of modifications at this position
+        def initialize(position, modifications)
+          @position = position
+          @modifications = modifications
+        end
+
+        # Check if this position has methylation
+        # @return [Boolean] true if any modification is methylation ('m')
+        def methylated?
+          @modifications.any? { |m| m.code == "m" }
+        end
+
+        # Check if this position has hydroxymethylation
+        # @return [Boolean] true if any modification is hydroxymethylation ('h')
+        def hydroxymethylated?
+          @modifications.any? { |m| m.code == "h" }
+        end
+
+        # Convert to hash representation
+        # @return [Hash] Hash with position information
+        def to_h
+          {
+            position: @position,
+            modifications: @modifications.map(&:to_h)
+          }
+        end
+
+        # String representation
+        # @return [String] String representation
+        def to_s
+          mods_str = @modifications.map(&:to_s).join(", ")
+          "pos=#{@position} [#{mods_str}]"
+        end
+
+        # Inspect string
+        # @return [String] Inspect string
+        def inspect
+          "#<HTS::Bam::BaseMod::Position #{self}>"
+        end
+      end
+
+      # Initialize a new BaseMod object
+      # @param record [Record] The BAM record to extract modifications from
+      # @param auto_parse [Boolean] If true, parse MM/ML lazily on first access
+      def initialize(record, auto_parse: true)
+        @record = record
+        @state = LibHTS.hts_base_mod_state_alloc
+        @closed = false
+        @auto_parse = !!auto_parse
+        @parsed = false
+        raise Error, "Failed to allocate hts_base_mod_state" if @state.null?
+      end
+
+      # Explicitly free the state
+      # @return [void]
+      def close
+        return if @closed
+
+        # With HtsBaseModState as an AutoPointer, releasing the Ruby object
+        # is sufficient. Avoid manual free to prevent double-free.
+        @state = nil
+        @closed = true
+      end
+
+      # Whether this object has parsed MM/ML tags already
+      # @return [Boolean]
+      def parsed?
+        @parsed
+      end
+
+      # Ensure MM/ML have been parsed, performing lazy parse if enabled.
+      # @param flags [Integer]
+      # @return [void]
+      def ensure_parsed!(flags = 0)
+        return if @parsed
+
+        raise NotParsedError, "BaseMod is not parsed. Call #parse first (auto_parse is disabled)." unless @auto_parse
+
+        parse(flags)
+      end
+
+      # Parse MM and ML tags from the record
+      # @param flags [Integer] Parsing flags (default: 0)
+      # @return [Integer] Number of modification types found, or -1 on error
+      # @raise [Error] If parsing fails
+      def parse(flags = 0)
+        ret = LibHTS.bam_parse_basemod2(@record.struct, @state, flags)
+        raise Error, "Failed to parse base modifications" if ret < 0
+
+        @parsed = true
+        ret
+      end
+
+      # Get modification information at a specific query position
+      # @param position [Integer] Query position (0-based)
+      # @param max_mods [Integer] Maximum number of modifications to retrieve
+      # @return [Position, nil] Position object with modifications, or nil if none
+      def at_pos(position, max_mods: 10)
+        # Reset state to ensure deterministic results even after prior iteration
+        parsed? ? parse : ensure_parsed!
+
+        mods_ptr = FFI::MemoryPointer.new(LibHTS::HtsBaseMod, max_mods)
+
+        ret = LibHTS.bam_mods_at_qpos(@record.struct, position, @state,
+                                      mods_ptr, max_mods)
+        return nil if ret <= 0
+
+        build_position(position, mods_ptr, [ret, max_mods].min)
+      end
+
+      # Array-style access to modifications at a position
+      # @param position [Integer] Query position (0-based)
+      # @return [Position, nil] Position object with modifications, or nil if none
+      def [](position)
+        at_pos(position)
+      end
+
+      # Iterate over all positions with modifications
+      # @param max_mods [Integer] Maximum number of modifications per position
+      # @yield [Position] Position object for each modified position
+      # @return [Enumerator] If no block given
+      def each_position(max_mods: 10)
+        return enum_for(__method__, max_mods: max_mods) unless block_given?
+
+        # Reset state at the start of iteration to allow repeated enumerations
+        parsed? ? parse : ensure_parsed!
+
+        pos_ptr = FFI::MemoryPointer.new(:int)
+        mods_ptr = FFI::MemoryPointer.new(LibHTS::HtsBaseMod, max_mods)
+
+        loop do
+          ret = LibHTS.bam_next_basemod(@record.struct, @state,
+                                        mods_ptr, max_mods, pos_ptr)
+          break if ret <= 0
+
+          position = pos_ptr.read_int
+          yield build_position(position, mods_ptr, [ret, max_mods].min)
+        end
+      end
+
+      alias each each_position
+
+      # Get list of modification types present in this record
+      # @return [Array<Integer>] Array of modification codes (char code or -ChEBI)
+      def modification_types
+        ensure_parsed!
+
+        ntype_ptr = FFI::MemoryPointer.new(:int)
+        codes_ptr = LibHTS.bam_mods_recorded(@state, ntype_ptr)
+
+        ntype = ntype_ptr.read_int
+        return [] if ntype <= 0 || codes_ptr.null?
+
+        codes_ptr.read_array_of_int(ntype)
+      end
+
+      alias recorded_types modification_types
+
+      # Query information about a specific modification type by code
+      # @param code [Integer, String] Modification code (char code or -ChEBI, or single char string)
+      # @return [Hash, nil] Hash with canonical, strand, implicit info, or nil if not found
+      def query_type(code)
+        ensure_parsed!
+
+        code = code.ord if code.is_a?(String)
+
+        strand_ptr = FFI::MemoryPointer.new(:int)
+        implicit_ptr = FFI::MemoryPointer.new(:int)
+        canonical_ptr = FFI::MemoryPointer.new(:char, 1)
+
+        ret = LibHTS.bam_mods_query_type(@state, code, strand_ptr,
+                                         implicit_ptr, canonical_ptr)
+        return nil if ret < 0
+
+        {
+          canonical: canonical_ptr.read_char.chr,
+          strand: strand_ptr.read_int,
+          implicit: implicit_ptr.read_int != 0
+        }
+      end
+
+      # Query information about i-th modification type
+      # @param index [Integer] Modification type index (0-based)
+      # @return [Hash, nil] Hash with code, canonical, strand, implicit info
+      def query_type_at(index)
+        ensure_parsed!
+
+        strand_ptr = FFI::MemoryPointer.new(:int)
+        implicit_ptr = FFI::MemoryPointer.new(:int)
+        canonical_ptr = FFI::MemoryPointer.new(:char, 1)
+
+        ret = LibHTS.bam_mods_queryi(@state, index, strand_ptr,
+                                     implicit_ptr, canonical_ptr)
+        return nil if ret < 0
+
+        types = modification_types
+        {
+          code: types[index],
+          canonical: canonical_ptr.read_char.chr,
+          strand: strand_ptr.read_int,
+          implicit: implicit_ptr.read_int != 0
+        }
+      end
+
+      # Get all modifications as an array
+      # @return [Array<Position>] Array of all positions with modifications
+      def to_a
+        each_position.to_a
+      end
+
+      # String representation for debugging
+      # @return [String] String representation
+      def to_s
+        return "#<HTS::Bam::BaseMod (not parsed)>" unless @parsed
+
+        mods = []
+        each_position do |pos|
+          mods << pos.to_s
+        end
+        "#<HTS::Bam::BaseMod #{mods.join(' ')}>"
+      end
+
+      # Inspect string
+      # @return [String] Inspect string
+      def inspect
+        to_s
+      end
+
+      private
+
+      # Build Position object from hts_base_mod array
+      # @param position [Integer] Query position
+      # @param mods_ptr [FFI::Pointer] Pointer to array of HtsBaseMod structures
+      # @param n_mods [Integer] Number of modifications
+      # @return [Position] Position object
+      def build_position(position, mods_ptr, n_mods)
+        modifications = []
+
+        n_mods.times do |i|
+          mod_struct = LibHTS::HtsBaseMod.new(mods_ptr + i * LibHTS::HtsBaseMod.size)
+
+          modifications << Modification.new(
+            modified_base: mod_struct[:modified_base],
+            canonical_base: mod_struct[:canonical_base],
+            strand: mod_struct[:strand],
+            qual: mod_struct[:qual]
+          )
+        end
+
+        Position.new(position, modifications)
+      end
+    end
+  end
+end

data/lib/hts/bam/header.rb

@@ -111,6 +111,23 @@ module HTS
         name2tid(name)
       end
 
+      # Add a @PG (program) line to the header
+      # @param program_name [String] Name of the program
+      # @param options [Hash] Key-value pairs for @PG tags (ID, PN, VN, CL, PP, etc.)
+      # @return [Integer] 0 on success, -1 on failure
+      #
+      # This is a convenience wrapper around sam_hdr_add_pg that automatically:
+      # - Generates a unique ID if the specified one clashes
+      # - Manages PP (previous program) chains automatically
+      #
+      # @example
+      #   header.add_pg("bwa", VN: "0.7.17", CL: "bwa mem ref.fa read.fq")
+      #   header.add_pg("samtools", VN: "1.15", PP: "bwa")
+      def add_pg(program_name, **options)
+        args = options.flat_map { |k, v| [:string, k.to_s, :string, v.to_s] }
+        LibHTS.sam_hdr_add_pg(@sam_hdr, program_name, *args, :pointer, FFI::Pointer::NULL)
+      end
+
       private
 
       def name2tid(name)

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