htslib 0.4.2 → 0.6.0

data/lib/hts/bam.rb

@@ -17,6 +17,25 @@ module HTS
   class Bam
     include Enumerable
 
+    class ReadError < HTS::Error; end
+    class WriteError < HTS::Error; end
+    class OpenError < HTS::Error; end
+    class MissingIndexError < HTS::Error; end
+
+    # Filter an owning batch of records in one native pass when available.
+    def self.filter_records(records, required_flags: 0, excluded_flags: 0,
+                            min_mapq: 0, tid: nil, beg: nil, end_: nil)
+      required_flags = Integer(required_flags)
+      excluded_flags = Integer(excluded_flags)
+      min_mapq = Integer(min_mapq)
+      Array(records).select do |record|
+        flags = record.flag_value
+        (flags & required_flags) == required_flags && (flags & excluded_flags).zero? &&
+          record.mapq >= min_mapq && (tid.nil? || record.tid == Integer(tid)) &&
+          (beg.nil? || record.endpos > Integer(beg)) && (end_.nil? || record.pos < Integer(end_))
+      end
+    end
+
     attr_reader :file_name, :index_name, :mode, :header, :nthreads
 
     def self.open(*args, **kw)
@@ -24,11 +43,11 @@ module HTS
       return file unless block_given?
 
       begin
-        yield file
+        result = yield file
       ensure
         file.close
       end
-      file
+      result
     end
 
     def self.build_index(file_name, index_name = nil, min_shift = 0, threads = 0, verbose = true)
@@ -40,7 +59,7 @@ module HTS
         end
       end
 
-      case LibHTS.sam_index_build3(file_name, index_name, min_shift, threads)
+      case Native::BamFileHandle.build_index(file_name, index_name, min_shift, threads)
       when 0 # successful
       when -1 then raise "indexing failed"
       when -2 then raise "opening #{file_name} failed"
@@ -63,9 +82,8 @@ module HTS
       @index_name = index
       @mode       = mode
       @nthreads   = threads
-      @hts_file   = LibHTS.hts_open(@file_name, mode)
-
-      raise Errno::ENOENT, "Failed to open #{@file_name}" if @hts_file.null?
+      @index_load_attempted = false
+      @native = Native::BamFileHandle.open(@file_name, mode)
 
       # Auto-detect and set reference for CRAM files
       if fai.nil? && @file_name.end_with?(".cram")
@@ -79,17 +97,25 @@ module HTS
       end
 
       if fai
-        r = LibHTS.hts_set_fai_filename(@hts_file, fai)
+        r = @native.set_fai(fai)
         raise "Failed to load fasta index: #{fai}" if r < 0
       end
 
       set_threads(threads) if threads
 
-      return if @mode[0] == "w"
+      if writing?
+        @auto_index_on_close = build_index
+        @index_name_on_close = index
+        return
+      end
 
-      @header = Bam::Header.new(@hts_file)
-      build_index(index) if build_index
-      @idx = load_index(index)
+      @header = Bam::Header.new(@native.read_header)
+      if build_index
+        build_index(index)
+        load_index(index)
+      elsif index
+        load_index(index)
+      end
       @start_position = tell
     end
 
@@ -97,36 +123,87 @@ module HTS
       check_closed
 
       self.class.build_index(@file_name, index_name, min_shift, @nthreads || 0, verbose)
+      @index_name = index_name
+      @index_load_attempted = false
       self # for method chaining
     end
 
     def load_index(index_name = nil)
+      return self if try_load_index(index_name)
+
+      raise MissingIndexError, "Failed to load index #{index_name || "for #{@file_name}"}"
+    end
+
+    def try_load_index(index_name = nil)
       check_closed
 
-      if index_name
-        LibHTS.sam_index_load2(@hts_file, @file_name, index_name)
-      else
-        LibHTS.sam_index_load3(@hts_file, @file_name, nil, 2) # should be 3 ? (copy remote file to local?)
-      end
+      @index_name = index_name
+      @index_load_attempted = true
+      @native.load_index(index_name)
     end
 
     def index_loaded?
       check_closed
 
-      !@idx.null?
+      @native.index_loaded?
     end
 
     def close
-      LibHTS.hts_idx_destroy(@idx) if @idx && !@idx.null?
-      @idx = nil
-      super
+      was_closed = closed?
+      result = @native&.close
+      raise WriteError, "Failed to close #{@file_name}: buffered output may be incomplete" if writing? && result&.negative?
+
+      if writing? && @auto_index_on_close && !was_closed
+        @auto_index_on_close = false
+        self.class.build_index(@file_name, @index_name_on_close, 0, @nthreads || 0, false)
+      end
+
+      nil
+    end
+
+    def closed? = @native.nil? || @native.closed?
+    def file_format = @native.file_format
+    def file_format_version = @native.file_format_version
+
+    def set_threads(n = nil)
+      if n.nil?
+        require "etc"
+        n = [Etc.nprocessors - 1, 1].max
+      end
+      raise TypeError unless n.is_a?(Integer)
+      raise ArgumentError, "Number of threads must be positive" if n < 1
+      raise "Failed to set number of threads: #{n}" if @native.set_threads(n).negative?
+
+      @nthreads = n
+      self
+    end
+
+    def seek(offset) = @native.seek(offset)
+    def tell = @native.tell
+
+    def rewind
+      raise "Cannot rewind: no start position" unless @start_position
+
+      result = seek(@start_position)
+      raise "Failed to rewind: #{result}" if result.negative?
+
+      tell
     end
 
+    private
+
+    def writing? = @mode&.start_with?("w", "a")
+
+    def native_handle = @native
+
+    public
+
     def write_header(header)
       check_closed
 
       @header = header.dup
-      LibHTS.sam_hdr_write(@hts_file, header)
+      @native.write_header(header.__send__(:native_handle))
+      nil
     end
 
     def header=(header)
@@ -136,12 +213,15 @@ module HTS
     def write(record)
       check_closed
 
-      r = LibHTS.sam_write1(@hts_file, header, record)
+      r = @native.write(header.__send__(:native_handle), record.__send__(:native_handle))
       raise "Failed to write record" if r < 0
+
+      nil
     end
 
     def <<(record)
       write(record)
+      self
     end
 
     # @!macro [attach] define_getter
@@ -172,6 +252,20 @@ module HTS
       seek(position) if position
       ary
     end
+    alias aux_array aux
+
+    # Materialize independent records from the current stream position.
+    # Unlike each.to_a, every element owns its bam1_t storage.
+    def collect_records
+      each(copy: true).to_a
+    end
+
+    # Materialize independent, owning records. Enumerable#to_a is unsafe for
+    # the default reused-record iterator because every array element would
+    # otherwise refer to the same native bam1_t buffer.
+    def to_a
+      collect_records
+    end
 
     # @!macro [attach] define_iterator
     #   @method each_$1
@@ -236,7 +330,7 @@ module HTS
     #   bam.query(["chr1:100-200", "chr2:500-600"]) { |r| puts r.qname }
     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?
+      raise "Index file is required to call the query method." unless ensure_index_loaded
 
       case region
       when Array
@@ -280,6 +374,13 @@ module HTS
 
     private
 
+    def ensure_index_loaded
+      return true if index_loaded?
+      return false if @index_load_attempted
+
+      load_index(@index_name)
+    end
+
     def queryi(tid, beg, end_, copy: false, &block)
       if copy
         queryi_copy(tid, beg, end_, &block)
@@ -313,9 +414,14 @@ module HTS
       # This is the common behavior of IO objects in Ruby.
       return to_enum(__method__) unless block_given?
 
-      bam1 = LibHTS.bam_init1
-      record = Record.new(header, bam1)
-      yield record while LibHTS.sam_read1(@hts_file, header, bam1) != -1
+      record = Record.new(header)
+      loop do
+        result = @native.read(header.__send__(:native_handle), record.__send__(:native_handle))
+        break if result == -1
+        raise ReadError, "Failed to read BAM/SAM record (HTSlib error #{result})" if result < -1
+
+        yield record
+      end
       self
     end
 
@@ -324,17 +430,22 @@ module HTS
       check_closed
       return to_enum(__method__) unless block_given?
 
-      bam1 = LibHTS.bam_init1
-      record = Record.new(header, bam1)
-      yield record.dup while LibHTS.sam_read1(@hts_file, header, bam1) != -1
+      record = Record.new(header)
+      loop do
+        result = @native.read(header.__send__(:native_handle), record.__send__(:native_handle))
+        break if result == -1
+        raise ReadError, "Failed to read BAM/SAM record (HTSlib error #{result})" if result < -1
+
+        yield record.dup
+      end
       self
     end
 
     def queryi_reuse(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?
+      qiter = @native.query_interval(tid, beg, end_)
+      raise "Failed to query region: #{tid} #{beg} #{end_}" unless qiter
 
       query_reuse_yield(qiter, &block)
       self
@@ -343,8 +454,8 @@ module HTS
     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?
+      qiter = @native.query_interval(tid, beg, end_)
+      raise "Failed to query region: #{tid} #{beg} #{end_}" unless qiter
 
       query_copy(qiter, &block)
       self
@@ -353,8 +464,8 @@ module HTS
     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?
+      qiter = @native.query_region(header.__send__(:native_handle), region)
+      raise "Failed to query region: #{region}" unless qiter
 
       query_reuse_yield(qiter, &block)
       self
@@ -363,8 +474,8 @@ module HTS
     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?
+      qiter = @native.query_region(header.__send__(:native_handle), region)
+      raise "Failed to query region: #{region}" unless qiter
 
       query_copy(qiter, &block)
       self
@@ -372,30 +483,28 @@ module HTS
 
     # Internal: reused-Record iterator over a query iterator.
     def query_reuse_yield(qiter)
-      bam1 = LibHTS.bam_init1
-      record = Record.new(header, bam1)
+      record = Record.new(header)
       begin
-        while (slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)) >= 0
+        while (slen = qiter.next(record.__send__(:native_handle))) >= 0
           yield record
         end
         raise if slen < -1
       ensure
-        LibHTS.hts_itr_destroy(qiter)
+        qiter.close
       end
     end
 
     def query_copy(qiter)
-      bam1 = LibHTS.bam_init1
-      record = Record.new(header, bam1)
+      record = Record.new(header)
       loop do
-        slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)
+        slen = qiter.next(record.__send__(:native_handle))
         break if slen == -1
         raise if slen < -1
 
         yield record.dup
       end
     ensure
-      LibHTS.hts_itr_destroy(qiter)
+      qiter.close
     end
 
     # Multi-region query using sequential single-region queries

data/lib/hts/bcf/errors.rb

@@ -5,14 +5,17 @@ module HTS
     class Error < HTS::Error; end
 
     class OpenError < Error; end
+    class WriteError < Error; end
     class IndexError < Error; end
     class MissingIndexError < IndexError; end
     class QueryError < Error; end
+    class RecordError < Error; end
     class HeaderError < Error; end
     class SubsetError < HeaderError; end
     class UnknownSampleError < SubsetError; end
     class FieldError < Error; end
     class InfoError < FieldError; end
+    class InfoDefinitionError < InfoError; end
     class InfoTypeError < InfoError; end
     class InfoReadError < InfoError; end
     class InfoUpdateError < InfoError; end
@@ -21,6 +24,7 @@ module HTS
     class FormatDefinitionError < FormatError; end
     class FormatTypeError < FormatError; end
     class FormatReadError < FormatError; end
+    class InvalidBorrowedViewError < FormatError; end
     class FormatUpdateError < FormatError; end
     class UnsupportedFormatOperationError < FormatError; end
   end