htslib 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea68a4c331c9a404cfce2bf86fea386985e96ee3b76ae25e9d9b701593294880
-  data.tar.gz: d826e59f66e20bc40bc47c2033295abe2b3aceab8cb9d5af3d4d41309e448732
+  metadata.gz: 9ed0d57a77d113e37ce3a9c8bf75ad8e35640a82eb51d7af09f39409c26a04ae
+  data.tar.gz: a5a4092321c2245fd4416ffe2b6b50014b5a6af1a40f20a4ca55a1296b96a2ff
 SHA512:
-  metadata.gz: 646dca4eb44c96a67020f57a090c26715b003521c9c6afffad1becf031576c334ea03c99b61f795a35932935535c53a1899a960ab986480cb3f5eef5b9913b96
-  data.tar.gz: e1cc5d9357932e04cebae1aaa5a8dc7024e0755584ea21999b18004dba76726c10b23276ee6d98fc1580ffb5aad45aeb12fd3e1bf94cfc45fdee70aefda87f91
+  metadata.gz: abd2f5234927ee1ba553c40194865ccfca47e24338c0859b46c370f248d9f7e602068500d6a49bd80b8cb4a12ef3f3e78efb49ff3d30b628bc1fea519d3d3fd6
+  data.tar.gz: af733241e107742ddc702619ac8ab226daa72bdc515c9f591bb3317be1d3f6556070df8afa664066aca6b38466a84cf9c45c4b76e32c68d607ada759818f7f1c

data/README.md

@@ -165,8 +165,6 @@ Try Crystal. [HTS.cr](https://github.com/bio-cr/hts.cr) is implemented in Crysta
 
 ## Development
 
-![Diagram](diagram.svg)
-
 #### Compile from source code
 
 [GNU Autotools](https://en.wikipedia.org/wiki/GNU_Autotools) is required to compile htslib.

data/TUTORIAL.md

@@ -254,6 +254,51 @@ in.close
 out.close
 ```
 
+Writing and modifying auxiliary tags
+
+```ruby
+# Reading auxiliary tags
+bam = HTS::Bam.open("input.bam")
+record = bam.first
+aux = record.aux
+
+# Read tags
+alignment_score = aux["AS"]           # Auto-detect type
+mc_cigar = aux.get_string("MC")       # Type-specific getter
+edit_distance = aux.get_int("NM")     # Type-specific getter
+
+# Writing/updating auxiliary tags
+in_bam = HTS::Bam.open("input.bam")
+out_bam = HTS::Bam.open("output.bam", "wb")
+out_bam.write_header(in_bam.header)
+
+in_bam.each do |record|
+  aux = record.aux
+  
+  # Update or add tags using type-specific methods
+  aux.update_int("AS", 100)                    # Integer tag
+  aux.update_float("ZQ", 0.95)                 # Float tag
+  aux.update_string("RG", "sample1")           # String tag
+  aux.update_array("BC", [25, 30, 28, 32])     # Array tag
+  
+  # Or use the []= operator (auto-detects type)
+  aux["NM"] = 2                                # Integer
+  aux["ZS"] = "modified"                       # String
+  aux["ZF"] = 3.14                             # Float
+  aux["ZA"] = [1, 2, 3, 4]                     # Array
+  
+  # Check if tag exists
+  if aux.key?("XS")
+    aux.delete("XS")  # Delete tag
+  end
+  
+  out_bam.write(record)
+end
+
+in_bam.close
+out_bam.close
+```
+
 Create index
 
 ```ruby

data/lib/hts/bam/auxi.rb

@@ -55,6 +55,124 @@ module HTS
         get(key)
       end
 
+      # Set auxiliary tag value (auto-detects type from value)
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Integer, Float, String, Array] tag value
+      def []=(key, value)
+        case value
+        when Integer
+          update_int(key, value)
+        when Float
+          update_float(key, value)
+        when String
+          update_string(key, value)
+        when Array
+          update_array(key, value)
+        else
+          raise ArgumentError, "Unsupported type: #{value.class}"
+        end
+      end
+
+      # Update or add an integer tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Integer] integer value
+      def update_int(key, value)
+        ret = LibHTS.bam_aux_update_int(@record.struct, key, value.to_i)
+        raise "Failed to update integer tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Update or add a floating-point tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Float] floating-point value
+      def update_float(key, value)
+        ret = LibHTS.bam_aux_update_float(@record.struct, key, value.to_f)
+        raise "Failed to update float tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Update or add a string tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [String] string value
+      def update_string(key, value)
+        ret = LibHTS.bam_aux_update_str(@record.struct, key, -1, value.to_s)
+        raise "Failed to update string tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Update or add an array tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Array] array of integers or floats
+      # @param type [String, nil] element type ('c', 'C', 's', 'S', 'i', 'I', 'f'). Auto-detected if nil.
+      def update_array(key, value, type: nil)
+        raise ArgumentError, "Array cannot be empty" if value.empty?
+
+        # Auto-detect type if not specified
+        if type.nil?
+          if value.all? { |v| v.is_a?(Integer) }
+            # Use 'i' for signed 32-bit integers by default
+            type = "i"
+          elsif value.all? { |v| v.is_a?(Float) || v.is_a?(Integer) }
+            type = "f"
+          else
+            raise ArgumentError, "Array must contain only integers or floats"
+          end
+        end
+
+        # Convert array to appropriate C type
+        case type
+        when "c", "C", "s", "S", "i", "I"
+          # Integer types
+          ptr = FFI::MemoryPointer.new(:int32, value.size)
+          ptr.write_array_of_int32(value.map(&:to_i))
+          ret = LibHTS.bam_aux_update_array(@record.struct, key, type.ord, value.size, ptr)
+        when "f"
+          # Float type
+          ptr = FFI::MemoryPointer.new(:float, value.size)
+          ptr.write_array_of_float(value.map(&:to_f))
+          ret = LibHTS.bam_aux_update_array(@record.struct, key, type.ord, value.size, ptr)
+        else
+          raise ArgumentError, "Invalid array type: #{type}"
+        end
+
+        raise "Failed to update array tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Delete an auxiliary tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @return [Boolean] true if tag was deleted, false if tag was not found
+      def delete(key)
+        aux_ptr = LibHTS.bam_aux_get(@record.struct, key)
+        return false if aux_ptr.null?
+
+        ret = LibHTS.bam_aux_del(@record.struct, aux_ptr)
+        raise "Failed to delete tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        true
+      end
+
+      # Check if a tag exists
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @return [Boolean] true if tag exists
+      def key?(key)
+        aux_ptr = LibHTS.bam_aux_get(@record.struct, key)
+        !aux_ptr.null?
+      end
+
+      alias include? key?
+
       def first
         aux_ptr = first_pointer
         return nil if aux_ptr.null?

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)