Update BCF INFO handling with int64 support and enhance tests for new functionalities

Author: kojix2

TUTORIAL.md

@@ -254,6 +254,23 @@ 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

lib/hts/bcf/format.rb

@@ -5,7 +5,6 @@ class Bcf < Hts
     class Format
       def initialize(record)
         @record = record
-        @p1 = FFI::MemoryPointer.new(:pointer) # FIXME: naming
       end
 
       # @note: Why is this method named "get" instead of "fetch"?
@@ -14,15 +13,22 @@ def initialize(record)
       # I think they are better than `fetch_int`` and `fetch_float`.
       def get(key, type = nil)
         n = FFI::MemoryPointer.new(:int)
-        p1 = @p1
+        p1 = FFI::MemoryPointer.new(:pointer)
+        p1.write_pointer(FFI::Pointer::NULL)
         h = @record.header.struct
         r = @record.struct
 
-        format_values = proc do |typ|
+        format_values = proc do |typ, reader|
           ret = LibHTS.bcf_get_format_values(h, r, key, p1, n, typ)
           return nil if ret < 0 # return from method.
 
-          p1.read_pointer
+          dst = p1.read_pointer
+          begin
+            reader.call(dst, n.read_int)
+          ensure
+            LibHTS.hts_free(dst) unless dst.null?
+            p1.write_pointer(FFI::Pointer::NULL)
+          end
         end
 
         # The GT FORMAT field is special in that it is marked as a string in the header,
@@ -35,11 +41,9 @@ def get(key, type = nil)
 
         case type&.to_sym
         when :int, :int32
-          format_values.call(LibHTS::BCF_HT_INT)
-                       .read_array_of_int32(n.read_int)
+          format_values.call(LibHTS::BCF_HT_INT, ->(dst, len) { dst.read_array_of_int32(len) })
         when :float, :real
-          format_values.call(LibHTS::BCF_HT_REAL)
-                       .read_array_of_float(n.read_int)
+          format_values.call(LibHTS::BCF_HT_REAL, ->(dst, len) { dst.read_array_of_float(len) })
         when :flag
           raise NotImplementedError, "Flag type not implemented yet. " \
           "Please file an issue on GitHub."

lib/hts/bcf/info.rb

@@ -6,7 +6,6 @@ class Bcf < Hts
     class Info
       def initialize(record)
         @record = record
-        @p1 = FFI::MemoryPointer.new(:pointer) # FIXME: naming
       end
 
       # @note Specify the type. If you don't specify a type, it will still work, but it will be slower.
@@ -16,37 +15,49 @@ def initialize(record)
       # I think they are better than `fetch_int`` and `fetch_float`.
       def get(key, type = nil)
         n = FFI::MemoryPointer.new(:int)
-        p1 = @p1
+        p1 = FFI::MemoryPointer.new(:pointer)
+        p1.write_pointer(FFI::Pointer::NULL)
         h = @record.header.struct
         r = @record.struct
 
-        info_values = proc do |typ|
+        info_values = proc do |typ, reader|
           ret = LibHTS.bcf_get_info_values(h, r, key, p1, n, typ)
           return nil if ret < 0 # return from method.
 
-          p1.read_pointer
+          dst = p1.read_pointer
+          begin
+            reader.call(dst, n.read_int)
+          ensure
+            LibHTS.hts_free(dst) unless dst.null?
+            p1.write_pointer(FFI::Pointer::NULL)
+          end
         end
 
         type ||= ht_type_to_sym(get_info_type(key))
 
         case type&.to_sym
         when :int, :int32
-          info_values.call(LibHTS::BCF_HT_INT)
-                     .read_array_of_int32(n.read_int)
+          info_values.call(LibHTS::BCF_HT_INT, ->(dst, len) { dst.read_array_of_int32(len) })
+        when :int64, :long
+          info_values.call(LibHTS::BCF_HT_LONG, ->(dst, len) { dst.read_array_of_int64(len) })
         when :float, :real
-          info_values.call(LibHTS::BCF_HT_REAL)
-                     .read_array_of_float(n.read_int)
+          info_values.call(LibHTS::BCF_HT_REAL, ->(dst, len) { dst.read_array_of_float(len) })
         when :flag, :bool
-          case ret = LibHTS.bcf_get_info_flag(h, r, key, p1, n)
-          when 1 then true
-          when 0 then false
-          when -1 then nil
-          else
-            raise "Unknown return value from bcf_get_info_flag: #{ret}"
+          begin
+            case ret = LibHTS.bcf_get_info_flag(h, r, key, p1, n)
+            when 1 then true
+            when 0 then false
+            when -1 then nil
+            else
+              raise "Unknown return value from bcf_get_info_flag: #{ret}"
+            end
+          ensure
+            dst = p1.read_pointer
+            LibHTS.hts_free(dst) unless dst.null?
+            p1.write_pointer(FFI::Pointer::NULL)
           end
         when :string, :str
-          info_values.call(LibHTS::BCF_HT_STR)
-                     .read_string
+          info_values.call(LibHTS::BCF_HT_STR, ->(dst, _len) { dst.read_string })
         end
       end
 
@@ -60,6 +71,11 @@ def get_float(key)
         get(key, :float)
       end
 
+      # For compatibility with HTS.cr.
+      def get_int64(key)
+        get(key, :int64)
+      end
+
       # For compatibility with HTS.cr.
       def get_string(key)
         get(key, :string)
@@ -89,6 +105,9 @@ def []=(key, value)
         when true, false
           update_flag(key, value)
         when Integer
+          unless int32_range?(value)
+            raise RangeError, "Integer out of int32 range for []=. Current htslib backend does not support int64 INFO update."
+          end
           update_int(key, [value])
         when Float
           update_float(key, [value])
@@ -98,6 +117,9 @@ def []=(key, value)
           if value.empty?
             raise ArgumentError, "Cannot set INFO field to empty array. Use nil to delete."
           elsif value.all? { |v| v.is_a?(Integer) }
+            unless value.all? { |v| int32_range?(v) }
+              raise RangeError, "Integer array contains out-of-int32 values for []=. Current htslib backend does not support int64 INFO update."
+            end
             update_int(key, value)
           elsif value.all? { |v| v.is_a?(Numeric) }
             update_float(key, value)
@@ -130,6 +152,14 @@ def update_int(key, values)
         ret
       end
 
+      # Update INFO field with int64 value(s).
+      # @note int64 INFO values are primarily relevant for VCF output.
+      # @param key [String] INFO tag name
+      # @param values [Array<Integer>] integer values (use single-element array for scalar)
+      def update_int64(key, values)
+        raise NotImplementedError, "htslib backend does not implement int64 INFO update (BCF_HT_LONG)"
+      end
+
       # Update INFO field with float value(s).
       # For compatibility with HTS.cr.
       # @param key [String] INFO tag name
@@ -295,9 +325,13 @@ def ht_type_to_sym(t)
         when LibHTS::BCF_HT_INT then :int
         when LibHTS::BCF_HT_REAL then :float
         when LibHTS::BCF_HT_STR then :string
-        when LibHTS::BCF_HT_LONG then :float
+        when LibHTS::BCF_HT_LONG then :int64
         end
       end
+
+      def int32_range?(value)
+        value >= -2_147_483_648 && value <= 2_147_483_647
+      end
     end
   end
 end

lib/hts/libhts/vcf_funcs.rb

@@ -97,6 +97,11 @@ def bcf_update_info_int32(hdr, line, key, values, n)
         bcf_update_info(hdr, line, key, values, n, BCF_HT_INT)
       end
 
+      # Function for updating INFO fields (int64; VCF only)
+      def bcf_update_info_int64(hdr, line, key, values, n)
+        bcf_update_info(hdr, line, key, values, n, BCF_HT_LONG)
+      end
+
       # Function for updating INFO fields
       def bcf_update_info_float(hdr, line, key, values, n)
         bcf_update_info(hdr, line, key, values, n, BCF_HT_REAL)
@@ -175,6 +180,11 @@ def bcf_get_info_int32(hdr, line, tag, dst, ndst)
         bcf_get_info_values(hdr, line, tag, dst, ndst, BCF_HT_INT)
       end
 
+      # Get INFO values (int64; VCF only)
+      def bcf_get_info_int64(hdr, line, tag, dst, ndst)
+        bcf_get_info_values(hdr, line, tag, dst, ndst, BCF_HT_LONG)
+      end
+
       # Get INFO values
       def bcf_get_info_float(hdr, line, tag, dst, ndst)
         bcf_get_info_values(hdr, line, tag, dst, ndst, BCF_HT_REAL)

test/bcf/info_test.rb

@@ -27,8 +27,11 @@ def test_get_with_type
 
   def test_get_like_crystal
     assert_equal [1, 2, 3, 4], @info.get_int("DP4")
+    assert_equal [1, 2, 3, 4], @info.get_int64("DP4")
     assert_equal [4], @info.get_int("AN")
+    assert_equal [4], @info.get_int64("AN")
     assert_equal [2], @info.get_int("AC")
+    assert_equal [2], @info.get_int64("AC")
     assert_equal true, @info.get_flag("INDEL")
     assert_equal "test", @info.get_string("STR")
   end
@@ -53,6 +56,8 @@ def test_get_unknown_key
     assert_nil @info.get("UNKNOWN")
     assert_nil @info.get("UNKNOWN", :int)
     assert_nil @info.get_int("UNKNOWN")
+    assert_nil @info.get("UNKNOWN", :int64)
+    assert_nil @info.get_int64("UNKNOWN")
     assert_nil @info.get("UNKNOWN", :float)
     assert_nil @info.get_float("UNKNOWN")
     assert_nil @info.get("UNKNOWN", :flag)

test/bcf_test.rb

@@ -230,9 +230,25 @@ def test_info_update_float
   end
 
   def test_info_update_string
-    # String INFO fields are rare in VCF, skip for now
-    # (would need to add string INFO to header first)
-    skip "String INFO fields require header definition"
+    require "tempfile"
+
+    Tempfile.create(["test_bcf_info_string_source", ".vcf"]) do |src|
+      src.write <<~VCF
+        ##fileformat=VCFv4.2
+        ##contig=<ID=1,length=1000>
+        ##INFO=<ID=STRX,Number=1,Type=String,Description="string info test">
+        #CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFO
+        1\t10\t.\tA\tT\t.\tPASS\t.
+      VCF
+      src.flush
+
+      bcf = HTS::Bcf.new(src.path)
+      record = bcf.first
+      info = record.info
+      info.update_string("STRX", "hello")
+      assert_equal "hello", info.get_string("STRX")
+      bcf.close
+    end
   end
 
   def test_info_update_flag