jandot-bio 1.2.1

data/lib/bio/util/restriction_enzyme.rb

@@ -0,0 +1,228 @@
+#
+# bio/util/restriction_enzyme.rb - Digests DNA based on restriction enzyme cut patterns
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id: restriction_enzyme.rb,v 1.16 2007/07/16 19:28:48 k Exp $
+#
+
+module Bio #:nodoc:
+
+  autoload :REBASE, 'bio/db/rebase'
+
+# = Description
+# 
+# Bio::RestrictionEnzyme allows you to fragment a DNA strand using one
+# or more restriction enzymes.  Bio::RestrictionEnzyme is aware that
+# multiple enzymes may be competing for the same recognition site and
+# returns the various possible fragmentation patterns that result in
+# such circumstances.
+# 
+# When using Bio::RestrictionEnzyme you may simply use the name of common
+# enzymes to cut your sequence or you may construct your own unique enzymes 
+# to use.
+#
+# Visit the documentaion for individual classes for more information.
+#
+# An examination of the unit tests will also reveal several interesting uses
+# for the curious programmer.
+# 
+# = Usage
+# 
+# == Basic
+#
+# EcoRI cut pattern:
+#   G|A A T T C
+#    +-------+
+#   C T T A A|G
+# 
+# This can also be written as:
+#   G^AATTC
+#
+# Note that to use the method +cut_with_enzyme+ from a Bio::Sequence object 
+# you currently must +require+ +bio/util/restriction_enzyme+ directly.  If
+# instead you're going to directly call Bio::RestrictionEnzyme::Analysis
+# then only +bio+ needs to be +required+.
+# 
+#   require 'bio'
+#   require 'bio/util/restriction_enzyme'
+#   
+#   seq = Bio::Sequence::NA.new('gaattc')
+#   cuts = seq.cut_with_enzyme('EcoRI')
+#   cuts.primary                        # => ["aattc", "g"]
+#   cuts.complement                     # => ["cttaa", "g"]
+#   cuts.inspect                        # => "[#<struct Bio::RestrictionEnzyme::Fragment primary=\"g    \", complement=\"cttaa\">, #<struct Bio::RestrictionEnzyme::Fragment primary=\"aattc\", complement=\"    g\">]"
+#   
+#   seq = Bio::Sequence::NA.new('gaattc')
+#   cuts = seq.cut_with_enzyme('g^aattc')
+#   cuts.primary                        # => ["aattc", "g"]
+#   cuts.complement                     # => ["cttaa", "g"]
+#   
+#   seq = Bio::Sequence::NA.new('gaattc')
+#   cuts = seq.cut_with_enzyme('g^aattc', 'gaatt^c')
+#   cuts.primary                        # => ["aattc", "c", "g", "gaatt"]
+#   cuts.complement                     # => ["c", "cttaa", "g", "ttaag"]
+#   
+#   seq = Bio::Sequence::NA.new('gaattcgaattc')
+#   cuts = seq.cut_with_enzyme('EcoRI')
+#   cuts.primary                        # => ["aattc", "aattcg", "g"]
+#   cuts.complement                     # => ["cttaa", "g", "gcttaa"]
+#   
+#   seq = Bio::Sequence::NA.new('gaattcgggaattc')
+#   cuts = seq.cut_with_enzyme('EcoRI')
+#   cuts.primary                        # => ["aattc", "aattcggg", "g"]
+#   cuts.complement                     # => ["cttaa", "g", "gcccttaa"]
+#   
+#   cuts[0].inspect                     # => "#<struct Bio::RestrictionEnzyme::Fragment primary=\"g    \", complement=\"cttaa\">"
+#   
+#   cuts[0].primary                     # => "g    "
+#   cuts[0].complement                  # => "cttaa"
+#   
+#   cuts[1].primary                     # => "aattcggg    "
+#   cuts[1].complement                  # => "    gcccttaa"
+#   
+#   cuts[2].primary                     # => "aattc"
+#   cuts[2].complement                  # => "    g"
+#   
+# == Advanced
+#
+#   require 'bio'
+#   
+#   enzyme_1 = Bio::RestrictionEnzyme.new('anna', [1,1], [3,3])
+#   enzyme_2 = Bio::RestrictionEnzyme.new('gg', [1,1])
+#   a = Bio::RestrictionEnzyme::Analysis.cut('agga', enzyme_1, enzyme_2)
+#   a.primary                           # => ["a", "ag", "g", "ga"]
+#   a.complement                        # => ["c", "ct", "t", "tc"]
+#   
+#   a[0].primary                        # => "ag"
+#   a[0].complement                     # => "tc"
+#   
+#   a[1].primary                        # => "ga"
+#   a[1].complement                     # => "ct"
+#   
+#   a[2].primary                        # => "a"
+#   a[2].complement                     # => "t"
+#   
+#   a[3].primary                        # => "g"
+#   a[3].complement                     # => "c"
+# 
+# = Todo / under development
+# 
+# * Circular DNA cutting
+#
+
+class RestrictionEnzyme
+
+  #require 'bio/util/restriction_enzyme/cut_symbol'
+
+  autoload :CutSymbol,               'bio/util/restriction_enzyme/cut_symbol'
+  autoload :StringFormatting,        'bio/util/restriction_enzyme/string_formatting'
+  autoload :SingleStrand,            'bio/util/restriction_enzyme/single_strand'
+  autoload :SingleStrandComplement,  'bio/util/restriction_enzyme/single_strand_complement'
+  autoload :DoubleStranded,          'bio/util/restriction_enzyme/double_stranded'
+  autoload :Analysis,                'bio/util/restriction_enzyme/analysis'
+  autoload :Range,                   'bio/util/restriction_enzyme/range/sequence_range'
+
+  include CutSymbol
+  extend CutSymbol
+
+  # See Bio::RestrictionEnzyme::DoubleStranded.new for more information.
+  #
+  # ---
+  # *Arguments*
+  # * +users_enzyme_or_rebase_or_pattern+: One of three possible parameters:  The name of an enzyme, a REBASE::EnzymeEntry object, or a nucleotide pattern with a cut mark.
+  # * +cut_locations+: The cut locations in enzyme index notation.
+  # *Returns*:: Bio::RestrictionEnzyme::DoubleStranded
+  #--
+  # Factory for DoubleStranded
+  #++
+  def self.new(users_enzyme_or_rebase_or_pattern, *cut_locations)
+    DoubleStranded.new(users_enzyme_or_rebase_or_pattern, *cut_locations)
+  end
+
+  # REBASE enzyme data information
+  #
+  # Returns a Bio::REBASE object loaded with all of the enzyme data on file.
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: Bio::REBASE
+  def self.rebase
+    enzymes_yaml_file = File.join(File.dirname(File.expand_path(__FILE__)), 'restriction_enzyme', 'enzymes.yaml')
+    @@rebase_enzymes ||= Bio::REBASE.load_yaml(enzymes_yaml_file)
+    @@rebase_enzymes
+  end
+
+  # Check if supplied name is the name of an available enzyme
+  #
+  # See Bio::REBASE.enzyme_name?
+  #
+  # ---
+  # *Arguments*
+  # * +name+: Enzyme name
+  # *Returns*:: +true+ _or_ +false+
+  def self.enzyme_name?( name )
+    self.rebase.enzyme_name?(name)
+  end
+
+  # See Bio::RestrictionEnzyme::Analysis.cut
+  def self.cut( sequence, enzymes )
+    Bio::RestrictionEnzyme::Analysis.cut( sequence, enzymes )
+  end
+
+  # A Bio::RestrictionEnzyme::Fragment is a DNA fragment composed of fused primary and 
+  # complementary strands that would be found floating in solution after a full
+  # sequence is digested by one or more RestrictionEnzymes.
+  #
+  # You will notice that either the primary or complement strand will be
+  # padded with spaces to make them line up according to the original DNA
+  # configuration before they were cut.
+  #
+  # Example:
+  #
+  # Fragment 1:
+  #   primary =    "attaca"
+  #   complement = "  atga"
+  # 
+  # Fragment 2:
+  #   primary =    "g  "
+  #   complement = "cta"
+  # 
+  # View these with the +primary+ and +complement+ methods.
+  # 
+  # Bio::RestrictionEnzyme::Fragment is a simple +Struct+ object.
+  # 
+  # Note: unrelated to Bio::RestrictionEnzyme::Range::SequenceRange::Fragment
+  Fragment = Struct.new(:primary, :complement, :p_left, :p_right, :c_left, :c_right)
+
+  # Bio::RestrictionEnzyme::Fragments inherits from +Array+.
+  #
+  # Bio::RestrictionEnzyme::Fragments is a container for Fragment objects.  It adds the
+  # methods +primary+ and +complement+ which returns an +Array+ of all
+  # respective strands from it's Fragment members in alphabetically sorted 
+  # order.  Note that it will
+  # not return duplicate items and does not return the spacing/padding 
+  # that you would
+  # find by accessing the members directly.
+  # 
+  # Example:
+  #
+  #   primary = ['attaca', 'g']
+  #   complement = ['atga', 'cta']
+  #
+  # Note: unrelated to Bio::RestrictionEnzyme::Range::SequenceRange::Fragments
+  class Fragments < Array
+    def primary; strip_and_sort(:primary); end
+    def complement; strip_and_sort(:complement); end
+
+    protected
+
+    def strip_and_sort( sym_strand )
+      self.map {|uf| uf.send( sym_strand ).tr(' ', '') }.sort
+    end
+  end
+end # RestrictionEnzyme
+end # Bio

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

@@ -0,0 +1,249 @@
+#
+# bio/util/restriction_enzyme/analysis.rb - Does the work of fragmenting the DNA from the enzymes
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+#  $Id: analysis.rb,v 1.20 2007/07/16 19:28:48 k Exp $
+#
+
+require 'bio/util/restriction_enzyme'
+require 'bio/util/restriction_enzyme/analysis_basic'
+
+module Bio
+class RestrictionEnzyme
+
+class Analysis
+
+  # See cut instance method
+  def self.cut( sequence, *args )
+    self.new.cut( sequence, *args )
+  end
+
+  # See main documentation for Bio::RestrictionEnzyme
+  #
+  #
+  # +cut+ takes into account
+  # permutations of cut variations based on competitiveness of enzymes for an
+  # enzyme cutsite or enzyme bindsite on a sequence.
+  #
+  # Example:
+  #
+  # FIXME add output
+  #
+  #   Bio::RestrictionEnzyme::Analysis.cut('gaattc', 'EcoRI')
+  #
+  # _same as:_
+  #
+  #   Bio::RestrictionEnzyme::Analysis.cut('gaattc', 'g^aattc')
+  # ---
+  # *Arguments*
+  # * +sequence+: +String+ kind of object that will be used as a nucleic acid sequence.
+  # * +args+: Series of enzyme names, enzymes sequences with cut marks, or RestrictionEnzyme objects.
+  # *Returns*:: Bio::RestrictionEnzyme::Fragments object populated with Bio::RestrictionEnzyme::Fragment objects.   (Note: unrelated to Bio::RestrictionEnzyme::Range::SequenceRange::Fragments) or a +Symbol+ containing an error code
+  def cut( sequence, *args )
+    view_ranges = false
+    
+    args.select { |i| i.class == Hash }.each do |hsh|
+      hsh.each do |key, value|
+        if key == :view_ranges
+          unless ( value.kind_of?(TrueClass) or value.kind_of?(FalseClass) )
+            raise ArgumentError, "view_ranges must be set to true or false, currently #{value.inspect}."
+          end
+          view_ranges = value
+        end
+      end
+    end
+    
+    res = cut_and_return_by_permutations( sequence, *args )
+    return res if res.class == Symbol
+    # Format the fragments for the user
+    fragments_for_display( res, view_ranges )
+  end
+
+  #########
+  protected
+  #########
+  
+  # See cut instance method
+  #
+  # ---
+  # *Arguments*
+  # * +sequence+: +String+ kind of object that will be used as a nucleic acid sequence.
+  # * +args+: Series of enzyme names, enzymes sequences with cut marks, or RestrictionEnzyme objects.
+  # May also supply a +Hash+ with the key ":max_permutations" to specificy how many permutations are allowed - a value of 0 indicates no permutations are allowed.
+  # *Returns*:: +Hash+ Keys are a permutation ID, values are SequenceRange objects that have cuts applied.
+  # _also_ may return the +Symbol+ ':sequence_empty', ':no_cuts_found', or ':too_many_permutations'
+  def cut_and_return_by_permutations( sequence, *args )
+    my_hash = {}
+    maximum_permutations = nil
+
+    hashes_in_args = args.select { |i| i.class == Hash }
+    args.delete_if { |i| i.class == Hash }
+    hashes_in_args.each do |hsh|
+      hsh.each do |key, value|
+        case key
+        when :max_permutations, 'max_permutations', :maximum_permutations, 'maximum_permutations'
+          maximum_permutations = value.to_i unless value == nil
+        when :view_ranges
+        else
+          raise ArgumentError, "Received key #{key.inspect} in argument - I only know the key ':max_permutations' and ':view_ranges' currently.  Hash passed: #{hsh.inspect}"
+        end
+      end
+    end
+    
+    if !sequence.kind_of?(String) or sequence.empty?
+      logger.warn "The supplied sequence is empty." if defined?(logger)
+      return :sequence_empty
+    end
+    sequence = Bio::Sequence::NA.new( sequence )
+    
+    enzyme_actions, initial_cuts = create_enzyme_actions( sequence, *args )
+
+    if enzyme_actions.empty? and initial_cuts.empty?
+      logger.warn "This enzyme does not make any cuts on this sequence." if defined?(logger)
+      return :no_cuts_found
+    end
+
+    # * When enzyme_actions.size is equal to '1' that means there are no permutations.
+    # * If enzyme_actions.size is equal to '2' there is one
+    #   permutation ("[0, 1]")
+    # * If enzyme_actions.size is equal to '3' there are two
+    #   permutations ("[0, 1, 2]")
+    # * and so on..
+    if maximum_permutations and enzyme_actions.size > 1
+      if (enzyme_actions.size - 1) > maximum_permutations.to_i
+        logger.warn "More permutations than maximum, skipping.  Found: #{enzyme_actions.size-1}  Max: #{maximum_permutations.to_i}" if defined?(logger)
+        return :too_many_permutations
+      end
+    end
+    
+    if enzyme_actions.size > 1
+      permutations = permute(enzyme_actions.size)
+      
+      permutations.each do |permutation|
+        previous_cut_ranges = []
+        # Primary and complement strands are both measured from '0' to 'sequence.size-1' here
+        sequence_range = Bio::RestrictionEnzyme::Range::SequenceRange.new( 0, 0, sequence.size-1, sequence.size-1 )
+
+        # Add the cuts to the sequence_range from each enzyme_action contained
+        # in initial_cuts.  These are the cuts that have no competition so are
+        # not subject to permutations.
+        initial_cuts.each do |enzyme_action|
+          enzyme_action.cut_ranges.each do |cut_range|
+            sequence_range.add_cut_range(cut_range)
+          end
+        end
+
+        permutation.each do |id|
+          enzyme_action = enzyme_actions[id]
+
+          # conflict is false if the current enzyme action may cut in it's range.
+          # conflict is true if it cannot due to a previous enzyme action making
+          # a cut where this enzyme action needs a whole recognition site.
+          conflict = false
+
+          # If current size of enzyme_action overlaps with previous cut_range, don't cut
+          # note that the enzyme action may fall in the middle of a previous enzyme action
+          # so all cut locations must be checked that would fall underneath.
+          previous_cut_ranges.each do |cut_range|
+            next unless cut_range.class == Bio::RestrictionEnzyme::Range::VerticalCutRange  # we aren't concerned with horizontal cuts
+            previous_cut_left = cut_range.range.first 
+            previous_cut_right = cut_range.range.last
+
+            # Keep in mind: 
+            # * The cut location is to the immediate right of the base located at the index.
+            #   ex: at^gc -- the cut location is at index 1
+            # * The enzyme action location is located at the base of the index.
+            #   ex: atgc -- 0 => 'a', 1 => 't', 2 => 'g', 3 => 'c'
+            # method create_enzyme_actions has similar commentary if interested
+            if (enzyme_action.right <= previous_cut_left) or
+               (enzyme_action.left > previous_cut_right) or
+               (enzyme_action.left > previous_cut_left and enzyme_action.right <= previous_cut_right) # in between cuts
+              # no conflict
+            else
+              conflict = true
+            end
+          end
+
+          next if conflict == true
+          enzyme_action.cut_ranges.each { |cut_range| sequence_range.add_cut_range(cut_range) }
+          previous_cut_ranges += enzyme_action.cut_ranges        
+        end # permutation.each
+
+        # Fill in the source sequence for sequence_range so it knows what bases
+        # to use
+        sequence_range.fragments.primary = sequence
+        sequence_range.fragments.complement = sequence.forward_complement
+        my_hash[permutation] = sequence_range
+      end # permutations.each
+      
+    else # if enzyme_actions.size == 1
+      # no permutations, just do it
+      sequence_range = Bio::RestrictionEnzyme::Range::SequenceRange.new( 0, 0, sequence.size-1, sequence.size-1 )
+      initial_cuts.each { |enzyme_action| enzyme_action.cut_ranges.each { |cut_range| sequence_range.add_cut_range(cut_range) } }
+      sequence_range.fragments.primary = sequence
+      sequence_range.fragments.complement = sequence.forward_complement
+      my_hash[0] = sequence_range
+    end
+
+    my_hash
+  end
+
+
+  # Returns permutation orders for a given number of elements.
+  #
+  # Examples:
+  #   permute(0) # => [[0]]
+  #   permute(1) # => [[0]]
+  #   permute(2) # => [[1, 0], [0, 1]]
+  #   permute(3) # => [[2, 1, 0], [2, 0, 1], [1, 2, 0], [0, 2, 1], [1, 0, 2], [0, 1, 2]]
+  #   permute(4) # => [[3, 2, 1, 0],
+  #                    [3, 2, 0, 1],
+  #                    [3, 1, 2, 0],
+  #                    [3, 0, 2, 1],
+  #                    [3, 1, 0, 2],
+  #                    [3, 0, 1, 2],
+  #                    [2, 3, 1, 0],
+  #                    [2, 3, 0, 1],
+  #                    [1, 3, 2, 0],
+  #                    [0, 3, 2, 1],
+  #                    [1, 3, 0, 2],
+  #                    [0, 3, 1, 2],
+  #                    [2, 1, 3, 0],
+  #                    [2, 0, 3, 1],
+  #                    [1, 2, 3, 0],
+  #                    [0, 2, 3, 1],
+  #                    [1, 0, 3, 2],
+  #                    [0, 1, 3, 2],
+  #                    [2, 1, 0, 3],
+  #                    [2, 0, 1, 3],
+  #                    [1, 2, 0, 3],
+  #                    [0, 2, 1, 3],
+  #                    [1, 0, 2, 3],
+  #                    [0, 1, 2, 3]]
+  #   
+  # ---
+  # *Arguments*
+  # * +count+: +Number+ of different elements to be permuted
+  # * +permutations+: ignore - for the recursive algorithm
+  # *Returns*:: +Array+ of +Array+ objects with different possible permutation orders.  See examples.
+  def permute(count, permutations = [[0]])
+    return permutations if count <= 1
+    new_arrays = []
+    new_array = []
+
+    (permutations[0].size + 1).times do |n|
+      new_array.clear
+      permutations.each { |a| new_array << a.dup }
+      new_array.each { |e| e.insert(n, permutations[0].size) }
+      new_arrays += new_array
+    end
+
+    permute(count-1, new_arrays)
+  end
+
+end # Analysis
+end # RestrictionEnzyme
+end # Bio