rgfa 1.2.1

data/lib/rgfa/line/path.rb

@@ -0,0 +1,106 @@
+# A path line of a RGFA file
+class RGFA::Line::Path < RGFA::Line
+
+  RECORD_TYPE = :P
+  REQFIELDS = [:path_name, :segment_names, :cigars]
+  PREDEFINED_OPTFIELDS = []
+  DATATYPE = {
+    :path_name => :lbl,
+    :segment_names => :lbs,
+    :cigars => :cgs,
+  }
+
+  define_field_methods!
+
+  # @note The field names are derived from the RGFA specification at:
+  #   https://github.com/pmelsted/RGFA-spec/blob/master/RGFA-spec.md#path-line
+  #   and were made all downcase with _ separating words;
+  #   the cigar and segment_name regexps and name were changed to better
+  #   implement what written in the commentaries of the specification
+  #   (i.e. name pluralized and regexp changed to a comma-separated list
+  #   for segment_name of segment names and orientations and for cigar of
+  #   CIGAR strings);
+
+  # @return [Symbol] name of the path as symbol
+  def to_sym
+    name.to_sym
+  end
+
+  # Is the path circular? In this case the number of CIGARs must be
+  # equal to the number of segments.
+  # @return [Boolean]
+  def circular?
+    self.cigars.size == self.segment_names.size
+  end
+
+  # Is the path linear? This is the case when the number of CIGARs
+  # is equal to the number of segments minus 1, or the CIGARs are
+  # represented by a single "*".
+  def linear?
+    !circular?
+  end
+
+  # Are the cigars a single "*"? This is a compact representation of
+  # a linear path where all CIGARs are "*"
+  # @return [Boolean]
+  def undef_cigars?
+    self.cigars.size == 1 and self.cigars[0].empty?
+  end
+
+  # The links to which the path refers; it can be an empty array
+  # (e.g. from a line which is not embedded in a graph);
+  # the boolean is true if the equivalent reverse link is used.
+  # @return [Array<RGFA::Line::Link, Boolean>]
+  def links
+    @links ||= []
+    @links
+  end
+
+  # computes the list of links which are required to support
+  # the path
+  # @return [Array<[RGFA::OrientedSegment, RGFA::OrientedSegment, RGFA::Cigar]>]
+  #   an array, which elements are 3-tuples (from oriented segment,
+  #   to oriented segment, cigar)
+  def required_links
+    has_undef_cigars = self.undef_cigars?
+    retval = []
+    self.segment_names.size.times do |i|
+      j = i+1
+      if j == self.segment_names.size
+        circular? ? j = 0 : break
+      end
+      cigar = has_undef_cigars ? [] : self.cigars[i]
+      retval << [self.segment_names[i], self.segment_names[j], cigar]
+    end
+    retval
+  end
+
+  private
+
+  def validate_lists_size!
+    n_cigars = self.cigars.size
+    n_segments = self.segment_names.size
+    if n_cigars == n_segments - 1
+      # case 1: linear path
+      return true
+    elsif n_cigars == 1 and self.cigars[0].empty?
+      # case 2: linear path, single "*" to represent cigars which are all "*"
+      return true
+    elsif n_cigars == n_segments
+      # case 3: circular path
+    else
+      raise RGFA::Line::Path::ListLengthsError,
+        "Path has #{n_segments} oriented segments, "+
+        "but #{n_cigars} CIGARs"
+    end
+  end
+
+  def validate_record_type_specific_info!
+    validate_lists_size!
+  end
+
+
+end
+
+# Error raised if number of segments and cigars are not consistent
+class RGFA::Line::Path::ListLengthsError < RGFA::Error; end

data/lib/rgfa/line/segment.rb

@@ -0,0 +1,209 @@
+# A segment line of a RGFA file
+class RGFA::Line::Segment < RGFA::Line
+
+  RECORD_TYPE = :S
+  REQFIELDS = [:name, :sequence]
+  PREDEFINED_OPTFIELDS = [:LN, :RC, :FC, :KC, :SH, :UR]
+  DATATYPE = {
+    :name => :lbl,
+    :sequence => :seq,
+    :LN => :i,
+    :RC => :i,
+    :FC => :i,
+    :KC => :i,
+    :SH => :H,
+    :UR => :Z
+  }
+
+  define_field_methods!
+
+  attr_writer :links, :containments, :paths
+
+  # References to the links in which the segment is involved.
+  #
+  # @!macro references_table
+  #   The references are in four arrays which are
+  #   accessed from a nested hash table. The first key is
+  #   the direction (from or to), the second is the orientation
+  #   (+ or -).
+  #
+  # @example
+  #   segment.links[:from][:+]
+  #
+  # @return [Hash{RGFA::Line::DIRECTION => Hash{RGFA::Line::ORIENTATION => Array<RGFA::Line::Link>}}]
+  def links
+    @links ||= {:from => {:+ => [], :- => []},
+                :to   => {:+ => [], :- => []}}
+    @links
+  end
+
+  # References to the containments in which the segment is involved.
+  # @!macro references_table
+  #
+  # @example
+  #   segment.containments[:from][:+]
+  #
+  # @return [Hash{RGFA::Line::DIRECTION => Hash{RGFA::Line::ORIENTATION => Array<RGFA::Line::Containment>}}]
+  def containments
+    @containments ||= {:from => {:+ => [], :- => []},
+                       :to   => {:+ => [], :- => []}}
+    @containments
+  end
+
+  # References to the containments in which the segment is involved.
+  #
+  # The references are in two arrays which are
+  # accessed from a hash table. The key is the orientation
+  # (+ or -).
+  #
+  # @example
+  #   segment.paths[:+]
+  #
+  # @return [Hash{RGFA::Line::ORIENTATION => Array<RGFA::Line::Path>}]
+  def paths
+    @paths ||= {:+ => [], :- => []}
+    @paths
+  end
+
+  # All containments where a segment is involved.
+  # @!macro this_is_a_copy
+  #   @note the list shall be considered read-only, as this
+  #     is a copy of the original arrays of references, concatenated
+  #     to each other.
+  def all_containments
+    l = self.containments
+    l[:from][:+] + l[:from][:-] + l[:to][:+] + l[:to][:-]
+  end
+
+  # All links where the segment is involved.
+  # @!macro this_is_a_copy
+  def all_links
+    l = self.links
+    l[:from][:+] + l[:from][:-] + l[:to][:+] + l[:to][:-]
+  end
+
+  # All links and containments where the segment is involved.
+  # @!macro this_is_a_copy
+  def all_connections
+    all_links + all_containments
+  end
+
+  # All paths where the segment is involved.
+  # @!macro this_is_a_copy
+  def all_paths
+    pt = self.paths
+    pt[:+] + pt[:-]
+  end
+
+  # All paths, links and containments where the segment is involved.
+  # @!macro this_is_a_copy
+  def all_references
+    all_connections + all_paths
+  end
+
+  # @raise [RGFA::Line::Segment::InconsistentLengthError]
+  #    if sequence length and LN tag are not consistent.
+  def validate_length!
+    if sequence != "*" and optional_fieldnames.include?(:LN)
+      if self.LN != sequence.length
+        raise RGFA::Line::Segment::InconsistentLengthError,
+          "Length in LN tag (#{self.LN}) "+
+          "is different from length of sequence field (#{sequence.length})"
+      end
+    end
+  end
+
+  # @!macro [new] length
+  #   @return [Integer] value of LN tag, if segment has LN tag
+  #   @return [Integer] sequence length if no LN and sequence not "*"
+  # @return [nil] if sequence is "*"
+  # @see #length!
+  def length
+    if self.LN
+      self.LN
+    elsif sequence != "*"
+      sequence.length
+    else
+      nil
+    end
+  end
+
+  # @!macro length
+  # @!macro [new] length_needed
+  #   @raise [RGFA::Line::Segment::UndefinedLengthError] if not an LN tag and
+  #     the sequence is "*"
+  # @see #length
+  def length!
+    l = self.length()
+    raise RGFA::Line::Segment::UndefinedLengthError,
+      "No length information available" if l.nil?
+    return l
+  end
+
+  # @!macro [new] coverage
+  #   The coverage computed from a count_tag.
+  #   If unit_length is provided then: count/(length-unit_length+1),
+  #   otherwise: count/length.
+  #   The latter is a good approximation if length >>> unit_length.
+  #   @param [Symbol] count_tag <i>(defaults to +:RC+)</i>
+  #     integer tag storing the count, usually :KC, :RC or :FC
+  #   @param [Integer] unit_length the (average) length of a read (for
+  #     :RC), fragment (for :FC) or k-mer (for :KC)
+  #   @return [Integer] coverage, if count_tag and length are defined
+  # @return [nil] otherwise
+  # @see #coverage!
+  def coverage(count_tag: :RC, unit_length: 1)
+    if optional_fieldnames.include?(count_tag) and self.length
+      return (self.get(count_tag).to_f)/(self.length-unit_length+1)
+    else
+      return nil
+    end
+  end
+
+  # @see #coverage
+  # @!macro coverage
+  # @raise [RGFA::Line::TagMissingError] if segment does not have count_tag
+  # @!macro length_needed
+  def coverage!(count_tag: :RC, unit_length: 1)
+    c = coverage(count_tag: count_tag, unit_length: unit_length)
+    if c.nil?
+      self.length!
+      raise RGFA::Line::TagMissingError,
+        "Tag #{count_tag} undefined for segment #{name}"
+    else
+      return c
+    end
+  end
+
+  # @return string representation of the segment
+  # @param [Boolean] without_sequence if +true+, output "*" instead of sequence
+  def to_s(without_sequence: false)
+    if !without_sequence
+      return super()
+    else
+      saved = self.sequence
+      self.sequence = "*"
+      retval = super()
+      self.sequence = saved
+      return retval
+    end
+  end
+
+  # @return [Symbol] name of the segment as symbol
+  def to_sym
+    name.to_sym
+  end
+
+  private
+
+  def validate_record_type_specific_info!
+    validate_length!
+  end
+
+end
+
+# Error raised if length of segment cannot be computed
+class RGFA::Line::Segment::UndefinedLengthError < RGFA::Error; end
+
+# Error raised if length of segment and LN are not consistent
+class RGFA::Line::Segment::InconsistentLengthError < RGFA::Error; end

data/lib/rgfa/linear_paths.rb

@@ -0,0 +1,285 @@
+require_relative "segment_ends_path"
+
+#
+# Methods for the RGFA class, which allow to find and merge linear paths.
+#
+module RGFA::LinearPaths
+
+  require "set"
+
+  #
+  # Find a path without branches.
+  #
+  # The path must
+  # include +segment+ and excludes segments in +exclude+.
+  # Any segment used in the returned path will be added to +exclude+
+  #
+  # @param s [String|RGFA::Line::Segment] a segment name or instance
+  # @param exclude [Set<String>] a set of segment names to exclude from the path
+  # @return [Array<RGFA::SegmentEnd>]
+  #
+  def linear_path(s, exclude = Set.new)
+    s = s.to_sym
+    cs = connectivity(s)
+    segpath = RGFA::SegmentEndsPath.new()
+    [:B, :E].each_with_index do |et, i|
+      if cs[i] == 1
+        exclude << s
+        segpath.pop
+        segpath += traverse_linear_path(RGFA::SegmentEnd.new([s, et]), exclude)
+      end
+    end
+    return (segpath.size < 2) ? nil : segpath
+  end
+
+  # Find all unbranched paths in the graph.
+  #
+  # @return [Array<Array<RGFA::SegmentEnd>>]
+  def linear_paths
+    exclude = Set.new
+    retval = []
+    segnames = segment_names
+    progress_log_init(:linear_paths, "segments", segnames.size,
+      "Detect linear paths (#{segnames.size} segments)")  if @progress
+    segnames.each do |sn|
+      progress_log(:linear_paths) if @progress
+      next if exclude.include?(sn)
+      retval << linear_path(sn, exclude)
+    end
+    progress_log_end(:linear_paths)
+    return retval.compact
+  end
+
+  # Merge a linear path, i.e. a path of segments without extra-branches
+  # @!macro [new] merge_lim
+  #   Limitations: all containments und paths involving merged segments are
+  #   deleted.
+  #
+  # @param segpath [Array<RGFA::SegmentEnd>] a linear path, such as that
+  #   retrieved by {#linear_path}
+  # @!macro [new] merge_options
+  #   @param options [Hash] optional keyword arguments
+  #   @option options [String, :short, nil] :merged_name (nil)
+  #     if nil, the merged_name is automatically computed; if :short,
+  #     a name is computed starting with "merged1" and calling next until
+  #     an available name is founf; if String, the name to use
+  #   @option options [Boolean] :cut_counts (false)
+  #     if true, total count in merged segment m, composed of segments
+  #     s of set S is multiplied by the factor Sum(|s in S|)/|m|
+  #
+  # @return [RGFA] self
+  # @see #merge_linear_paths
+  def merge_linear_path(segpath, **options)
+    return if segpath.size < 2
+    segpath.map!{|se|se.to_segment_end}
+    if segpath[1..-2].any? {|sn,et| connectivity(sn) != [1,1]}
+      raise ArgumentError, "The specified path is not linear"
+    end
+    merged, first_reversed, last_reversed =
+      create_merged_segment(segpath, options)
+    self << merged
+    link_merged(merged.name, segpath.first.to_segment_end.invert_end_type,
+                first_reversed)
+    link_merged(merged.name, segpath.last, last_reversed)
+    segpath.each do |sn_et|
+      delete_segment(sn_et.segment)
+      progress_log(:merge_linear_paths, 0.05) if @progress
+    end
+    self
+  end
+
+  # Merge all linear paths in the graph, i.e.
+  # paths of segments without extra-branches
+  # @!macro merge_lim
+  # @!macro merge_options
+  #
+  # @return [RGFA] self
+  def merge_linear_paths(**options)
+    paths = linear_paths
+    psize = paths.flatten.size / 2
+    progress_log_init(:merge_linear_paths, "segments", psize,
+      "Merge #{paths.size} linear paths (#{psize} segments)") if @progress
+    paths.each do |path|
+      merge_linear_path(path, **options)
+    end
+    progress_log_end(:merge_linear_paths)
+    self
+  end
+
+  private
+
+  # Traverse the links, starting from the segment +from+ :E end if
+  # +traverse_from_E_end+ is true, or :B end otherwise.
+  #
+  # If any segment after +from+ is found whose name is included in +exclude+
+  # the traversing is interrupted. The +exclude+ set is updated, so that
+  # circular paths are avoided.
+  #
+  # *Arguments*:
+  #   - +from+ -> first segment
+  #   - +traverse_from_E_end+ -> if true, start from E end, otherwise from B end
+  #   - +exclude+ -> Set of names of already visited segments
+  #
+  # *Side Effects*:
+  #   - Any element added to the returned list is also added to +exclude+
+  #
+  # *Returns*:
+  #   - An array of segment names of the unbranched path.
+  #     If +from+ is not an element of an unbranched path then [].
+  #     Otherwise the first (and possibly only) element is +from+.
+  #     All elements in the index range 1..-2 are :internal.
+  def traverse_linear_path(segment_end, exclude)
+    list = RGFA::SegmentEndsPath.new()
+    current = segment_end
+    loop do
+      after  = links_of(current)
+      before = links_of(current.to_segment_end.invert_end_type)
+      cs = connectivity_symbols(before.size, after.size)
+      if cs == [1,1] or list.empty?
+        list << current
+        exclude << current.name
+        l = after.first
+        current = l.other_end(current).invert_end_type
+        break if exclude.include?(current.name)
+      elsif cs[0] == 1
+        list << current
+        exclude << current.name
+        break
+      else
+        break
+      end
+    end
+    return segment_end.end_type == :B ? list.reverse : list
+  end
+
+  def sum_of_counts(segpath, multfactor = 1)
+    retval = {}
+    segs = segpath.map {|sn,et|segment!(sn)}
+    [:KC, :RC, :FC].each do |count_tag|
+      segs.each do |s|
+        if s.optional_fieldnames.include?(count_tag)
+          retval[count_tag] ||= 0
+          retval[count_tag] += s.get(count_tag)
+        end
+      end
+      if retval[count_tag]
+        retval[count_tag] = (retval[count_tag] * multfactor).to_i
+      end
+    end
+    return retval
+  end
+
+  def reverse_segment_name(name, separator)
+    name.to_s.split(separator).map do |part|
+      openp = part[0] == "("
+      part = part[1..-1] if openp
+      closep = part[-1] == ")"
+      part = part[0..-2] if closep
+      part = (part[-1] == "^") ? part[0..-2] : part+"^"
+      part += ")" if openp
+      part = "(#{part}" if closep
+      part
+    end.reverse.join(separator)
+  end
+
+  def reverse_pos_array(pos_array, lastpos)
+    return nil if pos_array.nil? or lastpos.nil?
+    pos_array.map {|pos| lastpos - pos + 1}.reverse
+  end
+
+  def add_segment_to_merged(merged, segment, reversed, cut, init, options)
+    s = (reversed ? segment.sequence.rc[cut..-1] : segment.sequence[cut..-1])
+    if init
+      merged.sequence = s
+      merged.name = (options[:merged_name].nil? ?
+                     segment.name : options[:merged_name])
+      merged.LN = segment.LN
+    else
+      (segment.sequence == "*") ? (merged.sequence = "*")
+                                : (merged.sequence += s)
+      if options[:merged_name].nil?
+        merged.name = "#{merged.name}_#{segment.name}"
+      end
+      if merged.LN
+        segment.LN ? merged.LN += (segment.LN - cut)
+                   : merged.LN = nil
+      end
+    end
+  end
+
+  def create_merged_segment(segpath, options)
+    merged = segment!(segpath.first.first).clone
+    total_cut = 0
+    a = segpath.first
+    first_reversed = (a.end_type == :B)
+    last_reversed = nil
+    if options[:merged_name] == :short
+      forbidden = (segment_names + path_names)
+      options[:merged_name] = "merged1"
+      while forbidden.include?(options[:merged_name])
+        options[:merged_name] = options[:merged_name].next
+      end
+    end
+    add_segment_to_merged(merged, segment(a.segment), first_reversed, 0, true,
+                          options)
+    progress_log(:merge_linear_paths, 0.95) if @progress
+    (segpath.size-1).times do |i|
+      b = segpath[i+1].to_segment_end.invert_end_type
+      l = link!(a, b)
+      if l.overlap == []
+        cut = 0
+      elsif l.overlap.all?{|op|[:M, :"="].include?(op.code)}
+        cut = l.overlap.map(&:len).inject(:+)
+      else
+        raise ArgumentError,
+          "Merging is only allowed if all operations are M/="
+      end
+      total_cut += cut
+      last_reversed = (b[1] == :E)
+      add_segment_to_merged(merged, segment(b.segment), last_reversed, cut,
+                            false, options)
+      a = b.to_segment_end.invert_end_type
+      if @progress
+        progress_log(:merge_linear_paths, 0.95)
+      end
+    end
+    if merged.sequence != "*"
+      if merged.LN.nil?
+        merged.LN = merged.sequence.length
+      elsif @validate and merged.LN != merged.sequence.length
+        raise RGFA::Line::Segment::InconsistentLengthError,
+              "Computed sequence length #{merged.sequence.length} "+
+              "and computed LN #{merged.LN} differ"
+      end
+    end
+    if merged.LN.nil?
+      [:KC, :RC, :FC].each {|count_tag| merged.set(count_tag, nil)}
+    else
+      sum_of_counts(segpath, (options[:cut_counts] ?
+                              merged.LN.to_f / (total_cut+merged.LN) : 1)).
+          each do |count_tag, count|
+        merged.set(count_tag, count)
+      end
+    end
+    return merged, first_reversed, last_reversed
+  end
+
+  def link_merged(merged_name, segment_end, reversed)
+    links_of(segment_end).each do |l|
+      l2 = l.clone
+      if l2.to == segment_end.first
+        l2.to = merged_name
+        if reversed
+          l2.to_orient = RGFA::OrientedSegment.invert(l2.to_orient)
+        end
+      else
+        l2.from = merged_name
+        if reversed
+          l2.from_orient = RGFA::OrientedSegment.invert(l2.from_orient)
+        end
+      end
+      self << l2
+    end
+  end
+
+end