ngoto-bio 1.2.9.9001

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

@@ -0,0 +1,257 @@
+#
+# bio/util/restriction_enzyme/range/sequence_range.rb - A defined range over a nucleotide sequence
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id: sequence_range.rb,v 1.9 2007/07/16 19:28:48 k Exp $
+#
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+class Range
+
+  autoload :CutRange,                'bio/util/restriction_enzyme/range/cut_range'
+  autoload :CutRanges,               'bio/util/restriction_enzyme/range/cut_ranges'
+  autoload :HorizontalCutRange,      'bio/util/restriction_enzyme/range/horizontal_cut_range'
+  autoload :VerticalCutRange,        'bio/util/restriction_enzyme/range/vertical_cut_range'
+
+# A defined range over a nucleotide sequence.
+#
+# This class accomadates having cuts defined on a sequence and returning the
+# fragments made by those cuts.
+class SequenceRange
+
+  autoload :Fragment,                'bio/util/restriction_enzyme/range/sequence_range/fragment'
+  autoload :Fragments,               'bio/util/restriction_enzyme/range/sequence_range/fragments'
+  autoload :CalculatedCuts,          'bio/util/restriction_enzyme/range/sequence_range/calculated_cuts'
+
+  # Left-most index of primary strand
+  attr_reader :p_left
+  
+  # Right-most index of primary strand
+  attr_reader :p_right
+  
+  # Left-most index of complementary strand
+  attr_reader :c_left
+  
+  # Right-most index of complementary strand
+  attr_reader :c_right
+
+  # Left-most index of DNA sequence
+  attr_reader :left
+  
+  # Right-most index of DNA sequence
+  attr_reader :right
+  
+  # Size of DNA sequence
+  attr_reader :size
+  
+  # CutRanges in this SequenceRange
+  attr_reader :cut_ranges
+
+  def initialize( p_left = nil, p_right = nil, c_left = nil, c_right = nil )
+    raise ArgumentError if p_left == nil and c_left == nil
+    raise ArgumentError if p_right == nil and c_right == nil
+    (raise ArgumentError unless p_left <= p_right) unless p_left == nil or p_right == nil
+    (raise ArgumentError unless c_left <= c_right) unless c_left == nil or c_right == nil
+
+    @p_left, @p_right, @c_left, @c_right = p_left, p_right, c_left, c_right
+    @left = [p_left, c_left].compact.sort.first
+    @right = [p_right, c_right].compact.sort.last
+    @size = (@right - @left) + 1 unless @left == nil or @right == nil
+    @cut_ranges = CutRanges.new
+    @__fragments_current = false
+  end
+
+
+  # If the first object is HorizontalCutRange or VerticalCutRange, that is
+  # added to the SequenceRange.  Otherwise this method
+  # builds a VerticalCutRange object and adds it to the SequenceRange.
+  # 
+  # Note:
+  # Cut occurs immediately after the index supplied.
+  # For example, a cut at '0' would mean a cut occurs between bases 0 and 1.
+  #
+  # ---
+  # *Arguments*
+  # * +p_cut_left+: (_optional_) Left-most cut on the primary strand *or* a CutRange object.  +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 add_cut_range( p_cut_left=nil, p_cut_right=nil, c_cut_left=nil, c_cut_right=nil )
+    @__fragments_current = false
+    if p_cut_left.kind_of? CutRange # shortcut
+      @cut_ranges << p_cut_left
+    else
+      [p_cut_left, p_cut_right, c_cut_left, c_cut_right].each { |n| (raise IndexError unless n >= @left and n <= @right) unless n == nil }
+      @cut_ranges << VerticalCutRange.new( p_cut_left, p_cut_right, c_cut_left, c_cut_right )
+    end
+  end
+
+  # Add a series of CutRange objects (HorizontalCutRange or VerticalCutRange).
+  #
+  # ---
+  # *Arguments*
+  # * +cut_ranges+: A series of CutRange objects
+  # *Returns*:: nothing
+  def add_cut_ranges(*cut_ranges)
+    cut_ranges.flatten.each do |cut_range|
+      raise TypeError, "Not of type CutRange" unless cut_range.kind_of? CutRange
+      self.add_cut_range( cut_range )
+    end
+  end
+
+  # Builds a HorizontalCutRange object and adds it to the SequenceRange.
+  #
+  # ---
+  # *Arguments*
+  # * +left+: Left-most cut
+  # * +right+: (_optional_) Right side - by default this equals the left side, default is recommended.
+  # *Returns*:: nothing
+  def add_horizontal_cut_range( left, right=left )
+    @__fragments_current = false
+    @cut_ranges << HorizontalCutRange.new( left, right )
+  end
+  
+  # A Bio::RestrictionEnzyme::Range::SequenceRange::Bin holds an +Array+ of 
+  # indexes for the primary and complement strands (+p+ and +c+ accessors).
+  # 
+  # Example hash with Bin values:
+  #   {0=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[0, 1], p=[0]>,
+  #    2=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[], p=[1, 2]>,
+  #    3=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[2, 3], p=[]>,
+  #    4=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[4, 5], p=[3, 4, 5]>}
+  #
+  # Note that the bin cannot be easily stored as a range since there may be
+  # nucleotides excised in the middle of a range.
+  #
+  # TODO: Perhaps store the bins as one-or-many ranges since missing
+  # nucleotides due to enzyme cutting is a special case.
+  Bin = Struct.new(:c, :p)
+
+  # Calculates the fragments over this sequence range as defined after using
+  # the methods add_cut_range, add_cut_ranges, and/or add_horizontal_cut_range
+  #
+  # Example return value:
+  #   [#<Bio::RestrictionEnzyme::Range::SequenceRange::Fragment:0x277bdc
+  #     @complement_bin=[0, 1],
+  #     @primary_bin=[0]>,
+  #    #<Bio::RestrictionEnzyme::Range::SequenceRange::Fragment:0x277bc8
+  #     @complement_bin=[],
+  #     @primary_bin=[1, 2]>,
+  #    #<Bio::RestrictionEnzyme::Range::SequenceRange::Fragment:0x277bb4
+  #     @complement_bin=[2, 3],
+  #     @primary_bin=[]>,
+  #    #<Bio::RestrictionEnzyme::Range::SequenceRange::Fragment:0x277ba0
+  #     @complement_bin=[4, 5],
+  #     @primary_bin=[3, 4, 5]>]
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: Bio::RestrictionEnzyme::Range::SequenceRange::Fragments
+  def fragments
+    return @__fragments if @__fragments_current == true
+    @__fragments_current = true
+    
+    num_txt = '0123456789'
+    num_txt_repeat = (num_txt * ( @size / num_txt.size.to_f ).ceil)[0..@size-1]
+    fragments = Fragments.new(num_txt_repeat, num_txt_repeat)
+
+    cc = Bio::RestrictionEnzyme::Range::SequenceRange::CalculatedCuts.new(@size)
+    cc.add_cuts_from_cut_ranges(@cut_ranges)
+    cc.remove_incomplete_cuts
+    
+    create_bins(cc).sort.each { |k, bin| fragments << Fragment.new( bin.p, bin.c ) }
+    @__fragments = fragments
+    return fragments
+  end
+  
+  #########
+  protected
+  #########
+  
+  # Example:
+  #   cc = Bio::RestrictionEnzyme::Range::SequenceRange::CalculatedCuts.new(@size)
+  #   cc.add_cuts_from_cut_ranges(@cut_ranges)
+  #   cc.remove_incomplete_cuts
+  #   bins = create_bins(cc)
+  # 
+  # Example return value:
+  #   {0=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[0, 1], p=[0]>,
+  #    2=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[], p=[1, 2]>,
+  #    3=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[2, 3], p=[]>,
+  #    4=>#<struct Bio::RestrictionEnzyme::Range::SequenceRange::Bin c=[4, 5], p=[3, 4, 5]>}
+  #
+  # ---
+  # *Arguments*
+  # * +cc+: Bio::RestrictionEnzyme::Range::SequenceRange::CalculatedCuts
+  # *Returns*:: +Hash+ Keys are unique, values are Bio::RestrictionEnzyme::Range::SequenceRange::Bin objects filled with indexes of the sequence locations they represent.
+  def create_bins(cc)
+    p_cut = cc.vc_primary
+    c_cut = cc.vc_complement
+    h_cut = cc.hc_between_strands
+    
+    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
+  
+      unique_id = 0
+    else
+      p_cut.unshift(-1) unless p_cut.include?(-1)
+      c_cut.unshift(-1) unless c_cut.include?(-1)
+      unique_id = -1
+    end
+
+    p_bin_id = c_bin_id = unique_id
+    bins = {}
+    setup_new_bin(bins, unique_id)
+
+    -1.upto(@size-1) do |idx| # NOTE - circular, for the future - should '-1' be replace with 'unique_id'?
+      
+      # if bin_ids are out of sync but the strands are attached
+      if (p_bin_id != c_bin_id) and !h_cut.include?(idx)
+        min_id, max_id = [p_bin_id, c_bin_id].sort
+        bins.delete(max_id)
+        p_bin_id = c_bin_id = min_id
+      end
+
+      bins[ p_bin_id ].p << idx
+      bins[ c_bin_id ].c << idx
+      
+      if p_cut.include? idx
+        p_bin_id = (unique_id += 1)
+        setup_new_bin(bins, p_bin_id)
+      end
+
+      if c_cut.include? idx             # repetition
+        c_bin_id = (unique_id += 1)     # repetition
+        setup_new_bin(bins, c_bin_id)   # repetition
+      end                               # repetition
+       
+    end
+  
+    # Bin "-1" is an easy way to indicate the start of a strand just in case
+    # there is a horizontal cut at position 0
+    bins.delete(-1) unless @circular
+    bins
+  end
+  
+  # Modifies bins in place by creating a new element with key bin_id and
+  # initializing the bin.
+  def setup_new_bin(bins, bin_id)
+    bins[ bin_id ] = Bin.new
+    bins[ bin_id ].p = []
+    bins[ bin_id ].c = []
+  end
+  
+end # SequenceRange
+end # Range
+end # RestrictionEnzyme
+end # Bio

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

@@ -0,0 +1,77 @@
+#
+# bio/util/restriction_enzyme/range/vertical_cut_range.rb - 
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id: vertical_cut_range.rb,v 1.5 2007/07/16 19:28:48 k Exp $
+#
+
+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/cut_locations_in_enzyme_notation.rb

@@ -0,0 +1,135 @@
+#
+# bio/util/restriction_enzyme/single_strand/cut_locations_in_enzyme_notation.rb - The cut locations, in enzyme notation
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id: cut_locations_in_enzyme_notation.rb,v 1.7 2007/07/16 19:28:48 k Exp $
+#
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+class SingleStrand
+
+# Stores the cut location in thier enzyme index notation
+# 
+# May be initialized with a series of cuts or an enzyme pattern marked
+# with cut symbols.
+# 
+# Enzyme index notation:: 1.._n_, value before 1 is -1
+#
+# example:: [-3][-2][-1][1][2][3][4][5]
+#
+# Negative values are used to indicate when a cut may occur at a specified
+# distance before the sequence begins.  This would be padded with 'n'
+# nucleotides to represent wildcards.
+# 
+# Notes:
+# * <code>0</code> is invalid as it does not refer to any index 
+# * +nil+ is not allowed here as it has no meaning
+# * +nil+ values are kept track of in DoubleStranded::CutLocations as they
+#   need a reference point on the correlating strand.  In 
+#   DoubleStranded::CutLocations +nil+ represents no cut or a partial 
+#   digestion.
+# 
+class CutLocationsInEnzymeNotation < Array
+  include CutSymbol
+  extend CutSymbol
+
+  # First cut, in enzyme-index notation
+  attr_reader :min
+  
+  # Last cut, in enzyme-index notation
+  attr_reader :max
+
+  # Constructor for CutLocationsInEnzymeNotation
+  #
+  # ---
+  # *Arguments*
+  # * +a+: Locations of cuts represented as a string with cuts or an array of values
+  # Examples:
+  # * n^ng^arraxt^n
+  # * 2
+  # * -1, 5
+  # * [-1, 5]
+  # *Returns*:: nothing
+  def initialize(*a)
+    a.flatten! # in case an array was passed as an argument
+
+    if a.size == 1 and a[0].kind_of? String and a[0] =~ re_cut_symbol
+      # Initialize with a cut symbol pattern such as 'n^ng^arraxt^n'
+      s = a[0]
+      a = []
+      i = -( s.tr(cut_symbol, '') =~ %r{[^n]} )  # First character that's not 'n'
+      s.each_byte { |c| (a << i; next) if c.chr == cut_symbol; i += 1 }
+      a.collect! { |n| n <= 0 ? n-1 : n } # 0 is not a valid enzyme index, decrement from 0 and all negative
+    else
+      a.collect! { |n| n.to_i } # Cut locations are always integers
+    end
+
+    validate_cut_locations( a )
+    super(a)
+    self.sort!
+    @min = self.first
+    @max = self.last
+    self.freeze
+  end
+
+  # Transform the cut locations from enzyme index notation to 0-based index
+  # notation.
+  #
+  #   input -> output
+  #   [  1, 2, 3 ] -> [ 0, 1, 2 ]
+  #   [  1, 3, 5 ] -> [ 0, 2, 4 ]
+  #   [ -1, 1, 2 ] -> [ 0, 1, 2 ]
+  #   [ -2, 1, 3 ] -> [ 0, 2, 4 ]
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: +Array+ of cuts in 0-based index notation
+  def to_array_index
+    return [] if @min == nil
+    if @min < 0
+      calc = lambda do |n| 
+        n -= 1 unless n < 0
+        n + @min.abs
+      end
+    else
+      calc = lambda { |n| n - 1 }
+    end
+    self.collect(&calc)
+  end
+
+  #########
+  protected
+  #########
+
+  def validate_cut_locations( input_cut_locations )
+    unless input_cut_locations == input_cut_locations.uniq
+      err = "The cut locations supplied contain duplicate values.  Redundant / undefined meaning.\n"
+      err += "cuts: #{input_cut_locations.inspect}\n"
+      err += "unique: #{input_cut_locations.uniq.inspect}"
+      raise ArgumentError, err
+    end
+
+    if input_cut_locations.include?(nil)
+      err = "The cut locations supplied contained a nil.  nil has no index for enzyme notation, alternative meaning is 'no cut'.\n"
+      err += "cuts: #{input_cut_locations.inspect}"
+      raise ArgumentError, err
+    end
+
+    if input_cut_locations.include?(0)
+      err = "The cut locations supplied contained a '0'.  '0' has no index for enzyme notation, alternative meaning is 'no cut'.\n"
+      err += "cuts: #{input_cut_locations.inspect}"
+      raise ArgumentError, err
+    end
+
+  end
+end # CutLocationsInEnzymeNotation
+end # SingleStrand
+end # RestrictionEnzyme
+end # Bio

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

@@ -0,0 +1,200 @@
+#
+# bio/util/restriction_enzyme/single_strand.rb - Single strand of a restriction enzyme sequence
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id:$
+#
+
+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
+    validate_args(sequence, c)
+    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

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

@@ -0,0 +1,23 @@
+#
+# bio/util/restriction_enzyme/single_strand_complement.rb - Single strand restriction enzyme sequence in complement orientation
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id: single_strand_complement.rb,v 1.5 2007/07/16 19:28:48 k Exp $
+#
+
+require 'bio/util/restriction_enzyme'
+
+module Bio
+class RestrictionEnzyme
+
+# A single strand of restriction enzyme sequence pattern with a 3' to 5' orientation.
+#
+class SingleStrandComplement < SingleStrand
+  # Orientation of the strand, 3' to 5'
+  def orientation; [3, 5]; end
+end # SingleStrandComplement
+end # RestrictionEnzyme
+end # Bio