bio-restriction_enzyme 1.0.0

data/lib/bio/util/restriction_enzyme/range/sequence_range/calculated_cuts.rb

@@ -0,0 +1,236 @@
+# bio/util/restriction_enzyme/range/sequence_range/calculated_cuts.rb -
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+class Range
+class SequenceRange
+
+# cc = CalculatedCuts.new(@size)
+# cc.add_cuts_from_cut_ranges(@cut_ranges)
+# cc.remove_incomplete_cuts
+#
+#    1 2 3 4 5 6 7
+#    G A|T T A C A
+#       +-----+
+#    C T A A T|G T
+#    1 2 3 4 5 6 7
+#
+# Primary cut = 2
+# Complement cut = 5
+# Horizontal cuts = 3, 4, 5
+#
+class CalculatedCuts
+  include CutSymbol
+  include StringFormatting
+
+  # +Array+ of vertical cuts on the primary strand in 0-based index notation
+  attr_reader :vc_primary
+
+  # +Array+ of vertical cuts on the complementary strand in 0-based index notation
+  attr_reader :vc_complement
+
+  # +Array+ of horizontal cuts between strands in 0-based index notation
+  attr_reader :hc_between_strands
+
+  # Set to +true+ if the fragment CalculatedCuts is working on is circular
+  attr_accessor :circular
+
+  #--
+  ## An +Array+ with the primary strand with vertical cuts, the horizontal cuts, and the complementary strand with vertical cuts.
+  #attr_reader :strands_for_display
+  #++
+
+  # If +false+ the strands_for_display method needs to be called to update the contents
+  # of @strands_for_display.  Becomes out of date whenever add_cuts_from_cut_ranges is called.
+  attr_reader :strands_for_display_current
+
+  # Size of the sequence being digested.
+  attr_reader :size
+
+  def initialize(size=nil, circular=false)
+    @size = size
+    @circular = circular
+    @vc_primary = []
+    @vc_complement = []
+    @hc_between_strands = []
+  end
+
+  # Accepts an +Array+ of CutRange type objects and applies them to
+  # @vc_complement, @vc_primary, and @hc_between_strands.
+  #
+  # ---
+  # *Arguments*
+  # * +cut_ranges+: An +Array+ of HorizontalCutRange or VerticalCutRange objects
+  # *Returns*:: nothing
+  def add_cuts_from_cut_ranges(cut_ranges)
+    @strands_for_display_current = false
+
+    cut_ranges.each do |cut_range|
+      @vc_primary += [cut_range.p_cut_left, cut_range.p_cut_right]
+      @vc_complement += [cut_range.c_cut_left, cut_range.c_cut_right]
+
+      # Add horizontal cut ranges.  This may happen from cuts made inbetween a
+      # VerticalCutRange or may be specifically defined by a HorizontalCutRange.
+      if cut_range.class == VerticalCutRange
+        ( cut_range.min + 1 ).upto( cut_range.max ){|i| @hc_between_strands << i} if cut_range.min < cut_range.max
+      elsif cut_range.class == HorizontalCutRange
+        ( cut_range.hcuts.first ).upto( cut_range.hcuts.last ){|i| @hc_between_strands << i}
+      end
+    end
+    clean_all
+    #return
+  end
+
+  # There may be incomplete cuts made, this method removes the cuts that don't
+  # create sub-sequences for easier processing.
+  #
+  # For example, stray horizontal cuts that do not end with a left
+  # and right separation:
+  #
+  #   G A T T A C A
+  #      +--  ---
+  #   C T|A A T G T
+  #
+  # Or stray vertical cuts:
+  #
+  #   G A T T A C A
+  #      +--   +
+  #   C T|A A T|G T
+  #
+  # However note that for non-circular sequences this would be a successful
+  # cut which would result in a floating 'GT' sub-sequence:
+  #
+  #   G A T T A C A
+  #            +---
+  #   C T A A T|G T
+  #
+  # Blunt cuts are also complete cuts.
+  # ---
+  # *Arguments*
+  # * +size+: (_optional_) Size of the sequence being digested.  Defined here or during initalization of CalculatedCuts.
+  # *Returns*:: nothing
+  def remove_incomplete_cuts(size=nil)
+    @strands_for_display_current = false
+    @size = size if size
+    raise IndexError, "Size of the strand must be provided here or during initalization." if !@size.kind_of?(Fixnum) and not @circular
+
+    vcuts = (@vc_primary + @vc_complement).uniq.sort
+    hcuts = @hc_between_strands
+    last_index = @size - 1
+    good_hcuts = []
+    potential_hcuts = []
+
+    if @circular
+    # NOTE
+    # if it's circular we should start at the beginning of a cut for orientation,
+    # scan for it, hack off the first set of hcuts and move them to the back
+    else
+      vcuts.unshift(-1) unless vcuts.include?(-1)
+      vcuts.push(last_index) unless vcuts.include?(last_index)
+    end
+
+    hcuts.each do |hcut|
+      raise IndexError if hcut < -1 or hcut > last_index
+      # skipped a nucleotide
+      potential_hcuts.clear if !potential_hcuts.empty? and (hcut - potential_hcuts.last).abs > 1
+
+      if potential_hcuts.empty?
+        if vcuts.include?( hcut ) and vcuts.include?( hcut - 1 )
+          good_hcuts += [hcut]
+        elsif vcuts.include?( hcut - 1 )
+          potential_hcuts << hcut
+        end
+      else
+        if vcuts.include?( hcut )
+          good_hcuts += potential_hcuts + [hcut]
+          potential_hcuts.clear
+        else
+          potential_hcuts << hcut
+        end
+      end
+    end
+
+    check_vc = lambda do |vertical_cuts, opposing_vcuts|
+      # opposing_vcuts is here only to check for blunt cuts, so there shouldn't
+      # be any out-of-order problems with this
+      good_vc = []
+      vertical_cuts.each { |vc| good_vc << vc if good_hcuts.include?( vc ) or good_hcuts.include?( vc + 1 ) or opposing_vcuts.include?( vc ) }
+      good_vc
+    end
+
+    @vc_primary = check_vc.call(@vc_primary, @vc_complement)
+    @vc_complement = check_vc.call(@vc_complement, @vc_primary)
+    @hc_between_strands = good_hcuts
+
+    clean_all
+  end
+
+  # Sets @strands_for_display_current to +true+ and populates @strands_for_display.
+  #
+  # ---
+  # *Arguments*
+  # * +str1+: (_optional_) For displaying a primary strand.  If +nil+ a numbered sequence will be used in place.
+  # * +str2+: (_optional_) For displaying a complementary strand.  If +nil+ a numbered sequence will be used in place.
+  # * +vcp+: (_optional_) An array of vertical cut locations on the primary strand.  If +nil+ the contents of @vc_primary is used.
+  # * +vcc+: (_optional_) An array of vertical cut locations on the complementary strand.  If +nil+ the contents of @vc_complementary is used.
+  # * +hc+: (_optional_) An array of horizontal cut locations between strands.  If +nil+ the contents of @hc_between_strands is used.
+  # *Returns*:: +Array+ An array with the primary strand with vertical cuts, the horizontal cuts, and the complementary strand with vertical cuts.
+  #
+  def strands_for_display(str1 = nil, str2 = nil, vcp=nil, vcc=nil, hc=nil)
+    return @strands_for_display if @strands_for_display_current
+    vcs = '|'   # Vertical cut symbol
+    hcs = '-'   # Horizontal cut symbol
+    vhcs = '+'  # Intersection of vertical and horizontal cut symbol
+
+    num_txt_repeat = lambda { num_txt = '0123456789'; (num_txt * ( @size / num_txt.size.to_f ).ceil)[0..@size-1] }
+    (str1 == nil) ? a = num_txt_repeat.call : a = str1.dup
+    (str2 == nil) ? b = num_txt_repeat.call : b = str2.dup
+
+    vcp = @vc_primary if vcp==nil
+    vcc = @vc_complement if vcc==nil
+    hc = @hc_between_strands if hc==nil
+
+    vcuts = (vcp + vcc).uniq.sort
+
+    vcp.reverse.each { |c| a.insert(c+1, vcs) }
+    vcc.reverse.each { |c| b.insert(c+1, vcs) }
+
+    between = ' ' * @size
+    hc.each {|hcut| between[hcut,1] = hcs }
+
+    s_a = add_spacing(a, vcs)
+    s_b = add_spacing(b, vcs)
+    s_bet = add_spacing(between)
+
+    # NOTE watch this for circular
+    i = 0
+    0.upto( s_a.size-1 ) do
+      if (s_a[i,1] == vcs) or (s_b[i,1] == vcs)
+        s_bet[i] = vhcs
+      elsif i != 0 and s_bet[i-1,1] == hcs and s_bet[i+1,1] == hcs
+        s_bet[i] = hcs
+      end
+      i+=1
+    end
+
+    @strands_for_display_current = true
+    @strands_for_display = [s_a, s_bet, s_b]
+  end
+
+  #########
+  protected
+  #########
+
+  # remove nil values, remove duplicate values, and
+  # sort @vc_primary, @vc_complement, and @hc_between_strands
+  def clean_all
+    [@vc_primary, @vc_complement, @hc_between_strands].collect { |a| a.delete(nil); a.uniq!; a.sort! }
+  end
+
+end # CalculatedCuts
+end # SequenceRange
+end # Range
+end # RestrictionEnzyme
+end # Bio

data/lib/bio/util/restriction_enzyme/range/sequence_range/fragment.rb

@@ -0,0 +1,43 @@
+# bio/util/restriction_enzyme/range/sequence_range/fragment.rb -
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+class Range
+class SequenceRange
+
+class Fragment
+
+  attr_reader :size
+
+  def initialize( primary_bin, complement_bin )
+    @primary_bin = primary_bin
+    @complement_bin = complement_bin
+  end
+
+  DisplayFragment = Struct.new(:primary, :complement, :p_left, :p_right, :c_left, :c_right)
+
+  def for_display(p_str=nil, c_str=nil)
+    df = DisplayFragment.new
+    df.primary = ''
+    df.complement = ''
+
+    both_bins = (@primary_bin + @complement_bin).sort.uniq
+    both_bins.each do |item|
+      @primary_bin.include?(item) ? df.primary << p_str[item] : df.primary << ' '
+      @complement_bin.include?(item) ? df.complement << c_str[item] : df.complement << ' '
+    end
+
+    df.p_left  = @primary_bin.first
+    df.p_right = @primary_bin.last
+    df.c_left  = @complement_bin.first
+    df.c_right = @complement_bin.last
+
+    df
+  end
+end # Fragment
+end # SequenceRange
+end # Range
+end # RestrictionEnzyme
+end # Bio

data/lib/bio/util/restriction_enzyme/range/sequence_range/fragments.rb

@@ -0,0 +1,33 @@
+# bio/util/restriction_enzyme/analysis/fragments.rb -
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+class Range
+class SequenceRange
+
+class Fragments < Array
+
+  attr_accessor :primary
+  attr_accessor :complement
+
+  def initialize(primary, complement)
+    @primary = primary
+    @complement = complement
+  end
+
+  DisplayFragment = Struct.new(:primary, :complement)
+
+  def for_display(p_str=nil, c_str=nil)
+    p_str ||= @primary
+    c_str ||= @complement
+    pretty_fragments = []
+    self.each { |fragment| pretty_fragments << fragment.for_display(p_str, c_str) }
+    pretty_fragments
+  end
+end # Fragments
+end # SequenceRange
+end # Range
+end # RestrictionEnzyme
+end # Bio

data/lib/bio/util/restriction_enzyme/range/vertical_cut_range.rb

@@ -0,0 +1,69 @@
+# bio/util/restriction_enzyme/range/vertical_cut_range.rb -
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+class Range
+
+# FIXME docs are kind of out of date.  Change this to VerticalAndHorizontalCutRange
+class VerticalCutRange < CutRange
+  attr_reader :p_cut_left, :p_cut_right
+  attr_reader :c_cut_left, :c_cut_right
+  attr_reader :min, :max
+  attr_reader :range
+
+  # VerticalCutRange provides an extremely raw, yet precise, method of
+  # defining the location of cuts on primary and complementary sequences.
+  #
+  # Many VerticalCutRange objects are used with HorizontalCutRange objects
+  # to be contained in CutRanges to define the cut pattern that a
+  # specific enzyme may make.
+  #
+  # VerticalCutRange takes up to four possible cuts, two on the primary
+  # strand and two on the complementary strand.  In typical usage
+  # you will want to make a single cut on the primary strand and a single
+  # cut on the complementary strand.
+  #
+  # However, you can construct it with whatever cuts you desire to accomadate
+  # the most eccentric of imaginary restriction enzymes.
+  #
+  # ---
+  # *Arguments*
+  # * +p_cut_left+: (_optional_) Left-most cut on the primary strand.  +nil+ to skip
+  # * +p_cut_right+: (_optional_) Right-most cut on the primary strand.  +nil+ to skip
+  # * +c_cut_left+: (_optional_) Left-most cut on the complementary strand.  +nil+ to skip
+  # * +c_cut_right+: (_optional_) Right-most cut on the complementary strand.  +nil+ to skip
+  # *Returns*:: nothing
+  def initialize( p_cut_left=nil, p_cut_right=nil, c_cut_left=nil, c_cut_right=nil )
+    @p_cut_left = p_cut_left
+    @p_cut_right = p_cut_right
+    @c_cut_left = c_cut_left
+    @c_cut_right = c_cut_right
+
+    a = [@p_cut_left, @c_cut_left, @p_cut_right, @c_cut_right]
+    a.delete(nil)
+    a.sort!
+    @min = a.first
+    @max = a.last
+
+    @range = nil
+    @range = (@min..@max) unless @min == nil or @max == nil
+    return
+  end
+
+  # Check if a location falls within the minimum or maximum values of this
+  # range.
+  #
+  # ---
+  # *Arguments*
+  # * +i+: Location to check if it is included in the range
+  # *Returns*:: +true+ _or_ +false+
+  def include?(i)
+    return false if @range == nil
+    @range.include?(i)
+  end
+end # VerticalCutRange
+end # Range
+end # RestrictionEnzyme
+end # Bio

data/lib/bio/util/restriction_enzyme/single_strand.rb

@@ -0,0 +1,193 @@
+# bio/util/restriction_enzyme/single_strand.rb - Single strand of a restriction enzyme sequence
+
+require 'bio/util/restriction_enzyme'
+require 'bio/sequence'
+
+module Bio
+class RestrictionEnzyme
+
+# A single strand of restriction enzyme sequence pattern with a 5' to 3'
+# orientation.
+#
+# DoubleStranded puts the SingleStrand and SingleStrandComplement together to
+# create the sequence pattern with cuts on both strands.
+#
+class SingleStrand < Bio::Sequence::NA
+
+  autoload :CutLocationsInEnzymeNotation, 'bio/util/restriction_enzyme/single_strand/cut_locations_in_enzyme_notation'
+
+  include CutSymbol
+  include StringFormatting
+
+  # The cut locations in enzyme notation. Contains a
+  # CutLocationsInEnzymeNotation object set when the SingleStrand
+  # object is initialized.
+  attr_reader :cut_locations_in_enzyme_notation
+
+  # The cut locations transformed from enzyme index notation to 0-based
+  # array index notation.  Contains an Array.
+  attr_reader :cut_locations
+
+  # Orientation of the strand, 5' to 3'
+  def orientation; [5,3]; end
+
+  # Constructor for a Bio::RestrictionEnzyme::StingleStrand object.
+  #
+  # A single strand of restriction enzyme sequence pattern with a 5' to 3' orientation.
+  #
+  # ---
+  # *Arguments*
+  # * +sequence+: (_required_) The enzyme sequence.
+  # * +c+: (_optional_) Cut locations in enzyme notation.
+  #   See Bio::RestrictionEnzyme::SingleStrand::CutLocationsInEnzymeNotation
+  #
+  # *Constraints*
+  # * +sequence+ cannot contain immediately adjacent cut symbols (ex. atg^^c).
+  # * +c+ is in enzyme index notation and therefore cannot contain a 0.
+  # * If +c+ is omitted, +sequence+ must contain a cut symbol.
+  # * You cannot provide both a sequence with cut symbols and provide cut locations - ambiguous.
+  #
+  # +sequence+ must be a kind of:
+  # * String
+  # * Bio::Sequence::NA
+  # * Bio::RestrictionEnzyme::SingleStrand
+  #
+  # +c+ must be a kind of:
+  # * Bio::RestrictionEnzyme::SingleStrand::CutLocationsInEnzymeNotation
+  # * Integer, one or more
+  # * Array
+  #
+  # *Returns*:: nothing
+  def initialize( sequence, *c )
+    c.flatten! # if an array was supplied as an argument
+  # NOTE t| 2009-09-19 commented out for library efficiency
+    # validate_args(sequence, c)
+    sequence = sequence.downcase
+
+    if sequence =~ re_cut_symbol
+      @cut_locations_in_enzyme_notation = CutLocationsInEnzymeNotation.new( strip_padding(sequence) )
+    else
+      @cut_locations_in_enzyme_notation = CutLocationsInEnzymeNotation.new( c )
+    end
+
+    @stripped = Bio::Sequence::NA.new( strip_cuts_and_padding( sequence ) )
+    super( pattern )
+    @cut_locations = @cut_locations_in_enzyme_notation.to_array_index
+    return
+  end
+
+  # Returns true if this enzyme is palindromic with its reverse complement.
+  # Does not report if the +cut_locations+ are palindromic or not.
+  #
+  # Examples:
+  # * This would be palindromic:
+  #     5' - ATGCAT - 3'
+  #          TACGTA
+  #
+  # * This would not be palindromic:
+  #     5' - ATGCGTA - 3'
+  #          TACGCAT
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: +true+ _or_ +false+
+  def palindromic?
+    @stripped.reverse_complement == @stripped
+  end
+
+  # Sequence pattern with no cut symbols and no 'n' padding.
+  # * <code>SingleStrand.new('garraxt', [-2, 1, 7]).stripped  # => "garraxt"</code>
+  attr_reader :stripped
+
+  # The sequence with 'n' padding and cut symbols.
+  # * <code>SingleStrand.new('garraxt', [-2, 1, 7]).with_cut_symbols  # => "n^ng^arraxt^n"</code>
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: The sequence with 'n' padding and cut symbols.
+  def with_cut_symbols
+    s = pattern
+    @cut_locations_in_enzyme_notation.to_array_index.sort.reverse.each { |c| s.insert(c+1, cut_symbol) }
+    s
+  end
+
+  # The sequence with 'n' padding on the left and right for cuts larger than the sequence.
+  # * <code>SingleStrand.new('garraxt', [-2, 1, 7]).pattern  # => "nngarraxtn"</code>
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: The sequence with 'n' padding on the left and right for cuts larger than the sequence.
+  def pattern
+    return stripped if @cut_locations_in_enzyme_notation.min == nil
+    left = (@cut_locations_in_enzyme_notation.min < 0 ? 'n' * @cut_locations_in_enzyme_notation.min.abs : '')
+
+    # Add one more 'n' if a cut is at the last position
+    right = ( (@cut_locations_in_enzyme_notation.max >= @stripped.length) ? ('n' * (@cut_locations_in_enzyme_notation.max - @stripped.length + 1)) : '')
+    [left, stripped, right].join('')
+  end
+
+  # The sequence with 'n' pads, cut symbols, and spacing for alignment.
+  # * <code>SingleStrand.new('garraxt', [-2, 1, 7]).with_spaces # => "n^n g^a r r a x t^n"</code>
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: The sequence with 'n' pads, cut symbols, and spacing for alignment.
+  def with_spaces
+    add_spacing( with_cut_symbols )
+  end
+
+  #########
+  protected
+  #########
+
+  def validate_args( input_pattern, input_cut_locations )
+    unless input_pattern.kind_of?(String)
+      err = "input_pattern is not a String, Bio::Sequence::NA, or Bio::RestrictionEnzyme::SingleStrand object\n"
+      err += "pattern: #{input_pattern}\n"
+      err += "class: #{input_pattern.class}"
+      raise ArgumentError, err
+    end
+
+    if ( input_pattern =~ re_cut_symbol ) and !input_cut_locations.empty?
+      err = "Cut symbol found in sequence, but cut locations were also supplied.  Ambiguous.\n"
+      err += "pattern: #{input_pattern}\n"
+      err += "symbol: #{cut_symbol}\n"
+      err += "locations: #{input_cut_locations.inspect}"
+      raise ArgumentError, err
+    end
+
+    input_pattern.each_byte do |c|
+      c = c.chr.downcase
+      unless Bio::NucleicAcid::NAMES.has_key?(c) or c == 'x' or c == 'X' or c == cut_symbol
+        err = "Invalid character in pattern.\n"
+        err += "Not a nucleotide or representation of possible nucleotides.  See Bio::NucleicAcid::NAMES for more information.\n"
+        err += "char: #{c}\n"
+        err += "input_pattern: #{input_pattern}"
+        raise ArgumentError, err
+      end
+    end
+  end
+
+  # Tadayoshi Funaba's method as discussed in Programming Ruby 2ed, p390
+  def self.once(*ids)
+    for id in ids
+      module_eval <<-"end;"
+        alias_method :__#{id.__id__}__, :#{id.to_s}
+        private :__#{id.__id__}__
+        def #{id.to_s}(*args, &block)
+          (@__#{id.__id__}__ ||= [__#{id.__id__}__(*args, &block)])[0]
+        end
+      end;
+    end
+  end
+  private_class_method :once
+
+  once :pattern, :with_cut_symbols, :with_spaces, :to_re
+
+end # SingleStrand
+end # RestrictionEnzyme
+end # Bio