rgfa 1.2.1

data/lib/rgfa/line/containment.rb

@@ -0,0 +1,87 @@
+# A containment line of a RGFA file
+class RGFA::Line::Containment < RGFA::Line
+
+  RECORD_TYPE = :C
+  REQFIELDS = [:from, :from_orient, :to, :to_orient, :pos, :overlap]
+  PREDEFINED_OPTFIELDS = [:MQ, :NM]
+  DATATYPE = {
+     :from => :lbl,
+     :from_orient => :orn,
+     :to => :lbl,
+     :to_orient => :orn,
+     :pos => :pos,
+     :overlap => :cig,
+     :MQ => :i,
+     :NM => :i,
+  }
+
+  define_field_methods!
+
+  # @return [RGFA::OrientedSegment] the oriented segment represented by the
+  #   from/from_orient fields
+  def oriented_from
+    [from, from_orient].to_oriented_segment
+  end
+
+  # @return [RGFA::OrientedSegment] the oriented segment represented by the
+  #   to/to_orient fields
+  def oriented_to
+    [to, to_orient].to_oriented_segment
+  end
+
+  # The from segment name, in both cases where from is a segment name (Symbol)
+  # or a segment (RGFA::Line::Segment)
+  # @return [Symbol]
+  def from_name
+    from.to_sym
+  end
+
+  # The to segment name, in both cases where to is a segment name (Symbol)
+  # or a segment (RGFA::Line::Segment)
+  # @return [Symbol]
+  def to_name
+    to.to_sym
+  end
+
+  # @return [Integer,nil] the rightmost 0-based coordinate of the contained
+  #   sequence in the container; nil if the overlap is unspecified
+  def rpos
+    return nil if overlap.empty?
+    rpos = pos
+    overlap.each do |op|
+      if [:M, :D].include?(op.code)
+        rpos += op.len
+      end
+    end
+    return rpos
+  end
+
+  # Returns true if the containment is normal, false otherwise
+  #
+  # <b> Definition of normal containment </b>
+  #
+  # Each containment has an equivalent reverse containment.
+  # Consider a containment of B (length:8) in A (length:100) at position 9 of A
+  # with a cigar 1M1I2M3D4M (i.e. rpos = 19).
+  #
+  #   A+ B+ 1M1I2M3D4M 9 == A- B- 4M3D2M1I1M 80
+  #   A+ B- 1M1I2M3D4M 9 == A- B+ 4M3D2M1I1M 80
+  #   A- B+ 1M1I2M3D4M 9 == A+ B- 4M3D2M1I1M 80
+  #   A- B- 1M1I2M3D4M 9 == A+ B+ 4M3D2M1I1M 80
+  #
+  # Pos in the reverse is equal to the length of A minus the right pos
+  # of B before reversing.
+  #
+  # We require here that A != B as A == B makes no sense for containments.
+  # Thus it is always possible to express the containment using a positive
+  # from orientation.
+  #
+  # For this reason the normality is simply defined as + from orientation.
+  #
+  # @return [Boolean]
+  #
+  def normal?
+    from_orient == :+
+  end
+
+end

data/lib/rgfa/line/header.rb

@@ -0,0 +1,92 @@
+# A header line of a RGFA file
+#
+# For examples on how to set the header data, see {RGFA::Headers}.
+#
+# @see RGFA::Line
+class RGFA::Line::Header < RGFA::Line
+
+  RECORD_TYPE = :H
+  REQFIELDS = []
+  PREDEFINED_OPTFIELDS = [:VN]
+  DATATYPE = {
+    :VN => :Z
+  }
+
+  define_field_methods!
+
+  # Set a header value (multi-value compatible).
+  #
+  # If a field does not exist yet, set it to value. If it exists and it is a
+  # {RGFA::FieldArray}, add the value to the field array. If it exists and it
+  # is not a field array, create a field array with the previous value and
+  # the new one
+  # @param fieldname [Symbol]
+  # @param value [Object]
+  # @param datatype [RGFA::Line::OPTFIELD_DATATYPE, nil] the datatype to use;
+  #   the default is to determine the datatype according to the value or the
+  #   previous values present int the field
+  def add(fieldname, value, datatype=nil)
+    fieldname = fieldname.to_sym
+    prev = get(fieldname)
+    if prev.nil?
+      set_datatype(fieldname, datatype) if datatype
+      set(fieldname, value)
+      return self
+    elsif !prev.kind_of?(RGFA::FieldArray)
+      prev = RGFA::FieldArray.new(get_datatype(fieldname), [prev])
+      set_datatype(fieldname, :J)
+      set(fieldname,prev)
+    end
+    prev.push_with_validation(value, datatype, fieldname)
+    return self
+  end
+
+  # Array of optional tags data.
+  #
+  # Returns the optional fields as an array of [fieldname, datatype, value]
+  # arrays. If a field is a FieldArray, this is splitted into multiple fields
+  # with the same fieldname.
+  # @return [Array<(Symbol, Symbol, Object)>]
+  # @api private
+  def tags
+    retval = []
+    optional_fieldnames.each do |of|
+      value = get(of)
+      if value.kind_of?(RGFA::FieldArray)
+        value.each do |elem|
+          retval << [of, value.datatype, elem]
+        end
+      else
+        retval << [of, get_datatype(of), value]
+      end
+    end
+    return retval
+  end
+
+  # Split the header line into single-tag lines.
+  #
+  # If a tag is a FieldArray, this is splitted into multiple fields
+  # with the same fieldname.
+  # @return [Array<RGFA::Line::Header>]
+  # @api private
+  def split
+    tags.map do |tagname, datatype, value|
+      h = RGFA::Line::Header.new([], validate: @validate)
+      h.set_datatype(tagname, datatype)
+      h.set(tagname, value)
+      h
+    end
+  end
+
+  # Merge an additional {RGFA::Line::Header} line into this header line.
+  # @param gfa_line [RGFA::Line::Header] the header line to merge
+  # @return [self]
+  # @api private
+  def merge(gfa_line)
+    gfa_line.optional_fieldnames.each do |of|
+      add(of, gfa_line.get(of), gfa_line.get_datatype(of))
+    end
+    self
+  end
+
+end

data/lib/rgfa/line/link.rb

@@ -0,0 +1,379 @@
+# A link connects two segments, or a segment to itself.
+#
+class RGFA::Line::Link < RGFA::Line
+
+  RECORD_TYPE = :L
+  REQFIELDS = [:from, :from_orient, :to, :to_orient, :overlap]
+  PREDEFINED_OPTFIELDS = [:MQ, :NM, :RC, :FC, :KC]
+  DATATYPE = {
+     :from => :lbl,
+     :from_orient => :orn,
+     :to => :lbl,
+     :to_orient => :orn,
+     :overlap => :cig,
+     :MQ => :i,
+     :NM => :i,
+     :RC => :i,
+     :FC => :i,
+     :KC => :i,
+  }
+
+  define_field_methods!
+
+  # The other segment of a link
+  # @param segment [RGFA::Line::Segment, Symbol] segment name or instance
+  # @raise [RGFA::LineMissingError]
+  #   if segment is not involved in the link
+  # @return [Symbol] the name of the other segment of the link
+  #   if circular, then +segment+
+  def other(segment)
+    segment_name =
+      (segment.kind_of?(RGFA::Line::Segment) ? segment.name : segment.to_sym)
+    if segment_name == from.to_sym
+      to
+    elsif segment_name == to.to_sym
+      from
+    else
+      raise RGFA::LineMissingError,
+        "Link #{self} does not involve segment #{segment_name}"
+    end
+  end
+
+  # @return [Boolean] is the from and to segments are equal
+  def circular?
+    from.to_sym == to.to_sym
+  end
+
+  # @return [Boolean] is the from and to segments are equal
+  def circular_same_end?
+    from_end == to_end
+  end
+
+  # @return [RGFA::OrientedSegment] the oriented segment represented by the
+  #   from/from_orient fields
+  def oriented_from
+    [from, from_orient].to_oriented_segment
+  end
+
+  # @return [RGFA::OrientedSegment] the oriented segment represented by the
+  #   to/to_orient fields
+  def oriented_to
+    [to, to_orient].to_oriented_segment
+  end
+
+  # @return [RGFA::SegmentEnd] the segment end represented by the
+  #   from/from_orient fields
+  def from_end
+    [from, from_orient == :+ ? :E : :B].to_segment_end
+  end
+
+  # @return [RGFA::SegmentEnd] the segment end represented by the
+  #   to/to_orient fields
+  def to_end
+    [to, to_orient == :+ ? :B : :E].to_segment_end
+  end
+
+  # Signature of the segment ends, for debugging
+  # @api private
+  def segment_ends_s
+    [from_end.to_s, to_end.to_s].join("---")
+  end
+
+  # @param segment_end [RGFA::SegmentEnd] one of the two segment ends
+  #   of the link
+  # @return [RGFA::SegmentEnd] the other segment end
+  #
+  # @raise [ArgumentError] if segment_end is not a valid segment end
+  #   representation
+  # @raise [RuntimeError] if segment_end is not a segment end of the link
+  def other_end(segment_end)
+    segment_end = segment_end.to_segment_end
+    if (from_end == segment_end)
+      return to_end
+    elsif (to_end == segment_end)
+      return from_end
+    else
+      raise "Segment end '#{segment_end.inspect}' not found\n"+
+            "(from=#{from_end.inspect};to=#{to_end.inspect})"
+    end
+  end
+
+  # The from segment name, in both cases where from is a segment name (Symbol)
+  # or a segment (RGFA::Line::Segment)
+  # @return [Symbol]
+  def from_name
+    from.to_sym
+  end
+
+  # The to segment name, in both cases where to is a segment name (Symbol)
+  # or a segment (RGFA::Line::Segment)
+  # @return [Symbol]
+  def to_name
+    to.to_sym
+  end
+
+  # Returns true if the link is normal, false otherwise
+  #
+  # == Definition of normal link
+  #
+  # Each link has an equivalent reverse link. Consider a link of A to B
+  # with a overlap 1M1I2M:
+  #
+  #   from+ to to+ (1M1I2M) == to- to from- (2M1D1M)
+  #   from- to to- (1M1I2M) == to+ to from+ (2M1D1M)
+  #   from+ to to- (1M1I2M) == to+ to from- (2M1D1M)
+  #   from- to to+ (1M1I2M) == to- to from+ (2M1D1M)
+  #
+  # Consider also the special case, where from == to and the overlap is not
+  # specified, or equal to its reverse:
+  #
+  #   from+ to from+ (*) == from- to from- (*) # left has a +; right has no +
+  #   from- to from- (*) == from+ to from+ (*) # left has no +; right has a +
+  #   from+ to from- (*) == from+ to from- (*) # left == right
+  #   from- to from+ (*) == from- to from+ (*) # left == right
+  #
+  # Thus we define a link as normal if:
+  # - from < to (lexicographical comparison of segments)
+  # - from == to and overlap.to_s < reverse_overlap.to_s
+  # - from == to, overlap == reverse_overlap and at least one orientation is +
+  #
+  # @return [Boolean]
+  #
+  def normal?
+    if from_name < to_name
+      return true
+    elsif from_name > to_name
+      return false
+    else
+      overlap_s = overlap.to_s
+      reverse_overlap_s = reverse_overlap.to_s
+      if overlap_s < reverse_overlap_s
+        return true
+      elsif overlap_s > reverse_overlap_s
+        return false
+      else
+        return [from_orient, to_orient].include?(:+)
+      end
+    end
+  end
+
+  # Returns the unchanged link if the link is normal,
+  # otherwise reverses the link and returns it.
+  #
+  # @note The path references are not corrected by this method; therefore
+  #   the method shall be used before the link is embedded in a graph.
+  #
+  # @return [RGFA::Line::Link] self
+  def normalize!
+    reverse! if !normal?
+  end
+
+  # Creates a link with both strands of the sequences inverted.
+  # The CIGAR operations (order/type) are inverted as well.
+  # Optional fields are left unchanged.
+  #
+  # @note The path references are not copied to the reverse link.
+  #
+  # @note This method shall be overridden if custom optional fields
+  #   are defined, which have a ``reverse'' operation which determines
+  #   their value in the equivalent but reverse link.
+  #
+  # @return [RGFA::Line::Link] the inverted link.
+  def reverse
+    l = self.clone
+    l.from = to
+    l.from_orient = (to_orient == :+ ? :- : :+)
+    l.to = from
+    l.to_orient = (from_orient == :+ ? :- : :+)
+    l.overlap = reverse_overlap
+    l
+  end
+
+  # Reverses the link inplace, i.e. sets:
+  #   from = to
+  #   from_orient = other_orient(to_orient)
+  #   to = from
+  #   to_orient = other_orient(from_orient)
+  #   overlap = reverse_overlap.
+  #
+  # The optional fields are left unchanged.
+  #
+  # @note The path references are not reversed by this method; therefore
+  #   the method shall be used before the link is embedded in a graph.
+  #
+  # @note This method shall be overridden if custom optional fields
+  #   are defined, which have a ``reverse'' operation which determines
+  #   their value in the equivalent but reverse link.
+  #
+  # @return [RGFA::Line::Link] self
+  def reverse!
+    tmp = self.from
+    self.from = self.to
+    self.to = tmp
+    tmp = self.from_orient
+    self.from_orient = (self.to_orient == :+) ? :- : :+
+    self.to_orient = (tmp == :+) ? :- : :+
+    self.overlap = self.reverse_overlap
+    return self
+  end
+
+  # Paths for which the link is required.
+  #
+  # The return value is an empty array
+  # if the link is not embedded in a graph.
+  #
+  # Otherwise, an array of tuples path/boolean is returned.
+  # The boolean value tells
+  # if the link is used in direct (true) or reverse direction (false)
+  # in the path.
+  # @return [Array<Array<(RGFA::Line::Path, Boolean)>>]
+  def paths
+    @paths ||= []
+    @paths
+  end
+
+  # Compute the overlap when the strand of both sequences is inverted.
+  #
+  # @return [RGFA::CIGAR]
+  def reverse_overlap
+    self.overlap.reverse
+  end
+
+  #
+  # Compares two links and determine their equivalence.
+  # Thereby, optional fields are not considered.
+  #
+  # @note Inverting the strand of both links and reversing
+  #   the CIGAR operations (order/type), one obtains a
+  #   reverse but equivalent link.
+  #
+  # @param other [RGFA::Line::Link] a link
+  # @return [Boolean] are self and other equivalent?
+  # @see #==
+  # @see #same?
+  # @see #reverse?
+  def eql?(other)
+    same?(other) or reverse?(other)
+  end
+
+  # Compares the optional fields of two links.
+  #
+  # @note This method shall be overridden if custom optional fields
+  #   are defined, which have a ``reverse'' operation which determines
+  #   their value in the equivalent but reverse link.
+  #
+  # @param other [RGFA::Line::Link] a link
+  # @return [Boolean] are self and other equivalent?
+  # @see #==
+  def eql_optional?(other)
+    (self.optional_fieldnames.sort == other.optional_fieldnames.sort) and
+      optional_fieldnames.each {|fn| self.get(fn) == other.get(fn)}
+  end
+
+  # Compares two links and determine their equivalence.
+  # Optional fields must have the same content.
+  #
+  # @note Inverting the strand of both links and reversing
+  #   the CIGAR operations (order/type), one obtains an equivalent
+  #   link.
+  #
+  # @param other [RGFA::Line::Link] a link
+  # @return [Boolean] are self and other equivalent?
+  # @see #eql?
+  # @see #eql_optional?
+  #def ==(other)
+  #  eql?(other) and eql_optional?(other)
+  #end
+
+  # Compares two links and determine their equivalence.
+  # Thereby, optional fields are not considered.
+  #
+  # @param other [RGFA::Line::Link] a link
+  # @return [Boolean] are self and other equivalent?
+  # @see #eql?
+  # @see #reverse?
+  # @see #==
+  def same?(other)
+    (from_end == other.from_end and
+      to_end == other.to_end and
+      overlap == other.overlap)
+  end
+
+  # Compares the reverse of the link to another link
+  # and determine their equivalence.
+  # Thereby, optional fields are not considered.
+  #
+  # @param other [RGFA::Line::Link] the other link
+  # @return [Boolean] are the reverse of self and other equivalent?
+  # @see #eql?
+  # @see #same?
+  # @see #==
+  def reverse?(other)
+    (from_end == other.to_end and
+      to_end == other.from_end and
+      overlap == other.reverse_overlap)
+  end
+
+  # Computes an hash for including a link in an Hash tables,
+  # so that the hash of a link and its reverse is the same.
+  # Thereby, optional fields are not considered.
+  # @see #eql?
+  def hash
+    from_end.hash + to_end.hash + overlap.hash + reverse_overlap.to_s.hash
+  end
+
+  # Compares a link and optionally the reverse link,
+  # with two oriented_segments and optionally an overlap.
+  # @param [RGFA::OrientedSegment] other_oriented_from
+  # @param [RGFA::OrientedSegment] other_oriented_to
+  # @param equivalent [Boolean] shall the reverse link also be considered?
+  # @param [RGFA::CIGAR] other_overlap compared only if not empty
+  # @return [Boolean] does the link or, if +equivalent+,
+  #   the reverse link go from the first
+  #   oriented segment to the second with an overlap equal to the provided one
+  #   (if not empty)?
+  def compatible?(other_oriented_from, other_oriented_to, other_overlap = [],
+                  equivalent = true)
+    other_overlap = other_overlap.to_cigar
+    is_direct = compatible_direct?(other_oriented_from, other_oriented_to,
+                                   other_overlap)
+    if is_direct
+      return true
+    elsif equivalent
+      return compatible_reverse?(other_oriented_from, other_oriented_to,
+                          other_overlap)
+    else
+      return false
+    end
+  end
+
+  # Compares a link with two oriented segments and optionally an overlap.
+  # @param [RGFA::OrientedSegment] other_oriented_from
+  # @param [RGFA::OrientedSegment] other_oriented_to
+  # @param [RGFA::CIGAR] other_overlap compared only if not empty
+  # @return [Boolean] does the link go from the first
+  #   oriented segment to the second with an overlap equal to the provided one
+  #   (if not empty)?
+  def compatible_direct?(other_oriented_from, other_oriented_to,
+                         other_overlap = [])
+    (oriented_from == other_oriented_from and
+     oriented_to == other_oriented_to) and
+     (overlap.empty? or other_overlap.empty? or (overlap == other_overlap))
+  end
+
+  # Compares the reverse link with two oriented segments and optionally an
+  # overlap.
+  # @param [RGFA::OrientedSegment] other_oriented_from
+  # @param [RGFA::OrientedSegment] other_oriented_to
+  # @param [RGFA::CIGAR] other_overlap compared only if not empty
+  # @return [Boolean] does the reverse link go from the first
+  #   oriented segment to the second with an overlap equal to the provided one
+  #   (if not empty)?
+  def compatible_reverse?(other_oriented_from, other_oriented_to,
+                          other_overlap = [])
+    (oriented_to == other_oriented_from.invert_orient and
+     oriented_from == other_oriented_to.invert_orient) and
+     (overlap.empty? or other_overlap.empty? or (overlap == other_overlap))
+  end
+
+end