finishm 0.0.1

data/lib/assembly/graph_explorer.rb

@@ -0,0 +1,85 @@
+require 'ds'
+require 'set'
+
+module Bio
+  module AssemblyGraphAlgorithms
+    class GraphExplorer
+      # Return all paths that emenate from a given node, in the graph
+      def explore_from_node(graph, initial_path, leash_length)
+        # Do a simple depth first search, forking at each node. Vanilla graph traversal.
+        depth_first_search_stack = DS::Stack.new
+        first_path = ExplorationPath.new initial_path
+        depth_first_search_stack.push first_path
+        found_paths = []
+        # While there's more paths to explore
+        while current_path = depth_first_search_stack.pop
+          last = current_path.path.last
+          if !leash_length.nil? and current_path.path.length_in_bp > leash_length
+            current_path.termination_type = 'Leashed'
+            found_paths.push current_path
+          else
+            neighbours = current_path.path.neighbours_of_last_node(graph)
+            if neighbours.empty?
+              current_path.termination_type = 'Dead end / coverage'
+              found_paths.push current_path
+            else
+              neighbours_to_add = []
+              neighbours.each do |oriented_neighbour|
+                # Test for loops, I'm only interested in acyclic paths for the moment
+                if current_path.include?(oriented_neighbour)
+                  #loop found, terminate path
+                  new_path = current_path.copy
+                  new_path.add_node oriented_neighbour
+                  new_path.termination_type = 'Loop'
+                  found_paths.push new_path
+                else
+                  neighbours_to_add.push oriented_neighbour
+                end
+              end
+              neighbours_to_add.each_with_index do |oriented_neighbour, i|
+                # If the last neighbour is being added here, reuse the path
+                next_path = nil
+                if i == neighbours_to_add.length-1
+                  next_path = current_path
+                else
+                  next_path = current_path.copy
+                end
+                next_path.add_node oriented_neighbour
+                depth_first_search_stack.push next_path
+              end
+            end
+          end
+        end
+
+        return found_paths
+      end
+
+      class ExplorationPath
+        attr_accessor :path, :set_of_nodes, :termination_type
+
+        def initialize(path)
+          @path = path
+          @set_of_nodes = Set.new path.collect{|n| n.to_settable}
+        end
+
+        def include?(oriented_node)
+          @set_of_nodes.include?(oriented_node.to_settable)
+        end
+
+        def add_node(onode)
+          path.add_oriented_node onode
+          @set_of_nodes << onode.to_settable
+        end
+
+        def copy
+          anew = ExplorationPath.new @path.copy
+          return anew
+        end
+
+        def to_s
+          @path.collect{|on| on.node_id}.join(',')
+        end
+      end
+    end
+  end
+end

data/lib/assembly/graph_generator.rb

@@ -0,0 +1,315 @@
+require 'bio-velvet'
+require 'bio'
+require 'pry'
+
+class Bio::FinishM::GraphGenerator
+  include Bio::FinishM::Logging
+
+  DEFAULT_OPTIONS = {
+    :velvet_kmer_size => 51,
+    :assembly_coverage_cutoff => 3.5,
+    }
+
+  def add_options(option_parser, options)
+    options.merge!(DEFAULT_OPTIONS)
+    option_parser.on("--assembly-kmer NUMBER", "when assembling, use this kmer length [default: #{options[:velvet_kmer_size] }]") do |arg|
+      options[:velvet_kmer_size] = arg.to_i
+    end
+    option_parser.on("--assembly-coverage-cutoff NUMBER", "Require this much coverage in each node, all other nodes are removed [default: #{options[:assembly_coverage_cutoff] }]") do |arg|
+      options[:assembly_coverage_cutoff] = arg.to_f
+    end
+    option_parser.on("--post-assembly-coverage-cutoff NUMBER", "Require this much coverage in each node, implemented after assembly [default: not used]") do |arg|
+      options[:post_assembly_coverage_cutoff] = arg.to_f
+    end
+    option_parser.on("--velvet-directory PATH", "Output assembly intermediate files to this directory [default: use temporary directory, delete afterwards]") do |arg|
+      options[:output_assembly_path] = arg
+    end
+    option_parser.on("--already-assembled-velvet-directory PATH", "If an assembly directory has been specified previously with --velvet-directory, re-use this assembly rather than re-doing the assembly [default: off]") do |arg|
+      options[:previous_assembly] = arg
+    end
+  end
+
+  # Generate a ProbedGraph object, given one or more 'probe sequences'
+  # and metagenomic reads. This is a rather large method, but seems to
+  # be approximately repeated in different applications of FinishM, so
+  # creating it for DRY purposes.
+  #
+  # probe_sequences: DNA sequences (as String objects whose direction points to the outsides of contigs)
+  # read_inputs: a ReadInput object, containing the information to feed to velveth
+  #
+  # options:
+  # :probe_reads: a list of sequence numbers (numbering as per velvet Sequence file)
+  # :probe_read_names: a list of sequence names (not IDs) that are probes (convert the names to IDs using the CnyUnifiedSeqNames file). There may not be a one to one correspondence of these read names and the probe reads returned in the ProbedGraph since reads can map to multiple sequence IDs.
+  # :velvet_kmer_size: kmer
+  # :assembly_coverage_cutoff: coverage cutoff for nodes
+  # :post_assembly_coverage_cutoff: apply this coverage cutoff to nodes after parsing assembly
+  # :output_assembly_path: write assembly to this directory
+  # :previous_assembly: a velvet directory from a previous run of the same probe sequences and reads. (Don't re-assemble)
+  # :use_textual_sequence_file: by default, a binary sequence file is used. Set this true to get velvet to generate the Sequences file
+  # :remove_unconnected_nodes: delete nodes from the graph that are not connected to the probe nodes
+  # :graph_search_leash_length: when :remove_unconnected_nodes'ing, use this leash length
+  # :dont_parse_noded_reads: if true, skip parsing noded reads (ie the positions of the reads in the graph)
+  # :dont_parse_reads: if true, skip parsing reads (ie the sequences of the reads themselves)
+  def generate_graph(probe_sequences, read_inputs, options={})
+    options[:parse_sequence_file] ||= true
+    graph = nil
+    read_probing_graph = nil
+    finishm_graph = Bio::FinishM::ProbedGraph.new
+
+    log.debug "Options for generate_graph: #{options}" if log.debug?
+
+    velvet_binary_folder = File.join(File.dirname(__FILE__),'..','..','ext','src')
+    log.debug "Using velvet binary folder #{velvet_binary_folder}" if log.debug?
+
+    velvet_result = nil
+
+    probe_read_ids = nil
+    if options[:probe_reads]
+      probe_read_ids = options[:probe_reads]
+    else
+      probe_read_ids = Set.new((1..probe_sequences.length))
+    end
+    if options[:previous_assembly].nil? #If assembly has not already been carried out
+      Tempfile.open('probes.fa') do |tempfile|
+        50.times do # Do 50 times to make sure that velvet doesn't throw out parts of the graph that contain this contig
+          probe_sequences.each_with_index do |probe, i|
+            tempfile.puts ">probe#{i}"
+            tempfile.puts probe
+          end
+        end
+        tempfile.close
+        singles = read_inputs.fasta_singles
+        if singles and !singles.empty?
+          read_inputs.fasta_singles = [tempfile.path, singles].flatten
+        else
+          read_inputs.fasta_singles = [tempfile.path]
+        end
+        log.debug "Inputting probes into the assembly:\n#{File.open(tempfile.path).read}" if log.debug?
+
+        runner = Bio::Velvet::Runner.new
+        required_version = '1.2.10-wwood_finishm'
+        found_version = runner.binary_version(File.join(velvet_binary_folder, 'velveth'))
+        if found_version != required_version
+          raise "Detected velvet version incompatible with FinishM: #{found_version}, expected #{required_version} which is available from https://github.com/wwood/velvet (on branch less_clipping)"
+        end
+
+        log.info "Assembling sampled reads with velvet"
+        raise "Need to specify -cov_cutoff" if options[:assembly_coverage_cutoff].nil?
+        raise "Need to specify a kmer size" if options[:velvet_kmer_size].nil?
+        # Bit of a hack, but have to use -short1 as the anchors because then start and end anchors will have node IDs 1,2,... etc.
+        use_binary = options[:use_textual_sequence_file] ? '' : '-create_binary'
+        velvet_result = runner.velvet(
+          options[:velvet_kmer_size],
+          "#{read_inputs.velvet_read_arguments} #{use_binary}",
+          "-read_trkg yes -cov_cutoff #{options[:assembly_coverage_cutoff] } -tour_bus no -read_to_node_binary yes",
+          :output_assembly_path => options[:output_assembly_path],
+          :velveth_path => File.join(velvet_binary_folder, 'velveth'),
+          :velvetg_path => File.join(velvet_binary_folder, 'velvetg'),
+          )
+        if log.debug?
+          log.debug "velveth stdout: #{velvet_result.velveth_stdout}"
+          log.debug "velveth stderr: #{velvet_result.velveth_stderr}"
+          log.debug "velvetg stdout: #{velvet_result.velvetg_stdout}"
+          log.debug "velvetg stderr: #{velvet_result.velvetg_stderr}"
+        end
+        log.info "Finished running assembly"
+        finishm_graph.velvet_result_directory = velvet_result.result_directory
+      end
+    else
+      log.info "Using previous assembly stored in #{options[:previous_assembly] }"
+      velvet_result = Bio::Velvet::Result.new
+      velvet_result.result_directory = options[:previous_assembly]
+      finishm_graph.velvet_result_directory = velvet_result.result_directory
+    end
+
+    # Check that the probe reads given are present in the assembly passed here
+    unless options[:dont_parse_reads]
+      sequence_store = parse_velvet_binary_reads(velvet_result.result_directory)
+      finishm_graph.velvet_sequences = sequence_store
+      if !check_probe_sequences(probe_sequences, sequence_store)
+        raise "Probe sequences changed since previous velvet assembly!"
+      end
+    end
+
+    log.info "Parsing the graph output from velvet"
+    opts = {
+      # noded reads are parsed in via C, if they are wanted at all
+      :dont_parse_noded_reads => true
+    }
+    bio_velvet_graph = Bio::Velvet::Graph.parse_from_file(
+      File.join(velvet_result.result_directory, 'LastGraph'),
+      opts
+      )
+    log.info "Finished parsing graph: found #{bio_velvet_graph.nodes.length} nodes and #{bio_velvet_graph.arcs.length} arcs"
+
+    if options[:dont_parse_noded_reads]
+      graph = bio_velvet_graph
+    else
+      log.info "Beginning parse of graph using velvet's parsing C code.."
+      read_probing_graph = Bio::Velvet::Underground::Graph.parse_from_file File.join(velvet_result.result_directory, 'LastGraph')
+      log.info "Completed velvet code parsing velvet graph"
+
+      # Make the two graphs into a hybrid one
+      graph = Bio::FinishM::HybridGraph.new(bio_velvet_graph, read_probing_graph)
+    end
+    finishm_graph.graph = graph
+
+    # Find the anchor nodes again
+    anchor_sequence_ids = probe_read_ids.to_a.sort
+    endings = []
+    unless probe_read_ids.empty? and options[:probe_read_names].nil? #don't bother trying to find probes if none exists
+      # Convert read names to read IDs if required
+      if options[:probe_read_names]
+        # Probe reads are given as names, not IDs. What are the corresponding probes then?
+        entries = Bio::Velvet::CnyUnifiedSeqNamesFile.extract_entries_using_grep_hack(
+          File.join(velvet_result.result_directory, 'CnyUnifiedSeq.names'),
+          options[:probe_read_names]
+          )
+        anchor_sequence_ids = []
+        double_counts = 0
+        options[:probe_read_names].each do |name| #maintain order of them as they are specified in the original array parameter
+          if entries[name].empty?
+            raise "Unable to find probe `#{name}' in the probe reads file - was it included in the assembly?"
+          elsif entries[name].length > 2
+            raise "Found >2 sequences named #{name} in the assembly, being conservative and not continuing"
+          else
+            entries[name].each do |res|
+              anchor_sequence_ids.push res.read_id
+            end
+            if entries[name].length == 2
+              double_counts += 1
+              log.debug "Found 2 sequences for #{name}" if log.debug?
+            end
+          end
+        end
+        if double_counts > 0
+          log.info "#{double_counts} reads were found twice (likely as pairs), including both as probes"
+        end
+        log.info "Recovered #{anchor_sequence_ids.length} sequences using their names" if log.info?
+      end
+
+
+      # Parse the read to node structure
+      log.info "Reading ReadToNode.bin file.." if log.info?
+      finishm_graph.read_to_nodes = Bio::FinishM::ReadToNode.new(File.join(velvet_result.result_directory, 'ReadToNode.bin'))
+
+      finder = Bio::AssemblyGraphAlgorithms::NodeFinder.new
+      log.info "Finding probe nodes in the assembly"
+      c_graph_endings = finder.find_probes_from_read_to_node(finishm_graph.graph, finishm_graph.read_to_nodes, anchor_sequence_ids)
+      log.debug "Converting probe nodes found in C graph to Ruby analogues and adding to Ruby-parsed graph"
+      endings = c_graph_endings.collect do |node_direction_read|
+        if node_direction_read.empty?
+          # No probe found
+          []
+        else #found a node.
+          #equivalent node
+          node = graph.nodes[node_direction_read[0].node_id]
+          #equivalent direction
+          direction = node_direction_read[1]
+          #equivalent noded read
+          nr = Bio::Velvet::Graph::NodedRead.new
+          #           nr.read_id = read_id
+          #           nr.offset_from_start_of_node = row[1].to_i
+          #           nr.start_coord = row[2].to_i
+          #           nr.direction = current_node_direction
+          cnr = node_direction_read[2]
+          nr.read_id = cnr.read_id
+          nr.offset_from_start_of_node = cnr.offset_from_start_of_node
+          nr.start_coord = cnr.start_coord
+          nr.direction = direction
+          # collect
+          [node, direction, nr]
+        end
+      end
+    end
+    finishm_graph.probe_nodes = endings.collect{|array| array[0]}
+    finishm_graph.probe_node_directions = endings.collect{|array| array[1]}
+    finishm_graph.probe_node_reads = endings.collect{|array| array[2]}
+
+    # Check to make sure the probe sequences map to nodes in the graph
+    if finishm_graph.completely_probed?
+      if log.info?
+        found_all = true
+        num_found = 0
+        finishm_graph.probe_nodes.each_with_index do |probe,i|
+          if probe.nil?
+            found_all = false
+            log.debug "Unable to recover probe ##{i+1}, perhaps this will cause problems, but proceding optimistically"
+          else
+            num_found += 1
+          end
+        end
+        if found_all
+          if finishm_graph.probe_nodes.empty?
+            log.debug "No probes specified, so didn't find any"
+          else
+            log.info "Found all anchoring nodes in the graph."
+          end
+        else
+          log.info "Found #{num_found} of #{finishm_graph.probe_nodes.length} anchoring nodes in the graph, ignoring the rest"
+        end
+      end
+    else
+      raise "Unable to find all anchor reads from the assembly, cannot continue. This is probably an error with this script, not you. Probes not found: #{finishm_graph.missing_probe_indices.inspect}"
+    end
+
+    if options[:post_assembly_coverage_cutoff]
+      log.info "Removing nodes with coverage < #{options[:post_assembly_coverage_cutoff] } from graph.."
+      original_num_nodes = graph.nodes.length
+      original_num_arcs = graph.arcs.length
+      filter = Bio::AssemblyGraphAlgorithms::CoverageBasedGraphFilter.new
+      filter.remove_low_coverage_nodes(graph,
+        options[:post_assembly_coverage_cutoff],
+        :whitelisted_sequences => Set.new(anchor_sequence_ids)
+      )
+      log.info "Removed #{original_num_nodes-graph.nodes.length} nodes and #{original_num_arcs-graph.arcs.length} arcs, leaving #{graph.nodes.length} nodes and #{graph.arcs.length} arcs."
+    end
+
+    if options[:remove_unconnected_nodes]
+      if options[:graph_search_leash_length]
+        log.info "Removing nodes unconnected to probe nodes from the graph using leash #{options[:graph_search_leash_length] }.."
+      else
+        log.info "Removing nodes unconnected to probe nodes from the graph without using a leash.."
+      end
+      original_num_nodes = graph.nodes.length
+      original_num_arcs = graph.arcs.length
+      filter = Bio::AssemblyGraphAlgorithms::ConnectivityBasedGraphFilter.new
+      filter.remove_unconnected_nodes(
+        graph,
+        finishm_graph.probe_nodes.reject{|n| n.nil?},
+        :leash_length => options[:graph_search_leash_length]
+        )
+      log.info "Removed #{original_num_nodes-graph.nodes.length} nodes and #{original_num_arcs-graph.arcs.length} arcs, leaving #{graph.nodes.length} nodes and #{graph.arcs.length} arcs."
+    end
+
+    return finishm_graph
+  end
+
+  # Read in the reads from a velvet result
+  def parse_velvet_binary_reads(velvet_result_directory)
+    sequences_file_path = File.join velvet_result_directory, 'CnyUnifiedSeq'
+    log.info "Reading in the actual sequences of all reads from #{sequences_file_path}"
+    sequences = Bio::Velvet::Underground::BinarySequenceStore.new sequences_file_path
+    log.info "Read in #{sequences.length} sequences"
+    return sequences
+  end
+
+  # When re-using an assembly, sometimes need to make
+  # sure that the probe sequences used previously are the same
+  # as what is given this time. Given am Array of probe sequences
+  # and a binary_sequence_file, check the probe sequences are the
+  # consistent.
+  def check_probe_sequences(probe_sequences, sequence_store)
+    return true if probe_sequences.nil?
+
+    probe_sequences.each_with_index do |probe, i|
+      log.debug "Checking probe sequence \##{i+1}" if log.debug?
+      if sequence_store[i+1].upcase != probe.upcase
+        log.error "Probe sequence \##{i+1} has changed - perhaps the wrong velvet assembly directory was specified, or a fresh assembly is required?"
+        return false
+      end
+    end
+    log.debug "Presence of #{probe_sequences.length} probe sequences verified"
+    return true
+  end
+end

data/lib/assembly/height_finder.rb

@@ -0,0 +1,355 @@
+require 'ds'
+require 'set'
+
+class Bio::AssemblyGraphAlgorithms::HeightFinder
+  include Bio::FinishM::Logging
+
+  # visit nodes in range and determine heights
+  def traverse(graph, initial_nodes, options={})
+    by_height = []
+    traversal_nodes = {}
+    cycles = {}
+    nodes_in_retrace_phase = Set.new
+
+    # depth-first so stack
+    stack = DS::Stack.new
+    initial_nodes.each do |onode|
+      next if options[:range] and options[:range].none?{|other| other == onode.node }
+      traversal_node = CyclicTraversalNode.new
+      traversal_node.onode = options[:reverse] ? onode.reverse : onode
+      traversal_node.nodes_in = []
+      traversal_nodes[traversal_node.onode.to_settable] = traversal_node
+      stack.push traversal_node
+    end
+
+    while traversal_node = stack.pop
+      settable = traversal_node.onode.to_settable
+      describe = nil
+
+      if log.debug?
+        log.debug "visiting #{traversal_node.describe}."
+      end
+
+      # Consider node solved if height is known.
+      if not traversal_node.height.nil?
+        log.debug "Height of #{traversal_node.describe} is known. Skip." if log.debug?
+        next
+      end
+
+      # find neighbours
+      neighbours = traversal_node.nodes_out
+      if neighbours.nil?
+        neighbours = traversal_node.onode.next_neighbours(graph)
+        if options[:range]
+          neighbours.reject!{|onode| options[:range].none?{|other| other == onode.node}} #not in defined range
+        end
+
+        # Get or create traversal version of node
+        neighbours = neighbours.collect do |onode|
+          nbr_settable = onode.to_settable
+          traversal_nbr = traversal_nodes[nbr_settable]
+          if traversal_nbr.nil?
+            traversal_nbr = CyclicTraversalNode.new
+            traversal_nbr.onode = onode
+            traversal_nbr.nodes_in = []
+            traversal_nodes[nbr_settable] = traversal_nbr
+          end
+          traversal_nbr
+        end
+
+        #remember neighbours
+        traversal_node.nodes_out = neighbours
+      end
+
+
+      # Can we solve the node?
+      if neighbours.empty? #check for a tip
+        log.debug "#{traversal_node.describe} is a tip." if log.debug?
+        traversal_node.height = 0
+        if by_height[0].nil?
+          by_height[0] = [traversal_node]
+        else
+          by_height[0].push(traversal_node)
+        end
+        log.debug "Found height '0' for #{traversal_node.describe}." if log.debug?
+        next
+      end
+
+      if nodes_in_retrace_phase.include? settable
+        log.debug "Retracing back to #{traversal_node.describe}." if log.debug?
+
+        # Neighbours should have been explored
+        # Are neighbours involved in cycles?
+        cyclic_neighbours = neighbours.reject{|node| node.cycles.nil?}
+        if not cyclic_neighbours.empty?
+          # current node is in a cycle if a neighbour is in an unclosed cycle
+          log.debug "Found cyclic neighbours #{cyclic_neighbours.collect{|node| node.describe}.join(',')}." if log.debug?
+          cyclic_neighbours.each do |node|
+            node.cycles.each do |cycle|
+              log.debug "Merging cycle #{cycle.onodes.collect{|onode| onode.to_shorthand}.join(',')}." if log.debug?
+              new_cycle = traversal_node.merge_unclosed_cycle cycle.copy
+              if not new_cycle.nil? and new_cycle.closed?
+                log.debug "Cycle completes at #{traversal_node.describe}."
+                new_cycle_key = new_cycle.to_settable
+                if cycles.has_key? new_cycle_key
+                  log.debug "Already seen this cycle." if log.debug?
+                else
+                  cycles[new_cycle_key] = new_cycle.onodes
+                end
+              end
+            end
+          end
+        end
+
+        # Unsolved neighbours imply a closed cyclic path.
+        # Are neighbours unsolved?
+        solved_neighbours = neighbours.reject{|node| node.height.nil?}
+        unless solved_neighbours.empty?
+          log.debug "We know the heights of neighbours #{solved_neighbours.collect{|node| node.describe}.join(',')}." if log.debug?
+          # Compute height from solved neighbours
+          height = solved_neighbours.map{|node| node.height}.max + 1
+          log.debug "Found height '#{height}' for #{traversal_node.describe}." if log.debug?
+          traversal_node.height = height
+          if by_height[height].nil?
+            by_height[height] = [traversal_node]
+          else
+            by_height[height].push(traversal_node)
+          end
+        end
+        # If no solved neighbours, leave unsolved
+
+        # Move out of retrace phase
+        nodes_in_retrace_phase.delete settable
+        log.debug "Finished retracing #{traversal_node.describe}." if log.debug?
+        next
+      end
+
+      # Move current node to retrace phase, before checking for retracing neighbours in case is own neighbour
+      nodes_in_retrace_phase << settable
+
+      # Look for currently retracing neighbours and initiate cycles
+      retracing_neighbours = neighbours.select{|node| nodes_in_retrace_phase.include? node.onode.to_settable}
+      if not retracing_neighbours.empty?
+        log.debug "Initiating cycles for neighbours #{retracing_neighbours.collect{|node| node.describe}.join(',')} currently retracing." if log.debug?
+        # initiate cycles for each retracing neighbour
+        retracing_neighbours.each{|node| traversal_node.initiate_cycle(node.onode)}
+      end
+
+      # Return node stack and push neighbours
+      stack.push traversal_node
+      log.debug "Pushing #{traversal_node.describe} in retrace mode." if log.debug?
+      neighbours.each do |node|
+        node_settable = node.onode.to_settable
+
+        # Note the parent of neighbour unless already known
+        nodes_in = node.nodes_in
+        if not nodes_in.any?{|nbr| nbr.onode == node.onode}
+          nodes_in.push traversal_node
+        end
+
+        if nodes_in_retrace_phase.include? node_settable
+          # A currently retracing neighbour implies a cycle, cut it off here
+          log.debug "Neighbour #{node.describe} is retracing. Not revisiting." if log.debug?
+        else
+          log.debug "Pushing neighbour #{node.describe}." if log.debug?
+          stack.push node
+        end
+      end
+    end
+    return by_height, cycles.values
+  end
+
+  class TraversalNode
+    attr_accessor :onode, :height, :nodes_in, :nodes_out
+
+    def describe
+      @onode.to_shorthand
+    end
+
+    def node_id
+      @onode.node_id
+    end
+  end
+
+  class CyclicTraversalNode < TraversalNode
+    attr_accessor :cycles
+
+    def initiate_cycle(onode)
+      cycle = CyclePath.new
+      cycle.onodes = [onode]
+      merge_unclosed_cycle cycle
+    end
+
+    def merge_unclosed_cycle(cycle)
+      return if cycle.closed?
+      if cycle.onodes.last == @onode
+        cycle.closed = true
+      else
+        cycle.onodes.unshift @onode
+      end
+      if @cycles.nil?
+        @cycles = [cycle]
+      else
+        @cycles.push(cycle)
+      end
+      return cycle
+    end
+
+    class CyclePath
+      attr_accessor :onodes, :closed
+
+      def closed?
+        return @closed == true
+      end
+
+      def copy
+        cycle = CyclePath.new
+        cycle.onodes = @onodes[0..-1]
+        cycle.closed = @closed
+        cycle
+      end
+
+      def to_settable
+        # return sorted list of onode settables
+        @onodes.collect{|onode| onode.to_settable}.sort do |a, b|
+          result = a[0] <=> b[0]
+          if result == 0
+            result = a[1] == Bio::Velvet::Graph::OrientedNodeTrail::OrientedNode::START_IS_FIRST ? -1 : 1
+          end
+          result
+        end
+      end
+    end
+  end
+
+
+  # maximum paths
+  def max_paths_through(by_height)
+    max_paths_from = {}
+    by_height.each_with_index do |nodes, level|
+      log.debug "At height #{level}." if log.debug?
+      if level == 0  # tips
+        nodes.each do |node|
+          log.debug "Counted maximum of 1 path to #{node.describe}." if log.debug?
+          max_paths_from[node.onode.to_settable] = 1
+        end
+        next
+      end
+
+      nodes.each do |node|
+        settable = node.onode.to_settable
+        max_paths_from_neighbours = node.nodes_out.collect{|nbr| max_paths_from[nbr.onode.to_settable]}.reject{|n| n.nil?}
+        log.debug "Found neighbours of #{node.describe} with maximum paths #{max_paths_from_neighbours.join(',')}." if log.debug?
+        max_paths_from[settable] = max_paths_from_neighbours.reduce{|memo, num| memo+num}
+        log.debug "Counted maximum of #{max_paths_from[settable]} paths to #{node.describe}." if log.debug?
+      end
+    end
+
+    # Get the graph roots (which are nodes with no parents) and add max_paths_from for each to get graph total
+    root_keys = by_height.flatten.select{|node| node.nodes_in.empty? }.collect{|node| node.onode.to_settable}
+    log.debug "Found graph roots #{root_keys.collect{|settable| settable[0]}.join(',')} with maximum paths #{root_keys.collect{|key| max_paths_from[key]}.join(',')}." if log.debug?
+    max_paths = root_keys.map{|settable| max_paths_from[settable]}.reduce{|memo, num| memo+num}
+    log.debug "Counted maximum of #{max_paths} through graph." if log.debug?
+    return max_paths
+  end
+
+  # minimum paths
+  def min_paths_through(by_height)
+    live_nodes = Set.new
+    max_alive_counter = 0
+    by_height.each_with_index do |nodes, level|
+      log.debug "At height #{level}." if log.debug?
+      # nodes at current level become live
+      nodes.each do |node|
+        settable = node.onode.to_settable
+        log.debug "Setting #{node.describe} as live." if log.debug?
+        live_nodes << settable
+      end
+      if level > 0
+        #children of nodes at current level are no longer live
+        nodes.each do |node|
+          children = node.nodes_out
+          children.each do |nbr|
+            log.debug "Setting child #{nbr.describe} of live node #{node.describe} as inactive." if log.debug?
+            live_nodes.delete(nbr.onode.to_settable)
+          end
+        end
+      end
+
+      log.debug "There are currently #{live_nodes.length} nodes alive. Max is #{max_alive_counter}." if log.debug?
+      if live_nodes.length > max_alive_counter
+        #track the maximum live nodes at any level
+        log.debug "Updating max to #{live_nodes.length}." if log.debug?
+        max_alive_counter = live_nodes.length
+      end
+    end
+    return max_alive_counter
+  end
+
+  def find_oriented_edge_of_range(graph, nodes=nil)
+    nodes ||= graph.nodes
+    log.debug "Looking for oriented start and end points from #{nodes.collect{|n| n.node_id}.join(',')}" if log.debug?
+    nodes_all_directions = nodes.collect{|node| [[node, true], [node, false]]}.flatten(1)
+
+
+    # Find nodes and directions which are not reachable from other nodes within range
+    unreached_nodes = {}
+    nodes_all_directions.each do |node_and_direction|
+      onode = Bio::Velvet::Graph::OrientedNodeTrail::OrientedNode.new node_and_direction[0], node_and_direction[1]
+      unless unreached_nodes.has_key? onode.to_settable
+        unreached_nodes[onode.to_settable] = onode
+      end
+      onode.next_neighbours(graph).each do |oneigh|
+        unreached_nodes[oneigh.to_settable] = nil
+      end
+    end
+
+    entry_points = unreached_nodes.values.reject{|n| n.nil?}
+    log.debug "Found the following nodes for a particular orientation have no paths connecting to other nodes in range: #{entry_points.collect{|n| n.to_shorthand}.join(',')}" if log.debug?
+
+    # Start from an unreachable node, and trace all paths until the reverse end of other unreachable nodes
+    # are reached, which are then defined as 'end' nodes. When finished, choose a remaining non-end unreachable
+    # node and repeat, stopping paths if an already seen node is encountered.
+    seen_nodes = Set.new
+    start_onodes = []
+    end_onodes = []
+    stack = DS::Stack.new
+    entry_points.reverse.each do |onode|
+      stack.push onode
+    end
+
+    while current_node = stack.pop
+      log.debug "At node #{current_node.to_shorthand}" if log.debug?
+
+      node_id = current_node.node_id
+      if seen_nodes.include? node_id or not nodes.include? current_node.node
+        log.debug "Node has been seen or is out of range. Skipping..." if log.debug?
+        next
+      end
+      seen_nodes << node_id
+
+      current_unreached = unreached_nodes[current_node.to_settable]
+      log.debug "Is current unreached? #{current_unreached}" if log.debug?
+      if current_unreached
+        log.debug "Defining starting node #{current_unreached.to_shorthand}" if log.debug?
+        # Found start node
+        start_onodes.push current_unreached
+      else
+        reverse_unreached = unreached_nodes[current_node.reverse.to_settable]
+        log.debug "Is reverse unreached? #{reverse_unreached}" if log.debug?
+        if reverse_unreached
+          log.debug "Found ending node #{reverse_unreached.to_shorthand}" if log.debug?
+          # Found end node
+          end_onodes.push reverse_unreached
+        end
+      end
+
+      current_node.next_neighbours(graph).each do |onode|
+        log.debug "Adding neighbour #{onode.to_shorthand} to stack" if log.debug?
+        stack.push onode
+      end
+    end
+
+    return start_onodes, end_onodes
+  end
+end