finishm 0.0.1

data/lib/assembly/bad_format_writer.rb

@@ -0,0 +1,46 @@
+require 'yaml'
+
+class Bio::FinishM::BadFormatWriter
+  def initialize
+    @to_yamlify = []
+  end
+
+  def add_metapath(name, metapath)
+    to_write = []
+    metapath.each do |onode_or_bubble|
+      if onode_or_bubble.kind_of?(Bio::Velvet::Graph::OrientedNodeTrail::OrientedNode)
+        next_to_write = {}
+        next_to_write['type'] = 'regular'
+        next_to_write['node'] = onode_or_bubble.to_shorthand
+        next_to_write['coverage'] = onode_or_bubble.node.coverage
+        to_write << next_to_write
+      else
+        # bubble
+        paths = []
+        onode_or_bubble.each_path do |path|
+          next_to_write = {}
+          next_to_write['nodes'] = path.to_shorthand
+          next_to_write['coverage'] = path.coverage
+          paths << next_to_write
+        end
+        to_write << {
+          'type' => 'bubble',
+          'paths' => paths
+          }
+      end
+    end
+
+    @to_yamlify << {
+      'contig_name' => name,
+      'graph' => to_write.to_yaml
+      }
+  end
+
+  def yaml
+    @to_yamlify.to_yaml
+  end
+
+  def write(output_io)
+    output_io.print yaml
+  end
+end

data/lib/assembly/bam_probe_read_selector.rb

@@ -0,0 +1,48 @@
+require 'bio-samtools'
+
+module Bio
+  module AssemblyGraphAlgorithms
+    class BamProbeReadSelector
+      include Bio::FinishM::Logging
+
+      # Given an indexed bam file of reads mapped onto contigs,
+      # an array of one or more [contig_name, position, direction] entries (i.e. places in the contigs to locate reads for),
+      # a kmer (the match has to be at least one perfect kmer overlapping the position) and a
+      # path to a CnyUnifiedSeq.names file, return an Array of read_IDs of reads that can be used to locate the contig
+      # ends in the velvet graph.
+      #
+      # This assumes that velvet hasn't done anything to clean up the graph as cleaning might remove reads
+      # of interest
+      def find_probes(indexed_bam_file, contig_names_positions_directions, kmer, path_to_cny_unified_seq_names_file)
+        # need to check the sequence of the aligned read is the same as what is in the cny_unified_seq_names_file
+      end
+
+      # Given a contig name and a side, together with a path to an indexed bam file,
+      # pick out a read that can be used to 'locate'
+      # the contig end in the assembly, and return a Bio::DB::Alignment object of it
+      def find_probe_read_alignment_from_contig_end(indexed_bam_file, contig_name, direction, position, kmer)
+        # Search for all reads that overlap the overhang base, and are in the correct direction
+        sam = Bio::DB::Sam.new(:bam => indexed_bam_file)
+        position_hash = {:chr => contig_name}
+
+        # The probes must overlap the position, to one back from
+        # the contig end
+        if direction
+          position_hash[:start] = position-1
+          position_hash[:stop] = position
+        else
+          position_hash[:start] = position
+          position_hash[:stop] = position+1
+        end
+        sam.each_alignment(position_hash) do |alignment|
+          # Reject reads that do not have matching stretches of DNA that are at least kmer length long
+          # as these will not be included in the assembly.
+          # If it passes, then return the alignment
+
+        end
+
+        # Return the 'best' read's name and sequence.
+      end
+    end
+  end
+end

data/lib/assembly/bubbly_assembler.rb

@@ -0,0 +1,842 @@
+require 'set'
+require 'ds'
+
+# Like DS::PriorityQueue except give the ability to define how priority is given
+class DS::AnyPriorityQueue < DS::PriorityQueue
+  #Create new priority queue. Internaly uses heap to store elements.
+  def initialize
+    @store = DS::BinaryHeap.new {|parent,child| yield parent.key, child.key}
+  end
+
+  def each
+    @store.to_a.each do |pair|
+      yield pair.value
+    end
+  end
+end
+
+
+
+class Bio::AssemblyGraphAlgorithms::BubblyAssembler < Bio::AssemblyGraphAlgorithms::SingleEndedAssembler
+  include Bio::FinishM::Logging
+
+  DEFAULT_MAX_BUBBLE_LENGTH = 500
+  DEFAULT_BUBBLE_NODE_COUNT_LIMIT = 20 #so, so very 'un-educated' guess
+  DEFAULT_BUBBLE_FORK_LIMIT = 20
+  DEFAULT_MAX_CYCLES = 1
+
+  def initialize(graph, assembly_options={})
+    opts = assembly_options
+    opts[:max_bubble_length] ||= DEFAULT_MAX_BUBBLE_LENGTH
+    opts[:bubble_node_count_limit] ||= DEFAULT_BUBBLE_NODE_COUNT_LIMIT
+    opts[:bubble_fork_limit] ||= DEFAULT_BUBBLE_FORK_LIMIT
+    opts[:max_cycles] ||= DEFAULT_MAX_CYCLES
+    super graph, opts
+  end
+
+  # Starting at a node within a graph, walk through the graph
+  # accepting forks, so long as the fork paths converge within some finite
+  # length in the graph (the leash length, measured in number of base pairs).
+  #
+  # Return an Array of Path arrays, a MetaPath, where each path array are the different paths
+  # that can be taken at each fork point
+  def assemble_from(starting_path, visited_oriented_node_settables=Set.new)
+    leash_length = @assembly_options[:max_bubble_length]
+    if log.info? and starting_path.kind_of?(Bio::Velvet::Graph::OrientedNodeTrail)
+      log.info "Assembling from: #{starting_path.to_shorthand}"
+    end
+
+    filter_neighbours = lambda do |neighbours|
+      legit_neighbours, visiteds = remove_tips(neighbours, @assembly_options[:max_tip_length])
+      visiteds.each do |onode|
+        log.debug "Adding #{onode} to list of visited nodes" if log.debug?
+        visited_oriented_node_settables << onode
+      end
+      legit_neighbours
+    end
+
+    filterVisited = lambda do |oneigh|
+      visited_oriented_node_settables.include? oneigh.to_settable
+    end
+
+    # set up basic dynamic programming problem
+    baseProblem = lambda do |oneigh|
+      new_problem = DynamicProgrammingProblem.new
+      new_problem.distance = 0
+      new_path = Bio::Velvet::Graph::OrientedNodeTrail.new
+      new_path.add_oriented_node oneigh
+      new_problem.path = new_path
+      new_problem.ubiquitous_oriented_nodes = Set.new
+      new_problem.ubiquitous_oriented_nodes << oneigh.to_settable
+      new_problem.visited_oriented_nodes = Set.new
+      new_problem.visited_oriented_nodes << oneigh.to_settable
+      new_problem
+    end
+
+    # extend dynamic programming problem
+    extendedProblem = lambda do |problem, oneigh|
+      new_problem = DynamicProgrammingProblem.new
+      new_problem.distance = problem.distance + problem.path[-1].node.length_alone
+      new_path = problem.path.copy
+      new_path.add_oriented_node oneigh
+      new_problem.path = new_path
+      new_problem.ubiquitous_oriented_nodes = Set.new problem.ubiquitous_oriented_nodes
+      new_problem.ubiquitous_oriented_nodes << oneigh.to_settable
+      new_problem.visited_oriented_nodes = Set.new problem.visited_oriented_nodes
+      new_problem.visited_oriented_nodes << oneigh.to_settable
+      new_problem.circular_path_detected = true if problem.visited_oriented_nodes.include? oneigh.to_settable
+      new_problem
+    end
+
+    current_bubble = nil
+    metapath = MetaPath.new
+    starting_path.each do |oriented_node|
+      log.debug "adding onode at the start: #{oriented_node.to_shorthand}" if log.debug?
+      metapath << oriented_node
+    end
+
+    # Keep track of nodes visited in this trajectory already so circuits can be avoided
+    #visited_oriented_node_settables = Set.new
+    starting_path.each do |e|
+      if e.kind_of?(Bubble)
+        e.oriented_nodes do |onode|
+          visited_oriented_node_settables << onode.to_settable
+        end
+      else
+        visited_oriented_node_settables << e.to_settable
+      end
+    end
+    #log.debug "Starting with visited nodes #{visited_oriented_node_settables.to_a.join(',')}" if log.debug?
+
+    current_mode = :linear # :linear, :bubble, or :finished
+
+    while current_mode != :finished
+      if current_mode == :linear
+        log.debug "Starting a non-bubble from #{metapath.to_shorthand}" if log.debug?
+        while true
+          oriented_neighbours = metapath.last_oriented_node.next_neighbours(@graph)
+          log.debug "Found oriented neighbours #{oriented_neighbours.collect{|onode| onode.to_shorthand} }" if log.debug?
+
+          legit_neighbours = nil
+          # Cut off tips unless it is the only way
+          if oriented_neighbours.length == 1
+            legit_neighbours = oriented_neighbours
+          else
+            legit_neighbours = filter_neighbours.call(oriented_neighbours)
+          end
+
+          if legit_neighbours.empty?
+            # This is just a straight out dead end, and we can go no further.
+            log.debug "Dead end reached" if log.debug?
+            metapath.fate = MetaPath::DEAD_END_FATE
+            current_mode = :finished
+            break
+          elsif legit_neighbours.length == 1
+            # Linear thing here, just keep moving forward
+            neighbour = legit_neighbours[0]
+
+            # Stop if a circuit is detected
+            # Tim - Always stop on a circuit in linear mode. "We cannot get out." - Book of Mazarbul.
+            if visited_oriented_node_settables.include?(neighbour.to_settable)
+              log.debug "Detected circuit in linear mode by running into #{neighbour.to_settable}" if log.debug?
+              metapath.fate = MetaPath::CIRCUIT_FATE
+              current_mode = :finished
+              break
+            else
+              visited_oriented_node_settables << neighbour.to_settable
+              metapath << neighbour
+            end
+
+          else
+            # Reached a fork in the graph here, the point of this algorithm, really.
+            current_bubble = Bubble.new metapath.last_oriented_node
+            log.debug "Starting a bubble forking from metapath #{metapath.to_shorthand}" if log.debug?
+
+            if legit_neighbours.all? &filterVisited
+              log.debug "Detected fork in linear mode where all neighbours have been previously traversed. This is effectively a dead end." if log.debug?
+              metapath.fate = MetaPath::CIRCUIT_FATE
+              current_mode = :finished
+            end
+
+            legit_neighbours.each do |oneigh|
+              new_problem = baseProblem.call oneigh
+              log.debug "Adding problem to bubble: #{new_problem}" if log.debug?
+
+              current_bubble.enqueue new_problem
+              current_mode = :bubble
+            end
+            break
+          end
+        end
+
+
+      elsif current_mode == :bubble
+        # We are in a bubble. Go get some.
+        log.debug "entering bubble mode" if log.debug?
+
+        # next problem = queue.shift. while distance of next problem is not beyond the leash length
+        while current_mode == :bubble
+          problem = current_bubble.shift
+
+          if problem.nil?
+            # Getting here seems improbable if not impossible.
+            # The current bubble doesn't converge and just has short tips at the end, don't add it to the metapath
+            metapath.fate = MetaPath::DEAD_END_FATE
+            current_mode = :finished
+            log.debug "Reached a dead end, ignoring this path" if log.debug?
+            break
+          end
+
+          log.debug "Dequeued #{problem.to_shorthand}" if log.debug?
+          if !leash_length.nil? and problem.distance > leash_length
+            # The current bubble doesn't converge, don't add it to the metapath
+            metapath.fate = MetaPath::DIVERGES_FATE
+            current_mode = :finished
+            log.debug "Bubble is past the leash length of #{leash_length}, giving up" if log.debug?
+            break
+          elsif current_bubble.convergent_on?(problem)
+            log.debug "Bubble #{current_bubble.to_shorthand} convergent on #{problem.to_shorthand}" if log.debug?
+            current_bubble.converge_on problem
+            # convergement!
+            # Bubble ended in a convergent fashion
+
+            metapath << current_bubble
+            # Add the nodes in the bubble to the list of visited nodes
+            current_bubble.oriented_nodes do |onode|
+              visited_oriented_node_settables << onode.to_settable
+            end
+
+            current_bubble = nil
+            current_mode = :linear
+            break
+          else
+            # otherwise we must search on in the bubble
+            # get all neighbours that are not short tips
+            log.debug "Bubble not convergent on #{problem.to_shorthand}" if log.debug?
+
+            neighbours = problem.path.neighbours_of_last_node(@graph)
+
+            # If there is only 1 way to go, go there
+            if neighbours.length == 1
+              log.debug "Only one way to go from this node, going there" if log.debug?
+
+              oneigh = neighbours[0]
+              new_problem = extendedProblem.call problem, oneigh
+              current_bubble.enqueue new_problem
+              log.debug "Enqueued #{new_problem.to_shorthand}, total nodes now #{current_bubble.num_known_problems} and num forks #{current_bubble.num_legit_forks}" if log.debug?
+
+              # check to make sure we aren't going overboard in the bubbly-ness
+              if !@assembly_options[:bubble_node_count_limit].nil? and current_bubble.num_known_problems > @assembly_options[:bubble_node_count_limit]
+                log.debug "Too complex a bubble detected, giving up" if log.debug?
+                metapath.fate = MetaPath::NODE_COUNT_LIMIT_REACHED
+                current_mode = :finished
+                break
+              end
+            else
+              legit_neighbours = filter_neighbours.call(neighbours)
+
+              if legit_neighbours.length == 0
+                # this is a kind of 'long' tip, possibly unlikely to happen much.
+                # Forget about it and progress to the next problem having effectively
+                # removed it from the bubble
+                log.debug "Found no neighbours to re-enqueue" if log.debug?
+              else
+                # Increment complexity counter if this is a real fork
+                if legit_neighbours.length > 1
+                  current_bubble.num_legit_forks += 1
+                end
+
+                legit_neighbours.each do |oneigh|
+                  new_problem = extendedProblem.call problem, oneigh
+                  current_bubble.enqueue new_problem
+                  log.debug "Enqueued #{new_problem.to_shorthand}, total nodes now #{current_bubble.num_known_problems} and num forks #{current_bubble.num_legit_forks}" if log.debug?
+
+                  # check to make sure we aren't going overboard in the bubbly-ness
+                  if (!@assembly_options[:bubble_fork_limit].nil? and current_bubble.num_legit_forks > @assembly_options[:bubble_fork_limit]) or
+                      (!@assembly_options[:bubble_node_count_limit].nil? and current_bubble.num_known_problems > @assembly_options[:bubble_node_count_limit])
+                    log.debug "Too complex a bubble detected, giving up" if log.debug?
+                    metapath.fate = MetaPath::NODE_COUNT_LIMIT_REACHED
+                    current_mode = :finished
+                    break
+                  end
+                end
+              end
+            end
+          end
+        end
+      else
+        raise "Programming error: Unexpected mode: #{current_mode}"
+      end
+
+      log.debug "Reached end of main loop in mode #{current_mode}" if log.debug?
+    end
+
+    return metapath, visited_oriented_node_settables
+  end
+
+  def seen_last_in_path?(path, seen_nodes)
+    last = path[-1]
+    if last.kind_of?(Bubble)
+      return remove_seen_nodes_from_end_of_path(path, seen_nodes).length < path.length
+    else
+      return seen_nodes.include?(path[-1].to_settable)
+    end
+  end
+
+
+  def remove_seen_nodes_from_end_of_path(path, seen_nodes)
+    log.debug "Removing from the end of the path #{path.to_shorthand} any nodes in set of length #{seen_nodes.length}" if log.debug?
+
+    node_seen = lambda do |oriented_node|
+      seen_nodes.include?([oriented_node.node_id, Bio::Velvet::Graph::OrientedNodeTrail::START_IS_FIRST]) or
+      seen_nodes.include?([oriented_node.node_id, Bio::Velvet::Graph::OrientedNodeTrail::END_IS_FIRST])
+    end
+
+    while !path.empty?
+      last_node_or_bubble_index = path.length-1
+      last_node_or_bubble = path[last_node_or_bubble_index]
+
+      delete = false
+      if last_node_or_bubble.kind_of?(Bubble)
+        last_node_or_bubble.oriented_nodes do |onode|
+          if node_seen.call(onode)
+            delete = true
+            break
+          end
+        end
+      else
+        delete = node_seen.call(last_node_or_bubble)
+      end
+
+      if delete
+        path.delete_at last_node_or_bubble_index
+      else
+        # Last node is not previously seen, chop no further.
+        break
+      end
+    end
+
+    return path
+  end
+
+
+  class MetaPath
+    DIVERGES_FATE = 'diverges'
+    DEAD_END_FATE = 'dead end'
+    CIRCUIT_FATE = 'circuit'
+    NODE_COUNT_LIMIT_REACHED = 'too many nodes in bubble'
+    #CIRCUIT_WITHIN_BUBBLE_FATE = 'circuit within bubble' #Tim - shouldn't end metapath
+
+    # How does this metapath end?
+    attr_accessor :fate
+
+    include Enumerable
+
+    def initialize
+      @internal_array = []
+    end
+
+    def each
+      @internal_array.each do |e|
+        yield e
+      end
+    end
+
+    def [](index)
+      @internal_array[index]
+    end
+
+    def delete_at(index)
+      @internal_array.delete_at index
+    end
+
+    def empty?
+      @internal_array.empty?
+    end
+
+    def last_oriented_node
+      e = @internal_array[-1]
+      if e.kind_of?(Bio::Velvet::Graph::OrientedNodeTrail::OrientedNode)
+        return e
+      else
+        # it is a bubble
+        return e.converging_oriented_node
+      end
+    end
+
+    def <<(oriented_node_or_bubble)
+      @internal_array << oriented_node_or_bubble
+    end
+    alias_method :push, :<<
+
+    def to_shorthand
+      @internal_array.collect{|e| e.to_shorthand}.join(',')
+    end
+
+    def reverse!
+      # Do regular reversal
+      @internal_array.reverse!
+
+      # Reverse all the internal parts
+      @internal_array.each do |e|
+        e.reverse!
+      end
+
+      return nil
+    end
+
+    def length
+      @internal_array.length
+    end
+
+        # Yield all oriented nodes anywhere in the regular or bubble
+    # bits.
+    def each_oriented_node
+      @internal_array.each do |e|
+        if e.kind_of?(Bio::AssemblyGraphAlgorithms::BubblyAssembler::Bubble)
+          e.oriented_nodes.each do |onode|
+            yield onode
+          end
+        else
+          yield e
+        end
+      end
+    end
+
+    def length_in_bp
+      sum = 0
+      each do |e|
+        if e.kind_of?(Bio::AssemblyGraphAlgorithms::BubblyAssembler::Bubble)
+          sum += e.reference_trail.length_in_bp_within_path
+        else
+          sum += e.node.length_alone
+        end
+      end
+      return sum
+    end
+
+    def reference_trail
+      trail = Bio::Velvet::Graph::OrientedNodeTrail.new
+
+      trail.trail = collect do |e|
+        if e.kind_of?(Bio::AssemblyGraphAlgorithms::BubblyAssembler::Bubble)
+          e.reference_trail.trail
+        else
+          e
+        end
+      end.flatten
+
+      return trail
+    end
+
+    def sequence
+      reference_trail.sequence
+    end
+
+    def coverage
+      coverages = []
+      lengths = []
+      each do |onode_or_bubble|
+        if onode_or_bubble.kind_of?(Bio::AssemblyGraphAlgorithms::BubblyAssembler::Bubble)
+          # Length isn't obvious, but let's go with reference path length just coz that's easy
+          this_length = onode_or_bubble.reference_trail.length_in_bp_within_path
+          lengths.push this_length
+
+          # Coverage of a bubble is the coverage of each node in the bubble
+          # each weighted by their length
+          coverages.push onode_or_bubble.coverage
+        else
+          #regular node. So simple average coverage
+          coverages.push onode_or_bubble.node.coverage
+          lengths.push onode_or_bubble.node.length_alone
+        end
+      end
+
+      # Then a simple weighted average
+      i = -1
+      total_length = lengths.reduce(:+)
+
+      answer =  coverages.reduce(0.0) do |sum, cov|
+        i += 1
+        sum + (cov * lengths[i].to_f / total_length)
+      end
+      answer
+    end
+  end
+
+
+  # Tim - use 'waiting train' algorithm (made up by me).
+  # Problems collect the nodes they visit, adding them to hashes of 'ubiquitous' and 'visited' nodes
+  # (metaphor: 'train' (problem) visiting 'stations' (nodes)).
+  # Each time a problem is dequeued, new problems are enqueued for all neighbours to the problem node
+  # (metaphor: 'trains' (problems) magically duplicate for each path to a new 'station' (node) (methaphor
+  # breaks a bit here)).
+  # At each step the algorithm dequeues a problem, prioritising problems by shortest distance of any path
+  # to the problem node, meaning if a a problem is enqueued for a node that is already known, then that
+  # problem is prioritised (metaphor: when a train leaves a station (problem is deqeued) other 'trains' will
+  # wait in case it catches up, or otherwise reaches a more distant station).
+  # If a new problem is enqueued for a problem node that is currently in enqueued, the new problem is added
+  # to known problems removed from queue, and when a problem is dequeued, its ubiquitous and visited nodes
+  # are set to the ubiquitous and visited nodes of all known problems for the node (metaphor: the carriages
+  # of all trains at a station are merged into one train).
+  # Cycles occur when a problem reaches a node that is in its visited nodes hash (metaphor: a station that
+  # one of the train carriages has previously visited).
+  # Queued cyclic problems are added to known problems and then dropped.
+  # Bubble is converged when all current problems have a ubiquitous node in common (metaphor: all carriages
+  # of all current trains have visited a station).
+  class Bubble
+    include Bio::FinishM::Logging
+
+    # The DynamicProgrammingProblem this bubble converges on
+    attr_reader :converging_oriented_node_settable, :is_reverse, :root
+
+    # how many legit forks have been explored
+    attr_accessor :num_legit_forks
+
+    def initialize(bubble_root, options = {})
+      @queue = DS::AnyPriorityQueue.new {|a,b| a<=b}
+      @known_problems = {}
+      @current_problems = Set.new
+      @num_legit_forks = 0
+      @max_cycles = options[:max_cycles] || DEFAULT_MAX_CYCLES
+      @root = bubble_root
+    end
+
+    # Return the next closest dynamic programming problem,
+    # removing it from the bubble
+    def shift
+      prob = @queue.shift
+      unless prob.nil?
+        prob.ubiquitous_oriented_nodes = ubiquitous_oriented_nodes(prob)
+        prob.visited_oriented_nodes = visited_oriented_nodes(prob)
+        @current_problems.delete prob.to_settable
+      end
+      return prob
+    end
+
+    def visited_oriented_nodes(prob)
+      #all visited nodes for relevant problems
+      @known_problems[prob.to_settable].reduce(prob.ubiquitous_oriented_nodes) do |memo, problem|
+        memo + problem.ubiquitous_oriented_nodes
+      end
+    end
+
+    def ubiquitous_oriented_nodes(prob)
+      #only ubiquitous nodes from relevant problems
+      @known_problems[prob.to_settable].reduce(prob.ubiquitous_oriented_nodes) do |memo, problem|
+        memo & problem.ubiquitous_oriented_nodes
+      end
+    end
+
+    def shortest_problem_distance(prob)
+      # prioritise by the shortest distance for current problem
+      @known_problems[prob.to_settable].collect{|prob| prob.distance}.min
+    end
+
+    def enqueue(dynamic_programming_problem)
+      settable = dynamic_programming_problem.to_settable
+
+
+      @known_problems[settable] ||= []
+      @known_problems[settable].push dynamic_programming_problem
+
+      # don't requeue current problem or circular problem
+      unless dynamic_programming_problem.circular_path_detected == true or @current_problems.include? settable
+        @queue.enqueue dynamic_programming_problem, shortest_problem_distance(dynamic_programming_problem)
+        @current_problems << settable
+      end
+    end
+
+
+    # return true if the given problem converges the bubble, else false
+    def convergent_on?(dynamic_programming_problem)
+      settable =  dynamic_programming_problem.to_settable
+
+      @queue.each do |problem| #convergent until not
+        return false unless ubiquitous_oriented_nodes(problem).include? settable
+      end
+      return true
+    end
+
+    # Finish off the bubble, assuming convergent_on? the given problem == true
+    def converge_on(dynamic_programming_problem)
+      @converging_oriented_node_settable = dynamic_programming_problem.to_settable
+      #free some memory
+      @queue = nil
+      @current_problems = nil
+    end
+
+    # yield or failing that return an Array of the list of oriented_nodes found
+    # in at least one path in this (presumed converged) bubble
+    def oriented_nodes
+      raise unless converged?
+      seen_nodes = {}
+      stack = DS::Stack.new
+      initial_solution = @known_problems[@converging_oriented_node_settable][0]
+      converging_onode = initial_solution.path[-1]
+      stack.push converging_onode
+
+      while onode = stack.pop
+        settable = onode.to_settable
+        next if seen_nodes.key?(settable)
+
+        if block_given?
+          if @is_reverse
+            yield onode.reverse
+          else
+            yield onode
+          end
+        end
+
+        seen_nodes[settable] = onode
+
+        # queue neighbours for paths that don't contain the converging onode
+        @known_problems[settable].each do |dpp|
+          stack.push dpp.path[-2] unless dpp.path.length < 2 or dpp.path[0...-1].include? converging_onode
+        end
+      end
+
+      return nil if block_given?
+      return seen_nodes.values
+    end
+
+    def num_known_problems
+      @known_problems.length
+    end
+
+
+    # Iterate over the paths returning each as an OrientedNodeTrail.
+    # Assumes the path is convergent.
+    def each_path(options = {})
+      raise unless converged?
+      max_cycles = options[:max_cycles] || @max_cycles
+
+      # Metric used to prioritise each_path
+      comparator = lambda do |problem1, problem2|
+        onode1 = nil
+        onode2 = nil
+        if problem1.path.length == 1 and problem2.path.length > 1
+          # Here the comparison cannot be made on 2nd last node coverages
+          # since one of the paths goes straight from the initial to the terminal
+          # node. Choose instead based on if the second last node has higher or lower
+          # coverage than the final node
+          onode1 = problem1.path[-1]
+          onode2 = problem2.path[-2]
+        elsif problem2.path.length == 1 and problem1.path.length > 1
+          onode1 = problem1.path[-2]
+          onode2 = problem2.path[-1]
+        else
+          onode1 = problem1.path[-2]
+          onode2 = problem2.path[-2]
+        end
+        #log.debug "Comparing nodes #{onode1.node.node_id} and #{onode2.node.node_id}" if log.debug?
+
+        if onode1.node.coverage == onode2.node.coverage
+          -(onode1.node.node_id <=> onode2.node.node_id)
+        else
+          onode1.node.coverage <=> onode2.node.coverage
+        end
+      end
+
+      log.debug "Iterating through each path of bubble" if log.debug?
+
+      # Tim - use stack and push paths with lowest coverage first
+      stack = DS::Stack.new
+      counter = Bio::AssemblyGraphAlgorithms::SingleCoherentPathsBetweenNodesFinder::CycleCounter.new max_cycles
+      initial_solution = @known_problems[@converging_oriented_node_settable][0]
+      stack.push [initial_solution.path, []]
+      converging_onode = converging_oriented_node
+      #log.debug "Pushed to stack #{initial_solution.path.to_shorthand}" if log.debug?
+
+
+      while path_parts = stack.pop
+        direct_node_trail = path_parts[0]
+        second_part = path_parts[1]
+        #log.debug "Popped #{direct_node_trail.to_shorthand} and [#{second_part.collect{|o| o.to_shorthand}.join(',') }]" if log.debug?
+
+
+        if direct_node_trail.trail.length == 0
+
+          # check for cycles through bubble root
+          if second_part.include? @root
+            #log.debug "Found cycle through bubble root." if log.debug?
+            @circuitous = true unless @circuitous
+            if max_cycles == 0 or max_cycles < counter.path_cycle_count([@root]+second_part)
+              #log.debug "Not finishing cyclic path with too many cycles." if log.debug?
+              next
+            end
+          end
+
+          yield_path = Bio::Velvet::Graph::OrientedNodeTrail.new
+          yield_path.trail = second_part
+          if @is_reverse
+            yield_path = yield_path.reverse
+          end
+          log.debug "Yielded #{yield_path.to_shorthand}" if log.debug?
+          yield yield_path
+        else
+          # go down the path, looking for other paths
+          head_onode = direct_node_trail.trail[-1]
+          new_second_part = [head_onode]+second_part
+          if second_part.length > 1 and head_onode == converging_oriented_node
+            #log.debug "Ignoring path with cycle through converged node." if log.debug?
+            next
+          end
+          if second_part.include? head_onode
+            #log.debug "Cycle at node #{head_onode.node_id} in path #{second_part.collect{|onode| onode.node.node_id}.join(',')}." if log.debug?
+            @circuitous = true unless @circuitous
+            if max_cycles == 0 or max_cycles < counter.path_cycle_count(new_second_part)
+              #log.debug "Not finishing cyclic path with too many cycles." if log.debug?
+              next
+            end
+          end
+
+          new_problems = @known_problems[head_onode.to_settable]
+          #log.debug "Found new problems: #{new_problems.collect{|prob| prob.to_shorthand}.join(' ') }" if log.debug?
+
+          problem_leads = Set.new
+          filtered_problems = new_problems.reject do |new_problem|
+            # Only enqueue paths where the second-to-head onode is not already queued
+            unless new_problem.path.length < 2
+              lead_settable = new_problem.path[-2].to_settable
+              if problem_leads.include? lead_settable
+                #log.debug "Ignoring duplicate neighbour problem #{new_problem.to_shorthand}" if log.debug?
+                next true
+              end
+              problem_leads << lead_settable
+            end
+            false
+          end
+
+          filtered_problems.sort(&comparator).each do |new_problem|
+            # TODO: deal with circuits
+            new_trail = Bio::Velvet::Graph::OrientedNodeTrail.new
+            new_trail.trail = new_problem.path[0...-1]
+            #log.debug "Enqueuing #{new_trail.to_shorthand} and [#{new_second_part.collect{|o| o.to_shorthand}.join(',') }]" if log.debug?
+            stack.push [new_trail, new_second_part]
+          end
+        end
+      end
+    end
+
+    def paths
+      to_return = []
+      each_path do |path|
+        to_return.push path
+      end
+      to_return
+    end
+
+    def converged?
+      !@converging_oriented_node_settable.nil?
+    end
+
+    # Return the OrientedNode that converges this bubble, behaviour
+    # undefined if bubble is not converged
+    def converging_oriented_node
+      @known_problems[@converging_oriented_node_settable][0].path[-1]
+    end
+
+    def to_shorthand
+      shorts = []
+      if converged?
+        shorts = paths.sort{|a,b| a.to_shorthand <=> b.to_shorthand }.collect{|path| path.to_shorthand}
+      else
+        @queue.each do |problem|
+          shorts.push problem.to_shorthand
+        end
+      end
+      return "{#{shorts.join('|') }}"
+    end
+
+    def reverse!
+      @is_reverse ||= false
+      @is_reverse = !@is_reverse
+    end
+
+    # This doesn't make sense unless this is a converged bubble and the index == -1
+    # because otherwise there is multiple answers
+    def [](index)
+      raise unless index == -1
+      return Bio::Velvet::Graph::OrientedNodeTrail::OrientedNode.new(
+        @converging_oriented_node_settable[0],
+        @converging_oriented_node_settable[1]
+        )
+    end
+
+    # Return one trail that exemplifies the paths through this bubble.
+    # Current method of path selection is simply greedy, taking the highest coverage node
+    # at each fork (or failing that the node with the lower node_id).
+    def reference_trail(max_cycles = @max_cycles)
+      raise unless converged?
+
+      converging_onode = converging_oriented_node
+      log.debug "Finding reference trail from node #{converging_onode.node.node_id}" if log.debug?
+
+      reference_trail = nil
+      each_path do |path|
+        #break when first path is found
+        reference_trail = path
+        break
+      end
+
+      return reference_trail
+    end
+
+    # Does this (coverged) bubble contain any circuits?
+    def circuitous?
+      raise unless converged?
+      if @circuitous.nil?
+        each_path({:max_cycles => 0}) {|| break if @circuitous}
+        @circuitous ||= false
+      end
+      @circuitous
+    end
+
+    # Coverage of a bubble is the coverage of each node in the bubble
+    # each weighted by their length
+    def coverage
+      sum = 0.0
+      length = 0
+      oriented_nodes do |onode|
+        node_length = onode.node.length_alone
+        sum += onode.node.coverage * node_length
+        length += node_length
+      end
+      return sum / length
+    end
+  end
+
+  class DynamicProgrammingProblem
+    attr_accessor :path, :ubiquitous_oriented_nodes, :visited_oriented_nodes, :distance, :circular_path_detected
+
+    def initialize
+      @path = []
+      @ubiquitous_oriented_nodes = Set.new
+    end
+
+    def to_settable
+      @path[-1].to_settable
+    end
+
+    def to_s
+      ubiquitous_nodes = @ubiquitous_oriented_nodes.collect do |settabled|
+        "#{settabled[0] }#{settabled[1] == Bio::Velvet::Graph::OrientedNodeTrail::START_IS_FIRST ? 's' : 'e'}"
+      end
+      return "DPP #{self.object_id}: #{@path.to_shorthand}/#{ubiquitous_nodes.join(',') }/#{distance}"
+    end
+
+    def to_shorthand
+      ubiquitous_nodes = @ubiquitous_oriented_nodes.collect do |settabled|
+        "#{settabled[0] }#{settabled[1] == Bio::Velvet::Graph::OrientedNodeTrail::START_IS_FIRST ? 's' : 'e'}"
+      end
+      "#{@path.to_shorthand}/#{ubiquitous_nodes.join(',') }/#{distance}"
+    end
+  end
+
+  class ComparableArray < Array
+    include Comparable
+  end
+
+  class CircuitousPathDetected < Exception; end
+end