bio 1.0.0 → 1.1.0

data/lib/bio/util/color_scheme/turn.rb

@@ -1,36 +1,17 @@
 #
 # bio/util/color_scheme/turn.rb - Color codings for turn propensity
 #
-# Copyright::  Copyright (C) 2005 Trevor Wennblom <trevor@corevx.com>
-# License::    LGPL
-#
-#  $Id: turn.rb,v 1.2 2005/12/13 14:58:07 trevor Exp $
-#
-#
-#--
-#
-#  This library is free software; you can redistribute it and/or
-#  modify it under the terms of the GNU Lesser General Public
-#  License as published by the Free Software Foundation; either
-#  version 2 of the License, or (at your option) any later version.
-#
-#  This library is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#  Lesser General Public License for more details.
-#
-#  You should have received a copy of the GNU Lesser General Public
-#  License along with this library; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
-#
-#++
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
 #
+#  $Id: turn.rb,v 1.4 2007/04/05 23:35:41 trevor Exp $
 #
 
 require 'bio/util/color_scheme'
 
 module Bio::ColorScheme
-  class Turn < Score
+  class Turn < Score #:nodoc:
 
     #########
     protected

data/lib/bio/util/color_scheme/zappo.rb

@@ -1,36 +1,17 @@
 #
 # bio/util/color_scheme/zappo.rb - Zappo color codings for amino acids
 #
-# Copyright::  Copyright (C) 2005 Trevor Wennblom <trevor@corevx.com>
-# License::    LGPL
-#
-#  $Id: zappo.rb,v 1.2 2005/12/13 14:58:07 trevor Exp $
-#
-#
-#--
-#
-#  This library is free software; you can redistribute it and/or
-#  modify it under the terms of the GNU Lesser General Public
-#  License as published by the Free Software Foundation; either
-#  version 2 of the License, or (at your option) any later version.
-#
-#  This library is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#  Lesser General Public License for more details.
-#
-#  You should have received a copy of the GNU Lesser General Public
-#  License along with this library; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
-#
-#++
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
 #
+#  $Id: zappo.rb,v 1.4 2007/04/05 23:35:41 trevor Exp $
 #
 
 require 'bio/util/color_scheme'
 
 module Bio::ColorScheme
-  class Zappo < Simple
+  class Zappo < Simple #:nodoc:
 
     #########
     protected

data/lib/bio/util/contingency_table.rb

@@ -1,12 +1,23 @@
 #
-# = bio/util/contingency_table.rb - Statistical contingency table analysis for aligned sequences
+# bio/util/contingency_table.rb - Statistical contingency table analysis for aligned sequences
 #
-# Copyright::  Copyright (C) 2005 Trevor Wennblom <trevor@corevx.com>
-# License::    LGPL
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
 #
-#  $Id: contingency_table.rb,v 1.4 2006/02/27 13:23:01 k Exp $
+#  $Id: contingency_table.rb,v 1.7 2007/04/05 23:35:41 trevor Exp $
 #
-# == Synopsis
+
+module Bio #:nodoc:
+
+#
+# bio/util/contingency_table.rb - Statistical contingency table analysis for aligned sequences
+#
+# Author::    Trevor Wennblom  <mailto:trevor@corevx.com>
+# Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
+# License::   The Ruby License
+#
+# = Description
 # 
 # The Bio::ContingencyTable class provides basic statistical contingency table
 # analysis for two positions within aligned sequences.
@@ -33,19 +44,18 @@
 # correlation.
 # 
 # 
-# == Further Reading
+# = Further Reading
 # 
 # * http://en.wikipedia.org/wiki/Contingency_table
 # * http://www.physics.csbsju.edu/stats/exact.details.html
 # * Numerical Recipes in C by Press, Flannery, Teukolsky, and Vetterling
-# # 
-# == Usage
+#  
+# = Usage
 # 
 # What follows is an example of ContingencyTable in typical usage
 # analyzing results from a clustal alignment.
 # 
 #   require 'bio'
-#   require 'bio/contingency_table'
 # 
 #   seqs = {}
 #   max_length = 0
@@ -78,9 +88,8 @@
 #   File.new('results.yml', 'a+') { |f| f.puts correlations.to_yaml }
 # 
 # 
-# == Tutorial
-# 
-
+# = Tutorial
+#
 # ContingencyTable returns the statistical significance of change
 # between two positions in an alignment.  If you would like to see how
 # every possible combination of positions in your alignment compares
@@ -209,15 +218,13 @@
 # with statistics, is to increase the sample size.
 # 
 # 
-# == A Note on Efficiency
+# = A Note on Efficiency
 # 
-
 # ContingencyTable is slow.  It involves many calculations for even a
 # seemingly small five-string data set.  Even worse, it's very
 # dependent on matrix traversal, and this is done with two dimensional
 # hashes which dashes any hope of decent speed.
 # 
-
 # Finally, half of the matrix is redundant and positions could be
 # summed with their companion position to reduce calculations.  For
 # example the positions (5,2) and (2,5) could both have their values
@@ -229,30 +236,8 @@
 # is short and to the point in aims of achieving that purpose.  If the
 # BioRuby project moves towards C extensions in the future a
 # professional caliber version will likely be created.
-# 
-# 
-#--
-#
-#  This library is free software; you can redistribute it and/or
-#  modify it under the terms of the GNU Lesser General Public
-#  License as published by the Free Software Foundation; either
-#  version 2 of the License, or (at your option) any later version.
-#
-#  This library is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#  Lesser General Public License for more details.
 #
-#  You should have received a copy of the GNU Lesser General Public
-#  License along with this library; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
-#
-#++
-#
-#
-
-module Bio
-
+  
 class ContingencyTable
   # Since we're making this math-notation friendly here is the layout of @table:
   # * @table[row][column]
@@ -263,6 +248,11 @@ class ContingencyTable
 
   # Create a ContingencyTable that has characters_in_sequence.size rows and
   # characters_in_sequence.size columns for each row
+  #
+  # ---
+  # *Arguments*
+  # * +characters_in_sequences+: (_optional_) The allowable characters that will be present in the aligned sequences.
+  # *Returns*:: +ContingencyTable+ object to be filled with values and calculated upon
   def initialize(characters_in_sequences = nil)
     @characters = ( characters_in_sequences or %w{a c d e f g h i k l m n p q r s t v w y - x u} )
     tmp = Hash[*@characters.collect { |v| [v, 0] }.flatten]
@@ -270,6 +260,11 @@ class ContingencyTable
   end
   
   # Report the sum of all values in a given row
+  #
+  # ---
+  # *Arguments*
+  # * +i+: Row to sum
+  # *Returns*:: +Integer+ sum of row
   def row_sum(i)
     total = 0
     @table[i].each { |k, v| total += v }
@@ -277,6 +272,11 @@ class ContingencyTable
   end
 
   # Report the sum of all values in a given column
+  #
+  # ---
+  # *Arguments*
+  # * +j+: Column to sum
+  # *Returns*:: +Integer+ sum of column
   def column_sum(j)
     total = 0
     @table.each { |row_key, column| total += column[j] }
@@ -287,6 +287,10 @@ class ContingencyTable
   #
   # * This is the same thing as asking for the sum of all values in the table.
   #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: +Integer+ sum of all columns
   def column_sum_all
     total = 0
     @characters.each { |j| total += column_sum(j) }
@@ -297,6 +301,10 @@ class ContingencyTable
   #
   # * This is the same thing as asking for the sum of all values in the table.
   #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: +Integer+ sum of all rows
   def row_sum_all
     total = 0
     @characters.each { |i| total += row_sum(i) }
@@ -304,14 +312,23 @@ class ContingencyTable
   end
   alias table_sum_all row_sum_all
 
+  # Calculate _e_, the _expected_ value.
   #
-  #   e(sub:ij) = (r(sub:i)/N) * (c(sub:j))
-  #
+  # ---
+  # *Arguments*
+  # * +i+: row
+  # * +j+: column
+  # *Returns*:: +Float+ e(sub:ij) = (r(sub:i)/N) * (c(sub:j))
   def expected(i, j)
     (row_sum(i).to_f / table_sum_all) * column_sum(j)
   end
 
   # Report the chi square of the entire table
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: +Float+ chi square value
   def chi_square
     total = 0
     c = @characters
@@ -324,7 +341,13 @@ class ContingencyTable
     total
   end
 
-  # Report the chi square relation of two elements in the table
+  # Report the chi-square relation of two elements in the table
+  #
+  # ---
+  # *Arguments*
+  # * +i+: row
+  # * +j+: column
+  # *Returns*:: +Float+ chi-square of an intersection
   def chi_square_element(i, j)
     eij = expected(i, j)
     return 0 if eij == 0
@@ -332,12 +355,16 @@ class ContingencyTable
   end
 
   # Report the contingency coefficient of the table
+  #
+  # ---
+  # *Arguments*
+  # * _none_
+  # *Returns*:: +Float+ contingency_coefficient of the table
   def contingency_coefficient
     c_s = chi_square
     Math.sqrt(c_s / (table_sum_all + c_s) )
   end
 
-end
-
+end # ContingencyTable
 end # Bio
 

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