wwood-bioruby 1.2.11

data/lib/bio/sequence/aa.rb

@@ -0,0 +1,152 @@
+#
+# = bio/sequence/aa.rb - amino acid sequence class
+#
+# Copyright::   Copyright (C) 2006
+#               Toshiaki Katayama <k@bioruby.org>,
+#               Ryan Raaum <ryan@raaum.org>
+# License::     The Ruby License
+#
+# $Id: aa.rb,v 1.4 2007/04/05 23:35:41 trevor Exp $
+#
+
+require 'bio/sequence/common'
+
+module Bio
+
+  autoload :AminoAcid, 'bio/data/aa'
+
+  class 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 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!
+        self.tr!(" \t\n\r",'')
+      end
+
+
+      # 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 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|
+          array.push(Bio::AminoAcid.names[x.chr])
+        end
+        return array
+      end
+
+      # 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]
+        end
+      end
+  
+  
+      # Return the number of bases considered acidic in this amino acid sequence in neutral conditions.
+      # Amino acids considered acidic are D and E.
+      def acidic_count
+        count = 0
+        comp = self.composition
+        Bio::AminoAcid::ACIDIC_AMINO_ACIDS.each do |acidic|
+          if comp[acidic]
+            count += comp[acidic]
+          end
+        end
+        return count
+      end
+  
+      # Return the number of bases considered basic in this amino acid sequence in neutral conditions.
+      # Amino acids considered acidic are H, K and R.
+      def basic_count
+        count = 0
+        comp = self.composition
+        Bio::AminoAcid::BASIC_AMINO_ACIDS.each do |basic|
+          if comp[basic]
+            count += comp[basic]
+          end
+        end
+        return count
+      end
+
+    end # AA
+
+  end # Sequence
+
+end # Bio
+

data/lib/bio/sequence/adapter.rb

@@ -0,0 +1,108 @@
+#
+# = bio/sequence/adapter.rb - Bio::Sequence adapter helper module
+#
+# Copyright::   Copyright (C) 2008
+#               Naohisa Goto <ng@bioruby.org>,
+# License::     The Ruby License
+#
+# $Id:$
+#
+
+require 'bio/sequence'
+
+# Internal use only. Normal users should not use this module.
+#
+# Helper methods for defining adapters used when converting data classes to
+# Bio::Sequence class, with pseudo lazy evaluation and pseudo memoization.
+#
+# This module is used by using "extend", not "include".
+# 
+module Bio::Sequence::Adapter
+
+  autoload :GenBank,     'bio/db/genbank/genbank_to_biosequence'
+  autoload :EMBL,        'bio/db/embl/embl_to_biosequence'
+  autoload :FastaFormat, 'bio/db/fasta/fasta_to_biosequence'
+  autoload :BioSQL,      'bio/db/biosql/biosql_to_biosequence'
+
+  private
+
+  # Defines a reader attribute method with psudo lazy evaluation/memoization.
+  #
+  # It defines a method <i>name</i> like attr_reader, but at the first time
+  # when the method <i>name</i> is called, it acts as follows:
+  # When instance variable @<i>name</i> is not defined,
+  # calls <tt>__get__<i>name</i>(@source_data)</tt> and stores the returned
+  # value to @<i>name</i>, and changes its behavior to the same as
+  # <tt>attr_reader </tt><i>:name</i>.
+  # When instance variable @name is already defined,
+  # its behavior is changed to the same as
+  # <tt>attr_reader </tt><i>:name</i>.
+  # When the object is frozen, storing to the instance variable and
+  # changing methods behavior do not occur, and the value of
+  # <tt>__get__<i>name</i>(@source_data)</tt> is returned.
+  # 
+  # Note that it assumes that the source data object is stored in
+  # @source_data instance variable.
+  def attr_reader_lazy(name)
+    #$stderr.puts "attr_reader_lazy :#{name}"
+    varname = "@#{name}".intern
+    methodname = "__get__#{name}".intern
+
+    # module to reset method's behavior to normal attr_reader
+    reset = "Attr_#{name}".intern
+    const_set(reset, Module.new { attr_reader name })
+    reset_module_name = "#{self}::#{reset}"
+
+    # define attr method
+    module_eval <<__END_OF_DEF__
+      def #{name}
+        unless defined? #{varname} then
+          #$stderr.puts "LAZY #{name}: calling #{methodname}"
+          val = #{methodname}(@source_data)
+          #{varname} = val unless frozen?
+        else
+          val = #{varname}
+        end
+        unless frozen? then
+          #$stderr.puts "LAZY #{name}: finalize: attr_reader :#{name}"
+          self.extend(#{reset_module_name})
+        end
+        val
+      end
+__END_OF_DEF__
+  end
+
+  # Defines a Bio::Sequence to Bio::* adapter method with
+  # psudo lazy evaluation and psudo memoization.
+  #
+  # Without block, defines a private method <tt>__get__<i>name</i>(orig)</tt>
+  # which calls <i>source_method</i> for @source_data.
+  #
+  # def__get__(name, source_method) is the same as:
+  #   def __get__name(orig); orig.source_method; end
+  #   attr_reader_lazy name
+  #
+  # If block is given, <tt>__get__<i>name</i>(orig)</tt> is defined
+  # with the block. The @source_data is given as an argument of the block,
+  # i.e. the block must get an argument.
+  #
+  def def_biosequence_adapter(name, source_method = name, &block)
+    methodname = "__get__#{name}".intern
+
+    if block then
+      define_method(methodname, block)
+    else
+      module_eval <<__END_OF_DEF__
+        def #{methodname}(orig)
+          orig.#{source_method}
+        end
+__END_OF_DEF__
+    end
+    private methodname
+    attr_reader_lazy name
+    true
+  end
+
+end #module Bio::Sequence::Adapter
+
+

data/lib/bio/sequence/common.rb

@@ -0,0 +1,310 @@
+#
+# = bio/sequence/common.rb - common methods for biological sequence
+#
+# Copyright::   Copyright (C) 2006
+#               Toshiaki Katayama <k@bioruby.org>,
+#               Ryan Raaum <ryan@raaum.org>
+# License::     The Ruby License
+#
+# $Id:$
+#
+
+module Bio
+
+  autoload :Locations, 'bio/location'
+
+class Sequence
+
+# = DESCRIPTION
+# Bio::Sequence::Common is a 
+# Mixin[http://www.rubycentral.com/book/tut_modules.html]
+# implementing methods common to
+# Bio::Sequence::AA and Bio::Sequence::NA.  All of these methods
+# are available to either Amino Acid or Nucleic Acid sequences, and
+# by encapsulation are also available to Bio::Sequence objects.
+#
+# = USAGE
+#
+#   # Create a sequence
+#   dna = Bio::Sequence.auto('atgcatgcatgc')
+#
+#   # Splice out a subsequence using a Genbank-style location string
+#   puts dna.splice('complement(1..4)')
+#
+#   # What is the base composition?
+#   puts dna.composition
+#
+#   # Create a random sequence with the composition of a current sequence
+#   puts dna.randomize
+module Common
+  
+  # Return sequence as 
+  # String[http://corelib.rubyonrails.org/classes/String.html].
+  # The original sequence is unchanged.
+  #
+  #   seq = Bio::Sequence::NA.new('atgc')
+  #   puts s.to_s                             #=> 'atgc'
+  #   puts s.to_s.class                       #=> String
+  #   puts s                                  #=> 'atgc'
+  #   puts s.class                            #=> Bio::Sequence::NA
+  # ---
+  # *Returns*:: String object
+  def to_s
+    String.new(self)
+  end
+  alias to_str to_s
+
+  # Create a new sequence based on the current sequence.
+  # The original sequence is unchanged.
+  # 
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   s2 = s.seq
+  #   puts s2                                 #=> 'atgc'
+  # ---
+  # *Returns*:: new Bio::Sequence::NA/AA object
+  def seq
+    self.class.new(self)
+  end
+  
+  # Normalize the current sequence, removing all whitespace and 
+  # transforming all positions to uppercase if the sequence is AA or
+  # transforming all positions to lowercase if the sequence is NA.
+  # The original sequence is modified.
+  #
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   s.normalize!
+  # ---
+  # *Returns*:: current Bio::Sequence::NA/AA object (modified)
+  def normalize!
+    initialize(self)
+    self
+  end
+  alias seq! normalize!
+
+  # Add new data to the end of the current sequence.
+  # The original sequence is modified.
+  #
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   s << 'atgc'
+  #   puts s                                  #=> "atgcatgc"
+  #   s << s
+  #   puts s                                  #=> "atgcatgcatgcatgc"
+  # ---
+  # *Returns*:: current Bio::Sequence::NA/AA object (modified)
+  def concat(*arg)
+    super(self.class.new(*arg))
+  end
+
+  def <<(*arg)
+    concat(*arg)
+  end
+
+  # Create a new sequence by adding to an existing sequence.
+  # The existing sequence is not modified.
+  #
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   s2 = s + 'atgc'
+  #   puts s2                                 #=> "atgcatgc"
+  #   puts s                                  #=> "atgc"
+  #
+  # The new sequence is of the same class as the existing sequence if 
+  # the new data was added to an existing sequence,
+  #
+  #   puts s2.class == s.class                #=> true
+  #
+  # but if an existing sequence is added to a String, the result is a String
+  #
+  #   s3 = 'atgc' + s
+  #   puts s3.class                           #=> String
+  # ---
+  # *Returns*:: new Bio::Sequence::NA/AA *or* String object
+  def +(*arg)
+    self.class.new(super(*arg))
+  end
+
+  # Returns a new sequence containing the subsequence identified by the 
+  # start and end numbers given as parameters.  *Important:* Biological 
+  # sequence numbering conventions (one-based) rather than ruby's 
+  # (zero-based) numbering conventions are used.  
+  #
+  #   s = Bio::Sequence::NA.new('atggaatga')
+  #   puts s.subseq(1,3)                      #=> "atg"
+  #
+  # Start defaults to 1 and end defaults to the entire existing string, so
+  # subseq called without any parameters simply returns a new sequence 
+  # identical to the existing sequence.
+  #
+  #   puts s.subseq                           #=> "atggaatga"
+  # ---
+  # *Arguments*:
+  # * (optional) _s_(start): Integer (default 1)
+  # * (optional) _e_(end): Integer (default current sequence length)
+  # *Returns*:: new Bio::Sequence::NA/AA object
+  def subseq(s = 1, e = self.length)
+    raise "Error: start/end position must be a positive integer" unless s > 0 and e > 0
+    s -= 1
+    e -= 1
+    self[s..e]
+  end
+
+  # This method steps through a sequences in steps of 'step_size' by 
+  # subsequences of 'window_size'. Typically used with a block.
+  # Any remaining sequence at the terminal end will be returned.
+  #
+  # Prints average GC% on each 100bp
+  #
+  #   s.window_search(100) do |subseq|
+  #     puts subseq.gc
+  #   end
+  #   
+  # Prints every translated peptide (length 5aa) in the same frame
+  #
+  #   s.window_search(15, 3) do |subseq|
+  #     puts subseq.translate
+  #   end
+  #
+  # Split genome sequence by 10000bp with 1000bp overlap in fasta format
+  #
+  #   i = 1
+  #   remainder = s.window_search(10000, 9000) do |subseq|
+  #     puts subseq.to_fasta("segment #{i}", 60)
+  #     i += 1
+  #   end
+  #   puts remainder.to_fasta("segment #{i}", 60)
+  # ---
+  # *Arguments*:
+  # * (required) _window_size_: Fixnum
+  # * (optional) _step_size_: Fixnum (default 1)
+  # *Returns*:: new Bio::Sequence::NA/AA object
+  def window_search(window_size, step_size = 1)
+    last_step = 0
+    0.step(self.length - window_size, step_size) do |i| 
+      yield self[i, window_size]                        
+      last_step = i
+    end                          
+    return self[last_step + window_size .. -1] 
+  end
+
+  # Returns a float total value for the sequence given a hash of
+  # base or residue values,
+  #
+  #   values = {'a' => 0.1, 't' => 0.2, 'g' => 0.3, 'c' => 0.4}
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   puts s.total(values)                    #=> 1.0
+  # ---
+  # *Arguments*:
+  # * (required) _hash_: Hash object
+  # *Returns*:: Float object
+  def total(hash)
+    hash.default = 0.0 unless hash.default
+    sum = 0.0
+    self.each_byte do |x|
+      begin
+        sum += hash[x.chr]
+      end
+    end
+    return sum
+  end
+
+  # Returns a hash of the occurrence counts for each residue or base.
+  #
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   puts s.composition              #=> {"a"=>1, "c"=>1, "g"=>1, "t"=>1}
+  # ---
+  # *Returns*:: Hash object
+  def composition
+    count = Hash.new(0)
+    self.scan(/./) do |x|
+      count[x] += 1
+    end
+    return count
+  end
+
+  # Returns a randomized sequence. The default is to retain the same 
+  # base/residue composition as the original.  If a hash of base/residue 
+  # counts is given, the new sequence will be based on that hash 
+  # composition.  If a block is given, each new randomly selected 
+  # position will be passed into the block.  In all cases, the
+  # original sequence is not modified.
+  #
+  #   s = Bio::Sequence::NA.new('atgc')
+  #   puts s.randomize                        #=> "tcag"  (for example)
+  #
+  #   new_composition = {'a' => 2, 't' => 2}
+  #   puts s.randomize(new_composition)       #=> "ttaa"  (for example)
+  #
+  #   count = 0
+  #   s.randomize { |x| count += 1 }
+  #   puts count                              #=> 4
+  # ---
+  # *Arguments*:
+  # * (optional) _hash_: Hash object
+  # *Returns*:: new Bio::Sequence::NA/AA object
+  def randomize(hash = nil)
+    if hash
+      tmp = ''
+      hash.each {|k, v|
+        tmp += k * v.to_i
+      }
+    else
+      tmp = self
+    end
+    seq = self.class.new(tmp)
+    # Reference: http://en.wikipedia.org/wiki/Fisher-Yates_shuffle
+    seq.length.downto(2) do |n|
+      k = rand(n)
+      c = seq[n - 1]
+      seq[n - 1] = seq[k]
+      seq[k] = c
+    end
+    if block_given? then
+      (0...seq.length).each do |i|
+        yield seq[i, 1]
+      end
+      return self.class.new('')
+    else
+      return seq
+    end
+  end
+
+  # Return a new sequence extracted from the original using a GenBank style 
+  # position string.  See also documentation for the Bio::Location class.
+  #
+  #   s = Bio::Sequence::NA.new('atgcatgcatgcatgc')
+  #   puts s.splice('1..3')                           #=> "atg"
+  #   puts s.splice('join(1..3,8..10)')               #=> "atgcat"
+  #   puts s.splice('complement(1..3)')               #=> "cat"
+  #   puts s.splice('complement(join(1..3,8..10))')   #=> "atgcat"
+  #
+  # Note that 'complement'ed Genbank position strings will have no 
+  # effect on Bio::Sequence::AA objects.
+  # ---
+  # *Arguments*:
+  # * (required) _position_: String *or* Bio::Location object
+  # *Returns*:: Bio::Sequence::NA/AA object
+  def splice(position)
+    unless position.is_a?(Locations) then
+      position = Locations.new(position)
+    end
+    s = ''
+    position.each do |location|
+      if location.sequence
+        s << location.sequence
+      else
+        exon = self.subseq(location.from, location.to)
+        begin
+          exon.complement! if location.strand < 0
+        rescue NameError
+        end
+        s << exon
+      end
+    end
+    return self.class.new(s)
+  end
+  alias splicing splice
+
+end # Common
+
+end # Sequence
+
+end # Bio