scaffolder 0.2.6 → 0.4.0

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+
+group :default do
+  gem "bio", "~> 1.4"
+end
+
+group :development do
+  gem "bundler", "~> 1.0"
+  gem "shoulda", "~> 2.11"
+  gem "mocha", "~> 0.9"
+  gem "yard", "~> 0.6"
+  gem "cucumber", "~> 0.9"
+  gem "jeweler", "~> 1.5"
+  gem "redgreen", "~> 1.2"
+end

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Michael Barton
+Copyright (c) 2010 Michael Barton
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,25 +1,37 @@
-= scaffolder
+== Synopsis
 
-Description goes here.
+A simple genome scaffolder API for merging sequence contigs to build a continuous
+draft sequence. The draft sequence is constructed through specifying the order of
+contigs in in human-readable YAML files. Since the draft genome is specified by the
+scaffold YAML it is easy to remove or manipulate already sequences. In addition as
+the scaffold file is easy to edit and is ideal for version control and
+repeatability.
 
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+== Feature List
 
-== Copyright
+* Construct a draft sequence scaffold using human-readable and versionable
+  plain text files.
+* A simple and extensible Ruby API to traverse the scaffold.
+
+== Installing
+
+Ruby and RubyGems are required to use scaffolder. Scaffolder is installed on
+the command line using:
 
-Copyright (c) 2010 Michael Barton. See LICENSE for details.
+  $ gem install scaffolder
 
-== Notes
+== Documentation
 
-Inserts processed are processed in reverse order according to end position. Last insert added up until first insert. Done to preserve insert coordinates.
+See the Scaffolder class for getting started with Scaffolder.
 
-Overlapping inserts may cause unexpected behaviour
+== Contact
+
+Scaffolder was developed by Michael Barton (www.michaelbarton.me.uk). Pull
+requests, patches and bug reports are welcome. The source code is available on
+github[http://github.com/michaelbarton/scaffolder]. Bug reports and feature
+requests may also be made there.
+
+== Copyright
 
-Sequence reversed after inserts have been added.
+Scaffolder © 2010 by Michael Barton. Scaffolder is licensed under the MIT
+license. Please see the LICENSE document for more information.

data/Rakefile

@@ -1,26 +1,25 @@
 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'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "scaffolder"
-    gem.summary = %Q{Scaffolder for genome sequence data}
-    gem.description = %Q{Organise genome sequence data into scaffolds using YAML configuration files.}
-    gem.email = "mail@michaelbarton.me.uk"
-    gem.homepage = "http://github.com/michaelbarton/scaffolder"
-    gem.authors = ["Michael Barton"]
-    gem.add_dependency "bio", ">= 0"
-    gem.add_development_dependency "rr", ">= 0.10.11"
-    gem.add_development_dependency "shoulda", ">= 0"
-    gem.add_development_dependency "redgreen", ">= 0"
-    gem.add_development_dependency "yard", ">= 0"
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "scaffolder"
+  gem.homepage = "http://www.michaelbarton.me.uk/scaffolder/"
+  gem.license = "MIT"
+  gem.summary = %Q{Genome scaffolding for human beings.}
+  gem.description = %Q{Organise sequence contigs into genome scaffolds using simple human-readable YAML files.}
+  gem.email = "mail@michaelbarton.me.uk"
+  gem.authors = ["Michael Barton"]
 end
+Jeweler::RubygemsDotOrgTasks.new
 
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
@@ -29,28 +28,10 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/test_*.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:features)
 
-task :test => :check_dependencies
+require 'yard'
+YARD::Rake::YardocTask.new
 
 task :default => :test
-
-begin
-  require 'yard'
-  YARD::Rake::YardocTask.new
-rescue LoadError
-  task :yardoc do
-    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
-  end
-end

data/VERSION

@@ -1 +1 @@
-0.2.6
+0.4.0

data/cucumber.yml

@@ -0,0 +1,2 @@
+---
+  default: --format progress --color

data/features/insert.feature

@@ -0,0 +1,15 @@
+Feature: The insert keyword
+  In order to place close gaps in the scaffold
+  A user can use the insert keyword
+
+  Scenario: A scaffold with a single insert keyword
+    Given the scaffold file has the sequences:
+      | name | nucleotides |
+      | seq  | ATGCCGCGTAA |
+    And the first scaffold sequence has the inserts:
+      | name | nucleotides | open | close |
+      | ins  | AAAA        | 4    | 6     |
+    When creating a scaffolder object
+    Then the scaffold should contain 1 sequence entries
+    Then the scaffold should contain 1 insert entries
+    And the scaffold sequence should be ATGAAAACGTAA

data/features/sequence.feature

@@ -0,0 +1,20 @@
+Feature: The sequence keyword
+  In order to place contigs the scaffold
+  A user can use the sequence keyword
+
+  Scenario: A scaffold with a single sequence keyword
+    Given the scaffold file has the sequences:
+      | name | nucleotides |
+      | seq  | ATGCC       |
+    When creating a scaffolder object
+    Then the scaffold should contain 1 sequence entries
+    And the scaffold sequence should be ATGCC
+
+  Scenario: A scaffold with a two sequence keywords
+    Given the scaffold file has the sequences:
+      | name | nucleotides |
+      | seq1 | ATGCC       |
+      | seq2 | ATGCC       |
+    When creating a scaffolder object
+    Then the scaffold should contain 2 sequence entries
+    And the scaffold sequence should be ATGCCATGCC

data/features/step_definitions/scaffolder_steps.rb

@@ -0,0 +1,48 @@
+Given /^the scaffold file has the sequences:$/ do |sequences|
+  @entries   ||= Array.new
+  @sequences ||= Array.new
+
+  sequences.hashes.each do |seq|
+    @entries << {'sequence' => {'source' => seq['name']}}
+  end
+  sequences.hashes.map do |seq|
+    @sequences << {:name => seq['name'], :sequence => seq['nucleotides']}
+  end
+end
+
+Given /^the first scaffold sequence has the inserts:$/ do |inserts|
+  sequence = @entries.detect{|s| s.keys.first == 'sequence' }
+  sequence['sequence']['inserts'] = (inserts.hashes.map do |insert|
+    i = {'source' => insert['name']}
+    i['open']  = insert['open'].to_i  if insert['open']
+    i['close'] = insert['close'].to_i if insert['close']
+    i
+  end)
+  inserts.hashes.map do |insert|
+    @sequences << {:name => insert['name'], :sequence => insert['nucleotides']}
+  end
+end
+
+When /^creating a scaffolder object$/ do
+  @scf_file = write_scaffold_file(@entries)
+  @seq_file = write_sequence_file(@sequences)
+
+  @scaffold = Scaffolder.new(YAML.load(File.read(@scf_file)),@seq_file)
+end
+
+Then /^the scaffold should contain (.*) sequence entries$/ do |n|
+  @scaffold.select{|s| s.entry_type == :sequence}.length.should == n.to_i
+end
+
+Then /^the scaffold should contain (.*) insert entries$/ do |n|
+  @scaffold.select{|s| s.entry_type == :sequence}.inject(0) do |count,seq|
+    count =+ seq.inserts.length
+  end.should == n.to_i
+end
+
+And /^the scaffold sequence should be (.*)$/ do |sequence|
+  generated_sequence = @scaffold.inject(String.new) do |build,entry|
+    build << entry.sequence
+  end
+  generated_sequence.should == sequence
+end

data/features/support/env.rb

@@ -0,0 +1,30 @@
+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 'tempfile'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'scaffolder'
+
+def write_sequence_file(*sequences)
+  file = Tempfile.new("sequence").path
+  File.open(file,'w') do |tmp|
+    sequences.flatten.each do |sequence|
+      seq = Bio::Sequence.new(sequence[:sequence])
+      tmp.print(seq.output(:fasta,:header => sequence[:name]))
+    end
+  end
+  file
+end
+
+def write_scaffold_file(scaffold)
+  file = Tempfile.new("scaffold").path
+  File.open(file,'w'){|tmp| tmp.print(YAML.dump(scaffold))}
+  file
+end

data/lib/scaffolder/errors.rb

@@ -0,0 +1,6 @@
+# Mixin module to define standard errors for scaffolder.
+#
+module Scaffolder::Errors
+  exceptions = %w[ UnknownAttributeError CoordinateError UnknownSequenceError]
+  exceptions.each { |e| const_set(e, Class.new(StandardError)) }
+end

data/lib/scaffolder/region/insert.rb

@@ -0,0 +1,51 @@
+# Inserts are used to additional usually smaller sequences to larger sequences.
+# The attributes in the sequence class are used to specify where the host
+# sequence is 'opened' and 'closed' to add the insert. Either one of these two
+# attributes may be ommitted. Omitting the 'open' attribute will cause the
+# insert open position to be calculated based on the close minus the sequence
+# length. The reverse is true if the close position is ommittted.
+#
+# @see Scaffolder::Region::Sequence Scaffolder::Region::Sequence for an
+#   example on adding inserts to a sequence.
+class Scaffolder::Region::Insert < Scaffolder::Region
+
+  # Fasta identifier for the insert sequence
+  #
+  # @param [String]
+  # @return [String]
+  attribute :source
+
+  # Open position where insert is added. Default is close position minus the
+  # sequence length.
+  #
+  # @param [Integer]
+  # @return [Integer]
+  attribute :open,
+    :default => lambda{|s| s.close - s.sequence_hook.length - 1 }
+
+  # End position where insert is added. Default is open position plus the
+  # sequence length.
+  #
+  # @param [Integer]
+  # @return [Integer]
+  attribute :close,
+    :default => lambda{|s| s.open  + s.sequence_hook.length - 1 }
+
+  # Insertion position as a Range
+  #
+  # @return [Range]
+  # @raise [CoordinateError] if both the open and close positions are nil.
+  def position
+    raise CoordinateError if @close.nil? && @open.nil?
+    open-1..close-1
+  end
+
+  # Inserts are comaprable by close position.
+  #
+  # @return [Integer]
+  # @param [Scaffolder::Region::Insert]
+  def <=>(other)
+    self.close <=> other.close
+  end
+
+end

data/lib/scaffolder/region/sequence.rb

@@ -0,0 +1,74 @@
+# Class for inserting fasta sequence into the genome scaffold. The
+# #raw_sequence method is also responsible for applying each of the sequence
+# inserts to the original sequence. The following example specifies the
+# insertion of a sequence identified by the fasta header 'sequence1'. The
+# example also outlines and insert to be added to the sequence in the region
+# between 3 and 10.
+#
+#  - sequence:
+#      source: 'sequence1'
+#      inserts:
+#        -
+#          source: 'insert1'
+#          open: 3
+#          close: 10
+class Scaffolder::Region::Sequence < Scaffolder::Region
+
+  # Fasta identifier for this sequence
+  #
+  # @param [String]
+  # @return [String]
+  attribute :source
+
+  # Array of inserts to add to this sequence. Each array entry may be either a
+  # Scaffolder::Region:Inserts or a corresponding to the attributes of an
+  # Insert. In the case of the latter each hash is used to generate a new
+  # Scaffolder::Region::Insert instance.
+  #
+  # @return [Array] Array of Scaffolder::Region::Insert
+  # @param [Array] inserts Accepts an array of either
+  #   Scaffolder::Region::Insert or a hash of insert keyword data.
+  def inserts(inserts=nil)
+    if inserts.nil?
+      @inserts || Array.new
+    else
+      @inserts = inserts.map do |insert|
+        if insert.instance_of? Insert
+          insert
+        else
+          Insert.generate(insert)
+        end
+      end
+    end
+  end
+
+#  attribute :inserts, :default => Array.new
+
+  # Adds each of the sequence inserts to the raw sequence. Updates the sequence
+  # length each time an insert is added to reflect the change.
+  #
+  # @return [String] original sequence with inserts added.
+  # @raise [CoordinateError] if any insert open position is greater than the
+  #   length of the original sequence
+  # @raise [CoordinateError] if any insert close position is less than one
+  # @raise [CoordinateError] if any insert open position is greater than the
+  #   close position
+  def sequence_hook
+    # Set the sequence stop positon if not defined as the stop
+    # position is updated as each insert is added
+    @stop ||= raw_sequence.length
+
+    return inserts.sort.reverse.inject(raw_sequence) do |seq,insert|
+      raise CoordinateError if insert.open  > raw_sequence.length
+      raise CoordinateError if insert.close < 1
+      raise CoordinateError if insert.open  > insert.close
+
+      before_size = seq.length
+      seq[insert.position] = insert.sequence
+      diff = seq.length - before_size
+      stop(stop + diff)
+
+      seq
+    end
+  end
+end

data/lib/scaffolder/region/unresolved.rb

@@ -0,0 +1,23 @@
+# This class is used to insert unreolved sequence regions in to the genome
+# build. The unresolved region is filled with N characters. The example below
+# with insert the characters 'NNNNN' into the genome build.
+#
+#   - unresolved:
+#       length: 5
+# 
+class Scaffolder::Region::Unresolved < Scaffolder::Region
+
+  # The length of the unresolved region
+  # @return [Integer]
+  # @param [Integer]
+  attribute :length
+
+  # Calculate unresolved region sequence
+  # @return [String] a string of Ns equal to length attribute
+  # @raise [CoordinateError] if the length attribute is nil
+  def sequence_hook
+    raise CoordinateError if length.nil?
+    'N' * length
+  end
+
+end

data/lib/scaffolder/region.rb

@@ -1 +1,139 @@
-Scaffolder::Region = Struct.new(:entry_type,:sequence)
+require 'scaffolder'
+
+class Scaffolder::Region
+  include Scaffolder::Errors
+
+  class << self
+    include Scaffolder::Errors
+
+    # @return [Scaffolder::Region] Returns subclassed instances of
+    #   Scaffolder::Region by name
+    def [](type)
+      self.const_get(type.capitalize)
+    end
+
+    # Links the specification of values in the scaffold file to the assignment
+    # of instance variables.
+    #
+    # @param [Symbol] Define attributes for this type of scaffold
+    #   region. Attributes are read from the scaffold file and stored as
+    #   instance variables.
+    # @param [Hash] options Attribute options.
+    # @option options [Object,Proc] Default Specify a default value for this
+    #   attribute if a value is not defined in the scaffold file.
+    # @example Simple specification
+    #   class MyRegion < Scaffolder::Region
+    #     attribute :value # "value" usable as a keyword in the scaffold file
+    #   end
+    # @example Specification with a default value
+    #   attribute :value, :default => 1
+    # @example Specification with where proc is evaluated for the default
+    #   attribute :value, :default => lamdba{ Time.now.to_s }
+    # @example Specification with proc where the region instance is avaiable
+    #   attribute :value, :default => lamdba{|s| s.other_variable + 1 }
+    def attribute(name,options = {})
+      define_method(name) do |*arg|
+        var = "@#{name}"
+        default = options[:default]
+        unless arg.first # Is an argument is passed to the method?
+          value = instance_variable_get(var)
+          return value if value
+          return default.respond_to?(:call) ? default.call(self) : default
+        end
+        instance_variable_set(var,arg.first)
+      end
+    end
+
+    # Parse each key-value pair in the scaffold hash calling the corresponding
+    # attribute method for the key and passing the value as an argument.
+    #
+    # @param [Hash] region_data Key-Value pairs of the data required to define
+    #   this scaffolder region.
+    # @return [Scaffolder::Region] Returns an region object where the
+    #   instance variables have been assigned according to the region data
+    #   hash.
+    # @raise [UnknownAttributeError] If a keyword in the scaffold file does not
+    #   have a corresponding attribute in the class.
+    # @see Scaffolder::Region.attribute
+    def generate(region_data)
+      region = self.new
+      region_data.each_pair do |attribute,value|
+        begin
+          region.send(attribute.to_sym,value)
+        rescue NoMethodError => e
+          raise UnknownAttributeError.new(e)
+        end
+      end
+      region
+    end
+
+  end
+
+  # The raw sequence for this region.
+  #
+  # @param [String]
+  # @return [String]
+  attribute :raw_sequence
+
+  # Trim the start of sequence to this position. Default is 1.
+  #
+  # @param [Interger]
+  # @return [Interger]
+  attribute :start, :default => 1
+
+  # Trim the end of sequence to this position. Default is the sequence length..
+  #
+  # @param [Interger]
+  # @return [Interger]
+  attribute :stop, :default => lambda{|s| s.sequence_hook.length}
+
+
+  # Should the sequence be reverse complemented. Reverse complementation is
+  # performed after the start and end of the sequence has been trimmed.
+  #
+  # @param [Boolean]
+  # @return [Boolean]
+  attribute :reverse
+
+  # Override this to manipulate the sequence before it's subsequenced, reverse
+  # complemented etc. by Scaffolder::Region#sequence.
+  #
+  # @return [String] The value of the raw_sequence attribute
+  # @see Scaffolder::Region#sequence
+  def sequence_hook
+    raw_sequence
+  end
+
+  # The name of the class. Useful for selecting specific region types.
+  #
+  # @return [Symbol]
+  def entry_type
+    self.class.name.split('::').last.downcase.to_sym
+  end
+
+  # Returns the value of the Scaffolder::Region#raw_sequence after
+  # subsequencing and reverse complementation (if specified in the
+  # scaffold file).
+  #
+  # @return [String] Sequence after all modifications
+  # @raise [CoordinateError] if the start position is less than 1.
+  # @raise [CoordinateError] if the stop position is greater than the sequence
+  #   length.
+  # @raise [CoordinateError] if the start position is greater than the stop
+  #   position.
+  def sequence
+    seq = sequence_hook
+
+    raise CoordinateError.new if start < 1
+    raise CoordinateError.new if stop  > seq.length
+    raise CoordinateError.new if start > stop
+
+    seq = seq[(start-1)..(stop-1)]
+    seq = Bio::Sequence::NA.new(seq).reverse_complement if reverse
+    seq.to_s.upcase
+  end
+
+  require 'scaffolder/region/unresolved'
+  require 'scaffolder/region/insert'
+  require 'scaffolder/region/sequence'
+end