htslib 0.2.5 → 0.2.8

data/lib/hts/bam/auxi.rb

@@ -3,22 +3,96 @@
 # Q. Why is the file name auxi.rb and not aux.rb?
 #
 # A. This is for compatibility with Windows.
+#
 # In Windows, aux is a reserved word
 # You cannot create a file named aux.
+#
+# What?! That's crazy!
 
 module HTS
   class Bam < Hts
     # Auxiliary record data
+    #
+    # @noge Aux is a View object.
+    # The result of the alignment is assigned to the bam1 structure.
+    # Ruby's Aux class references a part of it. There is no one-to-one
+    # correspondence between C structures and Ruby's Aux class.
     class Aux
+      include Enumerable
+      attr_reader :record
+
       def initialize(record)
         @record = record
       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)
         aux = LibHTS.bam_aux_get(@record.struct, key)
         return nil if aux.null?
 
-        type ||= aux.read_string(1)
+        get_ruby_aux(aux, type)
+      end
+
+      # For compatibility with HTS.cr.
+      def get_int(key)
+        get(key, "i")
+      end
+
+      # For compatibility with HTS.cr.
+      def get_float(key)
+        get(key, "f")
+      end
+
+      # For compatibility with HTS.cr.
+      def get_string(key)
+        get(key, "Z")
+      end
+
+      def [](key)
+        get(key)
+      end
+
+      def first
+        aux = LibHTS.bam_aux_first(@record.struct)
+        return nil if aux.null?
+
+        get_ruby_aux(aux)
+      end
+
+      def each
+        return enum_for(__method__) unless block_given?
+
+        aux = LibHTS.bam_aux_first(@record.struct)
+        return nil if aux.null?
+
+        loop do
+          yield get_ruby_aux(aux)
+          aux = LibHTS.bam_aux_next(@record.struct, aux)
+          break if aux.null?
+        end
+      end
+
+      def to_h
+        h = {}
+        aux = LibHTS.bam_aux_first(@record.struct)
+        return h if aux.null?
+
+        loop do
+          key = FFI::Pointer.new(aux.address - 2).read_string(2)
+          h[key] = get_ruby_aux(aux)
+          aux = LibHTS.bam_aux_next(@record.struct, aux)
+          break if aux.null?
+        end
+        h
+      end
+
+      private
+
+      def get_ruby_aux(aux, type = nil)
+        type = type ? type.to_s : aux.read_string(1)
 
         # A (character), B (general array),
         # f (real number), H (hexadecimal array),
@@ -33,14 +107,23 @@ module HTS
           LibHTS.bam_aux2Z(aux)
         when "A" # char
           LibHTS.bam_aux2A(aux).chr
+        when "B" # array
+          t2 = aux.read_string(2)[1] # just a little less efficient
+          l = LibHTS.bam_auxB_len(aux)
+          case t2
+          when "c", "C", "s", "S", "i", "I"
+            # FIXME : Not efficient.
+            Array.new(l) { |i| LibHTS.bam_auxB2i(aux, i) }
+          when "f", "d"
+            # FIXME : Not efficient.
+            Array.new(l) { |i| LibHTS.bam_auxB2f(aux, i) }
+          else
+            raise NotImplementedError, "type: #{type} #{t2}"
+          end
         else
-          raise NotImplementedError, "type: #{t}"
+          raise NotImplementedError, "type: #{type}"
         end
       end
-
-      def [](key)
-        get(key)
-      end
     end
   end
 end

data/lib/hts/bam/cigar.rb

@@ -6,11 +6,31 @@ module HTS
     class Cigar
       include Enumerable
 
-      def initialize(pointer, n_cigar)
-        @n_cigar = n_cigar
-        # Read the pointer before the memory is changed.
-        # Especially when called from a block of `each` iterator.
-        @c = pointer.read_array_of_uint32(n_cigar)
+      # a uint32_t array (with 32 bits for every CIGAR op: length<<4|operation)
+      attr_accessor :array
+
+      # Create a new Cigar object from a string.
+      # @param [String] cigar_str
+      # The CIGAR string is converted to a uint32_t array in htslib.
+      def self.parse(str)
+        c = FFI::MemoryPointer.new(:pointer)
+        m = FFI::MemoryPointer.new(:size_t)
+        LibHTS.sam_parse_cigar(str, FFI::Pointer::NULL, c, m)
+        cigar_array = c.read_pointer.read_array_of_uint32(m.read(:size_t))
+        obj = new
+        obj.array = cigar_array
+        obj
+      end
+
+      def initialize(record = nil)
+        if record
+          # The record is used at initialization and is not retained after that.
+          bam1 = record.struct
+          n_cigar = bam1[:core][:n_cigar]
+          @array = LibHTS.bam_get_cigar(bam1).read_array_of_uint32(n_cigar)
+        else
+          @array = []
+        end
       end
 
       def to_s
@@ -20,12 +40,32 @@ module HTS
       def each
         return to_enum(__method__) unless block_given?
 
-        @c.each do |c|
+        @array.each do |c|
           op =  LibHTS.bam_cigar_opchr(c)
           len = LibHTS.bam_cigar_oplen(c)
           yield [op, len]
         end
       end
+
+      def qlen
+        a = FFI::MemoryPointer.new(:uint32, @array.size)
+        a.write_array_of_uint32(@array)
+        LibHTS.bam_cigar2qlen(@array.size, a)
+      end
+
+      def rlen
+        a = FFI::MemoryPointer.new(:uint32, @array.size)
+        a.write_array_of_uint32(@array)
+        LibHTS.bam_cigar2rlen(@array.size, a)
+      end
+
+      def ==(other)
+        other.is_a?(Cigar) && (@array == other.array)
+      end
+
+      def eql?(other)
+        other.is_a?(Cigar) && @array.eql?(other.array)
+      end
     end
   end
 end

data/lib/hts/bam/flag.rb

@@ -28,8 +28,6 @@ module HTS
       # BAM_FDUP           = 1024
       # BAM_FSUPPLEMENTARY = 2048
 
-      # TODO: Enabling bitwise operations?
-
       TABLE = { paired?: LibHTS::BAM_FPAIRED,
                 proper_pair?: LibHTS::BAM_FPROPER_PAIR,
                 unmapped?: LibHTS::BAM_FUNMAP,
@@ -43,16 +41,57 @@ module HTS
                 duplicate?: LibHTS::BAM_FDUP,
                 supplementary?: LibHTS::BAM_FSUPPLEMENTARY }.freeze
 
-      TABLE.each do |name, v|
+      # @!macro [attach] generate_flag_methods
+      #   @!method $1
+      #   @return [Boolean]
+      def self.generate(name)
         define_method(name) do
-          has_flag?(v)
+          (@value & TABLE[name]) != 0
         end
       end
+      private_class_method :generate
+
+      generate :paired?
+      generate :proper_pair?
+      generate :unmapped?
+      generate :mate_unmapped?
+      generate :reverse?
+      generate :mate_reverse?
+      generate :read1?
+      generate :read2?
+      generate :secondary?
+      generate :qcfail?
+      generate :duplicate?
+      generate :supplementary?
 
       def has_flag?(f)
         (@value & f) != 0
       end
 
+      def &(other)
+        Flag.new(@value & other.to_i)
+      end
+
+      def |(other)
+        Flag.new(@value | other.to_i)
+      end
+
+      def ^(other)
+        Flag.new(@value ^ other.to_i)
+      end
+
+      def ~
+        Flag.new(~@value)
+      end
+
+      def <<(f)
+        Flag.new(@value << f.to_i)
+      end
+
+      def >>(other)
+        Flag.new(@value >> other.to_i)
+      end
+
       def to_i
         @value
       end

data/lib/hts/bam/header.rb

@@ -87,6 +87,14 @@ module HTS
         LibHTS.sam_hdr_str(@sam_hdr)
       end
 
+      def name2tid(name)
+        LibHTS.sam_hdr_name2tid(@sam_hdr, name)
+      end
+
+      def tid2name(tid)
+        LibHTS.sam_hdr_tid2name(@sam_hdr, tid)
+      end
+
       private
 
       def initialize_copy(orig)

data/lib/hts/bam/record.rb

@@ -12,8 +12,8 @@ module HTS
 
       attr_reader :header
 
-      def initialize(bam1_t, header)
-        @bam1 = bam1_t
+      def initialize(header, bam1_t = nil)
+        @bam1 = bam1_t || LibHTS.bam_init1
         @header = header
       end
 
@@ -32,6 +32,10 @@ module HTS
         LibHTS.bam_get_qname(@bam1).read_string
       end
 
+      def qname=(name)
+        LibHTS.bam_set_qname(@bam1, name)
+      end
+
       # Get the chromosome ID of the alignment. -1 if not mapped.
       # @return [Integer] chromosome ID
       def tid
@@ -151,12 +155,13 @@ module HTS
       # Get the Bam::Cigar object.
       # @return [Bam::Cigar] cigar
       def cigar
-        Cigar.new(LibHTS.bam_get_cigar(@bam1), @bam1[:core][:n_cigar])
+        Cigar.new(self)
       end
 
       # 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)
@@ -177,7 +182,7 @@ module HTS
       def seq
         r = LibHTS.bam_get_seq(@bam1)
         seq = String.new
-        (@bam1[:core][:l_qseq]).times do |i|
+        len.times do |i|
           seq << SEQ_NT16_STR[LibHTS.bam_seqi(r, i)]
         end
         seq
@@ -194,8 +199,8 @@ module HTS
       # @param [Integer] i index
       # @return [String] base
       def base(n)
-        n += @bam1[:core][:l_qseq] if n < 0
-        return "." if (n >= @bam1[:core][:l_qseq]) || (n < 0) # eg. base(-1000)
+        n += len if n < 0
+        return "." if (n >= len) || (n < 0) # eg. base(-1000)
 
         r = LibHTS.bam_get_seq(@bam1)
         SEQ_NT16_STR[LibHTS.bam_seqi(r, n)]
@@ -205,7 +210,7 @@ module HTS
       # @return [Array] base qualities
       def qual
         q_ptr = LibHTS.bam_get_qual(@bam1)
-        q_ptr.read_array_of_uint8(@bam1[:core][:l_qseq])
+        q_ptr.read_array_of_uint8(len)
       end
 
       # Get the base qualities as a string. (a.k.a QUAL)
@@ -219,8 +224,8 @@ module HTS
       # @param [Integer] i index
       # @return [Integer] base quality
       def base_qual(n)
-        n += @bam1[:core][:l_qseq] if n < 0
-        return 0 if (n >= @bam1[:core][:l_qseq]) || (n < 0) # eg. base_qual(-1000)
+        n += len if n < 0
+        return 0 if (n >= len) || (n < 0) # eg. base_qual(-1000)
 
         q_ptr = LibHTS.bam_get_qual(@bam1)
         q_ptr.get_uint8(n)
@@ -255,11 +260,11 @@ module HTS
         end
       end
 
-      # TODO: add a method to get the auxillary fields as a hash.
+      # TODO: add a method to get the auxiliary fields as a hash.
 
-      # TODO: add a method to set the auxillary fields.
+      # TODO: add a method to set the auxiliary fields.
 
-      # TODO: add a method to remove the auxillary fields.
+      # TODO: add a method to remove the auxiliary fields.
 
       # TODO: add a method to set variable length data (qname, cigar, seq, qual).
 

data/lib/hts/bam.rb

@@ -59,7 +59,7 @@ module HTS
       @start_position = tell
     end
 
-    def build_index(index_name = nil, min_shift: 0)
+    def build_index(index_name = nil, min_shift: 0, threads: 2)
       check_closed
 
       if index_name
@@ -67,10 +67,15 @@ module HTS
       else
         warn "Create index for #{@file_name}"
       end
-      r = LibHTS.sam_index_build3(@file_name, index_name, min_shift, @nthreads)
-      raise "Failed to build index for #{@file_name}" if r < 0
-
-      self
+      case LibHTS.sam_index_build3(@file_name, index_name, min_shift, (@nthreads || threads))
+      when 0 # successful
+      when -1 then raise "indexing failed"
+      when -2 then raise "opening #{@file_name} failed"
+      when -3 then raise "format not indexable"
+      when -4 then raise "failed to create and/or save the index"
+      else raise "unknown error"
+      end
+      self # for method chaining
     end
 
     def load_index(index_name = nil)
@@ -95,11 +100,6 @@ module HTS
       super
     end
 
-    def fai=(fai)
-      check_closed
-      LibHTS.hts_set_fai_filename(@hts_file, fai) > 0 || raise
-    end
-
     def write_header(header)
       check_closed
 
@@ -107,28 +107,19 @@ module HTS
       LibHTS.sam_hdr_write(@hts_file, header)
     end
 
-    def write(aln)
+    def header=(header)
+      write_header(header)
+    end
+
+    def write(record)
       check_closed
 
-      aln_dup = aln.dup
-      r = LibHTS.sam_write1(@hts_file, header, aln_dup)
+      r = LibHTS.sam_write1(@hts_file, header, record)
       raise "Failed to write record" if r < 0
     end
 
-    def each(copy: false, &block)
-      if copy
-        each_record_copy(&block)
-      else
-        each_record_reuse(&block)
-      end
-    end
-
-    def query(region, copy: false, &block)
-      if copy
-        query_copy(region, &block)
-      else
-        query_reuse(region, &block)
-      end
+    def <<(record)
+      write(record)
     end
 
     # @!macro [attach] define_getter
@@ -150,9 +141,10 @@ module HTS
     alias isize insert_size
     alias mpos mate_pos
 
+    # FXIME: experimental
     def aux(tag)
-      warn "experimental"
       check_closed
+
       position = tell
       ary = map { |r| r.aux(tag) }
       seek(position)
@@ -177,8 +169,8 @@ module HTS
     alias each_isize each_insert_size
     alias each_mpos each_mate_pos
 
+    # FIXME: experimental
     def each_aux(tag)
-      warn "experimental"
       check_closed
       return to_enum(__method__, tag) unless block_given?
 
@@ -189,47 +181,44 @@ module HTS
       self
     end
 
-    private
+    def each(copy: false, &block)
+      if copy
+        each_record_copy(&block)
+      else
+        each_record_reuse(&block)
+      end
+    end
 
-    def query_reuse(region)
+    def query(region, beg = nil, end_ = nil, copy: false, &block)
       check_closed
       raise "Index file is required to call the query method." unless index_loaded?
-      return to_enum(__method__, region) unless block_given?
-
-      qiter = LibHTS.sam_itr_querys(@idx, header, region)
-      raise "Failed to query region: #{region}" if qiter.null?
 
-      bam1 = LibHTS.bam_init1
-      record = Record.new(bam1, header)
-      begin
-        yield record while LibHTS.sam_itr_next(@hts_file, qiter, bam1) > 0
-      ensure
-        LibHTS.hts_itr_destroy(qiter)
+      if beg && end_
+        tid = header.name2tid(region)
+        queryi(tid, beg, end_, copy:, &block)
+      elsif beg.nil? && end_.nil?
+        querys(region, copy:, &block)
+      else
+        raise ArgumentError, "beg and end_ must be specified together"
       end
-      self
     end
 
-    def query_copy(region)
-      check_closed
-      raise "Index file is required to call the query method." unless index_loaded?
-      return to_enum(__method__, region) unless block_given?
+    private
 
-      qiter = LibHTS.sam_itr_querys(@idx, header, region)
-      raise "Failed to query region: #{region}" if qiter.null?
+    def queryi(tid, beg, end_, copy: false, &block)
+      if copy
+        queryi_copy(tid, beg, end_, &block)
+      else
+        queryi_reuse(tid, beg, end_, &block)
+      end
+    end
 
-      begin
-        loop do
-          bam1 = LibHTS.bam_init1
-          slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)
-          break if slen == -1
-          raise if slen < -1
-
-          yield Record.new(bam1, header)
-        end
-      ensure
-        LibHTS.hts_itr_destroy(qiter)
+    def querys(region, copy: false, &block)
+      if copy
+        querys_copy(region, &block)
+      else
+        querys_reuse(region, &block)
       end
-      self
     end
 
     def each_record_reuse
@@ -239,7 +228,7 @@ module HTS
       return to_enum(__method__) unless block_given?
 
       bam1 = LibHTS.bam_init1
-      record = Record.new(bam1, header)
+      record = Record.new(header, bam1)
       yield record while LibHTS.sam_read1(@hts_file, header, bam1) != -1
       self
     end
@@ -249,10 +238,73 @@ module HTS
       return to_enum(__method__) unless block_given?
 
       while LibHTS.sam_read1(@hts_file, header, bam1 = LibHTS.bam_init1) != -1
-        record = Record.new(bam1, header)
+        record = Record.new(header, bam1)
         yield record
       end
       self
     end
+
+    def queryi_reuse(tid, beg, end_, &block)
+      return to_enum(__method__, region, beg, end_) unless block_given?
+
+      qiter = LibHTS.sam_itr_queryi(@idx, tid, beg, end_)
+      raise "Failed to query region: #{tid} #{beg} #{end_}" if qiter.null?
+
+      query_reuse_yield(qiter, &block)
+      self
+    end
+
+    def queryi_copy(tid, beg, end_, &block)
+      return to_enum(__method__, tid, beg, end_) unless block_given?
+
+      qiter = LibHTS.sam_itr_queryi(@idx, tid, beg, end_)
+      raise "Failed to query region: #{tid} #{beg} #{end_}" if qiter.null?
+
+      query_copy(qiter, &block)
+      self
+    end
+
+    def querys_reuse(region, &block)
+      return to_enum(__method__, region) unless block_given?
+
+      qiter = LibHTS.sam_itr_querys(@idx, header, region)
+      raise "Failed to query region: #{region}" if qiter.null?
+
+      query_reuse_yield(qiter, &block)
+      self
+    end
+
+    def querys_copy(region, &block)
+      return to_enum(__method__, region) unless block_given?
+
+      qiter = LibHTS.sam_itr_querys(@idx, header, region)
+      raise "Failed to query region: #{region}" if qiter.null?
+
+      query_copy(qiter, &block)
+      self
+    end
+
+    def query_reuse_yield(qiter)
+      bam1 = LibHTS.bam_init1
+      record = Record.new(header, bam1)
+      begin
+        yield record while LibHTS.sam_itr_next(@hts_file, qiter, bam1) > 0
+      ensure
+        LibHTS.hts_itr_destroy(qiter)
+      end
+    end
+
+    def query_copy(qiter)
+      loop do
+        bam1 = LibHTS.bam_init1
+        slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)
+        break if slen == -1
+        raise if slen < -1
+
+        yield Record.new(header, bam1)
+      end
+    ensure
+      LibHTS.hts_itr_destroy(qiter)
+    end
   end
 end

data/lib/hts/bcf/format.rb

@@ -8,30 +8,10 @@ module HTS
         @p1 = FFI::MemoryPointer.new(:pointer) # FIXME: naming
       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_flag(key)
-        get(key, :flag)
-      end
-
-      # For compatibility with HTS.cr.
-      def get_string(key)
-        get(key, :string)
-      end
-
-      def [](key)
-        get(key)
-      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)
         n = FFI::MemoryPointer.new(:int)
         p1 = @p1
@@ -73,6 +53,30 @@ module HTS
         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_flag(key)
+        get(key, :flag)
+      end
+
+      # For compatibility with HTS.cr.
+      def get_string(key)
+        get(key, :string)
+      end
+
+      def [](key)
+        get(key)
+      end
+
       def fields
         ids.map do |id|
           name = LibHTS.bcf_hdr_int2id(@record.header.struct, LibHTS::BCF_DT_ID, id)