htslib 0.4.1 → 0.5.0

data/lib/hts/bam/record.rb

@@ -6,374 +6,337 @@ require_relative "auxi"
 
 module HTS
   class Bam < Hts
-    # A class for working with alignment records.
     class Record
       SEQ_NT16_STR = "=ACMGRSVTWYHKDBN"
-
+      UNSET = Object.new.freeze
+      private_constant :UNSET
       attr_reader :header
 
-      # Initialization API is experimental.
-
-      def initialize(
-        header,
-        bam1 = nil,
-        qname: nil,
-        flag: nil,
-        tid: nil,
-        pos: nil,
-        mapq: nil,
-        cigar: nil,
-        mtid: nil,
-        mpos: nil,
-        isize: nil,
-        seq: nil,
-        qual: nil,
-        l_aux: nil
-      )
-        @bam1 = bam1 || LibHTS.bam_init1
+      # Build a BAM record from Ruby values. Coordinates are zero-based, matching
+      # the rest of this API. +qualities+ is an Array of numeric Phred scores;
+      # use +quality_string+ for a FASTQ/SAM-style Phred+33 String.
+      def initialize(header, native_record = nil, qname: "*", flag: 0, tid: nil, chrom: nil,
+                     pos: -1, mapq: 0, cigar: nil, mtid: nil, mate_chrom: nil,
+                     mate_pos: -1, insert_size: 0, seq: UNSET, sequence: UNSET,
+                     qual: UNSET, qualities: UNSET, quality_string: UNSET, aux: nil)
+        @native = native_record || Native::BamRecordHandle.create
         @header = header
-
-        params = [qname, flag, tid, pos, mapq, cigar, mtid, mpos, isize, seq, qual, l_aux]
-        return if params.all? { |x| x.nil? }
-
-        if params.all?
-          cigar_array = Cigar.parse(cigar).array
-          cigar_pointer = if cigar_array.empty?
-                            FFI::Pointer::NULL
-                          else
-                            FFI::MemoryPointer.new(:uint32, cigar_array.length).tap do |pointer|
-                              pointer.write_array_of_uint32(cigar_array)
-                            end
-                          end
-          if qual.is_a?(Array)
-            qual = qual.pack("C*")
-          elsif qual.is_a?(String)
-            raise "Which implementation is better? +33 or not? Please tell me."
-          end
-          r = LibHTS.bam_set1(
-            @bam1,
-            qname.length,
-            qname,
-            flag,
-            tid,
-            pos,
-            mapq,
-            cigar_array.length,
-            cigar_pointer,
-            mtid,
-            mpos,
-            isize,
-            seq.length,
-            seq,
-            qual,
-            l_aux
-          )
-          raise "bam_set1 failed: #{r}" if r < 0
-        else
-          warn "Ignore bam_set1 because some arguments are missing."
-        end
-      end
-
-      # Return the FFI::Struct object.
-      def struct
-        @bam1
-      end
-
-      def to_ptr
-        @bam1.to_ptr
+        return if native_record
+
+        sequence = normalize_sequence(seq, sequence)
+        qualities = normalize_qualities(qual, qualities, quality_string, sequence.bytesize)
+        cigar_values = normalize_cigar(cigar)
+        validate_cigar_length!(cigar_values, sequence)
+
+        @native.replace(
+          normalize_qname(qname), normalize_flag(flag), resolve_tid(tid, chrom, "chrom"),
+          normalize_position(pos, "pos"), normalize_mapq(mapq), cigar_values,
+          resolve_tid(mtid, mate_chrom, "mate_chrom"), normalize_position(mate_pos, "mate_pos"),
+          Integer(insert_size), sequence, qualities
+        )
+        assign_aux(aux) if aux
       end
 
-      # Get the read name. (a.k.a QNAME)
-      # @return [String] query template name
-      def qname
-        LibHTS.bam_get_qname(@bam1).read_string
-      end
+      def qname = @native.qname
 
       def qname=(name)
-        LibHTS.bam_set_qname(@bam1, name)
+        @native.qname = name
       end
 
-      # Get the chromosome ID of the alignment. -1 if not mapped.
-      # @return [Integer] chromosome ID
-      def tid
-        @bam1[:core][:tid]
-      end
+      def tid = core_get(:tid)
 
-      def tid=(tid)
-        @bam1[:core][:tid] = tid
+      def tid=(value)
+        core_set(:tid, value)
       end
 
-      # Get the chromosome ID of the mate. -1 if not mapped.
-      # @return [Integer] chromosome ID
-      def mtid
-        @bam1[:core][:mtid]
-      end
+      def mtid = core_get(:mtid)
 
-      def mtid=(mtid)
-        @bam1[:core][:mtid] = mtid
+      def mtid=(value)
+        core_set(:mtid, value)
       end
 
-      # Get the 0-based leftmost coordinate of the alignment.
-      # @return [Integer] 0-based leftmost coordinate
-      def pos
-        @bam1[:core][:pos]
-      end
+      def pos = core_get(:pos)
 
-      def pos=(pos)
-        @bam1[:core][:pos] = pos
+      def pos=(value)
+        core_set(:pos, value)
       end
 
-      # Get the 0-based leftmost coordinate of the mate.
-      # @return [Integer] 0-based leftmost coordinate
-      def mate_pos
-        @bam1[:core][:mpos]
-      end
+      def mate_pos = core_get(:mpos)
 
-      def mate_pos=(mpos)
-        @bam1[:core][:mpos] = mpos
+      def mate_pos=(value)
+        core_set(:mpos, value)
       end
-
       alias mpos mate_pos
       alias mpos= mate_pos=
+      def bin = core_get(:bin)
 
-      # Get the bin calculated by bam_reg2bin().
-      # @return [Integer] bin
-      def bin
-        @bam1[:core][:bin]
+      def bin=(value)
+        core_set(:bin, value)
       end
 
-      def bin=(bin)
-        @bam1[:core][:bin] = bin
-      end
-
-      # Get the rightmost base position of the alignment on the reference genome.
-      # @return [Integer] 0-based rightmost coordinate
-      def endpos
-        LibHTS.bam_endpos @bam1
-      end
+      def endpos = @native.endpos
 
-      # Get the reference sequence name of the alignment. (a.k.a RNAME)
-      # '' if not mapped.
-      # @return [String] reference sequence name
       def chrom
         return "" if tid == -1
 
-        LibHTS.sam_hdr_tid2name(@header, tid)
+        @header.__send__(:native_handle).target_name(tid)
       end
-
       alias contig chrom
+      def chrom=(name)
+        self.tid = resolve_tid(nil, name, "chrom")
+      end
+      alias contig= chrom=
 
-      # Get the reference sequence name of the mate.
-      # '' if not mapped.
-      # @return [String] reference sequence name
       def mate_chrom
         return "" if mtid == -1
 
-        LibHTS.sam_hdr_tid2name(@header, mtid)
+        @header.__send__(:native_handle).target_name(mtid)
       end
-
       alias mate_contig mate_chrom
+      def mate_chrom=(name)
+        self.mtid = resolve_tid(nil, name, "mate_chrom")
+      end
+      alias mate_contig= mate_chrom=
 
-      # Get whether the query is on the reverse strand.
-      # @return [String] strand "+" or "-"
-      def strand
-        LibHTS.bam_is_rev(@bam1) ? "-" : "+"
+      def strand = reverse? ? "-" : "+"
+      def mate_strand = mate_reverse? ? "-" : "+"
+      def insert_size = core_get(:isize)
+
+      def insert_size=(value)
+        core_set(:isize, value)
       end
+      alias isize insert_size
+      alias isize= insert_size=
+      def mapq = core_get(:mapq)
 
-      # Get whether the query's mate is on the reverse strand.
-      # @return [String] strand "+" or "-"
-      def mate_strand
-        LibHTS.bam_is_mrev(@bam1) ? "-" : "+"
+      def mapq=(value)
+        core_set(:mapq, value)
       end
 
-      # Get the observed template length. (a.k.a TLEN)
-      # @return [Integer] isize
-      def insert_size
-        @bam1[:core][:isize]
+      def cigar = Cigar.new(self)
+
+      def cigar=(value)
+        raise ArgumentError, "cigar must be a String or Bam::Cigar" unless value.is_a?(String) || value.is_a?(Cigar)
+
+        @native.cigar = value.to_s
       end
 
-      def insert_size=(isize)
-        @bam1[:core][:isize] = isize
+      def qlen = @native.qlen
+      def rlen = @native.rlen
+      def seq = @native.sequence
+      alias sequence seq
+
+      def each_base(&block)
+        return to_enum(__method__) unless block_given?
+
+        seq.each_char(&block)
+        self
       end
 
-      alias isize insert_size
-      alias isize= insert_size=
+      def each_base_code(&block)
+        return to_enum(__method__) unless block_given?
 
-      # Get the mapping quality of the alignment. (a.k.a MAPQ)
-      # @return [Integer] mapping quality
-      def mapq
-        @bam1[:core][:qual]
+        @native.sequence_codes.each(&block)
+        self
       end
 
-      def mapq=(mapq)
-        @bam1[:core][:qual] = mapq
+      def len = core_get(:length)
+
+      def base(index)
+        index += len if index.negative?
+        code = @native.base_code(index)
+        code ? SEQ_NT16_STR[code] : "."
       end
+      alias base_at base
 
-      # Get the Bam::Cigar object.
-      # @return [Bam::Cigar] cigar
-      def cigar
-        Cigar.new(self)
+      def qual = @native.qualities
+      def qual_string = @native.quality_string
+
+      def each_qual(&block)
+        return to_enum(__method__) unless block_given?
+
+        @native.qualities.each(&block)
+        self
       end
 
-      def cigar=(str)
-        case str
-        when Cigar, String
-          r = LibHTS.bam_parse_cigar(str.to_s, FFI::Pointer::NULL, @bam1)
-          raise "bam_parse_cigar failed: #{r}" if r.negative?
-        else
-          raise ArgumentError, "cigar must be a String or Bam::Cigar"
-        end
+      def base_qual(index)
+        index += len if index.negative?
+        @native.quality_at(index) || 0
       end
+      alias qual_at base_qual
 
-      # Calculate query length from CIGAR.
-      # @return [Integer] query length
-      def qlen
-        # cigar.qlen will be slower because it converts to a Ruby array.
-        LibHTS.bam_cigar2qlen(
-          @bam1[:core][:n_cigar],
-          LibHTS.bam_get_cigar(@bam1)
-        )
+      def flag = Flag.new(flag_value)
+      def flag_value = core_get(:flag)
+
+      def flag=(value)
+        case value
+        when Integer then core_set(:flag, value)
+        when Flag then core_set(:flag, value.value)
+        else raise "Invalid flag type: #{value.class}"
+        end
       end
 
-      # Calculate reference length from CIGAR.
-      # @return [Integer] reference length
-      def rlen
-        LibHTS.bam_cigar2rlen(
-          @bam1[:core][:n_cigar],
-          LibHTS.bam_get_cigar(@bam1)
-        )
+      def aux(key = nil)
+        accessor = (@aux_accessor ||= Aux.new(self))
+        key ? accessor.get(key) : accessor
       end
 
-      # Get the sequence. (a.k.a SEQ)
-      # @return [String] sequence
-      def seq
-        r = LibHTS.bam_get_seq(@bam1)
-        seq = String.new
-        len.times do |i|
-          seq << SEQ_NT16_STR[LibHTS.bam_seqi(r, i)]
+      def base_mod(auto_parse: true) = BaseMod.new(self, auto_parse:)
+
+      def each_base_mod_raw(max_mods: 10, &block)
+        return enum_for(__method__, max_mods:) unless block
+
+        mods = BaseMod.new(self)
+        begin
+          mods.each_raw(max_mods:, &block)
+        ensure
+          mods.close
         end
-        seq
+        self
       end
-      alias sequence seq
 
-      # Get the length of the query sequence.
-      # @return [Integer] query length
-      def len
-        @bam1[:core][:l_qseq]
+      Flag::TABLE.each do |method_name, mask|
+        define_method(method_name) { (flag_value & mask) != 0 }
       end
 
-      # Get the base of the requested index "i" of the query sequence.
-      # @param [Integer] i index
-      # @return [String] base
-      def base(n)
-        n += len if n < 0
-        return "." if (n >= len) || (n < 0) # eg. base(-1000)
+      def each_cigar_raw
+        return to_enum(__method__) unless block_given?
 
-        r = LibHTS.bam_get_seq(@bam1)
-        SEQ_NT16_STR[LibHTS.bam_seqi(r, n)]
+        @native.cigar_values.each { |encoded| yield encoded & 15, encoded >> 4 }
+        self
       end
 
-      # Get the base qualities as raw PHRED bytes.
-      # Ruby has no UInt8 type, so this returns an Array<Integer> with values in 0..255,
-      # corresponding to Crystal's Array(UInt8).
-      # Use qual_string for the SAM-style ASCII representation.
-      # @return [Array<Integer>] base qualities as unsigned bytes
-      def qual
-        q_ptr = LibHTS.bam_get_qual(@bam1)
-        q_ptr.read_array_of_uint8(len)
+      def to_s = @native.format(@header.__send__(:native_handle))
+
+      private
+
+      def native_handle = @native
+      def core_get(field) = @native.core_get(field)
+      def core_set(field, value) = @native.core_set(field, value)
+
+      def normalize_qname(value)
+        value = value.to_s
+        raise ArgumentError, "qname must not contain NUL bytes" if value.include?("\0")
+
+        value
       end
 
-      # Get the base qualities as a string. (a.k.a QUAL)
-      # ASCII of base quality + 33.
-      # @return [String] base qualities
-      def qual_string
-        qual.map { |q| (q + 33).chr }.join
+      def normalize_flag(value)
+        integer = value.is_a?(Flag) ? value.value : Integer(value)
+        raise RangeError, "flag must be between 0 and 65535" unless integer.between?(0, 65_535)
+
+        integer
       end
 
-      # Get the base quality of the requested index "i" of the query sequence.
-      # @param [Integer] i index
-      # @return [Integer] base quality
-      def base_qual(n)
-        n += len if n < 0
-        return 0 if (n >= len) || (n < 0) # eg. base_qual(-1000)
+      def normalize_mapq(value)
+        integer = Integer(value)
+        raise RangeError, "mapq must be between 0 and 255" unless integer.between?(0, 255)
 
-        q_ptr = LibHTS.bam_get_qual(@bam1)
-        q_ptr.get_uint8(n)
+        integer
       end
 
-      # Get Bam::Flag object of the alignment.
-      # @return [Bam::Flag] flag
-      def flag
-        Flag.new(@bam1[:core][:flag])
+      def normalize_position(value, name)
+        integer = Integer(value)
+        raise RangeError, "#{name} must be -1 or greater" if integer < -1
+
+        integer
       end
 
-      def flag=(flag)
-        case flag
-        when Integer
-          @bam1[:core][:flag] = flag
-        when Flag
-          @bam1[:core][:flag] = flag.value
-        else
-          raise "Invalid flag type: #{flag.class}"
-        end
+      def resolve_tid(numeric, name, label)
+        raise ArgumentError, "specify either #{label} or its numeric id, not both" if !numeric.nil? && !name.nil?
+
+        id = if name.nil?
+               numeric.nil? ? -1 : Integer(numeric)
+             elsif name.to_s == "*"
+               -1
+             else
+               @header.get_tid(name.to_s)
+             end
+        raise ArgumentError, "unknown reference #{name.inspect}" if !name.nil? && id.negative? && name.to_s != "*"
+        raise RangeError, "reference id must be -1 or greater" if id < -1
+        raise RangeError, "reference id #{id} is not present in the header" if id >= @header.target_count
+
+        id
       end
 
-      # Get the auxiliary data.
-      # @param [String] key tag name
-      # @return [String] value
-      def aux(key = nil)
-        aux = Aux.new(self)
-        if key
-          aux.get(key)
-        else
-          aux
+      def normalize_sequence(short, long)
+        raise ArgumentError, "specify either seq or sequence, not both" unless short.equal?(UNSET) || long.equal?(UNSET)
+
+        value = long.equal?(UNSET) ? short : long
+        value = "" if value.equal?(UNSET) || value.nil? || value == "*"
+        value = value.to_s
+        unless /\A[=ACMGRSVTWYHKDBNacmgrsvtwyhkdbn]*\z/.match?(value)
+          raise ArgumentError, "sequence contains an invalid BAM base"
         end
+
+        value
       end
 
-      # Get base modification information from MM/ML tags
-      # @param auto_parse [Boolean] If true (default), parse lazily on first access
-      # @return [BaseMod] Base modification object
-      def base_mod(auto_parse: true)
-        BaseMod.new(self, auto_parse: auto_parse)
+      def normalize_qualities(short, long, string, sequence_length)
+        supplied = [short, long, string].count { |value| !value.equal?(UNSET) }
+        raise ArgumentError, "specify only one of qual, qualities, or quality_string" if supplied > 1
+
+        value = if !string.equal?(UNSET)
+                  quality_string_to_bytes(string)
+                elsif !long.equal?(UNSET)
+                  quality_values_to_bytes(long)
+                elsif !short.equal?(UNSET)
+                  short.is_a?(String) ? quality_string_to_bytes(short) : quality_values_to_bytes(short)
+                end
+        raise ArgumentError, "qualities length must match sequence length" if value && value.bytesize != sequence_length
+
+        value
       end
 
-      # TODO: add a method to get the auxiliary fields as a hash.
+      def quality_values_to_bytes(values)
+        return nil if values.nil?
 
-      # TODO: add a method to set the auxiliary fields.
+        array = Array(values).map { |value| Integer(value) }
+        invalid = array.find { |value| !value.between?(0, 93) }
+        raise RangeError, "quality scores must be between 0 and 93" if invalid
 
-      # TODO: add a method to remove the auxiliary fields.
+        array.pack("C*")
+      end
 
-      # TODO: add a method to set variable length data (qname, cigar, seq, qual).
+      def quality_string_to_bytes(value)
+        return nil if value.nil? || value == "*"
 
-      # Calling flag is delegated to the Flag object.
-      Flag::TABLE.each_key do |m|
-        define_method(m) do
-          flag.send(m)
+        string = value.to_s
+        unless string.ascii_only? && string.bytes.all? { |byte| byte.between?(33, 126) }
+          raise ArgumentError, "quality_string must contain only Phred+33 characters from ! to ~"
         end
+
+        string.bytes.map { |byte| byte - 33 }.pack("C*")
       end
 
-      # @return [String] a string representation of the alignment.
-      def to_s
-        kstr = LibHTS::KString.new
-        begin
-          raise "Failed to format bam record" if LibHTS.sam_format1(@header.struct, @bam1, kstr) == -1
+      def normalize_cigar(value)
+        return [] if value.nil? || value.to_s == "*"
 
-          kstr.read_string_copy
-        ensure
-          kstr.free_buffer
+        case value
+        when String then Cigar.parse(value).array
+        when Cigar then value.array.dup
+        else raise ArgumentError, "cigar must be a String or Bam::Cigar"
         end
       end
 
-      private
+      def validate_cigar_length!(values, sequence)
+        query_length = Native.cigar_qlen(values)
+        return if values.empty? || query_length == sequence.bytesize
 
-      def initialize_copy(orig)
-        super
-        @header = orig.header
-        # Deep-copy underlying bam1_t to detach from original buffer
-        dup_bam1 = LibHTS.bam_dup1(orig.struct)
-        raise "bam_dup1 failed" if dup_bam1.null?
+        raise ArgumentError, "CIGAR query length #{query_length} does not match sequence length #{sequence.bytesize}"
+      end
 
-        @bam1 = dup_bam1
+      def assign_aux(values)
+        raise ArgumentError, "aux must be a Hash-like object" unless values.respond_to?(:each_pair)
+
+        values.each_pair { |key, value| aux[key.to_s] = value }
+      end
+
+      def initialize_copy(original)
+        super
+        @header = original.header
+        @native = original.__send__(:native_handle).duplicate
+        @aux_accessor = nil
       end
     end
   end