htslib 0.4.2 → 0.6.0

data/lib/hts/bcf/info.rb

@@ -2,385 +2,138 @@
 
 module HTS
   class Bcf < Hts
-    # Info field
     class Info
-      def initialize(record)
-        @record = record
-      end
-
-      # @note Specify the type. If you don't specify a type, it will still work, but it will be slower.
-      # @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)
-        n = FFI::MemoryPointer.new(:int)
-        p1 = FFI::MemoryPointer.new(:pointer)
-        p1.write_pointer(FFI::Pointer::NULL)
-        h = @record.header.struct
-        r = @record.struct
-
-        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.
+      TYPE_CODES = {
+        flag: Native::BCF_HT_FLAG, bool: Native::BCF_HT_FLAG,
+        int: Native::BCF_HT_INT, int32: Native::BCF_HT_INT,
+        int64: Native::BCF_HT_LONG, long: Native::BCF_HT_LONG,
+        float: Native::BCF_HT_REAL, real: Native::BCF_HT_REAL,
+        string: Native::BCF_HT_STR, str: Native::BCF_HT_STR
+      }.freeze
 
-          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
+      def initialize(record) = @record = record
 
-        type ||= actual_type
-        return nil if actual_type && !key?(key)
+      def get(key, type = nil)
+        schema = header.schema("INFO", key.to_s)
+        raise InfoDefinitionError, "INFO tag #{key} not defined in header" unless schema
 
-        case type&.to_sym
-        when :int, :int32
-          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, ->(dst, len) { dst.read_array_of_float(len) })
-        when :flag, :bool
-          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, ->(dst, _len) { dst.read_string })
+        actual_type = schema.first
+        requested = type&.to_sym
+        if requested && !type_compatible?(actual_type, requested)
+          raise InfoTypeError, "Tag #{key} is not #{type_label(requested)} INFO field"
         end
-      end
-
-      # For compatibility with HTS.cr.
-      def get_int(key)
-        get(key, :int)
-      end
-
-      # For compatibility with HTS.cr.
-      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)
-      end
 
-      # For compatibility with HTS.cr.
-      def get_flag(key)
-        get(key, :flag)
+        code = TYPE_CODES.fetch(requested || actual_type)
+        value = native.info_get(header_native, key.to_s, code)
+        code == Native::BCF_HT_FLAG && value.nil? ? false : value
       end
 
-      def [](key)
-        get(key)
-      end
+      def get_int(key) = get(key, :int)
+      def get_float(key) = get(key, :float)
+      def get_int64(key) = get(key, :int64)
+      def get_string(key) = get(key, :string)
+      def get_flag(key) = get(key, :flag)
+      def [](key) = get(key)
 
-      # Set INFO field value with automatic type detection.
-      # @param key [String] INFO tag name
-      # @param value [Integer, Float, String, Array, true, false, nil] value to set
-      #   - Integer or Array<Integer> -> update_int
-      #   - Float or Array<Float,Integer> -> update_float
-      #   - String -> update_string
-      #   - true/false -> update_flag
-      #   - nil -> delete the INFO field
       def []=(key, value)
         case value
-        when nil
-          delete(key)
-        when true, false
-          update_flag(key, value)
+        when nil then delete(key)
+        when true, false then update_flag(key, value)
         when Integer
-          unless int32_range?(value)
+          unless int32?(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])
-        when String
-          update_string(key, value)
+        when Float then update_float(key, [value])
+        when String then update_string(key, value)
         when Array
-          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 ArgumentError, "Cannot set INFO field to empty array. Use nil to delete." if value.empty?
+
+          if value.all? { |item| item.is_a?(Integer) }
+            unless value.all? do |item|
+              int32?(item)
+            end
               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) }
+          elsif value.all? { |item| item.is_a?(Numeric) }
             update_float(key, value)
           else
             raise ArgumentError, "INFO array must contain only integers or floats, got: #{value.map(&:class).uniq}"
           end
-        else
-          raise ArgumentError, "Unsupported INFO value type: #{value.class}"
+        else raise ArgumentError, "Unsupported INFO value type: #{value.class}"
         end
       end
 
-      # Update INFO field with integer value(s).
-      # For compatibility with HTS.cr.
-      # @param key [String] INFO tag name
-      # @param values [Array<Integer>] integer values (use single-element array for scalar)
-      def update_int(key, values)
-        values = Array(values)
-        ptr = FFI::MemoryPointer.new(:int32, values.size)
-        ptr.write_array_of_int32(values)
-        ret = LibHTS.bcf_update_info(
-          @record.header.struct,
-          @record.struct,
-          key,
-          ptr,
-          values.size,
-          LibHTS::BCF_HT_INT
-        )
-        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
-      # @param values [Array<Float>] float values (use single-element array for scalar)
-      def update_float(key, values)
-        values = Array(values).map(&:to_f)
-        ptr = FFI::MemoryPointer.new(:float, values.size)
-        ptr.write_array_of_float(values)
-        ret = LibHTS.bcf_update_info(
-          @record.header.struct,
-          @record.struct,
-          key,
-          ptr,
-          values.size,
-          LibHTS::BCF_HT_REAL
-        )
-        raise InfoUpdateError, "Failed to update INFO float field '#{key}': #{ret}" if ret < 0
-
-        ret
-      end
-
-      # Update INFO field with string value.
-      # For compatibility with HTS.cr.
-      # @param key [String] INFO tag name
-      # @param value [String] string value
-      def update_string(key, value)
-        ret = LibHTS.bcf_update_info(
-          @record.header.struct,
-          @record.struct,
-          key,
-          value.to_s,
-          1,
-          LibHTS::BCF_HT_STR
-        )
-        raise InfoUpdateError, "Failed to update INFO string field '#{key}': #{ret}" if ret < 0
-
-        ret
-      end
+      def update_int(key, values) = update(key, Native::BCF_HT_INT, Array(values).map { |value| Integer(value) }, "int")
+      def update_float(key, values) = update(key, Native::BCF_HT_REAL, Array(values).map(&:to_f), "float")
+      def update_string(key, value) = update(key, Native::BCF_HT_STR, value.to_s, "string")
 
-      # Update INFO flag field.
-      # For compatibility with HTS.cr.
-      # @param key [String] INFO tag name
-      # @param present [Boolean] true to set flag, false to remove it
-      def update_flag(key, present = true)
-        ret = if present
-                LibHTS.bcf_update_info(
-                  @record.header.struct,
-                  @record.struct,
-                  key,
-                  FFI::Pointer::NULL,
-                  1,
-                  LibHTS::BCF_HT_FLAG
-                )
-              else
-                # Remove flag by setting n=0
-                LibHTS.bcf_update_info(
-                  @record.header.struct,
-                  @record.struct,
-                  key,
-                  FFI::Pointer::NULL,
-                  0,
-                  LibHTS::BCF_HT_FLAG
-                )
-              end
-        raise InfoUpdateError, "Failed to update INFO flag field '#{key}': #{ret}" if ret < 0
+      def update_int64(_key,
+                       _values) = raise(UnsupportedInfoOperationError,
+                                        "htslib backend does not implement int64 INFO update (BCF_HT_LONG)")
 
-        ret
-      end
+      def update_flag(key, present = true) = update(key, Native::BCF_HT_FLAG, !!present, "flag")
 
-      # Delete an INFO field.
-      # @param key [String] INFO tag name
-      # @return [Boolean] true if field was deleted, false if it didn't exist
       def delete(key)
-        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(
-          @record.header.struct,
-          @record.struct,
-          key,
-          FFI::Pointer::NULL,
-          0,
-          type
-        )
-        return false if ret < 0
+        schema = header.schema("INFO", key.to_s)
+        return false unless schema && key?(key)
 
+        native.info_update(header_native, key.to_s, TYPE_CODES.fetch(schema.first), false)
         true
       end
 
-      # Check if an INFO field exists.
-      # @param key [String] INFO tag name
-      # @return [Boolean] true if the field exists
       def key?(key)
-        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
+        schema = header.schema("INFO", key.to_s)
+        schema ? native.info_present?(header_native, key.to_s, TYPE_CODES.fetch(schema.first)) : false
       end
-
       alias include? key?
 
-      # FIXME: naming? room for improvement.
-      def fields
-        keys.map do |key|
-          name = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, key)
-          num  = LibHTS.bcf_hdr_id2number(@record.header.struct, LibHTS::BCF_HL_INFO, key)
-          type = LibHTS.bcf_hdr_id2type(@record.header.struct, LibHTS::BCF_HL_INFO, key)
-          {
-            name:,
-            n: num,
-            type: ht_type_to_sym(type),
-            key:
-          }
-        end
-      end
-
-      def length
-        @record.struct[:n_info]
-      end
-
-      def size
-        length
-      end
-
-      def to_h
-        ret = {}
-        keys.each do |key|
-          name = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, key)
-          ret[name] = get(name)
-        end
-        ret
-      end
+      def fields = native.info_fields(header_native)
+      def keys = fields.map { |field| field[:key] }
+      def length = fields.length
+      alias size length
+      def to_h = fields.to_h { |field| [field[:name], get(field[:name])] }
 
       private
 
-      def info_ptr
-        @record.struct[:d][:info].to_ptr
-      end
+      def native = @record.__send__(:native_handle)
+      def header = @record.header.__send__(:native_handle)
+      alias header_native header
 
-      def keys
-        info_ptr.read_array_of_struct(LibHTS::BcfInfo, length).map do |info|
-          info[:key]
-        end
-      end
+      def update(key, type, value, label)
+        result = native.info_update(header_native, key.to_s, type, value)
+        raise InfoUpdateError, "Failed to update INFO #{label} field '#{key}': #{result}" if result.negative?
 
-      def get_info_type(key)
-        header_info_type(key)
+        result
       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)
-        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
-        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
+      def type_compatible?(actual, requested)
+        case requested
+        when :int, :int32 then actual == :int
+        when :int64, :long then %i[int int64].include?(actual)
+        when :float, :real then actual == :float
+        when :flag, :bool then actual == :flag
+        when :string, :str then actual == :string
+        else actual == requested
         end
       end
 
       def type_label(type)
-        case type.to_sym
-        when :int, :int32 then "integer"
-        when :int64, :long then "integer"
+        case type
+        when :int, :int32, :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
+
+      def int32?(value) = value.between?(-2_147_483_648, 2_147_483_647)
     end
   end
 end

data/lib/hts/bcf/record.rb

@@ -2,148 +2,120 @@
 
 module HTS
   class Bcf < Hts
-    # A class for working with VCF records.
     class Record
-      def initialize(header, bcf_t = nil)
-        @bcf1 = bcf_t || LibHTS.bcf_init
+      attr_reader :header
+
+      def initialize(header, native_record = nil)
+        @native = native_record || Native::BcfRecordHandle.create
         @header = header
       end
 
-      attr_reader :header
+      def rid = @native.core_get(:rid)
 
-      def struct
-        @bcf1
+      def rid=(value)
+        @native.core_set(:rid, value)
       end
 
-      def to_ptr
-        @bcf1.to_ptr
-      end
+      def chrom = @header.id2name(rid)
+      def pos = @native.core_get(:pos)
 
-      # Get the reference id of the record.
-      def rid
-        @bcf1[:rid]
+      def pos=(value)
+        @native.core_set(:pos, value)
       end
 
-      def rid=(rid)
-        @bcf1[:rid] = rid
-      end
+      def endpos = pos + @native.core_get(:rlen)
+      def id = @native.id
 
-      # Get the chromosome of variant.
-      def chrom
-        LibHTS.bcf_hdr_id2name(@header.struct, rid)
+      def id=(value)
+        check_update_rc!(@native.set_id(@header.__send__(:native_handle), value), "ID", value)
+        value
       end
 
-      # Return 0-based position.
-      def pos
-        @bcf1[:pos]
+      def clear_id
+        check_update_rc!(@native.set_id(@header.__send__(:native_handle), "."), "ID", ".")
+        nil
       end
 
-      def pos=(pos)
-        @bcf1[:pos] = pos
-      end
+      def alleles = @native.alleles
+      def ref = alleles.first
+      def alt = alleles.drop(1)
+      def allele_count = alleles.length
 
-      # Return the 0-based, exclusive end position
-      def endpos
-        pos + @bcf1[:rlen]
-      end
+      def alleles=(values)
+        values = Array(values).map(&:to_s)
+        raise ArgumentError, "at least one allele is required" if values.empty?
 
-      # Return the value of the ID column.
-      def id
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_INFO)
-        @bcf1[:d][:id]
+        encoded = values.join(",")
+        check_update_rc!(@native.set_alleles(@header.__send__(:native_handle), encoded), "alleles", encoded)
+        values
       end
 
-      def id=(id)
-        LibHTS.bcf_update_id(@header.struct, @bcf1, id)
-      end
+      # Native migration replacement for the former pointer-yielding API.
+      def each_allele_raw
+        return to_enum(__method__) unless block_given?
 
-      def clear_id
-        LibHTS.bcf_update_id(@header.struct, @bcf1, ".")
+        alleles.each { |allele| yield allele, allele.bytesize }
+        self
       end
 
-      def ref
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_STR)
-        @bcf1[:d][:allele].get_pointer(0).read_string
-      end
+      def qual = @native.core_get(:qual)
 
-      def alt
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_STR)
-        @bcf1[:d][:allele].get_array_of_pointer(
-          FFI::TYPE_POINTER.size, @bcf1[:n_allele] - 1
-        ).map(&:read_string)
+      def qual=(value)
+        @native.core_set(:qual, value)
       end
 
-      def alleles
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_STR)
-        @bcf1[:d][:allele].get_array_of_pointer(
-          0, @bcf1[:n_allele]
-        ).map(&:read_string)
+      def filters
+        names = @native.filter_names(@header.__send__(:native_handle))
+        names
       end
 
-      # Get variant quality.
-      def qual
-        @bcf1[:qual]
-      end
 
-      def qual=(qual)
-        @bcf1[:qual] = qual
-      end
+      # VCF FILTER is a list even when it contains a single value. Keeping a
+      # stable return type avoids substring matching for single-filter records.
+      alias filter filters
+
+      def passed? = filters == ["PASS"]
+      def filter_missing? = filters.empty?
+      def filtered? = !passed? && !filter_missing?
+
+      def each_filter_id(&block)
+        return to_enum(__method__) unless block_given?
 
-      def filter
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_FLT)
-        d = @bcf1[:d]
-        n_flt = d[:n_flt]
-
-        case n_flt
-        when 0
-          "PASS"
-        when 1
-          id = d[:flt].read_int
-          LibHTS.bcf_hdr_int2id(@header.struct, LibHTS::BCF_DT_ID, id)
-        when 2..
-          d[:flt].get_array_of_int(0, n_flt).map do |i|
-            LibHTS.bcf_hdr_int2id(@header.struct, LibHTS::BCF_DT_ID, i)
-          end
-        else
-          raise "Unexpected number of filters. n_flt: #{n_flt}"
-        end
+        @native.filter_ids.each(&block)
+        self
       end
 
+      def filter_ids = @native.filter_ids
+      def filter_id?(target_id) = filter_ids.include?(Integer(target_id))
+
       def info(key = nil)
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_SHR)
-        info = Info.new(self)
-        if key
-          info.get(key)
-        else
-          info
-        end
+        accessor = (@info_accessor ||= Info.new(self))
+        key ? accessor.get(key) : accessor
       end
 
       def format(key = nil)
-        LibHTS.bcf_unpack(@bcf1, LibHTS::BCF_UN_FMT)
-        if key
-          Format.new(self).get(key)
-        else
-          Format.new(self)
-        end
+        accessor = (@format_accessor ||= Format.new(self))
+        key ? accessor.get(key) : accessor
       end
 
-      def to_s
-        ksr = LibHTS::KString.new
-        begin
-          raise "Failed to format record" if LibHTS.vcf_format(@header.struct, @bcf1, ksr) == -1
+      def to_s = @native.format_record(@header.__send__(:native_handle))
+
+      private
 
-          ksr.read_string_copy
-        ensure
-          ksr.free_buffer
-        end
+      def check_update_rc!(result, field, value)
+        return result unless result.negative?
+
+        raise RecordError, "Failed to update #{field} to #{value.inspect} (HTSlib error #{result})"
       end
 
-      private
+      def native_handle = @native
 
-      def initialize_copy(orig)
-        @header = orig.header
-        @bcf1 = LibHTS.bcf_dup(orig.struct)
+      def initialize_copy(original)
+        super
+        @header = original.header
+        @native = original.__send__(:native_handle).duplicate
+        @info_accessor = nil
+        @format_accessor = nil
       end
     end
   end