bio-bgzf 0.1.1 → 0.2.0

data/README.md

@@ -2,8 +2,8 @@
 
 [![Build Status](https://secure.travis-ci.org/csw/bioruby-bgzf.png)](http://travis-ci.org/csw/bioruby-bgzf)
 
-This library provides support for the [BGZF][] (Blocked GZip Format)
-in Ruby. BGZF, originally defined as part of the [SAM/BAM][]
+This library provides support for [BGZF][] (Blocked GZip Format) in
+Ruby. BGZF, originally defined as part of the [SAM/BAM][]
 specification, is used to compress record-oriented bioinformatics data
 in a way that facilitates random access, unlike plain gzip. A BGZF
 file consists of contatenated 64 KB blocks, each an independent gzip

data/Rakefile

@@ -18,7 +18,7 @@ Jeweler::Tasks.new do |gem|
   gem.homepage = "http://github.com/csw/bioruby-bgzf"
   gem.license = "MIT"
   gem.summary = %Q{Reading/writing BGZF blocks}
-  gem.description = %Q{BGZF compression is used nowadays only for providing random access to BAM format. However, it is completely independent from the format, and can be used for arbitrary data format. The gem allows to read BGZF blocks from streams and pack strings into blocks, aiming to facilitate introducing BGZF compression for Ruby users.}
+  gem.description = %Q{This library provides support for BGZF (Blocked GZip Format) in Ruby. BGZF, originally defined as part of the SAM/BAM specification, is used to compress record-oriented data in a way that facilitates random access, unlike plain gzip. BGZF is principally used for bioinformatics data but would be useful in other contexts as well.}
   gem.email = "cswh@umich.edu"
   gem.authors = ["Artem Tarasov", "Clayton Wheeler"]
   # dependencies defined in Gemfile

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/bio-bgzf.rb

@@ -2,5 +2,6 @@ require 'bio-bgzf/constants'
 require 'bio-bgzf/pack'
 require 'bio-bgzf/unpack'
 require 'bio-bgzf/block'
-require 'bio-bgzf/reader'
 require 'bio-bgzf/vo'
+require 'bio-bgzf/reader'
+require 'bio-bgzf/writer'

data/lib/bio-bgzf/block.rb

@@ -1,18 +1,24 @@
 module Bio::BGZF
 
+  class FormatError < StandardError
+  end
+
+  class NotBGZFError < FormatError
+  end
+
   def read_bgzf_block(f)
     hstart = f.read(12)
     return nil if hstart == nil # EOF?
     magic, gzip_extra_length = hstart.unpack('Vxxxxxxv')
-    raise 'wrong BGZF magic' unless magic == 0x04088B1F
+    raise NotBGZFError, "wrong BGZF magic: #{sprintf('%08x', magic)}" unless magic == 0x04088B1F
 
     len = 0
     bsize = nil
     while len < gzip_extra_length do
       si1, si2, slen = f.read(4).unpack('CCv')
       if si1 == 66 and si2 == 67 then
-        raise "BC subfield length is #{slen} but must be 2" if slen != 2
-        raise 'duplicate field with block size' unless bsize.nil?
+        raise FormatError, "BC subfield length is #{slen} but must be 2" if slen != 2
+        raise FormatError, 'duplicate field with block size' unless bsize.nil?
         bsize = f.read(2).unpack('v')[0]
         f.seek(slen - 2, IO::SEEK_CUR)
       else
@@ -22,9 +28,9 @@ module Bio::BGZF
     end
 
     if len != gzip_extra_length then
-      raise "total length of subfields is #{len} bytes but must be #{gzip_extra_length}"
+      raise FormatError, "total length of subfields is #{len} bytes but must be #{gzip_extra_length}"
     end
-    raise 'block size was not found in any subfield' if bsize.nil?
+    raise NotBGZFError, 'block size was not found in any subfield' if bsize.nil?
 
     compressed_data = f.read(bsize - gzip_extra_length - 19)
     crc32, input_size = f.read(8).unpack('VV')
@@ -38,11 +44,11 @@ module Bio::BGZF
     return nil if cdata == nil
     data = unpack(cdata)
     if data.bytesize != in_size
-      raise "Expected #{in_size} bytes from BGZF block at #{pos}, but got #{data.bytesize} bytes!"
+      raise FormatError, "Expected #{in_size} bytes from BGZF block at #{pos}, but got #{data.bytesize} bytes!"
     end
     crc = Zlib.crc32(data, 0)
     if crc != expected_crc
-      raise "CRC error: expected #{expected_crc.to_s(16)}, got #{crc.to_s(16)}"
+      raise FormatError, "CRC error: expected #{expected_crc.to_s(16)}, got #{crc.to_s(16)}"
     end
     return data
   end

data/lib/bio-bgzf/constants.rb

@@ -13,7 +13,9 @@ module Bio
     MTIME = 0
     XFL   = 0
     OS    = 255
-    XLEN  = 6 
+    XLEN  = 6
+
+    MAX_BYTES = 65536
 
   end
 end

data/lib/bio-bgzf/reader.rb

@@ -10,14 +10,32 @@ module Bio::BGZF
       @cur_block = nil
     end
 
+    # Returns the reader's current virtual offset. Between
+    # {#read_block} calls, the file position will always be at the
+    # start of a block or at EOF, so the low 16 bits of the virtual
+    # offset will always be zero.
+    #
+    # @return [Integer] virtual offset for current position
     def tell
       f.tell << 16
     end
 
+    # Reads the BGZF block at the current position. Returns its
+    # decompressed data.
+    #
+    # @return [String] decompressed block data
     def read_block
       decompress_block(f)
     end
 
+    # Reads a portion of a BGZF block, starting from the given virtual
+    # offset. If the offset is the start of a block (low 16 bits are
+    # zero) the entire block's data will be returned. Otherwise, the
+    # subset of the data starting at the given offset will be
+    # returned.
+    #
+    # @param [Integer] vo virtual offset to start from
+    # @return [String] decompressed block data
     def read_block_at(vo)
       block_offset = vo_block_offset(vo)
       data_offset = vo_data_offset(vo)
@@ -30,10 +48,14 @@ module Bio::BGZF
       end
     end
 
+    # Iterates over the blocks in a BGZF file, yielding [block, vo] pairs where 
     def each_block
       if block_given?
-        while b = read_block
-          yield b
+        while true
+          pos = tell
+          b = read_block
+          break unless b
+          yield b, pos
         end
       else
         enum_for(:each_block)

data/lib/bio-bgzf/writer.rb

@@ -0,0 +1,65 @@
+module Bio::BGZF
+  
+  class Writer
+    include Bio::BGZF
+
+    attr_reader :f, :buf
+
+    def initialize(f)
+      @f = f
+      @buf = ''
+      if block_given?
+        begin
+          yield self
+        ensure
+          self.close
+        end
+      end
+    end    
+
+    def tell
+      f.tell << 16
+    end
+
+    def write_buf
+      if buf.size > 0
+        raise "Buffer too large: #{buf.bytesize}" if buf.bytesize > MAX_BYTES
+        block = pack(buf)
+        f.write(block)
+        @buf = ''
+      end
+    end
+
+    def write(s)
+      if s.bytesize > MAX_BYTES
+        write_buf
+        _each_slice(s) do |slice|
+          write(slice)
+        end
+      else
+        if (s.bytesize + buf.bytesize) > MAX_BYTES
+          write_buf
+        end
+        buf << s
+      end
+    end
+
+    def _each_slice(s)
+      n = 0
+      size = s.bytesize
+      while true
+        offset = n * MAX_BYTES
+        break if offset >= size
+        yield s.slice(offset, MAX_BYTES)
+        n += 1
+      end
+    end
+
+    def close
+      write_buf
+      f.close
+    end
+    
+  end
+
+end

data/spec/bio-bgzf_spec.rb

@@ -11,8 +11,10 @@ describe Bio::BGZF do
   it "should be able to read BGZF blocks from a samtools file" do
     File.open("test/data/mm8.chrM.maf.gz") do |f|
       r = Bio::BGZF::Reader.new(f)
-      r.each_block do |block|
+      r.each_block do |block, pos|
         block.size.should <= 65536
+        pos.should.is_a? Integer
+        Bio::BGZF::vo_data_offset(pos).should == 0
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bio-bgzf
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-29 00:00:00.000000000 Z
+date: 2012-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -60,25 +60,23 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 2.10.0
-description: BGZF compression is used nowadays only for providing random access to
-  BAM format. However, it is completely independent from the format, and can be used
-  for arbitrary data format. The gem allows to read BGZF blocks from streams and pack
-  strings into blocks, aiming to facilitate introducing BGZF compression for Ruby
-  users.
+description: This library provides support for BGZF (Blocked GZip Format) in Ruby.
+  BGZF, originally defined as part of the SAM/BAM specification, is used to compress
+  record-oriented data in a way that facilitates random access, unlike plain gzip.
+  BGZF is principally used for bioinformatics data but would be useful in other contexts
+  as well.
 email: cswh@umich.edu
 executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
 - README.md
-- README.rdoc
 files:
 - .document
 - .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
-- README.rdoc
 - Rakefile
 - VERSION
 - lib/bio-bgzf.rb
@@ -88,6 +86,7 @@ files:
 - lib/bio-bgzf/reader.rb
 - lib/bio-bgzf/unpack.rb
 - lib/bio-bgzf/vo.rb
+- lib/bio-bgzf/writer.rb
 - spec/bio-bgzf_spec.rb
 - test/data/mm8.chrM.maf.gz
 homepage: http://github.com/csw/bioruby-bgzf
@@ -105,7 +104,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 887449106420092676
+      hash: 4066832272659457160
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/README.rdoc

@@ -1,48 +0,0 @@
-= bio-bgzf
-
-{<img
-src="https://secure.travis-ci.org/lomereiter/bioruby-bgzf.png"
-/>}[http://travis-ci.org/#!/lomereiter/bioruby-bgzf]
-
-Full description goes here
-
-Note: this software is under active development!
-
-== Installation
-
-        gem install bio-bgzf
-
-== Usage
-
-== Developers
-
-To use the library 
-
-        require 'bio-bgzf'
-
-The API doc is online. For more code examples see also the test files in
-the source tree.
-        
-== Project home page
-
-Information on the source tree, documentation, issues and how to contribute, see
-
-  http://github.com/lomereiter/bioruby-bgzf
-
-The BioRuby community is on IRC server: irc.freenode.org, channel: #bioruby.
-
-== Cite
-
-  If you use this software, please cite one of
- 
-* [BioRuby: bioinformatics software for the Ruby programming language](http://dx.doi.org/10.1093/bioinformatics/btq475)
-* [Biogem: an effective tool-based approach for scaling up open source software development in bioinformatics](http://dx.doi.org/10.1093/bioinformatics/bts080)
-
-== Biogems.info
-
-This Biogem is published at http://biogems.info/index.html#bio-bgzf
-
-== Copyright
-
-Copyright (c) 2012 Artem Tarasov. See LICENSE.txt for further details.
-