rgfa 1.2.1

data/lib/rgfa/lines.rb

@@ -0,0 +1,155 @@
+require_relative "error"
+
+#
+# Methods for the RGFA class, which allow to handle lines of multiple types.
+#
+module RGFA::Lines
+
+  # Add a line to a RGFA
+  #
+  # @overload <<(gfa_line_string)
+  #   @param [String] gfa_line_string representation of a RGFA line
+  # @overload <<(gfa_line)
+  #   @param [RGFA::Line] gfa_line instance of a subclass of RGFA::Line
+  # @raise [RGFA::DuplicatedLabelError] if multiple segment or path lines
+  #   with the same name are added
+  # @return [RGFA] self
+  def <<(gfa_line)
+    gfa_line = gfa_line.to_rgfa_line(validate: @validate)
+    rt = gfa_line.record_type
+    case rt
+    when :H
+      add_header(gfa_line)
+    when :S
+      add_segment(gfa_line)
+    when :L
+      add_link(gfa_line)
+    when :C
+      add_containment(gfa_line)
+    when :P
+      add_path(gfa_line)
+    else
+      raise # this never happens, as already catched by gfa_line init
+    end
+    return self
+  end
+
+  # Delete elements from the RGFA graph
+  # @overload rm(segment)
+  #   @param segment [String, RGFA::Line::Segment] segment name or instance
+  # @overload rm(path)
+  #   @param path [String, RGFA::Line::Segment] path name or instance
+  # @overload rm(link)
+  #   @param link [RGFA::Line::Link] link
+  # @overload rm(containment)
+  #   @param link [RGFA::Line::Containment] containment
+  # @overload rm(:headers)
+  #   Remove all headers
+  # @overload rm(array)
+  #   Calls {#rm} using each element of the array as argument
+  #   @param array [Array]
+  # @overload rm(method_name, *args)
+  #   Call a method of RGFA instance, then {#rm} for each returned value
+  #   @param method_name [Symbol] method to call
+  #   @param args arguments of the method
+  # @return [RGFA] self
+  def rm(x, *args)
+    if x.kind_of?(RGFA::Line)
+      raise ArgumentError,
+        "One argument required if first RGFA::Line" if !args.empty?
+      case x.record_type
+      when :H then raise ArgumentError, "Cannot remove single header lines"
+      when :S then delete_segment(x)
+      when :P then delete_path(x)
+      when :L then delete_link(x)
+      when :C then delete_containment(x)
+      end
+    elsif x.kind_of?(Symbol)
+      if @segments.has_key?(x)
+        if !args.empty?
+          raise ArgumentError, "One arguments required if first segment name"
+        end
+        delete_segment(x)
+      elsif @paths.has_key?(x)
+        if !args.empty?
+          raise ArgumentError, "One argument required if first path name"
+        end
+        delete_path(x)
+      elsif x == :headers
+        if !args.empty?
+          raise ArgumentError, "One argument required if first :headers"
+        end
+        delete_headers
+      else
+        if respond_to?(x)
+          rm(send(x, *args))
+        else
+          raise ArgumentError, "Cannot remove #{x.inspect}"
+        end
+      end
+    elsif x.kind_of?(String)
+      rm(x.to_sym, *args)
+    elsif x.kind_of?(Array)
+      x.each {|elem| rm(elem, *args)}
+    elsif x.nil?
+      return self
+    else
+      raise ArgumentError, "Cannot remove #{x.inspect}"
+    end
+    return self
+  end
+
+  # Rename a segment or a path
+  #
+  # @param old_name [String] the name of the segment or path to rename
+  # @param new_name [String] the new name for the segment or path
+  #
+  # @raise[RGFA::DuplicatedLabelError]
+  #   if +new_name+ is already a segment or path name
+  # @return [RGFA] self
+  def rename(old_name, new_name)
+    old_name = old_name.to_sym
+    new_name = new_name.to_sym
+    s = segment(old_name)
+    pt = nil
+    if s.nil?
+      pt = path(old_name)
+      if pt.nil?
+        raise RGFA::LineMissingError,
+          "#{old_name} is not a path or segment name"
+      end
+    end
+    if segment(new_name) or path(new_name)
+      raise RGFA::DuplicatedLabelError,
+        "#{new_name} is already a path or segment name"
+    end
+    if s
+      s.name = new_name
+      @segments.delete(old_name)
+      @segments[new_name] = s
+    else
+      pt.path_name = new_name
+      @paths.delete(old_name)
+      @paths[new_name] = pt
+    end
+    self
+  end
+
+  private
+
+  def lines
+    headers + segments + links + containments + paths
+  end
+
+  def each_line(&block)
+    lines.each(&block)
+  end
+
+end
+
+# Exception raised if a label for segment or path is duplicated
+class RGFA::DuplicatedLabelError < RGFA::Error; end
+
+# The error raised by banged line finders if no line respecting the criteria
+# exist in the RGFA
+class RGFA::LineMissingError < RGFA::Error; end

data/lib/rgfa/links.rb

@@ -0,0 +1,242 @@
+require_relative "error"
+
+#
+# Methods for the RGFA class, which allow to handle links in the graph.
+#
+module RGFA::Links
+
+  def add_link(gfa_line)
+    gfa_line = gfa_line.to_rgfa_line(validate: @validate)
+    gfa_line.normalize!
+    l = nil
+    if segment(gfa_line.from) and segment(gfa_line.to)
+      l = link_from_to(gfa_line.oriented_from,
+                       gfa_line.oriented_to,
+                       gfa_line.overlap)
+    end
+    if l.nil?
+      @links << gfa_line
+      [:from, :to].each do |dir|
+        segment_name = gfa_line.send(dir).to_sym
+        orient = gfa_line.send(:"#{dir}_orient").to_sym
+        if !@segments.has_key?(segment_name)
+          raise RGFA::LineMissingError if @segments_first_order
+          @segments[segment_name] =
+            RGFA::Line::Segment.new({:name => segment_name},
+                                    virtual: true)
+        end
+        @segments[segment_name].links[dir][orient] << gfa_line
+        gfa_line.send(:"#{dir}=", @segments[segment_name])
+      end
+    elsif l.virtual?
+      l.real!(gfa_line)
+    else
+      return
+    end
+  end
+  protected :add_link
+
+  # Deletes a link and all paths depending on it
+  #
+  # @param l [RGFA::Line::Link] link instance
+  # @return [RGFA] self
+  def delete_link(l)
+    @links.delete(l)
+    segment(l.from).links[:from][l.from_orient].delete(l)
+    segment(l.to).links[:to][l.to_orient].delete(l)
+    l.paths.each {|pt, orient| delete_path(pt)}
+  end
+
+  # Remove all links of a segment end end except that to the other specified
+  # segment end.
+  # @param segment_end [RGFA::SegmentEnd] the segment end
+  # @param other_end [RGFA::SegmentEnd] the other segment end
+  # @param conserve_components [Boolean] <i>(defaults to: +false+)</i>
+  #   Do not remove links if removing them breaks the graph into unconnected
+  #   components.
+  # @return [RGFA] self
+  def delete_other_links(segment_end, other_end, conserve_components: false)
+    other_end = other_end.to_segment_end
+    links_of(segment_end).each do |l|
+      if l.other_end(segment_end) != other_end
+        if !conserve_components or !cut_link?(l)
+          delete_link(l)
+        end
+      end
+    end
+  end
+
+  # All links of the graph
+  # @return [Array<RGFA::Line::Link>]
+  def links
+    @links
+  end
+
+  # Finds links of the specified end of segment.
+  #
+  # @param [RGFA::SegmentEnd] segment_end a segment end
+  #
+  # @return [Array<RGFA::Line::Link>] if segment_end[1] == :E,
+  #   links from sn with from_orient + and to sn with to_orient -
+  # @return [Array<RGFA::Line::Link>] if segment_end[1] == :B,
+  #   links to sn with to_orient + and from sn with from_orient -
+  #
+  # @note to add or remove links, use the appropriate methods;
+  #   adding or removing links from the returned array will not work
+  def links_of(segment_end)
+    segment_end = segment_end.to_segment_end
+    s = segment!(segment_end.segment)
+    o = segment_end.end_type == :E ? [:+,:-] : [:-,:+]
+    s.links[:from][o[0]] + s.links[:to][o[1]]
+  end
+
+  # Finds segment ends connected to the specified segment end.
+  #
+  # @param [RGFA::SegmentEnd] segment_end a segment end
+  #
+  # @return [Array<RGFA::SegmentEnd>>] segment ends connected by links
+  #   to +segment_end+
+  def neighbours(segment_end)
+    links_of(segment_end).map {|l| l.other_end(segment_end) }
+  end
+
+  # Searches all links between +segment_end1+ and +segment_end2+
+  #
+  # @!macro [new] two_segment_ends
+  #   @param segment_end1 [RGFA::SegmentEnd] a segment end
+  #   @param segment_end2 [RGFA::SegmentEnd] a segment end
+  # @return [Array<RGFA::Line::Link>] (possibly empty)
+  def links_between(segment_end1, segment_end2)
+    segment_end1 = segment_end1.to_segment_end
+    segment_end2 = segment_end2.to_segment_end
+    links_of(segment_end1).select do |l|
+      l.other_end(segment_end1) == segment_end2
+    end
+  end
+
+  # @!macro [new] link
+  #   Searches a link between +segment_end1+ and +segment_end2+
+  #   @!macro two_segment_ends
+  #   @return [RGFA::Line::Link] the first link found
+  # @return [nil] if no link is found.
+  def link(segment_end1, segment_end2)
+    segment_end1 = segment_end1.to_segment_end
+    segment_end2 = segment_end2.to_segment_end
+    links_of(segment_end1).each do |l|
+      return l if l.other_end(segment_end1) == segment_end2
+    end
+    return nil
+  end
+
+  # @!macro link
+  # @raise [RGFA::LineMissingError] if no link is found.
+  def link!(segment_end1, segment_end2)
+    l = link(segment_end1, segment_end2)
+    raise RGFA::LineMissingError,
+      "No link was found: "+
+          "#{segment_end1.to_s} -- "+
+          "#{segment_end2.to_s}" if l.nil?
+    l
+  end
+
+  # Find links from the segment in the specified orientation
+  # (or the equivalent links, i.e. to the segment in opposite orientation).
+  #
+  # @param [RGFA::OrientedSegment] oriented_segment a segment with orientation
+  # @param equivalent [Boolean] return also equivalent links.
+  # @return [Array<RGFA::Line::Link>]
+  # @note to add or remove links, use the appropriate methods;
+  #   adding or removing links from the returned array will not work
+  def links_from(oriented_segment, equivalent = true)
+    oriented_segment = oriented_segment.to_oriented_segment
+    s = segment!(oriented_segment.segment)
+    retval = s.links[:from][oriented_segment.orient]
+    if equivalent
+      retval + s.links[:to][oriented_segment.orient_inverted]
+    else
+      retval
+    end
+  end
+
+  # Find links to the segment in the specified orientation
+  # (or the equivalent links, i.e. from the segment in opposite orientation).
+  #
+  # @param [RGFA::OrientedSegment] oriented_segment a segment with orientation
+  # @param equivalent [Boolean] return also equivalent links.
+  # @return [Array<RGFA::Line::Link>]
+  # @note to add or remove links, use the appropriate methods;
+  #   adding or removing links from the returned array will not work
+  def links_to(oriented_segment, equivalent = true)
+    oriented_segment = oriented_segment.to_oriented_segment
+    s = segment!(oriented_segment.segment)
+    retval = s.links[:to][oriented_segment.orient]
+    if equivalent
+      retval + s.links[:from][oriented_segment.orient_inverted]
+    else
+      retval
+    end
+  end
+
+  # Search all links from a segment S1 in a given orientation
+  # to another segment S2 in a given, or the equivalent
+  # links from S2 to S1 with inverted orientations.
+  #
+  # @param [RGFA::OrientedSegment] oriented_segment1 a segment with orientation
+  # @param [RGFA::OrientedSegment] oriented_segment2 a segment with orientation
+  # @param [RGFA::CIGAR] cigar shall match if not empty/undef
+  # @param equivalent [Boolean] return also equivalent links.
+  # @return [Array<RGFA::Line::Link>]
+  # @note to add or remove links, use the appropriate methods;
+  #   adding or removing links from the returned array will not work
+  def links_from_to(oriented_segment1, oriented_segment2,
+                    cigar = [], equivalent = true)
+    oriented_segment1 = oriented_segment1.to_oriented_segment
+    oriented_segment2 = oriented_segment2.to_oriented_segment
+    links_from(oriented_segment1, equivalent).select do |l|
+      l.compatible?(oriented_segment1, oriented_segment2, cigar, equivalent)
+    end
+  end
+
+  # Search the link from a segment S1 in a given orientation
+  # to another segment S2 in a given, or the equivalent
+  # link from S2 to S1 with inverted orientations.
+  #
+  # @param [RGFA::OrientedSegment] oriented_segment1 a segment with orientation
+  # @param [RGFA::OrientedSegment] oriented_segment2 a segment with orientation
+  # @param [RGFA::CIGAR] cigar shall match if not empty/undef
+  # @param equivalent [Boolean] return also equivalent links.
+  # @return [RGFA::Line::Link] the first link found
+  # @return [nil] if no link is found.
+  def link_from_to(oriented_segment1, oriented_segment2,
+                   cigar = [], equivalent = true)
+    oriented_segment1 = oriented_segment1.to_oriented_segment
+    oriented_segment2 = oriented_segment2.to_oriented_segment
+    links_from(oriented_segment1, equivalent).select do |l|
+      return l if l.compatible?(oriented_segment1, oriented_segment2,
+                                cigar, equivalent)
+    end
+    return nil
+  end
+
+  # Search the link from a segment S1 in a given orientation
+  # to another segment S2 in a given, or the equivalent
+  # link from S2 to S1 with inverted orientations.
+  #
+  # @param [RGFA::OrientedSegment] oriented_segment1 a segment with orientation
+  # @param [RGFA::OrientedSegment] oriented_segment2 a segment with orientation
+  # @param [RGFA::CIGAR] cigar shall match if not empty/undef
+  # @param equivalent [Boolean] return also equivalent links.
+  # @return [RGFA::Line::Link] the first link found
+  # @raise [RGFA::LineMissingError] if no link is found.
+  def link_from_to!(oriented_segment1, oriented_segment2,
+                    cigar = [], equivalent = true)
+    l = link_from_to(oriented_segment1, oriented_segment2,
+                     cigar, equivalent)
+    raise RGFA::LineMissingError,
+      "No link was found: "+
+          "#{oriented_segment1.join(":")} -> "+
+          "#{oriented_segment2.join(":")}" if l.nil?
+    l
+  end
+
+end

data/lib/rgfa/logger.rb

@@ -0,0 +1,192 @@
+#
+# This class allows to output a message to the log file or STDERR and
+# to keep track of the progress of a method which takes long time to complete.
+#
+# @api private
+#
+class RGFA::Logger
+
+  # Information about the progress of a computation
+  ProgressData = Struct.new(:counter, :units, :partsize,
+                            :lastpart, :total, :starttime,
+                            :strlen)
+
+  # Create a Logger instance
+  #
+  # @param channel [#puts]
+  #    where to output (default: STDERR)
+  # @param prefix [String]
+  #   output prefix (default: "#")
+  # @param verbose_level [Integer]
+  #   0: no logging; >0: the higher, the more logging
+  # @return [RGFA::Logger]
+  def initialize(verbose_level: 1, channel: STDERR, prefix: "#")
+    @progress = false
+    if !verbose_level.kind_of?(Integer)
+      raise ArgumentError, "verbose_level must be an Integer"
+    end
+    if !channel.respond_to?(:puts)
+      raise TypeError, "channel must provide a puts method"
+    end
+    @channel = channel
+    @pfx = prefix
+    @verbose_level = verbose_level
+    @data = {}
+  end
+
+  # Output a message
+  #
+  # @param msg [String] message to output
+  # @param min_verbose_level [Integer]
+  # @return [void]
+  def log(msg, min_verbose_level=1)
+    @channel.puts "#@pfx #{msg}" if @verbose_level >= min_verbose_level
+    return nil
+  end
+
+  # Enable output from the Logger instance
+  #
+  # @param part [Float]
+  #  - part = 0      => output at every call of {RGFA::Logger.progress_log}
+  #  - 0 < part < 1  => output once per part of the total progress
+  #                     (e.g. 0.001 = log every 0.1% progress)
+  #  - part = 1      => output only total elapsed time
+  # @return [void]
+  def enable_progress(part: 0.1)
+    if part < 0 or part > 1
+      raise ArgumentError, "part must be in range [0..1]"
+    end
+    @progress = true
+    @part = part
+    @channel.puts "#@pfx Progress logging enabled" if @verbose_level > 0
+    return nil
+  end
+
+  # Disable progress logging
+  # @return [void]
+  def disable_progress
+    @progress = false
+    @channel.puts "#@pfx Progress logging disabled" if @verbose_level > 0
+    return nil
+  end
+
+  # @!macro progress_init
+  #   Initialize progress logging for a computation
+  #   @param symbol [Symbol] a symbol assigned to the computation
+  #   @param units [String] a string with the name of the units, in plural
+  #   @param total [Integer] total number of units
+  #   @param initmsg [String] an optional message to output at the beginning
+  # @return [void]
+  def progress_init(symbol, units, total, initmsg = nil)
+    return nil if !@progress or total == 0
+    str = "#@pfx 0.0% #{units} processed"
+    @data[symbol] = ProgressData.new(0, units, (@part*total).to_i, 1, total,
+                                     Time.now, str.size)
+    @channel.puts "#@pfx #{initmsg}" if initmsg
+    @channel.print str if @part != 1
+    return nil
+  end
+
+  # @!macro [new] progress_log
+  #   Updates progress logging for a computation
+  #   @!macro [new] prlog
+  #     @param symbol [Symbol] the symbol assigned to the computation at
+  #       init time
+  #     @param keyargs [Hash] additional units to display, with their current
+  #       value (e.g. segments_processed: 10000)
+  #   @param progress [Integer] how many units were processed
+  # @return [void]
+  def progress_log(symbol, progress=1, **keyargs)
+    return nil if !@progress or @part == 1
+    data = @data[symbol]
+    return nil if data.nil?
+    data.counter += progress
+    if data.counter == data.total
+      progress_end(symbol)
+    elsif data.partsize == 0 or
+        (data.counter / data.partsize).to_i > data.lastpart
+      return nil if data.partsize == 0 and @part > 0
+        # this means total is very small
+      data.lastpart = data.counter / data.partsize if data.partsize > 0
+      done = data.counter.to_f / data.total
+      t = Time.now - data.starttime
+      eta = (t / done) - t
+      tstr= ("Elapsed: %02dh %02dmin %02ds" % [t/3600, t/60%60, t%60])
+      etastr = ("ETA: %02dh %02dmin %02ds" % [eta/3600, eta/60%60, eta%60])
+      donestr = "%.1f" % (done*100)
+      keystr = ""
+      keyargs.each {|k,v| keystr << "; #{k}: #{v}"}
+      str = "#@pfx #{donestr}% #{data.units} processed "+
+              "[#{tstr}; #{etastr}#{keystr}]"
+      if str.size > data.strlen
+        data.strlen = str.size
+        spacediff = ""
+      else
+        spacediff = " "*(data.strlen-str.size)
+      end
+      @channel.print "\r#{str}#{spacediff}"
+      @channel.flush
+    end
+    return nil
+  end
+
+  # @!macro [new] progress_end
+  #   Completes progress logging for a computation
+  #   @!macro prlog
+  # @return [void]
+  def progress_end(symbol, **keyargs)
+    return if !@progress
+    data = @data[symbol]
+    return if data.nil?
+    t = Time.now - data.starttime
+    tstr= ("Elapsed time: %02dh %02dmin %02ds" % [t/3600, t/60%60, t%60])
+    quantity = @part == 1 ? data.total.to_s : "100.0%"
+    keystr = ""
+    keyargs.each {|k,v| keystr << "; #{k}: #{v}"}
+    str = "#@pfx #{quantity} #{data.units} processed [#{tstr}#{keystr}]"
+    spacediff = " "*([data.strlen - str.size,0].max)
+    @channel.print "\r" if @part != 1
+    @channel.puts "#{str}#{spacediff}"
+    @channel.flush
+    @data.delete(symbol)
+    return nil
+  end
+
+end
+
+# Progress logging related-methods for RGFA class
+module RGFA::LoggerSupport
+
+  # Activate logging of progress
+  # @return [RGFA] self
+  def enable_progress_logging(part: 0.1, channel: STDERR)
+    @progress = RGFA::Logger.new(channel: channel)
+    @progress.enable_progress(part: part)
+    return self
+  end
+
+  # @!macro progress_init
+  # @return [RGFA] self
+  # @api private
+  def progress_log_init(symbol, units, total, initmsg = nil)
+    @progress.progress_init(symbol, units, total, initmsg) if @progress
+    return self
+  end
+
+  # @!macro progress_log
+  # @return [RGFA] self
+  # @api private
+  def progress_log(symbol, progress=1, **keyargs)
+    @progress.progress_log(symbol, progress) if @progress
+    return self
+  end
+
+  # @!macro progress_end
+  # @return [RGFA] self
+  # @api private
+  def progress_log_end(symbol, **keyargs)
+    @progress.progress_end(symbol) if @progress
+    return self
+  end
+
+end