bio-maf 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.simplecov

@@ -0,0 +1 @@
+SimpleCov.start

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+before_install:
+  #- sudo update-java-alternatives -s java-1.7.0-openjdk-i386
+  - sudo update-java-alternatives -s java-1.6.0-openjdk
+  - sudo ./travis-ci/install_kc
+bundler_args: --without development
+script: "bundle exec rake test"
+after_script:
+  - ./travis-ci/report_errors
+rvm:
+  - 1.9.3
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode
+matrix:
+  allow_failures:
+    - rvm: rbx-19mode

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--markup-provider=redcarpet
+- DEVELOPMENT.md 

data/DEVELOPMENT.md

@@ -0,0 +1,40 @@
+# Development guide
+
+Here are notes on less obvious aspects of the development process for
+this library.
+
+## kyotocabinet-java
+
+Running `bio-maf` on JRuby requires the [kyotocabinet-java][] gem, a
+wrapper around the Kyoto Cabinet Java interface providing a Ruby API
+compatible with the standard Kyoto Cabinet Ruby API.
+
+[kyotocabinet-java]: https://github.com/csw/kyotocabinet-java
+
+## Man pages
+
+Man pages are developed with [ronn][] and live in `man/`; see
+[maf_index.1.ronn][] for an example. The generated man pages,
+e.g. `maf_index.1`, are added to Git for [gem-man][] support.
+
+[ronn]: https://github.com/rtomayko/ronn
+[gem-man]: https://github.com/defunkt/gem-man
+[maf_index.1.ronn]: https://github.com/csw/bioruby-maf/blob/master/man/maf_index.1.ronn
+
+HTML and roff versions are built with:
+
+    $ rake man
+
+The HTML versions are published through Octopress to Github Pages,
+e.g. <http://csw.github.com/bioruby-maf/man/maf_index.1.html>. This is
+a separate step, and necessarily dependent on the local filesystem
+layout. Specifically, there must be an `octopress` directory at the
+same level as `bioruby-maf`, containing a checked-out copy of
+<https://github.com/csw/bioruby-maf-blog>. Then, to publish the man
+pages, run:
+
+    $ rake man:publish
+    
+After this, in that Octopress instance, run:
+
+    $ rake deploy

data/Gemfile

@@ -0,0 +1,23 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+
+gemspec
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rdoc", "~> 3.12"
+  gem "simplecov", "~> 0.6.4", :platforms => :mri
+  gem "yard", "~> 0.8.1"
+  gem "kramdown", "~> 0.13.6"
+  gem "redcarpet", "~> 2.1.1", :platforms => :mri
+  gem "ronn", "~> 0.7.3", :platforms => :mri
+  gem "sinatra", "~> 1.3.2" # for ronn --server
+end
+
+group :test do
+  gem "bundler", ">= 1.0.0"
+  gem "rake", ">= 0.9"
+  gem "cucumber", ">= 0"
+  gem "rspec", "~> 2.10.0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 csw
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# bio-maf
+
+[![Build Status](https://secure.travis-ci.org/csw/bioruby-maf.png)](http://travis-ci.org/csw/bioruby-maf)
+
+This is a plugin for [BioRuby](http://bioruby.open-bio.org/) adding
+support for the
+[Multiple Alignment Format](http://genome.ucsc.edu/FAQ/FAQformat#format5)
+(MAF), used in bioinformatics to store whole-genome sets of multiple
+sequence alignments.
+
+Ultimately it will provide indexed and sequential access to MAF data,
+as well as performing various manipulations on it and writing modified
+MAF files. So far, it only supports simple sequential parsing.
+
+For more information, see the
+[project wiki](https://github.com/csw/bioruby-maf/wiki).
+
+Developer documentation generated with YARD is available at
+[rubydoc.info](http://rubydoc.info/github/csw/bioruby-maf/).
+
+This is being developed by Clayton Wheeler as
+[part of](http://www.bioruby.org/wiki/Google_Summer_of_Code) the
+Google Summer of Code 2012, under the auspices of the Open
+Bioinformatics Foundation. The development
+[blog](http://csw.github.com/bioruby-maf/) may be of interest.
+
+## Dependencies
+
+[Kyoto Cabinet][] is a database library, required for building MAF
+indexes. Install the core library in the appropriate way for your
+platform, as documented [here][].
+
+[Kyoto Cabinet]: http://fallabs.com/kyotocabinet/
+[here]: https://github.com/csw/bioruby-maf/wiki/Kyoto-Cabinet
+
+If you're using MRI, the [kyotocabinet-ruby][] gem will be used to
+interact with Kyoto Cabinet. For best performance, however, you should
+really consider using JRuby. On JRuby, the [kyotocabinet-java][] gem
+will be used instead; this builds a Java library using JNI to call
+into Kyoto Cabinet. Please file a [bug report][] if you encounter
+problems building or using this gem, which is still fairly new.
+
+[kyotocabinet-ruby]: https://rubygems.org/gems/kyotocabinet-ruby
+[kyotocabinet-java]: https://github.com/csw/kyotocabinet-java
+[bug report]: https://github.com/csw/kyotocabinet-java/issues
+
+
+## Installation
+
+    $ gem install bio-maf
+
+## Usage
+
+### Create an index on a MAF file
+
+Much of the functionality of this library relies on an index. You can
+create one with [maf_index(1)][], like so:
+
+[maf_index(1)]: http://csw.github.com/bioruby-maf/man/maf_index.1.html
+
+
+    $ maf_index test/data/mm8_chr7_tiny.maf /tmp/mm8_chr7_tiny.kct
+    
+Or programmatically:
+
+    require 'bio-maf'
+    parser = Bio::MAF::Parser.new("test/data/mm8_chr7_tiny.maf")
+    idx = Bio::MAF::KyotoIndex.build(parser, "/tmp/mm8_chr7_tiny.kct")
+
+### Extract blocks from an indexed MAF file, by genomic interval
+
+Refer to [`mm8_chr7_tiny.maf`](https://github.com/csw/bioruby-maf/blob/master/test/data/mm8_chr7_tiny.maf).
+
+
+    require 'bio-maf'
+    parser = Bio::MAF::Parser.new('test/data/mm8_chr7_tiny.maf')
+    idx = Bio::MAF::KyotoIndex.open('test/data/mm8_chr7_tiny.kct')
+
+    q = [Bio::GenomicInterval.zero_based('mm8.chr7', 80082592, 80082766)]
+    idx.find(q, parser).each do |block|
+      ref_seq = block.sequences[0]
+      puts "Matched block at #{ref_seq.start}, #{ref_seq.size} bases"
+    end
+
+    # => Matched block at 80082592, 121 bases
+    # => Matched block at 80082713, 54 bases
+
+### Filter species returned in alignment blocks
+
+    require 'bio-maf'
+    parser = Bio::MAF::Parser.new('test/data/mm8_chr7_tiny.maf')
+    idx = Bio::MAF::KyotoIndex.open('test/data/mm8_chr7_tiny.kct')
+
+    parser.sequence_filter = { :only_species => %w(hg18 mm8 rheMac2) }
+    q = [Bio::GenomicInterval.zero_based('mm8.chr7', 80082592, 80082766)]
+    blocks = idx.find(q, parser)
+    block = blocks.first
+    puts "Block has #{block.sequences.size} sequences."
+
+    # => Block has 3 sequences.
+
+### Extract blocks matching certain conditions
+
+See also the [Cucumber feature][] and [step definitions][] for this.
+
+[Cucumber feature]: https://github.com/csw/bioruby-maf/blob/master/features/maf-querying.feature
+[step definitions]: https://github.com/csw/bioruby-maf/blob/master/features/step_definitions/query_steps.rb
+
+#### Match only blocks with all specified species
+
+    q = [Bio::GenomicInterval.zero_based('mm8.chr7', 80082471, 80082730)]
+    filter = { :with_all_species => %w(panTro2 loxAfr1) }
+    n_blocks = idx.find(q, parser, filter).count
+    # => 1
+
+#### Match only blocks with a certain number of sequences
+
+    q = [Bio::GenomicInterval.zero_based('mm8.chr7', 80082767, 80083008)]
+    filter = { :at_least_n_sequences => 6 }
+    n_blocks = idx.find(q, parser, filter).count
+    # => 1
+
+#### Match only blocks within a text size range
+
+    q = [Bio::GenomicInterval.zero_based('mm8.chr7', 0, 80100000)]
+    filter = { :min_size => 72, :max_size => 160 }
+    n_blocks = idx.find(q, parser, filter).count
+    # => 3
+
+### Process each block in a MAF file
+
+    require 'bio-maf'
+    p = Bio::MAF::Parser.new('test/data/mm8_chr7_tiny.maf')
+    puts "MAF version: #{p.header.version}"
+    # => MAF version: 1
+
+    p.parse_blocks.each do |block|
+      block.sequences.each do |seq|
+        do_something(seq)
+      end
+    end
+
+### Parse empty ('e') lines
+
+Refer to [`chr22_ieq.maf`](https://github.com/csw/bioruby-maf/blob/master/test/data/chr22_ieq.maf).
+
+    require 'bio-maf'
+    p = Bio::MAF::Parser.new('test/data/chr22_ieq.maf',
+                             :parse_empty => false)
+    block = p.parse_block
+    block.sequences.size
+    # => 3
+
+    p = Bio::MAF::Parser.new('test/data/chr22_ieq.maf',
+                             :parse_empty => true)
+    block = p.parse_block
+    block.sequences.size
+    # => 4
+    block.sequences.find { |s| s.empty? }
+    # => #<Bio::MAF::EmptySequence:0x007fe1f39882d0 
+    #      @source="turTru1.scaffold_109008", @start=25049,
+    #      @size=1601, @strand=:+, @src_size=50103, @text=nil,
+    #      @status="I"> 
+
+
+### Command line tools
+
+Man pages for command line tools:
+
+* [`maf_index(1)`](http://csw.github.com/bioruby-maf/man/maf_index.1.html)
+* [`maf_to_fasta(1)`](http://csw.github.com/bioruby-maf/man/maf_to_fasta.1.html)
+
+### Other documentation
+
+Also see the [API documentation][]. For more code examples see the
+[RSpec][] and [Cucumber][] test files in the source tree.
+
+[API documentation]: http://rubydoc.info/github/csw/bioruby-maf/
+[RSpec]: https://github.com/csw/bioruby-maf/tree/master/spec/bio/maf
+[Cucumber]: https://github.com/csw/bioruby-maf/tree/master/features 
+
+Also, the scripts in the
+[bin](https://github.com/csw/bioruby-maf/tree/master/bin) directory
+provide good worked examples of how to use the existing parsing API.
+        
+## Project home page
+
+For information on the source tree, documentation, examples, issues
+and how to contribute, see
+
+  <http://github.com/csw/bioruby-maf>
+
+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 will be published at [#bio-maf](http://biogems.info/index.html)
+
+## Copyright
+
+Copyright (c) 2012 Clayton Wheeler. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'rubygems/package_task'
+
+$gemspec = Gem::Specification.load("bio-maf.gemspec")
+Gem::PackageTask.new($gemspec) { |pkg| }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new do |features|
+end
+
+task :test => [ :spec, :cucumber ] 
+task :default => :test
+
+#### Man pages
+# (borrowed from matthewtodd/shoe)
+ronn_avail = begin
+               require 'ronn'
+               true
+             rescue LoadError
+               false
+             end
+
+if ronn_avail
+  RONN_FILES = Rake::FileList["man/*.?.ronn"]
+
+  desc "Generate man pages"
+  task :man do
+    file_spec = RONN_FILES.join(' ')
+    sh "ronn --roff --html --style toc --date #{$gemspec.date.strftime('%Y-%m-%d')} --manual='BioRuby Manual' --organization='#{$gemspec.author}' #{file_spec}"
+  end
+
+  namespace :man do
+    desc "Publish man pages to Octopress source dir"
+    task :publish do
+      RONN_FILES.map { |path| path.sub(/\.ronn$/, '.html') }.each do |man|
+        cp man, "../octopress/source/man/#{File.basename(man)}"
+      end
+    end
+  end
+  task 'man:publish' => :man
+
+  namespace :ronn do
+    task :server do
+      sh "ronn --server #{RONN_FILES.join(' ')}"
+    end
+  end
+end # if ronn_avail
+
+#### RDoc (not currently used)
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "bio-maf #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/benchmarks/dispatch_bench

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+
+n = 10000000
+line = 's tupBel1.scaffold_3803.1-85889    33686 61 +    85889 ttcaggaagggggcccaaaacgcttgagtggtcagctctta-ttttgcgtttactggatggg'
+
+Benchmark.bmbm do |x|
+  x.report("case with strings") do
+    n.times do
+      i = 0
+      case line[0]
+      when 's'
+        i += 1
+      when 'i', 'e', 'q', '#', nil
+        next
+      else
+        raise "foo"
+      end
+    end
+  end
+  S = 's'.getbyte(0)
+  I = 'i'.getbyte(0)
+  E = 'e'.getbyte(0)
+  Q = 'q'.getbyte(0)
+  COMMENT = '#'.getbyte(0)
+  x.report("case with bytes") do
+    n.times do
+      i = 0
+      case line.getbyte(0)
+      when S
+        i += 1
+      when I, E, Q, COMMENT, nil
+        next
+      else
+        raise "foo"
+      end
+    end
+  end
+  x.report("if/else with bytes") do
+    n.times do
+      i = 0
+      b = line.getbyte(0)
+      if b == S
+        i += 1
+      elsif [I, E, Q, COMMENT, nil].contain?(b)
+        next
+      else
+        raise "foo"
+      end
+    end
+  end
+end

data/benchmarks/iter_bench

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+
+n = 1000000
+data = <<EOF
+a score=28680.000000
+s hg19.chr22                    16050711 61 + 51304566 atctccaagagggcataaaacac-tgagtaaacagctcttttatatgtgtttcctggatgag
+s panTro2.chrUn                  7681110 59 + 58616431 atctccaagagggcataaaacac-tgagtaaacagctctt--atatgtgtttcctggatgag
+q panTro2.chrUn                                        99999999999999999999999-9999999999999999--99999999999999999999
+i panTro2.chrUn                 C 0 C 0
+s tarSyr1.scaffold_75923            2859 50 -     8928 atctccaagagggctgaaaatgc-caaatga-----------tcacacgtttcctggacaag
+q tarSyr1.scaffold_75923                               79295966999999999999998-9999799-----------99999999997657759999
+i tarSyr1.scaffold_75923        N 0 C 0
+s micMur1.scaffold_22105            5493 59 -    10683 acctccgagagggctcaaaacgc-cgagtgatcagctctt--atgcgcgtttcctggacgag
+q micMur1.scaffold_22105                               99999999999999999999999-9999999999999999--99999999999999999999
+i micMur1.scaffold_22105        C 0 C 0
+s tupBel1.scaffold_3803.1-85889    33686 61 +    85889 ttcaggaagggggcccaaaacgcttgagtggtcagctctta-ttttgcgtttactggatggg
+q tupBel1.scaffold_3803.1-85889                        79648579699867994997775679665662767577569-69987455976776322888
+i tupBel1.scaffold_3803.1-85889 I 1 C 0
+s vicPac1.scaffold_12713            6831 55 -    10681 actgccatgggggctcagcgtac-tgaatggttaattact------gtggtccccgaatgag
+q vicPac1.scaffold_12713                               99999999999999999999999-9999999999999999------9999999999999999
+EOF
+
+Benchmark.bmbm do |x|
+  x.report("split/each") do
+    n.times do
+      i = 0
+      data.split("\n").each do |line|
+        i += line.size
+      end
+    end
+  end
+  x.report("until/shift") do
+    n.times do
+      i = 0
+      lines = data.split("\n")
+      until lines.empty?
+        line = lines.shift
+        i += line.size
+      end
+    end
+  end
+end

data/benchmarks/read_bench

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+
+FILE = '/Users/csw/maf/chr22.maf'
+
+Benchmark.bm do |x|
+  x.report("8k") do
+    File.open(FILE) do |f|
+      while true
+        r = f.read(8192)
+        break unless r
+      end
+    end
+  end
+  x.report("128k") do
+    File.open(FILE) do |f|
+      while true
+        r = f.read(128 * 1024)
+        break unless r
+      end
+    end
+  end
+  x.report("1M") do
+    File.open(FILE) do |f|
+      while true
+        r = f.read(1024 * 1024)
+        break unless r
+      end
+    end
+  end
+  x.report("8M") do
+    File.open(FILE) do |f|
+      while true
+        r = f.read(8 * 1024 * 1024)
+        break unless r
+      end
+    end
+  end
+end

data/benchmarks/sort_bench

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+
+class Thing
+  attr_reader :part
+
+  def initialize(part)
+    @part = part
+  end
+end
+
+prng = Random.new
+v_max = 1 << 31
+ary = []
+1000.times do
+  ary << Thing.new(rand(v_max))
+end
+
+Benchmark.bmbm do |x|
+  x.report("sort!") do
+    1000.times do
+      ary2 = ary.dup
+      ary2.sort! { |a, b| a.part <=> b.part }
+    end
+  end
+  x.report("sort_by!") do
+    1000.times do
+      ary2 = ary.dup
+      ary2.sort_by! { |i| i.part }
+    end
+  end
+end

data/benchmarks/split_bench

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+
+n = 2000000
+line = 's tupBel1.scaffold_3803.1-85889    33686 61 +    85889 ttcaggaagggggcccaaaacgcttgagtggtcagctctta-ttttgcgtttactggatggg'
+
+Benchmark.bmbm do |x|
+  x.report("basic String#split") do
+    n.times do
+      parts = line.split
+    end
+  end
+  x.report("regex split") do
+    n.times do
+      parts = line.split(/\s+/)
+    end
+  end
+  x.report("regex fields") do
+    n.times do
+      if m = /^s\s+(\S+)\s+(\d+)\s+(\d+)\s+([+-])\s+(\d+)\s+(\S+)/.match(line)
+        parts = m.captures
+      end
+    end
+  end
+  x.report("regex fields") do
+    n.times do
+      if m = /^s\s+(\S+)\s+(\d+)\s+(\d+)\s+([+-])\s+(\d+)\s+(\S+)/.match(line)
+        parts = m.captures
+      end
+    end
+  end
+end