htslib 0.4.2 → 0.5.0

data/lib/hts/bcf/format.rb

@@ -3,500 +3,399 @@
 module HTS
   class Bcf < Hts
     class Format
-      def initialize(record)
-        @record = record
-      end
+      GT_MISSING = 0
+      GT_VECTOR_END = Native::BCF_INT32_VECTOR_END
 
-      # @note: Why is this method named "get" instead of "fetch"?
-      # This is for compatibility with the Crystal language
-      # which provides methods like `get_int`, `get_float`, etc.
-      # I think they are better than `fetch_int`` and `fetch_float`.
-      def get(key, type = nil)
-        return get_typed(key, type) unless type.nil?
-
-        return decode_genotypes if key == "GT"
-
-        case header_format_type(key)
-        when :int
-          decode_integer_values(key)
-        when :float
-          decode_float_values(key)
-        when :flag
-          raise_unsupported_format_flag(key)
-        when :string
-          get_string_values(key)
-        end
+      class << self
+        def gt_unphased(allele) = (Integer(allele) + 1) << 1
+        def gt_phased(allele) = ((Integer(allele) + 1) << 1) | 1
+        def gt_allele(value) = (Integer(value) >> 1) - 1
+        def gt_missing?(value) = (Integer(value) >> 1).zero?
+        def gt_phased?(value) = (Integer(value) & 1) == 1
+        def gt_vector_end?(value) = Integer(value) == GT_VECTOR_END
       end
 
-      def get_raw(key, type = nil)
-        # The GT FORMAT field is special in that it is marked as a string in the header,
-        # but it is actually encoded as an integer.
-        type = if type.nil?
-                 key == "GT" ? :int : header_format_type(key)
-               else
-                 type.to_sym
-               end
+      BufferState = Struct.new(:generation)
 
-        case type
-        when :int, :int32
-          raise_unsupported_format_flag(key)
-          get_numeric_values(key, LibHTS::BCF_HT_INT, "integer") { |dst, len| dst.read_array_of_int32(len) }
-        when :float, :real
-          raise_unsupported_format_flag(key)
-          get_float_words(key)
-        when :flag
-          raise_unsupported_format_flag(key)
-        when :string, :str
-          return decode_genotypes if key == "GT"
-
-          raise_unsupported_format_flag(key)
-          get_string_values(key)
+      class NumericVectorView
+        include Enumerable
+        def initialize(type) = @type = type
+
+        def reset(values, buffer, generation)
+          @values = values
+          @buffer = buffer
+          @generation = generation
+          self
         end
-      end
 
-      # For compatibility with HTS.cr.
-      def get_int(key)
-        get_raw(key, :int)
-      end
+        def each(&block)
+          return to_enum(__method__) unless block_given?
 
-      # For compatibility with HTS.cr.
-      def get_float(key)
-        get_typed(key, :float)
-      end
+          ensure_valid!
+          @values.each(&block)
+          self
+        end
 
-      # For compatibility with HTS.cr.
-      def get_flag(key)
-        get_raw(key, :flag)
-      end
+        def to_a = each.to_a
 
-      # For compatibility with HTS.cr.
-      def get_string(key)
-        get_raw(key, :string)
-      end
+        private
 
-      # For compatibility with HTS.cr.
-      def get_genotypes
-        get_numeric_values("GT", LibHTS::BCF_HT_INT, "genotype") { |dst, len| dst.read_array_of_int32(len) }
-      end
+        def ensure_valid!
+          return if @buffer.generation == @generation
 
-      def [](key)
-        get(key)
+          raise InvalidBorrowedViewError,
+                "borrowed FORMAT view is no longer valid"
+        end
       end
 
-      def update_int(key, values)
-        raise UnsupportedFormatOperationError, "Use update_genotypes for GT" if key == "GT"
+      class GenotypeView
+        include Enumerable
 
-        ensure_expected_format_type!(key, :int, "integer")
-        values = normalize_int_values(values)
-        validate_numeric_sample_count!(key, values.size)
+        def reset(values, buffer, generation)
+          @values = values
+          @buffer = buffer
+          @generation = generation
+          self
+        end
 
-        ptr = FFI::MemoryPointer.new(:int32, values.size)
-        ptr.write_array_of_int32(values)
-        check_update_rc!(LibHTS.bcf_update_format_int32(@record.header.struct, @record.struct, key, ptr, values.size),
-                         key)
-      end
+        def each_allele
+          return to_enum(__method__) unless block_given?
 
-      def update_float(key, values)
-        ensure_expected_format_type!(key, :float, "float")
-        values = normalize_float_values(values)
-        validate_numeric_sample_count!(key, values.size)
+          ensure_valid!
+          @values.each_with_index do |encoded, index|
+            break if encoded == GT_VECTOR_END
 
-        ptr = FFI::MemoryPointer.new(:float, values.size)
-        ptr.write_array_of_float(values)
-        check_update_rc!(LibHTS.bcf_update_format_float(@record.header.struct, @record.struct, key, ptr, values.size),
-                         key)
-      end
+            missing = gt_missing?(encoded)
+            # The phase bit describes the separator before this allele. It has
+            # no semantic meaning for the first allele, and HTSlib versions do
+            # not consistently clear it while parsing VCF text.
+            phased = index.positive? && gt_phased?(encoded)
+            yield(missing ? nil : gt_allele(encoded), phased, missing)
+          end
+          self
+        end
+        alias each each_allele
+        def to_s
+          result = +""
+          each_allele.with_index do |(allele, phased, missing), index|
+            result << (phased && index.positive? ? "|" : "/") if index.positive?
+            result << (missing ? "." : allele.to_s)
+          end
+          result
+        end
 
-      def update_string(key, values)
-        raise UnsupportedFormatOperationError, "Use update_genotypes for GT" if key == "GT"
+        private
 
-        ensure_expected_format_type!(key, :string, "string")
-        values = normalize_string_values(values)
-        validate_string_sample_count!(key, values.size)
+        def ensure_valid!
+          return if @buffer.generation == @generation
+
+          raise InvalidBorrowedViewError,
+                "borrowed FORMAT view is no longer valid"
+        end
 
-        strings = values.map { |value| FFI::MemoryPointer.from_string(value) }
-        ptr = FFI::MemoryPointer.new(:pointer, strings.size)
-        ptr.write_array_of_pointer(strings)
-        check_update_rc!(LibHTS.bcf_update_format_string(@record.header.struct, @record.struct, key, ptr, values.size),
-                         key)
+        def gt_missing?(value) = (value >> 1).zero?
+        def gt_allele(value) = (value >> 1) - 1
+        def gt_phased?(value) = (value & 1) == 1
       end
 
-      def update_genotypes(values)
-        ensure_gt_defined!
+      def initialize(record)
+        @record = record
+        @buffers = {}
+      end
 
-        values = normalize_int_values(values)
-        validate_numeric_sample_count!("GT", values.size)
+      def get(key, type = nil)
+        key = key.to_s
+        schema = format_schema(key)
+        return nil unless schema
 
-        ptr = FFI::MemoryPointer.new(:int32, values.size)
-        ptr.write_array_of_int32(values)
-        check_update_rc!(LibHTS.bcf_update_genotypes(@record.header.struct, @record.struct, ptr, values.size), "GT")
-      end
+        raise_unsupported_flag(key) if schema.first == :flag
 
-      def delete(key)
-        return false if header_format_type(key).nil?
-        return false unless format_present?(key)
-
-        type = key == "GT" ? LibHTS::BCF_HT_INT : header_format_type_code(key)
-        ret = LibHTS.bcf_update_format(@record.header.struct, @record.struct, key, FFI::Pointer::NULL, 0, type)
-        raise FormatUpdateError, "Failed to delete FORMAT field '#{key}': #{ret}" if ret < 0
-
-        true
-      end
-
-      def fields
-        ids.map do |id|
-          name = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, id)
-          num  = LibHTS.bcf_hdr_id2number(@record.header.struct, LibHTS::BCF_HL_FMT, id)
-          type = LibHTS.bcf_hdr_id2type(@record.header.struct, LibHTS::BCF_HL_FMT, id)
-          {
-            name:,
-            n: num,
-            type: ht_type_to_sym(type),
-            id:
-          }
+        requested = type&.to_sym
+        if requested && !type_compatible?(schema.first, requested, key)
+          raise FormatTypeError, "Tag #{key} is not #{type_label(requested)} FORMAT field"
         end
-      end
+        return genotype_strings(key) if key == "GT" && (!requested || %i[string str].include?(requested))
 
-      def length
-        @record.struct[:n_fmt]
-      end
+        return get_float(key) if %i[float real].include?(requested)
 
-      def size
-        length
-      end
+        raw = get_raw(key, requested)
+        return raw if requested
+        return raw if schema.first == :string
 
-      def to_h
-        ret = {}
-        ids.each do |id|
-          name = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, id)
-          ret[name] = get(name)
-        end
-        ret
+        shape_values(raw, key, schema)
       end
 
-      # def genotypes; end
-
-      private
+      def get_raw(key, type = nil)
+        key = key.to_s
+        schema = format_schema(key)
+        return nil unless schema
 
-      def get_numeric_values(key, hts_type, expected_type)
-        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_format_values(@record.header.struct, @record.struct, key, dst_ptr, ndst, hts_type)
-        ret = normalize_format_rc(ret, key, expected_type)
-        return nil unless ret
-
-        dst = dst_ptr.read_pointer
-        begin
-          yield(dst, ret)
-        ensure
-          LibHTS.hts_free(dst) unless dst.null?
-          dst_ptr.write_pointer(FFI::Pointer::NULL)
+        requested = type&.to_sym
+        if requested && !type_compatible?(schema.first, requested, key)
+          raise FormatTypeError, "Tag #{key} is not #{type_label(requested)} FORMAT field"
         end
+
+        code = key == "GT" ? Native::BCF_HT_INT : type_code(requested || schema.first)
+        raw_float = code == Native::BCF_HT_REAL
+        invalidate_views!(key)
+        native.format_get(header_native, key, code, raw_float)
       end
 
-      def get_string_values(key)
-        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_format_string(@record.header.struct, @record.struct, key, dst_ptr, ndst)
-        ret = normalize_format_rc(ret, key, "string")
-        return nil unless ret
-
-        dst = dst_ptr.read_pointer
-        sample_count = @record.header.nsamples
-        begin
-          dst.read_array_of_pointer(sample_count).map(&:read_string)
-        ensure
-          unless dst.null?
-            collapsed = sample_count.positive? ? dst.get_pointer(0) : FFI::Pointer::NULL
-            LibHTS.hts_free(collapsed) unless collapsed.null?
-            LibHTS.hts_free(dst)
-          end
-          dst_ptr.write_pointer(FFI::Pointer::NULL)
-        end
+      def get_int(key) = get(key, :int)
+
+      def get_float(key)
+        words = get_raw(key, :float)
+        words&.map { |word| decode_float_word(word) }
       end
 
-      def decode_integer_values(key)
+      def get_flag(key) = get(key, :flag)
+      def get_string(key) = get(key, :string)
+      def get_genotypes = get_raw("GT", :int)
+      def [](key) = get(key)
+
+      def each_genotype(key = "GT")
+        return enum_for(__method__, key) unless block_given?
+        raise ArgumentError, "genotype FORMAT key must be GT" unless key.to_s == "GT"
+
         values = get_raw(key, :int)
         return nil unless values
 
-        sample_values = split_sample_values(values)
-        if scalar_format?(key)
-          sample_values.map do |values_per_sample|
-            map_integer_missing_value(trim_integer_vector_end(values_per_sample).first)
-          end
-        else
-          sample_values.map do |values_per_sample|
-            map_integer_missing(trim_integer_vector_end(values_per_sample))
-          end
+        count, width = sample_layout(values.length)
+        buffer, generation = advance_buffer(key, :genotype)
+        view = GenotypeView.new
+        count.times do |sample|
+          yield sample, view.reset(values.slice(sample * width, width), buffer, generation)
         end
+        self
       end
 
-      def decode_float_values(key)
-        values = get_float_words(key)
+      def genotype_at(key, sample_index)
+        values = get_raw(key, :int)
         return nil unless values
 
-        sample_values = split_sample_values(values)
-        if scalar_format?(key)
-          sample_values.map do |values_per_sample|
-            decode_float_word(trim_float_vector_end(values_per_sample).first)
-          end
-        else
-          sample_values.map do |values_per_sample|
-            map_float_words(trim_float_vector_end(values_per_sample))
-          end
-        end
-      end
+        count, width = sample_layout(values.length)
+        sample_index = Integer(sample_index)
+        sample_index += count if sample_index.negative?
+        raise IndexError, "sample index #{sample_index} outside of FORMAT" unless sample_index.between?(0, count - 1)
 
-      def decode_genotypes
-        genotypes = get_genotypes
-        return nil unless genotypes
+        buffer, generation = advance_buffer(key, :genotype)
+        GenotypeView.new.reset(values.slice(sample_index * width, width), buffer, generation)
+      end
 
-        split_sample_values(genotypes).map do |sample_values|
-          decode_genotype_sample(trim_genotype_vector_end(sample_values))
-        end
+      def genotype_strings(key = "GT")
+        strings = []
+        found = each_genotype(key) { |_, genotype| strings << genotype.to_s }
+        found ? strings : nil
       end
 
-      def decode_genotype_sample(values)
-        values.each_with_index.map do |value, index|
-          allele = if LibHTS.bcf_gt_is_missing(value) != 0
-                     "."
-                   else
-                     LibHTS.bcf_gt_allele(value).to_s
-                   end
+      def each_i32(key)
+        return enum_for(__method__, key) unless block_given?
 
-          next allele if index.zero?
+        ensure_scalar!(key, :int)
+        values = get_raw(key, :int)
+        return self unless values
 
-          separator = LibHTS.bcf_gt_is_phased(value) != 0 ? "|" : "/"
-          "#{separator}#{allele}"
-        end.join
+        values.each_with_index { |value, index| yield index, missing_int(value) }
+        self
       end
 
-      def split_sample_values(values)
-        sample_count = @record.header.nsamples
-        return [] if sample_count <= 0
+      def each_i32_vector(key, &block) = each_vector(key, :int, &block)
+      def each_f32_vector(key, &block) = each_vector(key, :float, &block)
 
-        raise FormatReadError, "Failed to split FORMAT values by sample" unless (values.size % sample_count).zero?
+      def update_int(key, values)
+        raise UnsupportedFormatOperationError, "Use update_genotypes for GT" if key.to_s == "GT"
 
-        values_per_sample = values.size / sample_count
-        Array.new(sample_count) do |sample_index|
-          start = sample_index * values_per_sample
-          values[start, values_per_sample]
-        end
+        values = normalize_values(values) { |value| Integer(value) }
+        validate_sample_divisibility!(key, values.length)
+        update_format(key, Native::BCF_HT_INT, values)
       end
 
-      def trim_genotype_vector_end(values)
-        end_index = values.index { |value| LibHTS.bcf_gt_is_vector_end(value) != 0 } || values.size
-        values[0, end_index]
+      def update_float(key, values)
+        values = normalize_values(values, &:to_f)
+        validate_sample_divisibility!(key, values.length)
+        update_format(key, Native::BCF_HT_REAL, values)
       end
 
-      def trim_integer_vector_end(values)
-        end_index = values.index { |value| value == LibHTS.bcf_int32_vector_end } || values.size
-        values[0, end_index]
-      end
+      def update_float_words(key, values)
+        values = normalize_values(values) { |value| Integer(value) }
+        validate_sample_divisibility!(key, values.length)
+        raise FormatDefinitionError, "FORMAT tag #{key} not defined in header" unless format_schema(key)
 
-      def trim_float_vector_end(values)
-        end_index = values.index(LibHTS.bcf_float_vector_end) || values.size
-        values[0, end_index]
-      end
+        result = native.format_update_float_words(header_native, key.to_s, values)
+        raise FormatUpdateError, "Failed to update FORMAT field '#{key}': #{result}" if result.negative?
 
-      def map_integer_missing(values)
-        values.map { |value| map_integer_missing_value(value) }
+        result
       end
 
-      def map_integer_missing_value(value)
-        value == LibHTS.bcf_int32_missing ? nil : value
-      end
+      def update_string(key, values)
+        values = Array(values).map(&:to_s)
+        expected = sample_count
+        unless values.length == expected
+          raise ArgumentError, "FORMAT string values for #{key} must provide one entry per sample (#{expected})"
+        end
 
-      def map_float_words(values)
-        values.map { |value| decode_float_word(value) }
+        update_format(key, Native::BCF_HT_STR, values)
       end
 
-      def decode_float_word(value)
-        return nil if value == LibHTS.bcf_float_missing
-        return nil if value == LibHTS.bcf_float_vector_end
+      def update_genotypes(values)
+        values = normalize_values(values) { |value| Integer(value) }
+        validate_sample_divisibility!("GT", values.length)
+        result = native.genotype_update(header_native, values)
+        raise FormatUpdateError, "Failed to update FORMAT field 'GT': #{result}" if result.negative?
 
-        [value].pack("V").unpack1("e")
+        result
       end
 
-      def get_float_words(key)
-        get_numeric_values(key, LibHTS::BCF_HT_REAL, "float") { |dst, len| dst.get_array_of_uint32(0, len) }
-      end
+      def delete(key)
+        schema = format_schema(key)
+        return false unless schema && !get_raw(key).nil?
 
-      def get_typed(key, type)
-        case type.to_sym
-        when :float, :real
-          raise_unsupported_format_flag(key)
-          words = get_float_words(key)
-          words&.map { |word| decode_float_word(word) }
-        else
-          get_raw(key, type)
-        end
+        result = native.format_delete(header_native, key.to_s, type_code(schema.first))
+        result >= 0
       end
 
-      def normalize_format_rc(rc, key, expected_type)
-        case rc
-        when -1, -3
-          nil
-        when -2
-          raise FormatTypeError, "Tag #{key} is not #{expected_type} FORMAT field"
-        when -4
-          raise FormatReadError, "Failed to read FORMAT/#{key}"
-        else
-          rc
-        end
-      end
+      def fields = native.format_fields(header_native)
+      def ids = fields.map { |field| field[:id] }
+      def get_float_words(key) = get_raw(key, :float)
+      def length = fields.length
+      alias size length
+      def to_h = fields.to_h { |field| [field[:name], get(field[:name])] }
 
-      def raise_unsupported_format_flag(key)
-        return unless header_format_type(key) == :flag
+      private
 
-        raise UnsupportedFormatOperationError,
-              "FORMAT flag fields are not supported: #{key}"
+      def native = @record.__send__(:native_handle)
+      def header_native = @record.header.__send__(:native_handle)
+      def sample_count = @record.header.nsamples
+      def format_schema(key) = header_native.schema("FORMAT", key.to_s)
+
+      def type_code(type)
+        { int: Native::BCF_HT_INT, int32: Native::BCF_HT_INT,
+          float: Native::BCF_HT_REAL, real: Native::BCF_HT_REAL,
+          string: Native::BCF_HT_STR, str: Native::BCF_HT_STR }.fetch(type)
       end
 
-      def ensure_expected_format_type!(key, expected_type, label)
-        actual_type = header_format_type(key)
-        raise FormatDefinitionError, "FORMAT tag #{key} not defined in header" if actual_type.nil?
+      def type_compatible?(actual, requested, key)
+        return true if key == "GT" && %i[int int32 string str].include?(requested)
 
-        raise_unsupported_format_flag(key)
-        raise FormatTypeError, "Tag #{key} is not #{label} FORMAT field" unless actual_type == expected_type
+        actual == case requested
+                  when :int, :int32 then :int
+                  when :float, :real then :float
+                  when :string, :str then :string
+                  when :flag then :flag
+                  else requested
+                  end
       end
 
-      def ensure_gt_defined!
-        raise FormatDefinitionError, "FORMAT tag GT not defined in header" if header_format_type("GT").nil?
+      def type_label(type)
+        case type
+        when :int, :int32 then "integer"
+        when :float, :real then "float"
+        when :string, :str then "string"
+        else type.to_s
+        end
       end
 
-      def check_update_rc!(rc, key)
-        case rc
-        when -1
-          raise FormatDefinitionError, "FORMAT tag #{key} not defined in header"
-        when 0
-          rc
-        else
-          raise FormatUpdateError, "Failed to update FORMAT field '#{key}': #{rc}" if rc.negative?
-
-          rc
-        end
+      def raise_unsupported_flag(key)
+        raise UnsupportedFormatOperationError, "FORMAT flag fields are not supported: #{key}"
       end
 
-      def validate_numeric_sample_count!(key, value_count)
-        sample_count = @record.header.nsamples
-        raise ArgumentError, "FORMAT fields require at least one sample" if sample_count <= 0
-        return if (value_count % sample_count).zero?
+      def sample_layout(value_count)
+        count = sample_count
+        raise FormatReadError, "invalid FORMAT sample layout" if count <= 0 || (value_count % count) != 0
 
-        raise ArgumentError, "FORMAT values for #{key} must be divisible by sample count (#{sample_count})"
+        [count, value_count / count]
       end
 
-      def validate_string_sample_count!(key, value_count)
-        sample_count = @record.header.nsamples
-        raise ArgumentError, "FORMAT fields require at least one sample" if sample_count <= 0
-        return if value_count == sample_count
+      def shape_values(values, _key, schema)
+        return nil unless values
 
-        raise ArgumentError, "FORMAT string values for #{key} must provide one entry per sample (#{sample_count})"
+        count, width = sample_layout(values.length)
+        scalar = schema[1] == 1
+        Array.new(count) do |sample|
+          row = values.slice(sample * width, width)
+          row = trim_vector(row, schema.first)
+          scalar ? row.first : row
+        end
       end
 
-      def normalize_int_values(values)
-        values = Array(values)
-        raise ArgumentError, "Cannot update FORMAT field with empty array. Use delete instead." if values.empty?
-        raise ArgumentError, "FORMAT integer values must all be Integer" unless values.all?(Integer)
-        raise RangeError, "FORMAT integer values must fit int32" unless values.all? { |value| int32_range?(value) }
+      def trim_vector(values, type)
+        if type == :int
+          values.take_while { |value| value != Native::BCF_INT32_VECTOR_END }.map { |value| missing_int(value) }
+        else
+          values.take_while { |word| word != Native::BCF_FLOAT_VECTOR_END }.map { |word| decode_float_word(word) }
+        end
+      end
 
-        values
+      def missing_int(value)
+        [Native::BCF_INT32_MISSING, Native::BCF_INT32_VECTOR_END].include?(value) ? nil : value
       end
 
-      def normalize_float_values(values)
-        values = Array(values)
-        raise ArgumentError, "Cannot update FORMAT field with empty array. Use delete instead." if values.empty?
-        raise ArgumentError, "FORMAT float values must all be Numeric" unless values.all?(Numeric)
+      def decode_float_word(word)
+        return nil if [Native::BCF_FLOAT_MISSING, Native::BCF_FLOAT_VECTOR_END].include?(word)
 
-        values.map(&:to_f)
+        [word].pack("L<").unpack1("e")
       end
 
-      def normalize_string_values(values)
-        values = Array(values)
-        raise ArgumentError, "Cannot update FORMAT field with empty array. Use delete instead." if values.empty?
-        raise ArgumentError, "FORMAT string values must all be String" unless values.all?(String)
-
-        values
+      def advance_buffer(key, type)
+        buffer = (@buffers[[key.to_s, type]] ||= BufferState.new(0))
+        buffer.generation += 1
+        [buffer, buffer.generation]
       end
 
-      def format_present?(key)
-        if key == "GT"
-          !get_genotypes.nil?
-        else
-          case header_format_type(key)
-          when :int then !get_int(key).nil?
-          when :float then !get_float(key).nil?
-          when :string then !get_string(key).nil?
-          else false
-          end
+      def invalidate_views!(key)
+        @buffers.each do |(buffer_key, _type), buffer|
+          buffer.generation += 1 if buffer_key == key.to_s
         end
       end
 
-      def fmt_ptr
-        @record.struct[:d][:fmt].to_ptr
-      end
+      def each_vector(key, type)
+        return enum_for(type == :int ? :each_i32_vector : :each_f32_vector, key) unless block_given?
 
-      def ids
-        fmt_ptr.read_array_of_struct(LibHTS::BcfFmt, length).map do |fmt|
-          fmt[:id]
-        end
-      end
+        values = get_raw(key, type)
+        return self unless values
 
-      def get_fmt_type(qname)
-        @record.struct[:n_fmt].times do |i|
-          fmt = LibHTS::BcfFmt.new(@record.struct[:d][:fmt] + i * LibHTS::BcfFmt.size)
-          id = fmt[:id]
-          name = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, id)
-          if name == qname
-            type = LibHTS.bcf_hdr_id2type(@record.header.struct, LibHTS::BCF_HL_FMT, id)
-            return type
-          end
+        count, width = sample_layout(values.length)
+        buffer, generation = advance_buffer(key, type)
+        view = NumericVectorView.new(type)
+        count.times do |sample|
+          decoded = trim_vector(values.slice(sample * width, width), type)
+          yield sample, view.reset(decoded, buffer, generation)
         end
-        nil
+        self
       end
 
-      def scalar_format?(key)
-        header_format_number(key) == 1
+      def ensure_scalar!(key, expected)
+        schema = format_schema(key)
+        return unless schema
+        raise FormatTypeError, "Tag #{key} is not #{type_label(expected)} FORMAT field" unless schema.first == expected
+        raise FormatReadError, "FORMAT field #{key} is not scalar" unless schema[1] == 1
       end
 
-      def header_format_number(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_FMT, id)
-
-        LibHTS.bcf_hdr_id2number(@record.header.struct, LibHTS::BCF_HL_FMT, id)
+      def normalize_values(values, &block)
+        Array(values).map(&block)
       end
 
-      def header_format_type_code(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_FMT, id)
+      def validate_sample_divisibility!(key, count)
+        samples = sample_count
+        return if samples.positive? && (count % samples).zero?
 
-        LibHTS.bcf_hdr_id2type(@record.header.struct, LibHTS::BCF_HL_FMT, id)
+        raise ArgumentError, "FORMAT values for #{key} must be divisible by sample count (#{samples})"
       end
 
-      def header_format_type(key)
-        ht_type_to_sym(header_format_type_code(key))
-      end
+      def update_format(key, type, values)
+        schema = format_schema(key)
+        raise FormatDefinitionError, "FORMAT tag #{key} not defined in header" unless schema
 
-      def ht_type_to_sym(t)
-        case t
-        when LibHTS::BCF_HT_FLAG then :flag
-        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 :int64
+        expected = type_code(schema.first)
+        unless expected == type
+          requested = { Native::BCF_HT_INT => :int, Native::BCF_HT_REAL => :float,
+                        Native::BCF_HT_STR => :string }.fetch(type)
+          raise FormatTypeError, "Tag #{key} is not #{type_label(requested)} FORMAT field"
         end
-      end
+        result = native.format_update(header_native, key.to_s, type, values)
+        raise FormatUpdateError, "Failed to update FORMAT field '#{key}': #{result}" if result.negative?
 
-      def int32_range?(value)
-        value >= -2_147_483_648 && value <= 2_147_483_647
+        result
       end
     end
   end