rgfa 1.2.1

data/lib/rgfa/sequence.rb

@@ -0,0 +1,65 @@
+#
+# Extensions of the String class to handle nucleotidic sequences
+#
+module RGFA::Sequence
+
+  # Computes the reverse complement of a nucleotidic sequence
+  #
+  # @return [String] reverse complement, without newlines and spaces
+  # @return [String] "*" if string is "*"
+  #
+  # @param tolerant [Boolean] <i>(defaults to: +false+)</i>
+  #   if true, anything non-sequence is complemented to itself
+  # @param rnasequence [Boolean] <i>(defaults to: +false+)</i>
+  #   if true, any A and a is complemented into u and U; otherwise
+  #   it is so, only if an U is found; otherwise DNA is assumed
+  #
+  # @raise [RuntimeError] if not +tolerant+ and chars are found for which
+  #   no Watson-Crick complement is defined
+  # @raise [RuntimeError] if sequence contains both U and T
+  #
+  # @example
+  #  "ACTG".rc  # => "CAGT"
+  #  "acGT".rc  # => "ACgt"
+  # @example Undefined sequence is represented by "*":
+  #  "*".rc     # => "*"
+  # @example Extended IUPAC Alphabet:
+  #  "ARBN".rc  # => "NVYT"
+  # @example Usage with RNA sequences:
+  #  "ACUG".rc                    # => "CAGU"
+  #  "ACG".rc(rnasequence: true)  # => "CGU"
+  #  "ACUT".rc                    # (raises RuntimeError, both U and T)
+  def rc(tolerant: false, rnasequence: false)
+    return "*" if self == "*"
+    retval = each_char.map do |c|
+      if c == "U" or c == "u"
+        rnasequence = true
+      elsif rnasequence and (c == "T" or c == "t")
+        raise "String contains both U/u and T/t"
+      end
+      wcc = WCC.fetch(c, tolerant ? c : nil)
+      raise "#{self}: no Watson-Crick complement for #{c}" if wcc.nil?
+      wcc
+    end.reverse.join
+    if rnasequence
+      retval.tr!("tT","uU")
+    end
+    retval
+  end
+
+  # Watson-Crick Complements
+  WCC = {"a"=>"t","t"=>"a","A"=>"T","T"=>"A",
+         "c"=>"g","g"=>"c","C"=>"G","G"=>"C",
+         "b"=>"v","B"=>"V","v"=>"b","V"=>"B",
+         "h"=>"d","H"=>"D","d"=>"h","D"=>"H",
+         "R"=>"Y","Y"=>"R","r"=>"y","y"=>"r",
+         "K"=>"M","M"=>"K","k"=>"m","m"=>"k",
+         "S"=>"S","s"=>"s","w"=>"w","W"=>"W",
+         "n"=>"n","N"=>"N","u"=>"a","U"=>"A",
+         "-"=>"-","."=>".","="=>"=",
+         " "=>"","\n"=>""}
+end
+
+class String
+  include RGFA::Sequence
+end

data/lib/rgfatools.rb

@@ -0,0 +1,102 @@
+require "rgfa"
+
+#
+# Module defining additional methods for the RGFA class.
+#
+# RGFATools is an extension to the RGFA library, which allow to perform further
+# operations. Thereby additional conventions are required, with respect to the
+# GFA specification, which are compatible with it.
+#
+# The methods defined here allow, e.g., to randomly orient a segment which has
+# the same connections on both sides, to compute copy numbers and multiply or
+# delete segments according to them, to distribute the links of copies after
+# multipling a segment, or to eliminate edges in the graph which are
+# incompatible with an hamiltonian path.
+#
+# Custom optional fields are defined, such as "cn" for the copy number of a
+# segment, "or" for the original segment(s) of a duplicated or merged segment,
+# "mp" for the starting position of original segments in a merged segment, "rp"
+# for the position of possible inversions due to arbitrary orientation of some
+# segments by the program.
+#
+# Furthermore a convention for the naming of the segments is introduced, which
+# gives a special meaning to the characters "_^()".
+#
+# @developer
+#   In the main file is only the method redefinition infrastructure
+#   (private methods). The public methods are in the included modules.
+#
+module RGFATools
+end
+
+require_relative "rgfatools/artifacts"
+require_relative "rgfatools/copy_number"
+require_relative "rgfatools/invertible_segments"
+require_relative "rgfatools/multiplication"
+require_relative "rgfatools/superfluous_links"
+require_relative "rgfatools/linear_paths"
+require_relative "rgfatools/p_bubbles"
+
+module RGFATools
+
+  include RGFATools::Artifacts
+  include RGFATools::CopyNumber
+  include RGFATools::InvertibleSegments
+  include RGFATools::Multiplication
+  include RGFATools::SuperfluousLinks
+  include RGFATools::LinearPaths
+  include RGFATools::PBubbles
+
+  private
+
+  def self.included(klass)
+    included_modules.each do |included_module|
+      if included_module.const_defined?("Redefined")
+        self.redefine_methods(included_module::Redefined, klass)
+      end
+      if included_module.const_defined?("ClassMethods")
+        klass.extend(included_module::ClassMethods)
+      end
+    end
+  end
+
+  def self.redefine_methods(redefined_methods, klass)
+    klass.class_eval do
+      redefined_methods.each do |redefined_method|
+        was_private = klass.private_instance_methods.include?(redefined_method)
+        public redefined_method
+        alias_method :"#{redefined_method}_without_rgfatools", redefined_method
+        alias_method redefined_method, :"#{redefined_method}_with_rgfatools"
+        if was_private
+          private redefined_method,
+                  :"#{redefined_method}_without_rgfatools",
+                  :"#{redefined_method}_with_rgfatools"
+        end
+      end
+    end
+  end
+
+  ProgramName = "RGFATools"
+
+  def add_program_name_to_header
+    set_header_field(:pn, RGFATools::ProgramName)
+  end
+
+end
+
+class RGFA
+  include RGFATools
+
+  # Enable {RGFATools} extensions of RGFA methods
+  # @return [void]
+  def enable_extensions
+    @extensions_enabled = true
+  end
+
+  # Disable {RGFATools} extensions of RGFA methods
+  # @return [void]
+  def disable_extensions
+    @extensions_enabled = false
+  end
+
+end

data/lib/rgfatools/artifacts.rb

@@ -0,0 +1,29 @@
+#
+# Methods which edit the graph components without traversal
+#
+module RGFATools::Artifacts
+
+  # Remove connected components whose sum of lengths of the segments
+  # is under a specified value.
+  # @param minlen [Integer] the minimum length
+  # @return [RGFA] self
+  def remove_small_components(minlen)
+    rm(connected_components.select {|cc|
+      cc.map{|sn|segment(sn).length}.reduce(:+) < minlen })
+    self
+  end
+
+  # Remove end segments, whose sequence length is under a specified value.
+  # @param minlen [Integer] the minimum length
+  # @return [RGFA] self
+  def remove_dead_ends(minlen)
+    segments.each do |s|
+      c = connectivity(s)
+      rm(s) if s.length < minlen and
+        (c[0] == 0 or c[1] == 0) and
+          !cut_segment?(s)
+    end
+    self
+  end
+
+end

data/lib/rgfatools/copy_number.rb

@@ -0,0 +1,126 @@
+#
+# Methods which edit the graph components without traversal
+#
+module RGFATools::CopyNumber
+
+  # Sets the count tag to use as default by coverage computations
+  # <i>(defaults to: +:RC+)</i>.
+  #
+  # @return [RGFA] self
+  # @param tag [Symbol] the tag to use
+  def set_default_count_tag(tag)
+    @default[:count_tag] = tag
+    return self
+  end
+
+  # Sets the unit length (k-mer size, average read lenght or average fragment
+  # length) to use for coverage computation
+  # <i>(defaults to: 1)</i>.
+  #
+  # @param unit_length [Integer] the unit length to use
+  # @return [RGFA] self
+  def set_count_unit_length(unit_length)
+    @default[:unit_length] = unit_length
+    return self
+  end
+
+  # Delete segments which have a coverage under a specified value.
+  #
+  # @param mincov [Integer] the minimum coverage
+  # @!macro [new] count_tag
+  #   @param count_tag [Symbol] <i>(defaults to: +:RC+ or the value set by
+  #     {#set_default_count_tag})</i> the count tag to use for coverage
+  #     computation
+  # @!macro [new] unit_length
+  #   @param unit_length [Integer] <i>(defaults to: 1 or the value set by
+  #     {#set_count_unit_length})</i> the unit length to use for coverage
+  #     computation
+  #
+  # @return [RGFA] self
+  def delete_low_coverage_segments(mincov,
+                                   count_tag: @default[:count_tag],
+                                   unit_length: @default[:unit_length])
+    segments.map do |s|
+      cov = s.coverage(count_tag: count_tag,
+                       unit_length: unit_length)
+      cov < mincov ? s.name : nil
+    end.compact.each do |sn|
+      delete_segment(sn)
+    end
+    self
+  end
+
+  # @param mincov [Integer] <i>(defaults to: 1/4 of +single_copy_coverage+)</i>
+  #   the minimum coverage, cn for segments under this value is set to 0
+  # @param single_copy_coverage [Integer]
+  #   the coverage that shall be considered to be single copy
+  # @param cn_tag [Symbol] <i>(defaults to: +:cn+)</i>
+  #   the tag to use for storing the copy number
+  # @!macro count_tag
+  # @!macro unit_length
+  # @return [RGFA] self
+  def compute_copy_numbers(single_copy_coverage,
+                           mincov: single_copy_coverage * 0.25,
+                           count_tag: @default[:count_tag],
+                           cn_tag: :cn,
+                           unit_length: @default[:unit_length])
+    segments.each do |s|
+      cov = s.coverage!(count_tag: count_tag, unit_length: unit_length).to_f
+      if cov < mincov
+        cn = 0
+      elsif cov < single_copy_coverage
+        cn = 1
+      else
+        cn = (cov / single_copy_coverage).round
+      end
+      s.set(cn_tag, cn)
+    end
+    self
+  end
+
+  # Applies the computed copy number to a segment
+  # @!macro [new] apply_copy_number
+  #   @return [RGFA] self
+  #   @param [:lowcase, :upcase, :number, :copy] copy_names_suffix
+  #     <i>(Defaults to: +:lowcase+)</i>
+  #     Symbol representing a system to compute the names from the name of
+  #     the original segment. See "Automatic computation of the copy names"
+  #     in #multiply_extended.
+  #   @param count_tag [Symbol] tag to use for storing the copy number
+  #     (default: cn)
+  #   @param distribute [Symbol] distribution policy, see #multiply_extended
+  #   @param origin_tag [Symbol] tag to use for storing the origin (default: or)
+  #   @param conserve_components [Boolean] when factor is 0,
+  #     do not remove segments if doing so increases the number of components
+  #     in the graph (default: true)
+  # @param segment [RGFA::Line::Segment, Symbol] segment or segment name
+  def apply_copy_number(segment, count_tag: :cn,
+                        distribute: :auto,
+                        copy_names_suffix: :lowcase, origin_tag: :or,
+                        conserve_components: true)
+    s, sn = segment_and_segment_name(segment)
+    factor = s.get!(count_tag)
+    multiply_extended(sn, factor,
+             distribute: distribute,
+             copy_names: copy_names_suffix,
+             conserve_components: conserve_components,
+             origin_tag: origin_tag)
+    self
+  end
+
+  # Applies the computed copy number to all segments
+  # @!macro apply_copy_number
+  def apply_copy_numbers(count_tag: :cn, distribute: :auto,
+                         copy_names_suffix: :lowcase, origin_tag: :or,
+                         conserve_components: true)
+    segments.sort_by{|s|s.get!(count_tag)}.each do |s|
+      multiply_extended(s.name, s.get(count_tag),
+               distribute: distribute,
+               copy_names: copy_names_suffix,
+               conserve_components: conserve_components,
+               origin_tag: origin_tag)
+    end
+    self
+  end
+
+end

data/lib/rgfatools/invertible_segments.rb

@@ -0,0 +1,104 @@
+#
+# Methods which edit the graph components without traversal
+#
+module RGFATools::InvertibleSegments
+
+  # Selects a random orientation for all invertible segments
+  # @return [RGFA] self
+  def randomly_orient_invertibles
+    segment_names.each do |sn|
+      if segment_same_links_both_ends?(sn)
+        randomly_orient_proven_invertible_segment(sn)
+      end
+    end
+    self
+  end
+
+  # Selects a random orientation for an invertible segment
+  # @return [RGFA] self
+  # @!macro segment_param
+  def randomly_orient_invertible(segment)
+    segment_name = segment.kind_of?(RGFA::Line) ? segment.name : segment
+    if !segment_same_links_both_ends?(segment_name)
+      raise "Only segments with links to the same or equivalent segments "+
+              "at both ends can be randomly oriented"
+    end
+    randomly_orient_proven_invertible_segment(segment_name)
+    self
+  end
+
+  private
+
+  def randomly_orient_proven_invertible_segment(segment_name)
+    parts = partitioned_links_of([segment_name, :E])
+    if parts.size == 2
+      tokeep1_other_end = parts[0][0].other_end([segment_name, :E])
+      tokeep2_other_end = parts[1][0].other_end([segment_name, :E])
+    elsif parts.size == 1 and parts[0].size == 2
+      tokeep1_other_end = parts[0][0].other_end([segment_name, :E])
+      tokeep2_other_end = parts[0][1].other_end([segment_name, :E])
+    else
+      return
+    end
+    return if links_of(tokeep1_other_end).size < 2
+    return if links_of(tokeep2_other_end).size < 2
+    delete_other_links([segment_name, :E], tokeep1_other_end)
+    delete_other_links([segment_name, :B], tokeep2_other_end)
+    annotate_random_orientation(segment_name)
+  end
+
+  def link_targets_for_cmp(segment_end)
+    links_of(segment_end).map {|l| l.other_end(segment_end).join}
+  end
+
+  def segment_same_links_both_ends?(segment_name)
+    e_links = link_targets_for_cmp([segment_name, :E])
+    b_links = link_targets_for_cmp([segment_name, :B])
+    return e_links == b_links
+  end
+
+  def segment_signature(segment_end)
+    s = segment!(segment_end[0])
+    link_targets_for_cmp(segment_end).join(",")+"\t"+
+    link_targets_for_cmp(segment_end.invert_end_type).join(",")+"\t"+
+    [:or].map do |field|
+      s.send(field)
+    end.join("\t")
+  end
+
+  def partitioned_links_of(segment_end)
+    links_of(segment_end).group_by do |l|
+      other_end = l.other_end(segment_end)
+      sig = segment_signature(other_end)
+      sig
+    end.map {|sig, par| par}
+  end
+
+  def annotate_random_orientation(segment_name)
+    segment = segment!(segment_name)
+    n = segment.name.to_s.split("_")
+    pairs = 0
+    pos = [1, segment.LN]
+    if segment.or
+      o = segment.or.to_s.split(",")
+      if o.size > 2
+        while o.last == o.first + "^" or o.last + "^" == o.first
+          pairs += 1
+          o.pop
+          o.shift
+        end
+      end
+      if segment.mp
+        pos = [segment.mp[pairs*2], segment.mp[-1-pairs*2]]
+      end
+    end
+    rn = segment.rn
+    rn ||= []
+    rn += pos
+    segment.rn = rn
+    n[pairs] = "(" + n[pairs]
+    n[-1-pairs] = n[-1-pairs] + ")"
+    rename(segment.name, n.join("_"))
+  end
+
+end

data/lib/rgfatools/linear_paths.rb

@@ -0,0 +1,140 @@
+#
+# Methods for the RGFA class, which involve a traversal of the graph following
+# links
+#
+module RGFATools::LinearPaths
+
+  # @!method merge_linear_path(segpath, **options)
+  #   Merge a linear path, i.e. a path of segments without extra-branches.
+  #   @!macro [new] merge_more
+  #     Extends the RGFA method, with additional functionality:
+  #     - +name+: the name of the merged segment is set to the name of the
+  #       single segments joined by underscore (+_+). If a name already
+  #       contained an underscore, it is splitted before merging. Whenever a
+  #       segment is reversed complemented, its name (or the name of all its
+  #       components) is suffixed with a +^+; if the last letter was already
+  #       +^+, it is removed; if it contained +_+ the name is splitted, the
+  #       elements reversed and joined back using +_+; round parentheses are
+  #       removed from the name before processing and added back after it.
+  #     - +:or+: keeps track of the origin of the merged segment; the
+  #       origin tag is set to an array of :or or name
+  #       (if no :or available) tags of the segment which have been merged;
+  #       the character +^+ is assigned the same meaning as in +name+
+  #     - +:rn+: tag used to store possible inversion positions and
+  #       it is updated by this method; i.e. it is passed from the single
+  #       segments to the merged segment, and the coordinates updated
+  #     - +:mp+: tag used to store the position of the
+  #       single segments in the merged segment; it is created or updated by
+  #       this method
+  #     Note that the extensions to the original method will only be run
+  #     if either #enable_extensions has been called on RGFA object
+  #     or the enable_tracking parameter is set..
+  #     After calling #enable_extensions, you may still obtain the original
+  #     behaviour by setting the disable_tracking parameter.
+  #   @!macro merge_more
+  #
+  #   @!macro [new] merge_lim
+  #
+  #     Limitations: all containments und paths involving merged segments are
+  #     deleted.
+  #   @!macro merge_lim
+  #
+  #   @param segpath [Array<RGFA::SegmentEnd>] a linear path, such as that
+  #     retrieved by #linear_path (see RGFA API documentation)
+  #   @!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|
+  #     @option options [Boolean] :enable_tracking (false)
+  #       if true, the extended method with RGFATools is called,
+  #       no matter if RGFA#enable_extensions was called.
+  #     @option options [Boolean] :disable_tracking (false)
+  #       if true, the original method of RGFA without RGFATools is called,
+  #       no matter if RGFA#enable_extensions was called.
+  #   @!macro merge_options
+  #
+  #   @return [RGFA] self
+  #   @see #merge_linear_paths
+
+  # @!method merge_linear_paths(**options)
+  #   Merge all linear paths in the graph, i.e.
+  #   paths of segments without extra-branches
+  #   @!macro merge_more
+  #   @!macro merge_lim
+  #   @!macro merge_options
+  #
+  #   @return [RGFA] self
+
+  private
+
+  Redefined = [:add_segment_to_merged]
+
+  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_with_rgfatools(merged, segment, reversed, cut, init,
+                                          options)
+    if !options[:enable_tracking] and
+        (options[:disable_tracking] or !@extensions_enabled)
+      return add_segment_to_merged_without_rgfatools(merged, segment, reversed,
+                                                    cut, init, options)
+    end
+    s = (reversed ? segment.sequence.rc[cut..-1] : segment.sequence[cut..-1])
+    n = (reversed ? reverse_segment_name(segment.name, "_") : segment.name.to_s)
+    rn = (reversed ? reverse_pos_array(segment.rn, segment.LN) : segment.rn)
+    mp = (reversed ? reverse_pos_array(segment.mp, segment.LN) : segment.mp)
+    mp = [1, segment.LN] if mp.nil? and segment.LN
+    if segment.or.nil?
+      o = n
+    else
+      o = (reversed ? reverse_segment_name(segment.or, ",") : segment.or)
+    end
+    if init
+      merged.sequence = s
+      merged.name = options[:merged_name].nil? ? n : options[:merged_name]
+      merged.LN = segment.LN
+      merged.rn = rn
+      merged.or = o
+      merged.mp = mp
+    else
+      (segment.sequence == "*") ? (merged.sequence = "*")
+                                : (merged.sequence += s)
+      merged.name = "#{merged.name}_#{n}" if options[:merged_name].nil?
+      if merged.LN
+        if rn
+          rn = rn.map {|pos| pos - cut + merged.LN}
+          merged.rn = merged.rn.nil? ? rn : merged.rn + rn
+        end
+        if mp and merged.mp
+          merged.mp += mp.map {|pos| pos - cut + merged.LN}
+        end
+        segment.LN ? merged.LN += (segment.LN - cut)
+                   : merged.LN = nil
+      else
+        merged.mp = nil
+      end
+      merged.or = merged.or.nil? ? o : "#{merged.or},#{o}"
+    end
+  end
+
+end