htslib 0.2.3 → 0.2.6

data/lib/hts/bam/header.rb

@@ -1,11 +1,26 @@
 # frozen_string_literal: true
 
+require_relative "header_record"
+
 module HTS
   class Bam < Hts
     # A class for working with alignment header.
     class Header
-      def initialize(hts_file)
-        @sam_hdr = LibHTS.sam_hdr_read(hts_file)
+      def self.parse(str)
+        new(LibHTS.sam_hdr_parse(str.size, str))
+      end
+
+      def initialize(arg = nil)
+        case arg
+        when LibHTS::HtsFile
+          @sam_hdr = LibHTS.sam_hdr_read(arg)
+        when LibHTS::SamHdr
+          @sam_hdr = arg
+        when nil
+          @sam_hdr = LibHTS.sam_hdr_init
+        else
+          raise TypeError, "Invalid argument"
+        end
       end
 
       def struct
@@ -17,6 +32,7 @@ module HTS
       end
 
       def target_count
+        # FIXME: sam_hdr_nref
         @sam_hdr[:n_targets]
       end
 
@@ -32,6 +48,41 @@ module HTS
         end
       end
 
+      # experimental
+      def add_lines(str)
+        LibHTS.sam_hdr_add_lines(@sam_hdr, str, 0)
+      end
+
+      # experimental
+      def add_line(type, *args)
+        args = args.flat_map { |arg| [:string, arg] }
+        LibHTS.sam_hdr_add_line(@sam_hdr, type, *args, :pointer, FFI::Pointer::NULL)
+      end
+
+      # experimental
+      def find_line(type, key, value)
+        ks = LibHTS::KString.new
+        r = LibHTS.sam_hdr_find_line_id(@sam_hdr, type, key, value, ks)
+        r == 0 ? ks[:s] : nil
+      end
+
+      # experimental
+      def find_line_at(type, pos)
+        ks = LibHTS::KString.new
+        r = LibHTS.sam_hdr_find_line_pos(@sam_hdr, type, pos, ks)
+        r == 0 ? ks[:s] : nil
+      end
+
+      # experimental
+      def remove_line(type, key, value)
+        LibHTS.sam_hdr_remove_line_id(@sam_hdr, type, key, value)
+      end
+
+      # experimental
+      def remove_line_at(type, pos)
+        LibHTS.sam_hdr_remove_line_pos(@sam_hdr, type, pos)
+      end
+
       def to_s
         LibHTS.sam_hdr_str(@sam_hdr)
       end

data/lib/hts/bam/header_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    class HeaderRecord
+      def initialize
+        @bam_hrec
+      end
+    end
+  end
+end

data/lib/hts/bam/record.rb

@@ -17,6 +17,7 @@ module HTS
         @header = header
       end
 
+      # Return the FFI::Struct object.
       def struct
         @bam1
       end
@@ -25,17 +26,14 @@ module HTS
         @bam1.to_ptr
       end
 
-      # returns the query name.
+      # Get the read name. (a.k.a QNAME)
+      # @return [String] query template name
       def qname
         LibHTS.bam_get_qname(@bam1).read_string
       end
 
-      # Set (query) name.
-      # def qname=(name)
-      #   raise 'Not Implemented'
-      # end
-
-      # returns the tid of the record or -1 if not mapped.
+      # Get the chromosome ID of the alignment. -1 if not mapped.
+      # @return [Integer] chromosome ID
       def tid
         @bam1[:core][:tid]
       end
@@ -44,7 +42,8 @@ module HTS
         @bam1[:core][:tid] = tid
       end
 
-      # returns the tid of the mate or -1 if not mapped.
+      # Get the chromosome ID of the mate. -1 if not mapped.
+      # @return [Integer] chromosome ID
       def mtid
         @bam1[:core][:mtid]
       end
@@ -53,7 +52,8 @@ module HTS
         @bam1[:core][:mtid] = mtid
       end
 
-      # returns 0-based start position.
+      # Get the 0-based leftmost coordinate of the alignment.
+      # @return [Integer] 0-based leftmost coordinate
       def pos
         @bam1[:core][:pos]
       end
@@ -62,7 +62,8 @@ module HTS
         @bam1[:core][:pos] = pos
       end
 
-      # returns 0-based mate position
+      # Get the 0-based leftmost coordinate of the mate.
+      # @return [Integer] 0-based leftmost coordinate
       def mate_pos
         @bam1[:core][:mpos]
       end
@@ -74,6 +75,8 @@ module HTS
       alias mpos mate_pos
       alias mpos= mate_pos=
 
+      # Get the bin calculated by bam_reg2bin().
+      # @return [Integer] bin
       def bin
         @bam1[:core][:bin]
       end
@@ -82,12 +85,15 @@ module HTS
         @bam1[:core][:bin] = bin
       end
 
-      # returns end position of the read.
+      # 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
 
-      # returns the chromosome or '' if not mapped.
+      # 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
 
@@ -96,7 +102,9 @@ module HTS
 
       alias contig chrom
 
-      # returns the chromosome of the mate or '' if not mapped.
+      # Get the reference sequence name of the mate.
+      # '' if not mapped.
+      # @return [String] reference sequence name
       def mate_chrom
         return "" if mtid == -1
 
@@ -105,12 +113,20 @@ module HTS
 
       alias mate_contig mate_chrom
 
-      # Get strand information.
+      # Get whether the query is on the reverse strand.
+      # @return [String] strand "+" or "-"
       def strand
         LibHTS.bam_is_rev(@bam1) ? "-" : "+"
       end
 
-      # insert size
+      # Get whether the query's mate is on the reverse strand.
+      # @return [String] strand "+" or "-"
+      def mate_strand
+        LibHTS.bam_is_mrev(@bam1) ? "-" : "+"
+      end
+
+      # Get the observed template length. (a.k.a TLEN)
+      # @return [Integer] isize
       def insert_size
         @bam1[:core][:isize]
       end
@@ -122,7 +138,8 @@ module HTS
       alias isize insert_size
       alias isize= insert_size=
 
-      # mapping quality
+      # Get the mapping quality of the alignment. (a.k.a MAPQ)
+      # @return [Integer] mapping quality
       def mapq
         @bam1[:core][:qual]
       end
@@ -131,18 +148,24 @@ module HTS
         @bam1[:core][:qual] = mapq
       end
 
-      # returns a `Cigar` object.
+      # 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)
         )
       end
 
+      # Calculate reference length from CIGAR.
+      # @return [Integer] reference length
       def rlen
         LibHTS.bam_cigar2rlen(
           @bam1[:core][:n_cigar],
@@ -150,7 +173,8 @@ module HTS
         )
       end
 
-      # return the read sequence
+      # Get the sequence. (a.k.a SEQ)
+      # @return [String] sequence
       def seq
         r = LibHTS.bam_get_seq(@bam1)
         seq = String.new
@@ -161,11 +185,15 @@ module HTS
       end
       alias sequence seq
 
+      # Get the length of the query sequence.
+      # @return [Integer] query length
       def len
         @bam1[:core][:l_qseq]
       end
 
-      # return only the base of the requested index "i" of the query sequence.
+      # Get the base of the requested index "i" of the query sequence.
+      # @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)
@@ -174,13 +202,23 @@ module HTS
         SEQ_NT16_STR[LibHTS.bam_seqi(r, n)]
       end
 
-      # return the base qualities
+      # Get the base qualities.
+      # @return [Array] base qualities
       def qual
         q_ptr = LibHTS.bam_get_qual(@bam1)
         q_ptr.read_array_of_uint8(@bam1[:core][:l_qseq])
       end
 
-      # return only the base quality of the requested index "i" of the query sequence.
+      # 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
+      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 += @bam1[:core][:l_qseq] if n < 0
         return 0 if (n >= @bam1[:core][:l_qseq]) || (n < 0) # eg. base_qual(-1000)
@@ -189,7 +227,8 @@ module HTS
         q_ptr.get_uint8(n)
       end
 
-      # returns a `Flag` object.
+      # Get Bam::Flag object of the alignment.
+      # @return [Bam::Flag] flag
       def flag
         Flag.new(@bam1[:core][:flag])
       end
@@ -205,7 +244,9 @@ module HTS
         end
       end
 
-      # retruns the auxillary fields.
+      # Get the auxiliary data.
+      # @param [String] key tag name
+      # @return [String] value
       def aux(key = nil)
         aux = Aux.new(self)
         if key
@@ -230,6 +271,7 @@ module HTS
         end
       end
 
+      # @return [String] a string representation of the alignment.
       def to_s
         kstr = LibHTS::KString.new
         raise "Failed to format bam record" if LibHTS.sam_format1(@header.struct, @bam1, kstr) == -1

data/lib/hts/bam.rb

@@ -57,10 +57,9 @@ module HTS
       build_index(index) if build_index
       @idx = load_index(index)
       @start_position = tell
-      super # do nothing
     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
@@ -68,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)
@@ -90,7 +94,6 @@ module HTS
       !@idx.null?
     end
 
-    # Close the current file.
     def close
       LibHTS.hts_idx_destroy(@idx) if @idx&.null?
       @idx = nil
@@ -101,15 +104,23 @@ module HTS
       check_closed
 
       @header = header.dup
-      LibHTS.hts_set_fai_filename(@hts_file, @file_name)
       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
-      LibHTS.sam_write1(@hts_file, header, aln_dup) > 0 || raise
+      # record = record.dup
+      r = LibHTS.sam_write1(@hts_file, header, record)
+      raise "Failed to write record" if r < 0
+    end
+
+    def <<(aln)
+      write(aln)
     end
 
     def each(copy: false, &block)
@@ -120,29 +131,6 @@ module HTS
       end
     end
 
-    private def each_record_copy
-      check_closed
-      return to_enum(__method__) unless block_given?
-
-      while LibHTS.sam_read1(@hts_file, header, bam1 = LibHTS.bam_init1) != -1
-        record = Record.new(bam1, header)
-        yield record
-      end
-      self
-    end
-
-    private def each_record_reuse
-      check_closed
-      # Each does not always start at the beginning of the file.
-      # This is the common behavior of IO objects in Ruby.
-      return to_enum(__method__) unless block_given?
-
-      bam1 = LibHTS.bam_init1
-      record = Record.new(bam1, header)
-      yield record while LibHTS.sam_read1(@hts_file, header, bam1) != -1
-      self
-    end
-
     def query(region, copy: false, &block)
       if copy
         query_copy(region, &block)
@@ -151,45 +139,6 @@ module HTS
       end
     end
 
-    private 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?
-
-      qiter = LibHTS.sam_itr_querys(@idx, header, region)
-
-      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)
-      end
-      self
-    end
-
-    private def query_reuse(region)
-      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)
-
-      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)
-      end
-      self
-    end
-
     # @!macro [attach] define_getter
     #   @method $1
     #   Get $1 array
@@ -247,5 +196,71 @@ module HTS
 
       self
     end
+
+    private
+
+    def query_reuse(region)
+      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)
+      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?
+
+      qiter = LibHTS.sam_itr_querys(@idx, header, region)
+      raise "Failed to query region: #{region}" if qiter.null?
+
+      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)
+      end
+      self
+    end
+
+    def each_record_reuse
+      check_closed
+      # Each does not always start at the beginning of the file.
+      # This is the common behavior of IO objects in Ruby.
+      return to_enum(__method__) unless block_given?
+
+      bam1 = LibHTS.bam_init1
+      record = Record.new(bam1, header)
+      yield record while LibHTS.sam_read1(@hts_file, header, bam1) != -1
+      self
+    end
+
+    def each_record_copy
+      check_closed
+      return to_enum(__method__) unless block_given?
+
+      while LibHTS.sam_read1(@hts_file, header, bam1 = LibHTS.bam_init1) != -1
+        record = Record.new(bam1, header)
+        yield record
+      end
+      self
+    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 htslib.cr.
-      def get_int(key)
-        get(key, :int)
-      end
-
-      # For compatibility with htslib.cr.
-      def get_float(key)
-        get(key, :float)
-      end
-
-      # For compatibility with htslib.cr.
-      def get_flag(key)
-        get(key, :flag)
-      end
-
-      # For compatibility with htslib.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)