bio 1.0.0 → 1.1.0

data/lib/bio/sequence.rb

@@ -4,16 +4,65 @@
 # Copyright::   Copyright (C) 2000-2006
 #               Toshiaki Katayama <k@bioruby.org>,
 #               Yoshinori K. Okuji <okuji@enbug.org>,
-#               Naohisa Goto <ng@bioruby.org>
-# License::     Ruby's
+#               Naohisa Goto <ng@bioruby.org>,
+#               Ryan Raaum <ryan@raaum.org>,
+#               Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::     The Ruby License
 #
-# $Id: sequence.rb,v 0.56 2006/02/17 17:15:08 k Exp $
+# $Id: sequence.rb,v 0.58 2007/04/05 23:35:39 trevor Exp $
 #
 
 require 'bio/sequence/compat'
 
 module Bio
 
+# = DESCRIPTION
+# Bio::Sequence objects represent annotated sequences in bioruby.
+# A Bio::Sequence object is a wrapper around the actual sequence, 
+# represented as either a Bio::Sequence::NA or a Bio::Sequence::AA object.
+# For most users, this encapsulation will be completely transparent.
+# Bio::Sequence responds to all methods defined for Bio::Sequence::NA/AA
+# objects using the same arguments and returning the same values (even though 
+# these methods are not documented specifically for Bio::Sequence).
+#
+# = USAGE
+#   # Create a nucleic or amino acid sequence
+#   dna = Bio::Sequence.auto('atgcatgcATGCATGCAAAA')
+#   rna = Bio::Sequence.auto('augcaugcaugcaugcaaaa')
+#   aa = Bio::Sequence.auto('ACDEFGHIKLMNPQRSTVWYU')
+# 
+#   # Print it out
+#   puts dna.to_s
+#   puts aa.to_s
+# 
+#   # Get a subsequence, bioinformatics style (first nucleotide is '1')
+#   puts dna.subseq(2,6)
+# 
+#   # Get a subsequence, informatics style (first nucleotide is '0')
+#   puts dna[2,6]
+# 
+#   # Print in FASTA format
+#   puts dna.output(:fasta)
+# 
+#   # Print all codons
+#   dna.window_search(3,3) do |codon|
+#     puts codon
+#   end
+# 
+#   # Splice or otherwise mangle your sequence
+#   puts dna.splicing("complement(join(1..5,16..20))")
+#   puts rna.splicing("complement(join(1..5,16..20))")
+# 
+#   # Convert a sequence containing ambiguity codes into a 
+#   # regular expression you can use for subsequent searching
+#   puts aa.to_re
+# 
+#   # These should speak for themselves
+#   puts dna.complement
+#   puts dna.composition
+#   puts dna.molecular_weight
+#   puts dna.translate
+#   puts dna.gc_percent
 class Sequence
 
   autoload :Common,  'bio/sequence/common'
@@ -22,17 +71,82 @@ class Sequence
   autoload :Generic, 'bio/sequence/generic'
   autoload :Format,  'bio/sequence/format'
 
+  # Create a new Bio::Sequence object
+  #
+  #   s = Bio::Sequence.new('atgc')
+  #   puts s                                  #=> 'atgc'
+  #
+  # Note that this method does not intialize the contained sequence
+  # as any kind of bioruby object, only as a simple string
+  #
+  #   puts s.seq.class                        #=> String
+  #
+  # See Bio::Sequence#na, Bio::Sequence#aa, and Bio::Sequence#auto 
+  # for methods to transform the basic String of a just created 
+  # Bio::Sequence object to a proper bioruby object
+  # ---
+  # *Arguments*:
+  # * (required) _str_: String or Bio::Sequence::NA/AA object
+  # *Returns*:: Bio::Sequence object
   def initialize(str)
     @seq = str
   end
 
-  def method_missing(*arg)
-    @seq.send(*arg)
+  # Pass any unknown method calls to the wrapped sequence object.  see
+  # http://www.rubycentral.com/book/ref_c_object.html#Object.method_missing
+  def method_missing(sym, *args, &block) #:nodoc:
+    @seq.send(sym, *args, &block)
   end
-
-  attr_accessor :entry_id, :definition, :features, :references, :comments,
-    :date, :keywords, :dblinks, :taxonomy, :moltype, :seq
-
+  
+  # The sequence identifier.  For example, for a sequence
+  # of Genbank origin, this is the accession number.
+  attr_accessor :entry_id
+  
+  # A String with a description of the sequence
+  attr_accessor :definition
+  
+  # An Array of Bio::Feature objects
+  attr_accessor :features
+  
+  # An Array of Bio::Reference objects
+  attr_accessor :references
+  
+  # A comment String
+  attr_accessor :comments
+  
+  # Date from sequence source. Often date of deposition.
+  attr_accessor :date
+  
+  # An Array of Strings
+  attr_accessor :keywords
+  
+  # An Array of Strings; links to other database entries.
+  attr_accessor :dblinks
+  
+  # A taxonomy String
+  attr_accessor :taxonomy
+  
+  # Bio::Sequence::NA/AA
+  attr_accessor :moltype
+  
+  # The sequence object, usually Bio::Sequence::NA/AA, 
+  # but could be a simple String
+  attr_accessor :seq
+  
+  # Using Bio::Sequence::Format, return a String with the Bio::Sequence
+  # object formatted in the given style.
+  #
+  # Formats currently implemented are: 'fasta', 'genbank', and 'embl'
+  #
+  #   s = Bio::Sequence.new('atgc')
+  #   puts s.output(:fasta)                   #=> "> \natgc\n"
+  #
+  # The style argument is given as a Ruby 
+  # Symbol(http://www.ruby-doc.org/core/classes/Symbol.html)
+  # ---
+  # *Arguments*: 
+  # * (required) _style_: :fasta, :genbank, *or* :embl
+  # *Returns*:: String object
   def output(style)
     extend Bio::Sequence::Format
     case style
@@ -47,6 +161,16 @@ class Sequence
     end
   end
 
+  # Guess the type of sequence, Amino Acid or Nucleic Acid, and create a 
+  # new sequence object (Bio::Sequence::AA or Bio::Sequence::NA) on the basis
+  # of this guess.  This method will change the current Bio::Sequence object.
+  #
+  #   s = Bio::Sequence.new('atgc')
+  #   puts s.seq.class                        #=> String
+  #   s.auto
+  #   puts s.seq.class                        #=> Bio::Sequence::NA
+  # ---
+  # *Returns*:: Bio::Sequence::NA/AA object
   def auto
     @moltype = guess
     if @moltype == NA
@@ -56,20 +180,69 @@ class Sequence
     end
   end
 
+  # Given a sequence String, guess its type, Amino Acid or Nucleic Acid, and
+  # return a new Bio::Sequence object wrapping a sequence of the guessed type
+  # (either Bio::Sequence::AA or Bio::Sequence::NA)
+  # 
+  #   s = Bio::Sequence.auto('atgc')
+  #   puts s.seq.class                        #=> Bio::Sequence::NA
+  # ---
+  # *Arguments*:
+  # * (required) _str_: String *or* Bio::Sequence::NA/AA object
+  # *Returns*:: Bio::Sequence object
   def self.auto(str)
     seq = self.new(str)
     seq.auto
     return seq
   end
 
+  # Guess the class of the current sequence.  Returns the class
+  # (Bio::Sequence::AA or Bio::Sequence::NA) guessed.  In general, used by
+  # developers only, but if you know what you are doing, feel free.
+  # 
+  #   s = Bio::Sequence.new('atgc')
+  #   puts s.guess                            #=> Bio::Sequence::NA
+  #
+  # There are three parameters: `threshold`, `length`, and `index`.  
+  #
+  # The `threshold` value (defaults to 0.9) is the frequency of 
+  # nucleic acid bases [AGCTUagctu] required in the sequence for this method
+  # to produce a Bio::Sequence::NA "guess".  In the default case, if less
+  # than 90% of the bases (after excluding [Nn]) are in the set [AGCTUagctu],
+  # then the guess is Bio::Sequence::AA.
+  # 
+  #   s = Bio::Sequence.new('atgcatgcqq')
+  #   puts s.guess                            #=> Bio::Sequence::AA
+  #   puts s.guess(0.8)                       #=> Bio::Sequence::AA
+  #   puts s.guess(0.7)                       #=> Bio::Sequence::NA
+  #
+  # The `length` value is how much of the total sequence to use in the
+  # guess (default 10000).  If your sequence is very long, you may 
+  # want to use a smaller amount to reduce the computational burden.
+  #
+  #   s = Bio::Sequence.new(A VERY LONG SEQUENCE)
+  #   puts s.guess(0.9, 1000)  # limit the guess to the first 1000 positions
+  #
+  # The `index` value is where to start the guess.  Perhaps you know there
+  # are a lot of gaps at the start...
+  #
+  #   s = Bio::Sequence.new('-----atgcc')
+  #   puts s.guess                            #=> Bio::Sequence::AA
+  #   puts s.guess(0.9,10000,5)               #=> Bio::Sequence::NA
+  # ---
+  # *Arguments*:
+  # * (optional) _threshold_: Float in range 0,1 (default 0.9)
+  # * (optional) _length_: Fixnum (default 10000)
+  # * (optional) _index_: Fixnum (default 1)
+  # *Returns*:: Bio::Sequence::NA/AA
   def guess(threshold = 0.9, length = 10000, index = 0)
     str = @seq.to_s[index,length].to_s.extend Bio::Sequence::Common
     cmp = str.composition
 
-    bases = cmp['A'] + cmp['T'] + cmp['G'] + cmp['C'] + 
-            cmp['a'] + cmp['t'] + cmp['g'] + cmp['c']
+    bases = cmp['A'] + cmp['T'] + cmp['G'] + cmp['C'] + cmp['U'] +
+            cmp['a'] + cmp['t'] + cmp['g'] + cmp['c'] + cmp['u']
 
-    total = @seq.length - cmp['N'] - cmp['n']
+    total = str.length - cmp['N'] - cmp['n']
 
     if bases.to_f / total > threshold
       return NA
@@ -78,20 +251,89 @@ class Sequence
     end
   end 
 
+  # Guess the class of a given sequence.  Returns the class
+  # (Bio::Sequence::AA or Bio::Sequence::NA) guessed.  In general, used by
+  # developers only, but if you know what you are doing, feel free.
+  # 
+  #   puts .guess('atgc')        #=> Bio::Sequence::NA
+  #
+  # There are three optional parameters: `threshold`, `length`, and `index`.  
+  #
+  # The `threshold` value (defaults to 0.9) is the frequency of 
+  # nucleic acid bases [AGCTUagctu] required in the sequence for this method
+  # to produce a Bio::Sequence::NA "guess".  In the default case, if less
+  # than 90% of the bases (after excluding [Nn]) are in the set [AGCTUagctu],
+  # then the guess is Bio::Sequence::AA.
+  # 
+  #   puts Bio::Sequence.guess('atgcatgcqq')      #=> Bio::Sequence::AA
+  #   puts Bio::Sequence.guess('atgcatgcqq', 0.8) #=> Bio::Sequence::AA
+  #   puts Bio::Sequence.guess('atgcatgcqq', 0.7) #=> Bio::Sequence::NA
+  #
+  # The `length` value is how much of the total sequence to use in the
+  # guess (default 10000).  If your sequence is very long, you may 
+  # want to use a smaller amount to reduce the computational burden.
+  #
+  #   # limit the guess to the first 1000 positions
+  #   puts Bio::Sequence.guess('A VERY LONG SEQUENCE', 0.9, 1000)  
+  #
+  # The `index` value is where to start the guess.  Perhaps you know there
+  # are a lot of gaps at the start...
+  #
+  #   puts Bio::Sequence.guess('-----atgcc')             #=> Bio::Sequence::AA
+  #   puts Bio::Sequence.guess('-----atgcc',0.9,10000,5) #=> Bio::Sequence::NA
+  # ---
+  # *Arguments*:
+  # * (required) _str_: String *or* Bio::Sequence::NA/AA object
+  # * (optional) _threshold_: Float in range 0,1 (default 0.9)
+  # * (optional) _length_: Fixnum (default 10000)
+  # * (optional) _index_: Fixnum (default 1)
+  # *Returns*:: Bio::Sequence::NA/AA
   def self.guess(str, *args)
     self.new(str).guess(*args)
   end
 
+  # Transform the sequence wrapped in the current Bio::Sequence object
+  # into a Bio::Sequence::NA object.  This method will change the current
+  # object.  This method does not validate your choice, so be careful!
+  #
+  #   s = Bio::Sequence.new('RRLE')
+  #   puts s.seq.class                        #=> String
+  #   s.na
+  #   puts s.seq.class                        #=> Bio::Sequence::NA !!!
+  #
+  # However, if you know your sequence type, this method may be 
+  # constructively used after initialization,
+  #
+  #   s = Bio::Sequence.new('atgc')
+  #   s.na
+  # ---
+  # *Returns*:: Bio::Sequence::NA
   def na
     @seq = NA.new(@seq)
     @moltype = NA
   end
 
+  # Transform the sequence wrapped in the current Bio::Sequence object
+  # into a Bio::Sequence::NA object.  This method will change the current
+  # object.  This method does not validate your choice, so be careful!
+  #
+  #   s = Bio::Sequence.new('atgc')
+  #   puts s.seq.class                        #=> String
+  #   s.aa
+  #   puts s.seq.class                        #=> Bio::Sequence::AA !!!
+  #
+  # However, if you know your sequence type, this method may be 
+  # constructively used after initialization,
+  #
+  #   s = Bio::Sequence.new('RRLE')
+  #   s.aa
+  # ---
+  # *Returns*:: Bio::Sequence::AA
   def aa
     @seq = AA.new(@seq)
     @moltype = AA
   end
-
+  
 end # Sequence
 
 

data/lib/bio/sequence/aa.rb

@@ -2,10 +2,11 @@
 # = bio/sequence/aa.rb - amino acid sequence class
 #
 # Copyright::   Copyright (C) 2006
-#               Toshiaki Katayama <k@bioruby.org>
-# License::     Ruby's
+#               Toshiaki Katayama <k@bioruby.org>,
+#               Ryan Raaum <ryan@raaum.org>
+# License::     The Ruby License
 #
-# $Id: aa.rb,v 1.2 2006/02/06 14:11:31 k Exp $
+# $Id: aa.rb,v 1.4 2007/04/05 23:35:41 trevor Exp $
 #
 
 require 'bio/sequence/common'
@@ -16,13 +17,46 @@ module Bio
 
 class Sequence
 
-
-# Amino Acid sequence
+# = DESCRIPTION
+# Bio::Sequence::AA represents a bare Amino Acid sequence in bioruby.
+#
+# = USAGE
+#   # Create an Amino Acid sequence.
+#   aa = Bio::Sequence::AA.new('ACDEFGHIKLMNPQRSTVWYU')
+#
+#   # What are the three-letter codes for all the residues?
+#   puts aa.codes
+#
+#   # What are the names of all the residues?
+#   puts aa.names
+#
+#   # What is the molecular weight of this peptide?
+#   puts aa.molecular_weight
 class AA < String
 
   include Bio::Sequence::Common
 
-  # Generate a amino acid sequence object from a string.
+  # Generate an amino acid sequence object from a string.
+  #
+  #   s = Bio::Sequence::AA.new("RRLEHTFVFLRNFSLMLLRY")
+  #
+  # or maybe (if you have an amino acid sequence in a file)
+  #
+  #   s = Bio::Sequence:AA.new(File.open('aa.txt').read)
+  #
+  # Amino Acid sequences are *always* all uppercase in bioruby
+  #
+  #   s = Bio::Sequence::AA.new("rrLeHtfV")
+  #   puts s                                  #=> "RRLEHTFVF"
+  #
+  # Whitespace is stripped from the sequence
+  #
+  #   s = Bio::Sequence::AA.new("RRL\nELA\tRG\r  RL")
+  #   puts s                                  #=> "RRLELARGRL"
+  # ---
+  # *Arguments*:
+  # * (required) _str_: String
+  # *Returns*:: Bio::Sequence::AA object
   def initialize(str)
     super
     self.upcase!
@@ -30,17 +64,36 @@ class AA < String
   end
 
 
-  # Estimate the weight of this protein.
+  # Estimate molecular weight based on 
+  # Fasman1976[http://www.genome.ad.jp/dbget-bin/www_bget?aaindex+FASG760101]
+  #
+  #   s = Bio::Sequence::AA.new("RRLE")
+  #   puts s.molecular_weight             #=> 572.655
+  # ---
+  # *Returns*:: Float object
   def molecular_weight
     Bio::AminoAcid.weight(self)
   end
 
+  # Create a ruby regular expression instance 
+  # (Regexp)[http://corelib.rubyonrails.org/classes/Regexp.html]  
+  #
+  #   s = Bio::Sequence::AA.new("RRLE")
+  #   puts s.to_re                        #=> /RRLE/
+  # ---
+  # *Returns*:: Regexp object
   def to_re
     Bio::AminoAcid.to_re(self)
   end
 
-  # Generate the list of the names of the each residue along with the
-  # sequence (3 letters code).
+  # Generate the list of the names of each residue along with the
+  # sequence (3 letters code).  Codes used in bioruby are found in the
+  # Bio::AminoAcid::NAMES hash.
+  #
+  #   s = Bio::Sequence::AA.new("RRLE")
+  #   puts s.codes                        #=> ["Arg", "Arg", "Leu", "Glu"]
+  # ---
+  # *Returns*:: Array object
   def codes
     array = []
     self.each_byte do |x|
@@ -49,7 +102,15 @@ class AA < String
     return array
   end
 
-  # Similar to codes but returns long names.
+  # Generate the list of the names of each residue along with the
+  # sequence (full name).  Names used in bioruby are found in the
+  # Bio::AminoAcid::NAMES hash.
+  #
+  #   s = Bio::Sequence::AA.new("RRLE")
+  #   puts s.names  
+  #               #=> ["arginine", "arginine", "leucine", "glutamic acid"]
+  # ---
+  # *Returns*:: Array object
   def names
     self.codes.map do |x|
       Bio::AminoAcid.names[x]