bio 0.7.0 → 0.7.1

data/lib/bio/db/pdb/residue.rb

@@ -1,8 +1,14 @@
 #
-# bio/db/pdb/residue.rb - residue class for PDB
+# = bio/db/pdb/residue.rb - residue class for PDB
 #
-#   Copyright (C) 2004 Alex Gutteridge <alexg@ebi.ac.uk>
+# Copyright::  Copyright (C) 2004, 2006
+#              Alex Gutteridge <alexg@ebi.ac.uk>
+#              Naohisa Goto <ng@bioruby.org>
+# License:: LGPL
 #
+#  $Id: residue.rb,v 1.10 2006/01/20 13:54:08 ngoto 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
@@ -16,8 +22,12 @@
 #  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
+#++
+#
+# = Bio::PDB::Residue
+#
+# = Bio::PDB::Heterogen
 #
-#  $Id: residue.rb,v 1.4 2005/12/18 17:34:47 ngoto Exp $
 
 require 'bio/db/pdb'
 
@@ -25,81 +35,103 @@ module Bio
 
   class PDB
 
-    #Residue class - id is a composite of resSeq and iCode
+    # Bio::PDB::Residue is a class to store a residue.
+    # The object would contain some atoms (Bio::PDB::Record::ATOM objects).
+    #
     class Residue
       
       include Utils
       include AtomFinder
+
       include Enumerable
       include Comparable
-      
-      attr_reader :resName, :resSeq, :iCode, :id, :chain, :hetatm
-      attr_writer :resName, :chain, :hetatm
-      
+
+      # Creates residue id from an ATOM (or HETATM) object.
+      def self.get_residue_id_from_atom(atom)
+        "#{atom.resSeq}#{atom.iCode.strip}".strip
+      end
+
+      # Creates a new Residue object.
       def initialize(resName = nil, resSeq = nil, iCode = nil, 
-                     chain = nil, hetatm = false)
+                     chain = nil)
         
         @resName = resName
         @resSeq  = resSeq
         @iCode   = iCode
         
-        @hetatm  = hetatm
-        
-        #Residue id is required because resSeq doesn't uniquely identify
-        #a residue. ID is constructed from resSeq and iCode and is appended
-        #to 'LIGAND' if the residue is a HETATM
-        if (!@resSeq and !@iCode)
-          @id = nil
-        else
-          @id = "#{@resSeq}#{@iCode.strip}"
-          if @hetatm
-            @id = 'LIGAND' + @id
-          end
-        end
-        
         @chain   = chain
-        
-        @atoms   = Array.new
-        
+        @atoms   = []
+
+        update_residue_id
       end
-      
+
+      # atoms in this residue. (Array)
+      attr_reader :atoms
+
+      # the chain to which this residue belongs
+      attr_accessor :chain
+
+      # resName (residue name)
+      attr_accessor :resName
+
+      # residue id (String or nil).
+      # The id is a composite of resSeq and iCode.
+      attr_reader   :residue_id
+
+      # Now, Residue#id is an alias of residue_id.
+      alias id residue_id
+
       #Keyed access to atoms based on element e.g. ["CA"]
       def [](key)
         atom = @atoms.find{ |atom| key == atom.element }
       end
-      
-      #Need to define these to make sure id is correctly updated
+
+      # Updates residue id. This is a private method.
+      # Need to call this method to make sure id is correctly updated.
+      def update_residue_id
+        if !@resSeq and !@iCode
+          @residue_id = nil
+        else
+          @residue_id = "#{@resSeq}#{@iCode.to_s.strip}".strip
+        end
+      end
+      private :update_residue_id
+
+      # resSeq
+      attr_reader :resSeq
+
+      # resSeq=()
       def resSeq=(resSeq)
         @resSeq = resSeq.to_i
-        @id      = "#{@resSeq}#{@iCode.strip}"
-        if @hetatm
-          @id = 'LIGAND' + @id
-        end
+        update_residue_id
+        @resSeq
       end
-      
+
+      # iCode
+      attr_reader :iCode
+
+      # iCode=()
       def iCode=(iCode)
         @iCode = iCode
-        @id    = "#{@resSeq}#{@iCode.strip}"
-        if @hetatm
-          @id = 'LIGAND' + @id
-        end
+        update_residue_id
+        @iCode
       end
       
-      #Adds an atom to this residue
+      # Adds an atom to this residue
       def addAtom(atom)
         raise "Expecting ATOM or HETATM" unless atom.is_a? Bio::PDB::Record::ATOM
         @atoms.push(atom)
         self
       end
       
-      #Iterator over the atoms
+      # Iterator over the atoms
       def each
         @atoms.each{ |atom| yield atom }
       end
-      #Alias to override AtomFinder#each_atom
+      # Alias to override AtomFinder#each_atom
       alias each_atom each
       
-      #Sorts based on resSeq and iCode if need be
+      # Sorts based on resSeq and iCode if need be
       def <=>(other)
         if @resSeq != other.resSeq
           return @resSeq <=> other.resSeq
@@ -108,15 +140,47 @@ module Bio
         end
       end
       
-      #Stringifies each atom
+      # Stringifies each atom
       def to_s
-        string = ""
-        @atoms.each{ |atom| string << atom.to_s << "\n" }
-        return string
+        @atoms.join('')
       end
-      
-    end
 
-  end
+      # Always returns false.
+      #
+      # If the residue is HETATM, returns true.
+      # Otherwise, returns false.
+      def hetatm
+        false
+      end
+    end #class Residue
+
+    # Bio::PDB::Heterogen is a class to store a heterogen.
+    # It inherits Bio::PDB::Residue and most of the methods are the same.
+    #
+    # The object would contain some HETATMs
+    # (Bio::PDB::Record::HETATM objects).
+    class Heterogen < Residue
+
+      include HetatmFinder
+
+      # Always returns true.
+      #
+      # If the residue is HETATM, returns true.
+      # Otherwise, returns false.
+      def hetatm
+        true
+      end
+
+      # Alias to override HetatmFinder#each_hetatm
+      alias each_hetatm each
+
+      # Alias needed for HeterogenFinder.
+      alias hetatms atoms
+
+      # Alias to avoid confusion
+      alias heterogen_id residue_id
+    end #class Heterogen
+
+  end #class PDB
 
-end
+end #module Bio

data/lib/bio/db/pdb/utils.rb

@@ -1,9 +1,14 @@
 #
-# bio/db/pdb/utils.rb - Utility modules for PDB
+# = bio/db/pdb/utils.rb - Utility modules for PDB
 #
-#   Copyright (C) 2004 Alex Gutteridge <alexg@ebi.ac.uk>
-#   Copyright (C) 2004 GOTO Naohisa <ngoto@gen-info.osaka-u.ac.jp>
+# Copyright::  Copyright (C) 2004, 2006
+#              Alex Gutteridge <alexg@ebi.ac.uk>
+#              Naohisa Goto <ng@bioruby.org>
+# License:: LGPL
 #
+#  $Id: utils.rb,v 1.5 2006/01/08 12:59:04 ngoto 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
@@ -17,36 +22,69 @@
 #  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
+#++
+#
+# = Bio::PDB::Utils
+#
+# Bio::PDB::Utils
+#
+# = Bio::PDB::ModelFinder
+#
+# Bio::PDB::ModelFinder
+#
+# = Bio::PDB::ChainFinder
+#
+# Bio::PDB::ChainFinder
+#
+# = Bio::PDB::ResidueFinder
+#
+# Bio::PDB::ResidueFinder
+#
+# = Bio::PDB::AtomFinder
+#
+# Bio::PDB::AtomFinder
+#
+# = Bio::PDB::HeterogenFinder
+#
+# Bio::PDB::HeterogenFinder
+#
+# = Bio::PDB::HetatmFinder
+#
+# Bio::PDB::HetatmFinder
 #
-#  $Id: utils.rb,v 1.2 2005/09/08 01:22:11 k Exp $
 
 require 'matrix'
 require 'bio/db/pdb'
 
 module Bio; class PDB
 
+  # Utility methods for PDB data.
+  # The methods in this mixin should be applicalbe to all PDB objects.
+  #
+  # Bio::PDB::Utils is included by Bio::PDB, Bio::PDB::Model,
+  # Bio::PDB::Chain, Bio::PDB::Residue, and Bio::PDB::Heterogen classes.
   module Utils
-    #The methods in this mixin should be applicalbe to all PDB objects
     
-    #Returns the coordinates of the geometric centre (average co-ord)
-    #of any AtomFinder (or .atoms) implementing object
-    def geometricCentre()
-      
+    # Returns the coordinates of the geometric centre (average co-ord)
+    # of any AtomFinder (or .atoms) implementing object
+    #
+    # If you want to get the geometric centre of hetatms,
+    # call geometricCentre(:each_hetatm).
+    def geometricCentre(method = :each_atom)
       x = y = z = count = 0
       
-      self.each_atom{ |atom|
+      self.__send__(method) do |atom|
         x += atom.x
         y += atom.y
         z += atom.z
         count += 1
-      }
-      
-      x = x / count
-      y = y / count
-      z = z / count
+      end
       
+      x = (x / count)
+      y = (y / count)
+      z = (z / count)
+     
       Coordinate[x,y,z]
-      
     end
 
     #Returns the coords of the centre of gravity for any
@@ -63,8 +101,8 @@ module Bio; class PDB
       'P' => 31
     }
 
+    # calculates centre of gravitiy
     def centreOfGravity()
-      
       x = y = z = total = 0
       
       self.each_atom{ |atom|
@@ -81,19 +119,23 @@ module Bio; class PDB
       z = z / total
       
       Coordinate[x,y,z]
-      
     end
 
+    #--
     #Perhaps distance and dihedral would be better off as class methods?
     #(rather) than instance methods
-    def self.distance(coord1,coord2)
-      coord1 = to_xyz(coord1)
-      coord2 = to_xyz(coord2)
+    #++
+
+    # Calculates distance between _coord1_ and _coord2_.
+    def distance(coord1, coord2)
+      coord1 = convert_to_xyz(coord1)
+      coord2 = convert_to_xyz(coord2)
       (coord1 - coord2).r
     end
+    module_function :distance
 
-    def self.dihedral_angle(coord1,coord2,coord3,coord4)
-        
+    # Calculates dihedral angle.
+    def dihedral_angle(coord1, coord2, coord3, coord4)
       (a1,b1,c1,d) = calculatePlane(coord1,coord2,coord3)
       (a2,b2,c2)   = calculatePlane(coord2,coord3,coord4)
       
@@ -105,9 +147,10 @@ module Bio; class PDB
         torsion
       end
     end
+    module_function :dihedral_angle
       
-    #Implicit conversion into Vector or Bio::PDB::Coordinate
-    def self.to_xyz(obj)
+    # Implicit conversion into Vector or Bio::PDB::Coordinate
+    def convert_to_xyz(obj)
       unless obj.is_a?(Vector)
         begin
           obj = obj.xyz
@@ -117,18 +160,32 @@ module Bio; class PDB
       end
       obj
     end
+    module_function :convert_to_xyz
+
+    # (Deprecated) alias of convert_to_xyz(obj)
+    def self.to_xyz(obj)
+      convert_to_xyz(obj)
+    end
 
+    #--
     #Methods required for the dihedral angle calculations
     #perhaps these should go in some separate Math module
-    def self.rad2deg(r)
+    #++
+
+    # radian to degree
+    def rad2deg(r)
       (r/Math::PI)*180
     end
-    
-    def self.acos(x)
+    module_function :rad2deg
+
+    # acos
+    def acos(x)
       Math.atan2(Math.sqrt(1 - x**2),x)
     end
-      
-    def self.calculatePlane(coord1,coord2,coord3)
+    module_function :acos
+
+    # calculates plane
+    def calculatePlane(coord1, coord2, coord3)
       a = coord1.y * (coord2.z - coord3.z) +
           coord2.y * (coord3.z - coord1.z) + 
           coord3.y * (coord1.z - coord2.z)
@@ -146,13 +203,16 @@ module Bio; class PDB
            )
 
       return [a,b,c,d]
-        
     end
+    module_function :calculatePlane
 
-    #Every class in the heirarchy implements finder, this takes 
-    #a class which determines which type of object to find, the associated
-    #block is then run in classic .find style
-    def finder(findtype,&block)
+    # Every class in the heirarchy implements finder, this takes 
+    # a class which determines which type of object to find, the associated
+    # block is then run in classic .find style.
+    # 
+    # The method might be deprecated.
+    # You'd better using find_XXX  directly.
+    def finder(findtype, &block) #:yields: obj
       if findtype == Bio::PDB::Atom
         return self.find_atom(&block)
       elsif findtype == Bio::PDB::Residue
@@ -166,69 +226,190 @@ module Bio; class PDB
       end
     end
   end #module Utils
-  
+
+  #--
   #The *Finder modules implement a find_* method which returns
   #an array of anything for which the block evals true
   #(suppose Enumerable#find_all method).
   #The each_* style methods act as classic iterators.
+  #++
+
+  # methods to access models
+  #
+  # XXX#each_model must be defined.
+  #
+  # Bio::PDB::ModelFinder is included by Bio::PDB::PDB.
+  #
   module ModelFinder
-    def find_model()
+    # returns an array containing all chains for which given block
+    # is not +false+ (similar to Enumerable#find_all).
+    def find_model
       array = []
-      self.each_model{ |model|
+      self.each_model do |model|
         array.push(model) if yield(model)
-      }
+      end
       return array
     end
-  end
+  end #module ModelFinder
   
+  #--
   #The heirarchical nature of the objects allow us to re-use the
   #methods from the previous level - e.g. A PDB object can use the .models
   #method defined in ModuleFinder to iterate through the models to find the
   #chains
+  #++
+
+  # methods to access chains
+  #
+  # XXX#each_model must be defined.
+  #
+  # Bio::PDB::ChainFinder is included by Bio::PDB::PDB and Bio::PDB::Model.
+  #
   module ChainFinder
-    def find_chain()
+
+    # returns an array containing all chains for which given block
+    # is not +false+ (similar to Enumerable#find_all).
+    def find_chain
       array = []
-      self.each_chain{ |chain|
+      self.each_chain do |chain|
         array.push(chain) if yield(chain)
-      }
+      end
       return array
     end
-    def each_chain()
-      self.each_model{ |model|
-        model.each{ |chain| yield chain }
-      }
+
+    # iterates over each chain
+    def each_chain(&x) #:yields: chain
+      self.each_model { |model| model.each(&x) }
     end
-  end
+
+    # returns all chains
+    def chains
+      array = []
+      self.each_model { |model| array.concat(model.chains) }
+      return array
+    end
+  end #module ChainFinder
   
+  # methods to access residues
+  #
+  # XXX#each_chain must be defined.
+  #
+  # Bio::PDB::ResidueFinder is included by Bio::PDB::PDB, Bio::PDB::Model,
+  # and Bio::PDB::Chain.
+  #
   module ResidueFinder
-    def find_residue()
+
+    # returns an array containing all residues for which given block
+    # is not +false+ (similar to Enumerable#find_all).
+    def find_residue
       array = []
-      self.each_residue{ |residue|
+      self.each_residue do |residue|
         array.push(residue) if yield(residue)
-      }
+      end
       return array
     end
-    def each_residue()
-      self.each_chain{ |chain|
-        chain.each{ |residue| yield residue }
-      }
+
+    # iterates over each residue
+    def each_residue(&x) #:yields: residue
+      self.each_chain { |chain| chain.each(&x) }
+    end
+
+    # returns all residues
+    def residues
+      array = []
+      self.each_chain { |chain| array.concat(chain.residues) }
+      return array
     end
-  end
+  end #module ResidueFinder
   
+  # methods to access atoms
+  #
+  # XXX#each_residue must be defined.
   module AtomFinder
-    def find_atom()
+    # returns an array containing all atoms for which given block
+    # is not +false+ (similar to Enumerable#find_all).
+    def find_atom
       array = []
-      self.each_atom{ |atom|
+      self.each_atom do |atom|
         array.push(atom) if yield(atom)
-      }
+      end
       return array
     end
-    def each_atom()
-      self.each_residue{ |residue|
-        residue.each{ |atom| yield atom }
-      }
+
+    # iterates over each atom
+    def each_atom(&x) #:yields: atom
+      self.each_residue { |residue| residue.each(&x) }
+    end
+
+    # returns all atoms
+    def atoms
+      array = []
+      self.each_residue { |residue| array.concat(residue.atoms) }
+      return array
+    end
+  end #module AtomFinder
+
+  # methods to access HETATMs
+  #
+  # XXX#each_heterogen must be defined.
+  #
+  # Bio::PDB::HetatmFinder is included by Bio::PDB::PDB, Bio::PDB::Model,
+  # Bio::PDB::Chain, and Bio::PDB::Heterogen.
+  #
+  module HetatmFinder
+    # returns an array containing all HETATMs for which given block
+    # is not +false+ (similar to Enumerable#find_all).
+    def find_hetatm
+      array = []
+      self.each_hetatm do |hetatm|
+        array.push(hetatm) if yield(hetatm)
+      end
+      return array
+    end
+
+    # iterates over each HETATM
+    def each_hetatm(&x) #:yields: hetatm
+      self.each_heterogen { |heterogen| heterogen.each(&x) }
+    end
+
+    # returns all HETATMs
+    def hetatms
+      array = []
+      self.each_heterogen { |heterogen| array.concat(heterogen.hetatms) }
+      return array
+    end
+  end #module HetatmFinder
+
+  # methods to access heterogens (compounds or ligands)
+  #
+  # XXX#each_chain must be defined.
+  #
+  # Bio::PDB::HeterogenFinder is included by Bio::PDB::PDB, Bio::PDB::Model,
+  # and Bio::PDB::Chain.
+  #
+  module HeterogenFinder
+    # returns an array containing all heterogens for which given block
+    # is not +false+ (similar to Enumerable#find_all).
+    def find_heterogen
+      array = []
+      self.each_heterogen do |heterogen|
+        array.push(heterogen) if yield(heterogen)
+      end
+      return array
+    end
+
+    # iterates over each heterogens
+    def each_heterogen(&x) #:yields: heterogen
+      self.each_chain { |chain| chain.each_heterogen(&x) }
+    end
+
+    # returns all heterogens
+    def heterogens
+      array = []
+      self.each_chain { |chain| array.concat(chain.heterogens) }
+      return array
     end
-  end
+  end #module HeterogenFinder
 
 end; end #module Bio; class PDB