htslib 0.3.2 → 0.4.0

data/lib/hts/bcf/header.rb

@@ -8,6 +8,19 @@ module HTS
     # NOTE: This class has a lot of methods that are not stable.
     # The method names and the number of arguments may change in the future.
     class Header
+      BCF_TYPE_MAP = {
+        int: "Integer",
+        integer: "Integer",
+        int32: "Integer",
+        float: "Float",
+        real: "Float",
+        string: "String",
+        str: "String",
+        character: "Character",
+        char: "Character",
+        flag: "Flag"
+      }.freeze
+
       def initialize(arg = nil)
         case arg
         when LibHTS::HtsFile
@@ -20,6 +33,12 @@ module HTS
           raise TypeError, "Invalid argument"
         end
 
+        @sync_depth = 0
+        @sync_needed = false
+        @subset_samples = nil
+        @subset_imap = nil
+        @subset_imap_pointer = nil
+
         yield self if block_given?
       end
 
@@ -36,13 +55,34 @@ module HTS
       end
 
       def set_version(version)
-        LibHTS.bcf_hdr_set_version(@bcf_hdr, version)
+        rc = LibHTS.bcf_hdr_set_version(@bcf_hdr, version)
+        raise "Failed to set VCF header version" if rc.negative?
+
+        mark_sync_needed!
+        sync_if_needed!
+        self
       end
 
       def nsamples
         LibHTS.bcf_hdr_nsamples(@bcf_hdr)
       end
 
+      def target_count
+        target_names.size
+      end
+
+      def get_tid(name)
+        name2id(name)
+      end
+
+      def target_name(rid)
+        id2name(rid)
+      end
+
+      def target_names
+        seqnames
+      end
+
       def samples
         # bcf_hdr_id2name is macro function
         @bcf_hdr[:samples]
@@ -50,17 +90,65 @@ module HTS
           .map(&:read_string)
       end
 
+      attr_reader :subset_samples, :subset_imap_pointer
+
+      def subset?
+        !@subset_imap.nil?
+      end
+
+      def subset_sample_count
+        subset? ? @subset_samples.length : 0
+      end
+
+      def subset(samples)
+        subset_samples = normalize_subset_samples(samples)
+        validate_subset_samples!(subset_samples)
+
+        nil
+        imap_pointer = nil
+        if subset_samples.empty?
+          subset_hdr = LibHTS.bcf_hdr_subset(@bcf_hdr, 0, ::FFI::Pointer::NULL, ::FFI::Pointer::NULL)
+        else
+          encoded_samples = subset_samples.map { |name| FFI::MemoryPointer.from_string(name) }
+          sample_pointers = FFI::MemoryPointer.new(:pointer, subset_samples.length)
+          sample_pointers.write_array_of_pointer(encoded_samples)
+          imap_pointer = FFI::MemoryPointer.new(:int, subset_samples.length)
+          subset_hdr = LibHTS.bcf_hdr_subset(@bcf_hdr, subset_samples.length, sample_pointers, imap_pointer)
+        end
+
+        raise SubsetError, "Failed to subset BCF header samples #{subset_samples.inspect}" if subset_hdr.to_ptr.null?
+
+        composed_imap = compose_subset_imap(read_subset_imap(imap_pointer, subset_samples.length))
+        self.class.new(subset_hdr).tap do |header|
+          header.send(:set_subset_state, subset_samples, composed_imap)
+        end
+      end
+
       def add_sample(sample, sync: true)
-        LibHTS.bcf_hdr_add_sample(@bcf_hdr, sample)
-        self.sync if sync
+        rc = LibHTS.bcf_hdr_add_sample(@bcf_hdr, sample)
+        raise "Failed to add sample #{sample}" if rc.negative?
+
+        mark_sync_needed!
+        sync_if_needed! if sync
+        self
       end
 
       def merge(hdr)
-        LibHTS.bcf_hdr_merge(@bcf_hdr, hdr.struct)
+        merged = LibHTS.bcf_hdr_merge(@bcf_hdr, hdr.struct)
+        raise "Failed to merge BCF headers" if merged.to_ptr.null?
+
+        @bcf_hdr = merged
+        mark_sync_needed!
+        sync_if_needed!
+        self
       end
 
       def sync
-        LibHTS.bcf_hdr_sync(@bcf_hdr)
+        rc = LibHTS.bcf_hdr_sync(@bcf_hdr)
+        raise "Failed to sync BCF header" if rc.negative?
+
+        @sync_needed = false
+        self
       end
 
       def read_bcf(fname)
@@ -68,32 +156,121 @@ module HTS
       end
 
       def append(line)
-        LibHTS.bcf_hdr_append(@bcf_hdr, line)
+        rc = LibHTS.bcf_hdr_append(@bcf_hdr, line)
+        raise "Failed to append VCF header line" if rc.negative?
+
+        mark_sync_needed!
+        self
       end
 
-      def delete(bcf_hl_type, key) # FIXME
+      def delete(bcf_hl_type, key = nil) # FIXME
+        existed = hrec_exists?(bcf_hl_type, key)
         type = bcf_hl_type_to_int(bcf_hl_type)
         LibHTS.bcf_hdr_remove(@bcf_hdr, type, key)
+        mark_sync_needed! if existed
+        existed
       end
 
       def get_hrec(bcf_hl_type, key, value, str_class = nil)
         type = bcf_hl_type_to_int(bcf_hl_type)
-        hrec = LibHTS.bcf_hdr_get_hrec(@bcf_hdr, type, key, value, str_class)
-        HeaderRecord.new(hrec)
+        hrec = borrowed_hrec(type, key, value, str_class)
+        return nil if hrec.to_ptr.null?
+
+        HeaderRecord.new(owned_hrec(hrec))
+      end
+
+      def edit
+        @sync_depth += 1
+        yield self
+        self
+      ensure
+        @sync_depth -= 1
+        sync_if_needed!
+      end
+
+      def add_contig(id, length: nil, **attributes)
+        fields = [["ID", id.to_s]]
+        fields << ["length", length.to_s] unless length.nil?
+        fields.concat normalize_meta_attributes(attributes)
+        append_structured_meta("contig", fields)
+      end
+
+      def remove_contig(id)
+        delete("CONTIG", id.to_s).tap { sync_if_needed! }
+      end
+
+      def add_filter(id, description:, **attributes)
+        fields = [["ID", id.to_s], ["Description", description.to_s]]
+        fields.concat normalize_meta_attributes(attributes)
+        append_structured_meta("FILTER", fields)
+      end
+
+      def remove_filter(id)
+        delete("FILTER", id.to_s).tap { sync_if_needed! }
+      end
+
+      def add_info(id, number:, type:, description:, **attributes)
+        fields = [["ID", id.to_s], ["Number", normalize_bcf_number(number)], ["Type", normalize_bcf_type(type)],
+                  ["Description", description.to_s]]
+        fields.concat normalize_meta_attributes(attributes)
+        append_structured_meta("INFO", fields)
+      end
+
+      def update_info(id, number:, type:, description:, **attributes)
+        delete("INFO", id.to_s)
+        add_info(id, number:, type:, description:, **attributes)
+      end
+
+      def remove_info(id)
+        delete("INFO", id.to_s).tap { sync_if_needed! }
+      end
+
+      def add_format(id, number:, type:, description:, **attributes)
+        fields = [["ID", id.to_s], ["Number", normalize_bcf_number(number)], ["Type", normalize_bcf_type(type)],
+                  ["Description", description.to_s]]
+        fields.concat normalize_meta_attributes(attributes)
+        append_structured_meta("FORMAT", fields)
+      end
+
+      def update_format(id, number:, type:, description:, **attributes)
+        delete("FORMAT", id.to_s)
+        add_format(id, number:, type:, description:, **attributes)
+      end
+
+      def remove_format(id)
+        delete("FORMAT", id.to_s).tap { sync_if_needed! }
+      end
+
+      def add_meta(key, value = nil, **attributes)
+        if attributes.empty?
+          append("###{key}=#{value}")
+          sync_if_needed!
+          self
+        else
+          append_structured_meta(key.to_s, normalize_meta_attributes(attributes))
+        end
       end
 
       def seqnames
         n = FFI::MemoryPointer.new(:int)
         names = LibHTS.bcf_hdr_seqnames(@bcf_hdr, n)
-        names.read_array_of_pointer(n.read_int)
-             .map(&:read_string)
+        begin
+          names.read_array_of_pointer(n.read_int)
+               .map(&:read_string)
+        ensure
+          LibHTS.hts_free(names) unless names.null?
+        end
       end
 
       def to_s
         kstr = LibHTS::KString.new
-        raise "Failed to get header string" unless LibHTS.bcf_hdr_format(@bcf_hdr, 0, kstr)
+        begin
+          raise "Failed to get header string" if LibHTS.bcf_hdr_format(@bcf_hdr, 0, kstr).negative?
 
-        kstr[:s]
+          kstr.read_string_copy
+        ensure
+          kstr.free_buffer
+        end
       end
 
       def name2id(name)
@@ -106,6 +283,82 @@ module HTS
 
       private
 
+      def normalize_bcf_type(type)
+        BCF_TYPE_MAP.fetch(type.to_sym, type.to_s)
+      end
+
+      def normalize_bcf_number(number)
+        case number
+        when :a, :A then "A"
+        when :r, :R then "R"
+        when :g, :G then "G"
+        when :variable, :var, :dot then "."
+        else number.to_s
+        end
+      end
+
+      def normalize_meta_attributes(attributes)
+        attributes.map do |key, value|
+          meta_key = key.to_s.split("_").map.with_index { |part, index| index.zero? ? part : part.capitalize }.join
+          meta_value = value.is_a?(Array) ? value.join(",") : value.to_s
+          [meta_key, meta_value]
+        end
+      end
+
+      def append_structured_meta(label, fields)
+        body = fields.map { |key, value| "#{key}=#{format_meta_value(key, value)}" }.join(",")
+        append("###{label}=<#{body}>")
+        sync_if_needed!
+        self
+      end
+
+      def format_meta_value(key, value)
+        return quote_meta_value(value) if key == "Description"
+        return value if value.match?(/\A[[:alnum:]_.:+-]+\z/)
+
+        quote_meta_value(value)
+      end
+
+      def quote_meta_value(value)
+        %("#{value.gsub(/([\\"])/, '\\\\1')}")
+      end
+
+      def mark_sync_needed!
+        @sync_needed = true
+      end
+
+      def sync_if_needed!
+        sync if @sync_needed && @sync_depth.zero?
+      end
+
+      def hrec_exists?(bcf_hl_type, key)
+        type = bcf_hl_type_to_int(bcf_hl_type)
+        lookup_key, lookup_value, str_class = hrec_lookup_args(type, key)
+        hrec = borrowed_hrec(type, lookup_key, lookup_value, str_class)
+        !hrec.to_ptr.null?
+      end
+
+      def borrowed_hrec(type, key, value, str_class)
+        LibHTS.bcf_hdr_get_hrec(@bcf_hdr, type, key, value, str_class)
+      end
+
+      def owned_hrec(hrec)
+        LibHTS.bcf_hrec_dup(hrec).tap do |owned|
+          raise "Failed to duplicate BCF header record" if owned.to_ptr.null?
+        end
+      end
+
+      def hrec_lookup_args(type, key)
+        case type
+        when LibHTS::BCF_HL_FLT, LibHTS::BCF_HL_INFO, LibHTS::BCF_HL_FMT, LibHTS::BCF_HL_CTG
+          ["ID", key, nil]
+        when LibHTS::BCF_HL_GEN
+          [key, nil, nil]
+        else
+          ["ID", key, nil]
+        end
+      end
+
       def bcf_hl_type_to_int(bcf_hl_type)
         return bcf_hl_type if bcf_hl_type.is_a?(Integer)
 
@@ -129,6 +382,60 @@ module HTS
 
       def initialize_copy(orig)
         @bcf_hdr = LibHTS.bcf_hdr_dup(orig.struct)
+        @sync_depth = 0
+        @sync_needed = false
+        set_subset_state(orig.subset_samples, orig.send(:subset_imap))
+      end
+
+      protected
+
+      attr_reader :subset_imap
+
+      def set_subset_state(samples, imap)
+        @subset_samples = samples&.dup
+        @subset_imap = imap&.dup
+        @subset_imap_pointer = build_subset_imap_pointer(@subset_imap)
+      end
+
+      private
+
+      def normalize_subset_samples(samples)
+        case samples
+        when String
+          [samples]
+        else
+          Array(samples).map(&:to_s)
+        end
+      rescue TypeError
+        raise SubsetError, "Sample subset must be a String or an Array of sample names"
+      end
+
+      def validate_subset_samples!(subset_samples)
+        duplicates = subset_samples.group_by(&:itself).select { |_name, group| group.length > 1 }.keys
+        raise SubsetError, "Duplicate sample names in subset: #{duplicates.join(', ')}" unless duplicates.empty?
+
+        missing = subset_samples.reject { |name| samples.include?(name) }
+        raise UnknownSampleError, "Unknown sample names: #{missing.join(', ')}" unless missing.empty?
+      end
+
+      def read_subset_imap(pointer, length)
+        return [] if length.zero?
+
+        pointer.read_array_of_int(length)
+      end
+
+      def compose_subset_imap(imap)
+        base_imap = @subset_imap || Array.new(samples.length, &:itself)
+        imap.map { |index| base_imap.fetch(index) }
+      end
+
+      def build_subset_imap_pointer(imap)
+        return nil unless imap
+        return nil if imap.empty?
+
+        FFI::MemoryPointer.new(:int, imap.length).tap do |pointer|
+          pointer.write_array_of_int(imap)
+        end
       end
     end
   end

data/lib/hts/bcf/header_record.rb

@@ -31,8 +31,12 @@ module HTS
 
       def to_s
         kstr = LibHTS::KString.new
-        LibHTS.bcf_hrec_format(@bcf_hrec, kstr)
-        kstr[:s]
+        begin
+          LibHTS.bcf_hrec_format(@bcf_hrec, kstr)
+          kstr.read_string_copy
+        ensure
+          kstr.free_buffer
+        end
       end
 
       private

data/lib/hts/bcf/info.rb

@@ -6,7 +6,6 @@ module 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,55 @@ module HTS
       # 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
+
+        actual_type = ht_type_to_sym(get_info_type(key))
+        if type && actual_type && !info_type_compatible?(actual_type, type.to_sym)
+          raise InfoTypeError, "Tag #{key} is not #{type_label(type)} INFO field"
         end
 
-        type ||= ht_type_to_sym(get_info_type(key))
+        type ||= actual_type
+        return nil if actual_type && !key?(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 InfoReadError, "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 +77,11 @@ module HTS
         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 +111,11 @@ module HTS
         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 +125,11 @@ module HTS
           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)
@@ -125,11 +157,19 @@ module HTS
           values.size,
           LibHTS::BCF_HT_INT
         )
-        raise "Failed to update INFO int field '#{key}': #{ret}" if ret < 0
+        raise InfoUpdateError, "Failed to update INFO int field '#{key}': #{ret}" if ret < 0
 
         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 UnsupportedInfoOperationError, "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
@@ -146,7 +186,7 @@ module HTS
           values.size,
           LibHTS::BCF_HT_REAL
         )
-        raise "Failed to update INFO float field '#{key}': #{ret}" if ret < 0
+        raise InfoUpdateError, "Failed to update INFO float field '#{key}': #{ret}" if ret < 0
 
         ret
       end
@@ -164,7 +204,7 @@ module HTS
           1,
           LibHTS::BCF_HT_STR
         )
-        raise "Failed to update INFO string field '#{key}': #{ret}" if ret < 0
+        raise InfoUpdateError, "Failed to update INFO string field '#{key}': #{ret}" if ret < 0
 
         ret
       end
@@ -194,7 +234,7 @@ module HTS
                   LibHTS::BCF_HT_FLAG
                 )
               end
-        raise "Failed to update INFO flag field '#{key}': #{ret}" if ret < 0
+        raise InfoUpdateError, "Failed to update INFO flag field '#{key}': #{ret}" if ret < 0
 
         ret
       end
@@ -203,9 +243,9 @@ module HTS
       # @param key [String] INFO tag name
       # @return [Boolean] true if field was deleted, false if it didn't exist
       def delete(key)
-        # Try to get current type to check existence
         type = get_info_type(key)
         return false if type.nil?
+        return false unless key?(key)
 
         # Delete by setting n=0
         ret = LibHTS.bcf_update_info(
@@ -225,9 +265,21 @@ module HTS
       # @param key [String] INFO tag name
       # @return [Boolean] true if the field exists
       def key?(key)
-        # Use get() to check if value is actually present
-        # (get_info_type only checks header, not actual value)
-        !get(key).nil?
+        type = header_info_type(key)
+        return false if type.nil?
+
+        ndst = FFI::MemoryPointer.new(:int)
+        ndst.write_int(0)
+        dst_ptr = FFI::MemoryPointer.new(:pointer)
+        dst_ptr.write_pointer(FFI::Pointer::NULL)
+
+        ret = LibHTS.bcf_get_info_values(@record.header.struct, @record.struct, key, dst_ptr, ndst, type)
+        type == LibHTS::BCF_HT_FLAG ? ret == 1 : ret >= 0
+      ensure
+        if dst_ptr
+          dst = dst_ptr.read_pointer
+          LibHTS.hts_free(dst) unless dst.null?
+        end
       end
 
       alias include? key?
@@ -277,16 +329,15 @@ module HTS
       end
 
       def get_info_type(key)
-        @record.struct[:n_info].times do |i|
-          info = LibHTS::BcfInfo.new(@record.struct[:d][:info] + i * LibHTS::BcfInfo.size)
-          k = info[:key]
-          id = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, k)
-          if id == key
-            type = LibHTS.bcf_hdr_id2type(@record.header.struct, LibHTS::BCF_HL_INFO, k)
-            return type
-          end
-        end
-        nil
+        header_info_type(key)
+      end
+
+      def header_info_type(key)
+        id = LibHTS.bcf_hdr_id2int(@record.header.struct, LibHTS::BCF_DT_ID, key)
+        return nil if id.negative?
+        return nil unless LibHTS.bcf_hdr_idinfo_exists(@record.header.struct, LibHTS::BCF_HL_INFO, id)
+
+        LibHTS.bcf_hdr_id2type(@record.header.struct, LibHTS::BCF_HL_INFO, id)
       end
 
       def ht_type_to_sym(t)
@@ -295,7 +346,39 @@ module HTS
         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
+
+      def info_type_compatible?(actual_type, requested_type)
+        case requested_type
+        when :int, :int32
+          actual_type == :int
+        when :int64, :long
+          %i[int int64].include?(actual_type)
+        when :float, :real
+          actual_type == :float
+        when :flag, :bool
+          actual_type == :flag
+        when :string, :str
+          actual_type == :string
+        else
+          actual_type == requested_type
+        end
+      end
+
+      def type_label(type)
+        case type.to_sym
+        when :int, :int32 then "integer"
+        when :int64, :long then "integer"
+        when :float, :real then "float"
+        when :flag, :bool then "flag"
+        when :string, :str then "string"
+        else type.to_s
         end
       end
     end