lib/bio/db/pdb/chain.rb in bio-0.7.0 vs lib/bio/db/pdb/chain.rb in bio-0.7.1

@@ -1,10 +1,16 @@
 #
-# bio/db/pdb/chain.rb - chain class for PDB
+# = bio/db/pdb/chain.rb - chain class for PDB
 #
-#   Copyright (C) 2004 Alex Gutteridge <[e-mail]>
+# Copyright:: Copyright (C) 2004, 2006
+#             Alex Gutteridge <[e-mail]>
+#             Naohisa Goto <[e-mail]>
+# License:: LGPL
+# 
+#  $Id: chain.rb,v 1.6 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
 #  version 2 of the License, or (at your option) any later version.
 #
@@ -14,104 +20,197 @@
 #  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
+#++
 #
-#  $Id: chain.rb,v 1.2 2005/09/26 13:00:08 k Exp $
+# = Bio::PDB::Chain
+# 
+# Please refer Bio::PDB::Chain.
+#
 
 require 'bio/db/pdb'
 
 module Bio
 
   class PDB
 
+    # Bio::PDB::Chain is a class to store a chain.
+    #
+    # The object would contain some residues (Bio::PDB::Residue objects)
+    # and some heterogens (Bio::PDB::Heterogen objects).
+    # 
     class Chain
       
       include Utils
       include AtomFinder
       include ResidueFinder
+
+      include HetatmFinder
+      include HeterogenFinder
+
       include Enumerable
       include Comparable
-      
-      attr_reader :id, :model
-      attr_writer :id
-      
+
+      # Creates a new chain object.
       def initialize(id = nil, model = nil)
         
-        @id       = id
+        @chain_id  = id
         
         @model    = model
         
-        @residues = Array.new
-        @ligands  = Array.new
-        
+        @residues   = []
+        @residues_hash = {}
+        @heterogens = []
+        @heterogens_hash = {}
       end
+
+      # Identifier of this chain
+      attr_accessor :chain_id
+      # alias
+      alias id chain_id
+
+      # the model to which this chain belongs.
+      attr_reader :model
+
+      # residues in this chain
+      attr_reader :residues
+
+      # heterogens in this chain
+      attr_reader :heterogens
       
-      #Keyed access to residues based on ids
+      # get the residue by id
+      def get_residue_by_id(key)
+        #@residues.find { |r| r.residue_id == key }
+        @residues_hash[key]
+      end
+
+      # get the residue by id.
+      #
+      # Compatibility Note: Now, you cannot find HETATMS in this method.
+      # To add "LIGAND" to the id is no longer available.
+      # To get heterogens, you must use <code>get_heterogen_by_id</code>.
       def [](key)
-        #If you want to find HETATMS you need to add LIGAND to the id
-        if key.to_s[0,6] == 'LIGAND'
-          residue = @ligands.find{ |residue| key.to_s == residue.id }
-        else
-          residue = @residues.find{ |residue| key.to_s == residue.id }
-        end
+        get_residue_by_id(key)
       end
+
+      # get the heterogen (ligand) by id
+      def get_heterogen_by_id(key)
+        #@heterogens.find { |r| r.residue_id == key }
+        @heterogens_hash[key]
+      end
       
       #Add a residue to this chain
       def addResidue(residue)
-        raise "Expecting a Bio::PDB::Residue" if not residue.is_a? Bio::PDB::Residue
+        raise "Expecting a Bio::PDB::Residue" unless residue.is_a? Bio::PDB::Residue
         @residues.push(residue)
+        if @residues_hash[residue.residue_id] then
+          $stderr.puts "Warning: residue_id #{residue.residue_id.inspect} is already used" if $VERBOSE
+        else
+          @residues_hash[residue.residue_id] = residue
+        end
         self
       end
       
-      #Add a ligand to this chain
-      def addLigand(residue)
-        raise "Expecting a Bio::PDB::Residue" if not residue.is_a? Bio::PDB::Residue
-        @ligands.push(residue)
+      #Add a heterogen (ligand) to this chain
+      def addLigand(ligand)
+        raise "Expecting a Bio::PDB::Residue" unless ligand.is_a? Bio::PDB::Residue
+        @heterogens.push(ligand)
+        if @heterogens_hash[ligand.residue_id] then
+          $stderr.puts "Warning: heterogen_id (residue_id) #{ligand.residue_id.inspect} is already used" if $VERBOSE
+        else
+          @heterogens_hash[ligand.residue_id] = ligand
+        end
         self
       end
-      
-      #Residue iterator
-      def each
-        @residues.each{ |residue| yield residue }
+
+      # rehash residues hash
+      def rehash_residues
+        begin
+          residues_bak = @residues
+          residues_hash_bak = @residues_hash
+          @residues = []
+          @residues_hash = {}
+          residues_bak.each do |residue|
+            self.addResidue(residue)
+          end
+        rescue RuntimeError
+          @residues = residues_bak
+          @residues_hash = residues_hash_bak
+          raise
+        end
+        self
       end
+
+      # rehash heterogens hash
+      def rehash_heterogens
+        begin
+          heterogens_bak = @heterogens
+          heterogens_hash_bak = @heterogens_hash
+          @heterogens = []
+          @heterogens_hash = {}
+          heterogens_bak.each do |heterogen|
+            self.addLigand(heterogen)
+          end
+        rescue RuntimeError
+          @heterogens = heterogens_bak
+          @heterogens_hash = heterogens_hash_bak
+          raise
+        end
+        self
+      end
+
+      # rehash residues hash and heterogens hash
+      def rehash
+        rehash_residues
+        rehash_heterogens
+      end
+
+      # Iterates over each residue
+      def each(&x) #:yields: residue
+        @residues.each(&x)
+      end
       #Alias to override ResidueFinder#each_residue
       alias each_residue each
+
+      # Iterates over each hetero-compound
+      def each_heterogen(&x) #:yields: heterogen
+        @heterogens.each(&x)
+      end
       
-      #Sort based on chain id
+      # Operator aimed to sort based on chain id
       def <=>(other)
-        return @id <=> other.id
+        return @chain_id <=> other.chain_id
       end
       
-      #Stringifies each residue
+      # Stringifies each residue
       def to_s
-        string = ""
-        @residues.each{ |residue| string << residue.to_s }
-        string = string << "TER\n"
-        return string
+        @residues.join('') + "TER\n" + @heterogens.join('')
       end
 
-      def atom_seq
-        string = ""
-        last_residue_num = nil
-        @residues.each{ |residue|
-          if last_residue_num and 
-              (residue.resSeq.to_i - last_residue_num).abs > 1
-            (residue.resSeq.to_i - last_residue_num).abs.times{ string << 'X' }
+      # gets an amino acid sequence of this chain from ATOM records
+      def aaseq
+        unless defined? @aaseq
+          string = ""
+          last_residue_num = nil
+          @residues.each do |residue|
+            if last_residue_num and 
+                (x = (residue.resSeq.to_i - last_residue_num).abs) > 1 then
+              x.times { string << 'X' }
+            end
+            tlc = residue.resName.capitalize
+            olc = (Bio::AminoAcid.three2one(tlc) or 'X')
+            string << olc
           end
-          tlc = residue.resName.capitalize
-          olc = AminoAcid.names.invert[tlc]
-          if !olc
-            olc = 'X'
-          end
-          string << olc
-        }
-        Bio::Sequence::AA.new(string)
-        
+          @aaseq = Bio::Sequence::AA.new(string)
+        end
+        @aaseq
       end
+      # for backward compatibility
+      alias atom_seq aaseq
       
-    end
+    end #class Chain
 
-  end
+  end #class PDB
 
-end
+end #module Bio