htslib 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1bf158506931c62ffae1a524158de9fbb451796a68a7586cf788203f67a8cc4
-  data.tar.gz: d3289551dac8783cfa23f1f8d44e1b4be44b6dab3d6369f816491ceea653188f
+  metadata.gz: 26b019acbf5b8e110829d2666710f9187923edc57a4af486be8fc4ac690cd0e0
+  data.tar.gz: 8edf3b8fc44ce5ce42f0d09f2dcfffdb3dd4b145e72aac28bf13b4daa6d952ad
 SHA512:
-  metadata.gz: d1c316a599c2dc08e6589f980e9dd4ae6d8d6bababbfef424f35e5c25453b667bdc48570578e88a9eba142553fffb25b49ae4de54a061f99f7cbf286988ec618
-  data.tar.gz: 8529c6a02c354419dd722abc0bd6f27ec514ffe980f4b0d7014914de11551a45c4e96b803bc77255c3b423129a8743a3c39556d9d3d44ec6c6692556485379cf
+  metadata.gz: 6429da59067ed17e863117a98320304eb9445b82eb0a8ed94c6afe0b5c01cd149797e068cfa6c14cb32f7e60c0cfeedfc9c49d47cf7a5d92191a3818ad8f63a6
+  data.tar.gz: 5f6ce5d70616eb23213ebde0a77b1a0efb66664263c839eb3d00bc08d957c77655d9b03c426573e3db7b5a9d459f8ec86077e771b55b51523fbda520ac82cfcb

data/TUTORIAL.md

@@ -254,6 +254,73 @@ in.close
 out.close
 ```
 
+Update INFO fields
+
+```ruby
+bcf = HTS::Bcf.open("in.vcf")
+record = bcf.first
+info = record.info
+
+info.update_int("DP", [30])
+# info.update_int64("DP", [2**40])     # Backend-dependent (BCF_HT_LONG)
+info.update_float("AF", [0.25])
+info.update_string("STR", "sample")
+info.update_flag("SOMATIC", true)
+
+info["DP"] = 100
+# Out-of-int32 integers require explicit update_int64
+```
+
+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_uint8("XI", 255)                  # Exact unsigned 8-bit integer tag
+  aux.update_float("ZQ", 0.95)                 # Float tag
+  aux.update_double("ZD", 0.125)               # Double tag
+  aux.update_char("XC", "Y")                  # Character tag
+  aux.update_hex("XH", "DEADBEEF")            # Hex string tag
+  aux.update_string("RG", "sample1")           # String tag
+  aux.update_array("BC", [25, 30, 28, 32])     # Array tag (default subtype: i)
+  aux.update_array("BQ", [25, 30, 28, 32], type: "C") # Array tag with explicit subtype
+  
+  # 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,179 @@ 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)
+        validate_tag!(key)
+        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 signed 8-bit integer tag.
+      def update_int8(key, value)
+        update_exact_integer(key, value, "c", -128, 127)
+      end
+
+      # Update or add an unsigned 8-bit integer tag.
+      def update_uint8(key, value)
+        update_exact_integer(key, value, "C", 0, 255)
+      end
+
+      # Update or add a signed 16-bit integer tag.
+      def update_int16(key, value)
+        update_exact_integer(key, value, "s", -32_768, 32_767)
+      end
+
+      # Update or add an unsigned 16-bit integer tag.
+      def update_uint16(key, value)
+        update_exact_integer(key, value, "S", 0, 65_535)
+      end
+
+      # Update or add a signed 32-bit integer tag.
+      def update_int32(key, value)
+        update_exact_integer(key, value, "i", -2_147_483_648, 2_147_483_647)
+      end
+
+      # Update or add an unsigned 32-bit integer tag.
+      def update_uint32(key, value)
+        update_exact_integer(key, value, "I", 0, 4_294_967_295)
+      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)
+        validate_tag!(key)
+        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)
+        validate_tag!(key)
+        string = value.to_s
+        validate_string_value!(string)
+        ret = LibHTS.bam_aux_update_str(@record.struct, key, -1, string)
+        raise "Failed to update string tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        string
+      end
+
+      # Update or add a character tag.
+      def update_char(key, value)
+        validate_tag!(key)
+
+        string = value.to_s
+        validate_char_value!(string)
+
+        replace_with_append(key, "A", string.b)
+        string
+      end
+
+      # Update or add a hexadecimal string tag.
+      def update_hex(key, value)
+        validate_tag!(key)
+
+        string = value.to_s
+        validate_hex_value!(string)
+
+        replace_with_append(key, "H", string.b + "\0")
+        string
+      end
+
+      # Update or add a double-precision floating-point tag.
+      def update_double(key, value)
+        validate_tag!(key)
+
+        replace_with_append(key, "d", [Float(value)].pack("E"))
+        value.to_f
+      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)
+        validate_tag!(key)
+        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
+
+        payload = pack_array_payload(value, type)
+        ptr = FFI::MemoryPointer.new(:uint8, payload.bytesize)
+        ptr.put_bytes(0, payload)
+        ret = LibHTS.bam_aux_update_array(@record.struct, key, type.ord, value.size, ptr)
+
+        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?
@@ -62,7 +235,7 @@ module HTS
         get_ruby_aux(aux_ptr)
       end
 
-      def each
+      def each_value
         return enum_for(__method__) unless block_given?
 
         aux_ptr = first_pointer
@@ -75,6 +248,27 @@ module HTS
         end
       end
 
+      # Iterate auxiliary tags with their SAM/BAM type.
+      #
+      # @yieldparam tag [String] 2-byte AUX tag name
+      # @yieldparam type [String] AUX type, e.g. "i", "Z", or "B:C"
+      # @yieldparam value [Object] Ruby representation of the AUX value
+      def each
+        return enum_for(__method__) unless block_given?
+
+        aux_ptr = first_pointer
+        return nil if aux_ptr.null?
+
+        loop do
+          tag = FFI::Pointer.new(aux_ptr.address - 2).read_string(2)
+          yield tag, aux_type(aux_ptr), get_ruby_aux(aux_ptr)
+          aux_ptr = LibHTS.bam_aux_next(@record.struct, aux_ptr)
+          break if aux_ptr.null?
+        end
+      end
+
+      alias each_pair each
+
       def to_h
         h = {}
         aux_ptr = first_pointer
@@ -95,8 +289,120 @@ module HTS
         LibHTS.bam_aux_first(@record.struct)
       end
 
+      def aux_type(aux_ptr)
+        type = aux_ptr.read_string(1)
+        return type unless type == "B"
+
+        "#{type}:#{aux_ptr.read_string(2)[1]}"
+      end
+
+      def validate_tag!(key)
+        return if key.is_a?(String) && key.bytesize == 2 && key.ascii_only?
+
+        raise ArgumentError, "AUX tag must be a 2-byte ASCII String"
+      end
+
+      def validate_string_value!(string)
+        return unless string.include?("\0")
+
+        raise ArgumentError, "String AUX tags must not contain NUL bytes"
+      end
+
+      def validate_char_value!(string)
+        return if string.bytesize == 1 && string.ascii_only? && /\A[!-~]\z/.match?(string)
+
+        raise ArgumentError, "Character AUX tags must be a single printable ASCII byte"
+      end
+
+      def validate_hex_value!(string)
+        raise ArgumentError, "Hex AUX tags must contain an even number of characters" if string.bytesize.odd?
+
+        return if string.ascii_only? && /\A[0-9A-Fa-f]*\z/.match?(string)
+
+        raise ArgumentError,
+              "Hex AUX tags must contain only ASCII hexadecimal characters"
+      end
+
+      def update_exact_integer(key, value, type, min, max)
+        validate_tag!(key)
+
+        integer = Integer(value)
+        raise RangeError, "Value #{integer} is out of range for AUX type #{type}" unless integer.between?(min, max)
+
+        replace_with_append(key, type, pack_scalar_payload(integer, type))
+        integer
+      end
+
+      def replace_with_append(key, type, payload)
+        delete(key) if key?(key)
+
+        ptr = FFI::MemoryPointer.new(:uint8, payload.bytesize)
+        ptr.put_bytes(0, payload)
+        ret = LibHTS.bam_aux_append(@record.struct, key, type.ord, payload.bytesize, ptr)
+        raise "Failed to update #{type} tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        true
+      end
+
+      def pack_scalar_payload(value, type)
+        case type
+        when "c"
+          [value].pack("c")
+        when "C"
+          [value].pack("C")
+        when "s"
+          [value].pack("s<")
+        when "S"
+          [value].pack("S<")
+        when "i"
+          [value].pack("l<")
+        when "I"
+          [value].pack("L<")
+        else
+          raise ArgumentError, "Unsupported scalar AUX type: #{type}"
+        end
+      end
+
+      def pack_array_payload(value, type)
+        case type
+        when "c"
+          validate_integer_array_range!(value, -128, 127, type)
+          value.pack("c*")
+        when "C"
+          validate_integer_array_range!(value, 0, 255, type)
+          value.pack("C*")
+        when "s"
+          validate_integer_array_range!(value, -32_768, 32_767, type)
+          value.pack("s<*")
+        when "S"
+          validate_integer_array_range!(value, 0, 65_535, type)
+          value.pack("S<*")
+        when "i"
+          validate_integer_array_range!(value, -2_147_483_648, 2_147_483_647, type)
+          value.pack("l<*")
+        when "I"
+          validate_integer_array_range!(value, 0, 4_294_967_295, type)
+          value.pack("L<*")
+        when "f"
+          value.map(&:to_f).pack("e*")
+        else
+          raise ArgumentError, "Invalid array type: #{type}"
+        end
+      end
+
+      def validate_integer_array_range!(value, min, max, type)
+        value.each do |element|
+          integer = Integer(element)
+          unless integer.between?(min, max)
+            raise RangeError, "Array element #{integer} is out of range for AUX array type #{type}"
+          end
+        end
+      end
+
       def get_ruby_aux(aux_ptr, type = nil)
-        type = type ? type.to_s : aux_ptr.read_string(1)
+        actual_type = aux_ptr.read_string(1)
+        type = type ? type.to_s : actual_type
+        validate_aux_type!(actual_type, type)
 
         # A (character), B (general array),
         # f (real number), H (hexadecimal array),
@@ -128,6 +434,27 @@ module HTS
           raise NotImplementedError, "type: #{type}"
         end
       end
+
+      def validate_aux_type!(actual_type, requested_type)
+        return if aux_type_compatible?(actual_type, requested_type)
+
+        raise TypeError, "AUX type mismatch: requested #{requested_type.inspect}, actual #{actual_type.inspect}"
+      end
+
+      def aux_type_compatible?(actual_type, requested_type)
+        case requested_type
+        when "i", "I", "c", "C", "s", "S"
+          %w[i I c C s S].include?(actual_type)
+        when "f", "d"
+          %w[f d].include?(actual_type)
+        when "Z", "H"
+          %w[Z H].include?(actual_type)
+        when "A", "B"
+          actual_type == requested_type
+        else
+          true
+        end
+      end
     end
   end
 end

data/lib/hts/bam/cigar.rb

@@ -15,11 +15,19 @@ module HTS
       def self.parse(str)
         c = FFI::MemoryPointer.new(:pointer)
         m = FFI::MemoryPointer.new(:size_t)
-        LibHTS.sam_parse_cigar(str, FFI::Pointer::NULL, c, m)
-        cigar_array = c.read_pointer.read_array_of_uint32(m.read(:size_t))
+        c.write_pointer(FFI::Pointer::NULL)
+        m.write(:size_t, 0)
+        ptr = nil
+        n_cigar = LibHTS.sam_parse_cigar(str, FFI::Pointer::NULL, c, m)
+        raise "sam_parse_cigar failed: #{n_cigar}" if n_cigar.negative?
+
+        ptr = c.read_pointer
+        cigar_array = ptr.null? ? [] : ptr.read_array_of_uint32(n_cigar)
         obj = new
         obj.array = cigar_array
         obj
+      ensure
+        LibHTS.hts_free(ptr) if ptr && !ptr.null?
       end
 
       def initialize(record = nil)