scaffolder 0.2.6 → 0.4.0

data/lib/scaffolder.rb

@@ -1,51 +1,215 @@
 require 'delegate'
 require 'bio'
 
+# == Quick start
+#
+# Given a fasta file containing two sequences.
+#
+#   >seqA
+#   GCGCGC
+#   >seqB
+#   ATATAT
+#
+# A simple genome scaffold containing the two sequences is specified as a YAML
+# formatted text file shown below. Each dash (-) indicates a region in the
+# scaffold. In the example below the keyword *sequence* inserts a sequence from
+# the fasta file, the keyword *source* identifies that seqA should be used.
+#
+#   ---
+#     - sequence:
+#         source: 'seqA'
+#     - sequence:
+#         source: 'seqB'
+#
+# The scaffolder API can then be used as follows to generate a complete
+# sequence.
+#
+#   scaffold = Scaffolder.new('scaffold.yml','sequences.fasta')
+#   sequence = scaffold.inject(String.new) do |build,entry|
+#     build << entry.sequence
+#   end
+#   puts sequence # Prints GCGCGCATATAT
+#
+# == The Scaffold File
+#
+# The above example is simplified to demonstrates basic usage. The sections
+# below outline the types of regions that can be used in the scaffold file.
+#
+# === Sequence Regions
+#
+# Contigs sequences in the scaffold are specified using the *sequence* keyword.
+# The *source* keyword should specifies the sequence to use from the fasta file
+# and should match the first space delimited word in the fasta header.
+#
+# ==== Sub-Sequences
+#
+# When generating a scaffolder only a subset of a sequence may be required.
+# Inserting sub-sequences into the scaffold is specified using the *start* and
+# *stop* keywords. All of the sequence before the start coordinate is ignored
+# and all of sequence after the stop coordinate is ignored, meaning only the
+# sequence between the start and stop position inclusively is used in the
+# scaffold.
+#
+#   ---
+#     - sequence:
+#         source: 'sequence1'
+#         start: 42
+#         stop: 1764
+#
+# ==== Reverse Complementation
+#
+# The *reverse* keyword specifies that the selected sequence is reversed
+# complemented.
+#
+#   ---
+#     - sequence:
+#         source: 'sequence1'
+#         reverse: true
+#
+# === Insert Regions
+#
+# Sequence contigs may contain gaps, for example where the sequence could not
+# be correctly resolved during assembly. Additional sequencing may however
+# produce sequences that can be used to fill these gaps. These inserts can be
+# added to a sequence using the *insert* keyword and specifying a YAML array of
+# the inserts. Multiple inserts can be specified, each separated by a dash (-)
+# followed by a new line.
+#
+#   ---
+#     - sequence:
+#         source: 'sequence1'
+#         inserts:
+#           -
+#             source: 'insert1'
+#             open: 3
+#             close: 10
+#
+# ==== Insert Position
+#
+# The location where an insert is added to a sequence is defined by either the
+# *open*, *close* keywords, or both. This defines where the host sequence is
+# 'opened' and 'closed' to add the insert. If only one parameter is used, for
+# example using *open*, then the close position is determined from the length
+# of the insert sequence and vice versa.
+#
+# ==== Insert Sub-Sequence
+#
+# An insert can be subsequenced in the same way as a sequence using the *start*
+# and *stop* keywords. Similarly the insert sequence can be reverse completed
+# using the *reverse* keyword.
+#
+#   ---
+#     - sequence:
+#         source: 'sequence1'
+#         inserts:
+#           -
+#             source: 'insert1'
+#             open: 3
+#             close: 10
+#             start: 8
+#             stop: 16
+#             reverse: true
+#
+#
+# === Unresolved Regions
+#
+# There may be regions in between sequences in the genome which are unknown but
+# which the approximate length is. These can be specified in the scaffold file
+# using the *unresolved* keyword. Unresolved regions are filled with 'N'
+# nucleotide characters equal to the value specified by the *length* keyword.
+#
+#   ---
+#     - unresolved:
+#         length: 10
+#
+# === Scaffold File Processing Order
+#
+# The scaffolder API processes the regions in YAML scaffold file as follows:
+#
+# * Each region in the scaffold in processed in the order specified in the
+#   scaffolder file.
+# * If the region is a sequence and inserts are specified, the inserts are
+#   sorted by stop position, then processed from last to first.  Each insert is
+#   processed as follows:
+#
+#   * The insert is subsequenced if specified.
+#   * The insert is reverse complemented if specified.
+#   * The insert is added to each host sequence replacing the region of
+#     sequence specified by the open and close co-ordinates.
+#   * The host sequence stop position is extended by the difference in length
+#     that the insert sequence fills. For example if a 5 base pair insert fills
+#     a 4 base region, the host sequence stop position is increased by the
+#     difference: 1.
+#   * The region is subsequenced if specified.
+#   * The region is reverse complemented if specified.
+#
+# === WARNING
+#
+# Inserts with overlapping *open* and *close* regions in the same sequence will
+# cause unexpected behaviour and should be avoided.
+#
 class Scaffolder < DelegateClass(Array)
-  autoload :Region,   'scaffolder/region'
-  autoload :Insert,   'scaffolder/insert'
-  autoload :Sequence, 'scaffolder/sequence'
+  require 'scaffolder/errors'
+  require 'scaffolder/region'
 
+  include Scaffolder::Errors
+
+  # Source is a reserved keyword. The 'source' keyword identifies the
+  # which corresponding fasta sequence should be retreived from the fasta
+  # file.
+  SOURCE = 'source'
+
+  # Raw_sequence is a reserved keyword. The 'raw_sequence' keyword points to
+  # the sequence from the fasta file identified by the 'source' keyword.
+  RAW_SEQUENCE = 'raw_sequence'
+
+  # @param [Hash] assembly Produced from loading the scaffold file using YAML.load
+  # @param [String] sequence Location of the fasta file corresponding to the
+  #   scaffold sequences
+  # @return [Array] Returns an array of scaffold regions
+  # @example
+  #   Scaffolder.new(YAML.load('scaffold.yml'),'sequences.fasta')
   def initialize(assembly,sequence)
-    @sequences = Hash[ *Bio::FlatFile::auto(sequence).collect { |s|
+    sequences = Hash[ *Bio::FlatFile::auto(sequence).collect { |s|
       [s.definition.split.first,s.seq]
     }.flatten]
 
     super(assembly.map do |entry|
       type, data = entry.keys.first, entry.values.first
 
-      case type
-      when 'unresolved'
-        Scaffolder::Region.new(:unresolved,'N'*data['length'])
-      when 'sequence'
-        sequence = Scaffolder::Sequence.new(
-          :name     => data['source'],
-          :start    => data['start'],
-          :end      => data['end'],
-          :reverse  => data['reverse'],
-          :sequence => fetch_sequence(data['source'])
-        )
-        if data['inserts']
-          sequence.add_inserts(data['inserts'].map do |insert|
-            Scaffolder::Insert.new(
-              :start    => insert['start'],
-              :stop     => insert['stop'],
-              :reverse  => insert['reverse'],
-              :sequence => fetch_sequence(insert['source'])
-            )
-          end)
-        end
-        sequence
-      else
-        raise ArgumentError.new("Unknown tag: #{type}")
-      end
+      # Source is the only reserved keyword. Fetches sequence from fasta file.
+      data = Scaffolder.update_with_sequence(data,sequences)
+
+      Scaffolder::Region[type].generate(data)
     end)
   end
 
-  def fetch_sequence(name)
-    sequence = @sequences[name]
-    raise ArgumentError.new("Missing sequence: #{name}") unless sequence
-    sequence
+  # Inserts corresponding fasta data into scaffold data hash. Every hash
+  # that contains the reserved 'source' keyword has the 'raw_sequence' keyword
+  # added for the corresponding fasta sequence from the fasta file.
+  # @param [Hash] data The scaffold hash
+  # @param [Hash] seqs A hash with identifier => sequence key/value pairs from 
+  #   the fasta sequence data.
+  # @return [Hash] The data hash updated with the 'raw_sequence' sequence
+  #   keyword data.
+  # @raise [UnkownSequenceError] if the source keyword is used but
+  #   there is no corresponding fasta sequence entry
+  def self.update_with_sequence(data,seqs)
+    if data.instance_of? Array
+      data.each{|a| update_with_sequence(a,seqs) }
+    else
+      if data[SOURCE]
+        sequence = seqs[data[SOURCE]]
+        if sequence.nil?
+          raise UnknownSequenceError.new("Unknown sequence: #{data[SOURCE]}")
+        end
+        data.merge!({RAW_SEQUENCE => sequence})
+      end
+      data.select{|k,v| v.respond_to? :each}.each do |key,hash|
+        update_with_sequence(hash,seqs)
+      end
+    end
+    data
   end
 
 end

data/scaffolder.gemspec

@@ -1,51 +1,60 @@
 # Generated by jeweler
 # DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{scaffolder}
-  s.version = "0.2.6"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Michael Barton"]
-  s.date = %q{2010-10-10}
-  s.description = %q{Organise genome sequence data into scaffolds using YAML configuration files.}
+  s.date = %q{2011-01-04}
+  s.description = %q{Organise sequence contigs into genome scaffolds using simple human-readable YAML files.}
   s.email = %q{mail@michaelbarton.me.uk}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+    "README.rdoc"
   ]
   s.files = [
     ".document",
-     ".gitignore",
-     "LICENSE",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION",
-     "lib/scaffolder.rb",
-     "lib/scaffolder/insert.rb",
-     "lib/scaffolder/region.rb",
-     "lib/scaffolder/sequence.rb",
-     "scaffolder.gemspec",
-     "test/data/sequences.fna",
-     "test/helper.rb",
-     "test/test_insert.rb",
-     "test/test_region.rb",
-     "test/test_scaffolder.rb",
-     "test/test_sequence.rb"
+    "Gemfile",
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "cucumber.yml",
+    "features/insert.feature",
+    "features/sequence.feature",
+    "features/step_definitions/scaffolder_steps.rb",
+    "features/support/env.rb",
+    "lib/scaffolder.rb",
+    "lib/scaffolder/errors.rb",
+    "lib/scaffolder/region.rb",
+    "lib/scaffolder/region/insert.rb",
+    "lib/scaffolder/region/sequence.rb",
+    "lib/scaffolder/region/unresolved.rb",
+    "scaffolder.gemspec",
+    "test/helper.rb",
+    "test/test_insert.rb",
+    "test/test_region.rb",
+    "test/test_scaffolder.rb",
+    "test/test_sequence.rb",
+    "test/test_unresolved.rb",
+    "yard/attribute_handler.rb"
   ]
-  s.homepage = %q{http://github.com/michaelbarton/scaffolder}
-  s.rdoc_options = ["--charset=UTF-8"]
+  s.homepage = %q{http://www.michaelbarton.me.uk/scaffolder/}
+  s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Scaffolder for genome sequence data}
+  s.summary = %q{Genome scaffolding for human beings.}
   s.test_files = [
     "test/helper.rb",
-     "test/test_insert.rb",
-     "test/test_region.rb",
-     "test/test_scaffolder.rb",
-     "test/test_sequence.rb"
+    "test/test_insert.rb",
+    "test/test_region.rb",
+    "test/test_scaffolder.rb",
+    "test/test_sequence.rb",
+    "test/test_unresolved.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -53,24 +62,33 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<bio>, [">= 0"])
-      s.add_development_dependency(%q<rr>, [">= 0.10.11"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<redgreen>, [">= 0"])
-      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_runtime_dependency(%q<bio>, ["~> 1.4"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<shoulda>, ["~> 2.11"])
+      s.add_development_dependency(%q<mocha>, ["~> 0.9"])
+      s.add_development_dependency(%q<yard>, ["~> 0.6"])
+      s.add_development_dependency(%q<cucumber>, ["~> 0.9"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5"])
+      s.add_development_dependency(%q<redgreen>, ["~> 1.2"])
     else
-      s.add_dependency(%q<bio>, [">= 0"])
-      s.add_dependency(%q<rr>, [">= 0.10.11"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<redgreen>, [">= 0"])
-      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<bio>, ["~> 1.4"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<shoulda>, ["~> 2.11"])
+      s.add_dependency(%q<mocha>, ["~> 0.9"])
+      s.add_dependency(%q<yard>, ["~> 0.6"])
+      s.add_dependency(%q<cucumber>, ["~> 0.9"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5"])
+      s.add_dependency(%q<redgreen>, ["~> 1.2"])
     end
   else
-    s.add_dependency(%q<bio>, [">= 0"])
-    s.add_dependency(%q<rr>, [">= 0.10.11"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<redgreen>, [">= 0"])
-    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<bio>, ["~> 1.4"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<shoulda>, ["~> 2.11"])
+    s.add_dependency(%q<mocha>, ["~> 0.9"])
+    s.add_dependency(%q<yard>, ["~> 0.6"])
+    s.add_dependency(%q<cucumber>, ["~> 0.9"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5"])
+    s.add_dependency(%q<redgreen>, ["~> 1.2"])
   end
 end
 

data/test/helper.rb

@@ -2,7 +2,7 @@ require 'rubygems'
 require 'test/unit'
 require 'shoulda'
 require 'redgreen'
-require 'rr'
+require 'mocha'
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
@@ -10,6 +10,21 @@ $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'scaffolder'
 
 class Test::Unit::TestCase
-  require 'tempfile'
-  include RR::Adapters::TestUnit
+  class << self
+
+    def should_have_method_attribute(klass)
+      should "have method #attribute" do
+        assert_respond_to( klass, :attribute )
+      end
+    end
+
+    def should_have_attribute(klass, *attributes)
+      attributes.each do |attribute|
+        should "have instance attribute #{attribute}" do
+          assert_respond_to( klass.new, attribute )
+        end
+      end
+    end
+
+  end
 end

data/test/test_insert.rb

@@ -1,58 +1,50 @@
 require 'helper'
 
 class TestInsert < Test::Unit::TestCase
-  context Scaffolder::Insert do
-
-    setup do
-      @options = {
-        :start    => 5,
-        :stop     => 10,
-        :sequence => "ATGCGGGC"
-      }
-    end
+  context Scaffolder::Region::Insert do
 
-    should "correctly store the passed options" do
-      i = Scaffolder::Insert.new @options
-      assert_equal(i.start, @options[:start])
-      assert_equal(i.stop, @options[:stop])
-      assert_equal(i.sequence, @options[:sequence])
-    end
+    context "attributes" do
 
-    should "reverse the sequence when passed the reverse tag" do
-      i = Scaffolder::Insert.new @options.merge(:reverse => true)
-      rev = Bio::Sequence::NA.new(@options[:sequence]).reverse_complement
-      assert_equal(i.sequence, rev.upcase)
-    end
+      should_have_attribute Scaffolder::Region::Insert, :source, :open, :close
 
-    should "correctly generate the position" do
-      i = Scaffolder::Insert.new @options
-      assert_equal(i.position, (@options[:start]-1)..(@options[:stop]-1))
-    end
+      setup do
+        @length = 15
+        @insert = Scaffolder::Region::Insert.new
+        @insert.raw_sequence('N' * @length)
+      end
 
-    should "estimate the sequence end position" do
-      @options.delete(:stop)
-      i = Scaffolder::Insert.new @options
-      assert_equal(i.stop, @options[:start] + @options[:sequence].length - 1)
-    end
+      should "return open plus sequence length as default close" do
+        @insert.open  5
+        assert_equal(@insert.close,@insert.open + @length - 1)
+      end
 
-    should "estimate the sequence start position" do
-      @options.delete(:start)
-      i = Scaffolder::Insert.new @options
-      assert_equal(i.start, @options[:stop] - @options[:sequence].length - 1)
-    end
+      should "return close minus sequence length as default open" do
+        @insert.close 20
+        assert_equal(@insert.open,@insert.close - @length - 1)
+      end
+
+      should "include the insert position" do
+        @insert.open  5
+        @insert.close 10
+        assert_equal(@insert.position,4..9)
+      end
 
-    should "throw error when neither start or stop are provided" do
-      @options.delete(:start)
-      @options.delete(:stop)
-      assert_raise ArgumentError do
-        Scaffolder::Insert.new @options
+      should "throw an error when neither open or close are provided" do
+        assert_raise(Scaffolder::Errors::CoordinateError){ @insert.position }
       end
+
     end
 
-    should "be comparable by end position" do
-      a = Scaffolder::Insert.new @options
-      b = Scaffolder::Insert.new @options.merge(:stop => @options[:stop] + 1)
-      c = Scaffolder::Insert.new @options.merge(:stop => @options[:stop] + 2)
+    should "be comparable by close position" do
+      a = Scaffolder::Region::Insert.new
+      a.close 1
+
+      b = a.clone
+      b.close 2
+
+      c = b.clone
+      c.close 3
+
       assert_equal([c,a,b].sort, [a,b,c])
     end
 

data/test/test_region.rb

@@ -2,10 +2,149 @@ require 'helper'
 
 class TestScaffolder < Test::Unit::TestCase
   context Scaffolder::Region do
-    should "be created from parameters" do
-      region = Scaffolder::Region.new(:unresolved,'NNNN')
-      assert_equal(region.entry_type,:unresolved)
-      assert_equal(region.sequence,'NNNN')
+
+    context "adding instance methods with attribute method" do
+
+      setup do
+        @attr = :some_attribute
+      end
+
+      should "create a single accessor attribute" do
+        Scaffolder::Region.attribute @attr
+        assert(Scaffolder::Region.instance_methods.include? @attr.to_s)
+      end
+
+      should "return nil until attribute value is stored" do
+        Scaffolder::Region.attribute @attr
+        region = Scaffolder::Region.new
+        assert_equal(region.send(@attr),nil)
+        region.send(@attr,5)
+        assert_equal(region.send(@attr),5)
+      end
+
+      should "allow specification of default value" do
+        Scaffolder::Region.attribute @attr, :default => 1
+        region = Scaffolder::Region.new
+        assert_equal(region.send(@attr),1)
+        region.send(@attr,5)
+        assert_equal(region.send(@attr),5)
+      end
+
+      should "allow specification of default value using a block" do
+        Scaffolder::Region.attribute @attr, :default => lambda{|s| s.entry_type }
+        region = Scaffolder::Region.new
+        assert_equal(region.send(@attr),region.entry_type)
+        region.send(@attr,5)
+        assert_equal(region.send(@attr),5)
+      end
+
+    end
+
+    context "passing the yaml hash to the generate method" do
+
+      setup do
+        Scaffolder::Region.attribute(:one)
+        Scaffolder::Region.attribute(:two)
+        @tags = {'one' => 1, 'two' => 2}
+      end
+
+      should "should call each tag in the hash as a method to store the value" do
+        Scaffolder::Region.any_instance.expects(:one).with(1)
+        Scaffolder::Region.any_instance.expects(:two).with(2)
+        Scaffolder::Region.generate(@tags)
+      end
+
+      should "return an instantiated region object" do
+        region = Scaffolder::Region.generate(@tags)
+        assert_equal(region.one,1)
+        assert_equal(region.two,2)
+      end
+
+      should "throw UnknownAttributeError for an unknown attribute" do
+        assert_raise Scaffolder::Errors::UnknownAttributeError do
+          Scaffolder::Region.generate({:three => 3})
+        end
+      end
+
+    end
+
+    context "attributes" do
+
+      should_have_attribute Scaffolder::Region,
+        :start, :stop, :reverse, :raw_sequence
+
+      should "return the class name as the entry type" do
+        Scaffolder::Region::NewRegion = Class.new(Scaffolder::Region)
+        assert_equal(Scaffolder::Region::NewRegion.new.entry_type,:newregion)
+      end
+
+      should "return 1 as default value for start attribute" do
+        sequence = Scaffolder::Region.new
+        assert_equal(sequence.start,1)
+      end
+
+      should "return #raw_sequence length as default value for stop attribute" do
+        length = 5
+        sequence = Scaffolder::Region.new
+        sequence.raw_sequence 'N' * length
+        assert_equal(sequence.stop,length)
+      end
+
     end
+
+    context "generating the processed sequence" do
+
+      [:sequence_hook, :raw_sequence].each do |method|
+
+        context "using the #{method} method" do
+
+          setup do
+            # Test class to prevent interference with other tests
+            @s = Class.new(Scaffolder::Region).new
+            @s.class.send(:define_method,method,lambda{'ATGCCAGATAACTGACTAGCATG'})
+          end
+
+          should "return the sequence when no other options are passed" do
+            assert_equal(@s.sequence,'ATGCCAGATAACTGACTAGCATG')
+          end
+
+          should "reverse complement sequence when passed the reverse option" do
+            @s.reverse true
+            assert_equal(@s.sequence, 'CATGCTAGTCAGTTATCTGGCAT')
+          end
+
+          should "create subsequence when passed sequence coordinates" do
+            @s.start 5
+            @s.stop 20
+            assert_equal(@s.sequence,'CAGATAACTGACTAGC')
+          end
+
+          should "raise a CoordinateError when start is less than 1" do
+            @s.start 0
+            assert_raise(Scaffolder::Errors::CoordinateError){ @s.sequence }
+          end
+
+          should "raise a CoordinateError when stop is greater than sequence " do
+            @s.stop 24
+            assert_raise(Scaffolder::Errors::CoordinateError){ @s.sequence }
+          end
+
+          should "raise a CoordinateError when stop is greater than start " do
+            @s.start 6
+            @s.stop 5
+            assert_raise(Scaffolder::Errors::CoordinateError){ @s.sequence }
+          end
+
+        end
+
+      end
+
+    end
+
+    should "instantiate return corresponding region subclass when requested" do
+      Scaffolder::Region::Type = Class.new
+      assert_equal(Scaffolder::Region['type'],Scaffolder::Region::Type)
+    end
+
   end
 end