bio 0.7.1 → 1.0.0

data/lib/bio/db/embl/common.rb

@@ -4,12 +4,15 @@
 # Copyright::   Copyright (C) 2001-2005 Mitsuteru C. Nakao <n@bioruby.org>
 # License::     LGPL
 #
-# $Id: common.rb,v 1.8 2005/11/02 07:30:14 nakao Exp $
+# $Id: common.rb,v 1.9 2006/01/28 06:40:38 nakao Exp $
 #
-# == EMBL style databases class
+# == Description
 #
-# This module defines a common framework among EMBL, SWISS-PROT, TrEMBL.
-# For more details, see the documentations in each embl/*.rb libraries.
+# EMBL style databases class
+#
+# This module defines a common framework among EMBL, UniProtKB, SWISS-PROT, 
+# TrEMBL. For more details, see the documentations in each embl/*.rb 
+# libraries.
 #
 # EMBL style format:
 #     ID - identification             (begins each entry; 1 per entry)
@@ -38,9 +41,9 @@
 #     bb - (blanks) sequence data     (>=1 per entry)
 #     // - termination line           (ends each entry; 1 per entry)
 #
-#
-# == Example
+# == Examples
 # 
+#  # Make a new parser class for EMBL style database entry.
 #  require 'bio/db/embl/common'
 #  module Bio
 #    class NEWDB < EMBLDB
@@ -48,6 +51,24 @@
 #    end
 #  end
 #
+# == References
+#
+# * The EMBL Nucleotide Sequence Database
+#   http://www.ebi.ac.uk/embl/
+#
+# * The EMBL Nucleotide Sequence Database: Users Manual
+#   http://www.ebi.ac.uk/embl/Documentation/User_manual/usrman.html
+# 
+# * Swiss-Prot Protein knowledgebase. TrEMBL Computer-annotated supplement 
+#   to Swiss-Prot 
+#   http://au.expasy.org/sprot/
+# 
+# * UniProt 
+#   http://uniprot.org/
+# 
+# * The UniProtKB/SwissProt/TrEMBL User Manual 
+#   http://www.expasy.org/sprot/userman.html
+#
 #--
 #
 #  This library is free software; you can redistribute it and/or

data/lib/bio/db/embl/embl.rb

@@ -5,20 +5,28 @@
 # Copyright::   Copyright (C) 2001-2005 Mitsuteru C. Nakao <n@bioruby.org>
 # License::     LGPL
 #
-# $Id: embl.rb,v 1.25 2005/11/02 07:30:14 nakao Exp $
+# $Id: embl.rb,v 1.26 2006/01/28 06:40:38 nakao Exp $
 #
-# == EMBL database entry
+# == Description
 #
+# Parser class for EMBL database entry.
 #
-#
-# == Example
+# == Examples
 # 
-# emb = Bio::EMBL.new($<.read)
-# emb.entry_id
-# emb.each_cds do |cds|
-#   cds
-# end
-# emb.seq
+#   emb = Bio::EMBL.new($<.read)
+#   emb.entry_id
+#   emb.each_cds do |cds|
+#     cds # A CDS in feature table.
+#   end
+#   emb.seq #=> "ACGT..."
+#
+# == References
+#
+# * The EMBL Nucleotide Sequence Database
+#   http://www.ebi.ac.uk/embl/
+#
+# * The EMBL Nucleotide Sequence Database: Users Manual
+#   http://www.ebi.ac.uk/embl/Documentation/User_manual/usrman.html
 #
 #--
 #

data/lib/bio/db/embl/sptr.rb

@@ -4,13 +4,32 @@
 # Copyright::   Copyright (C) 2001-2005 Mitsuteru C. Nakao <n@bioruby.org>
 # License::     LGPL
 #
-# $Id: sptr.rb,v 1.29 2005/11/02 07:30:14 nakao Exp $
+# $Id: sptr.rb,v 1.30 2006/01/28 06:40:38 nakao Exp $
 #
-# == UniProtKB/SwissProt and TrEMBL
+# == Description
+# 
+# Shared methods for UniProtKB/SwissProt and TrEMBL classes.
+#
+# See the SWISS-PROT document file SPECLIST.TXT or UniProtKB/SwissProt 
+# user manual.
+# 
+# == Examples
+#
+#   str = File.read("p53_human.swiss")
+#   obj = Bio::SPTR.new(str)
+#   obj.entry_id #=> "P53_HUMAN"
+# 
+# == References
+# 
+# * Swiss-Prot Protein knowledgebase. TrEMBL Computer-annotated supplement 
+#   to Swiss-Prot	
+#   http://au.expasy.org/sprot/
 #
-# See the SWISS-PROT dicument file SPECLIST.TXT.
+# * UniProt
+#   http://uniprot.org/
 #
-# == Example
+# * The UniProtKB/SwissProt/TrEMBL User Manual
+#   http://www.expasy.org/sprot/userman.html
 #
 #--
 #
@@ -36,7 +55,7 @@ require 'bio/db/embl/common'
 
 module Bio
 
-# Parser class for UniProtKB/SwissProt and TrEMBL database entry
+# Parser class for UniProtKB/SwissProt and TrEMBL database entry.
 class SPTR < EMBLDB
   include Bio::EMBLDB::Common
     
@@ -45,17 +64,19 @@ class SPTR < EMBLDB
 
   
   # returns a Hash of the ID line.
+  #
   # returns a content (Int or String) of the ID line by a given key.
   # Hash keys: ['ENTRY_NAME', 'DATA_CLASS', 'MODECULE_TYPE', 'SEQUENCE_LENGTH']
   #
-  # ID Line
-  # "ID  #{ENTRY_NAME} #{DATA_CLASS}; #{MOLECULE_TYPE}; #{SEQUENCE_LENGTH}."
+  # === ID Line
+  #   ID   P53_HUMAN      STANDARD;      PRT;   393 AA.
+  #   #"ID  #{ENTRY_NAME} #{DATA_CLASS}; #{MOLECULE_TYPE}; #{SEQUENCE_LENGTH}."
+  #
+  # === Examples
+  #   obj.id_line  #=> {"ENTRY_NAME"=>"P53_HUMAN", "DATA_CLASS"=>"STANDARD", "SEQUENCE_LENGTH"=>393, "MOLECULE_TYPE"=>"PRT"}
+  #
+  #   obj.id_line('ENTRY_NAME') #=> "P53_HUMAN"
   #
-  #   ENTRY_NAME := "#{X}_#{Y}"
-  #     X =~ /[A-Z0-9]{1,5}/ # The protein name.
-  #     Y =~ /[A-Z0-9]{1,5}/ # The biological source of the protein.
-  #   MOLECULE_TYPE := 'PRT' =~ /\w{3}/ 
-  #   SEQUENCE_LENGTH =~ /\d+ AA/
   def id_line(key = nil)
     unless @data['ID']
       tmp = Hash.new
@@ -78,7 +99,6 @@ class SPTR < EMBLDB
 
   # returns a ENTRY_NAME in the ID line. 
   #
-  # A short-cut for Bio::SPTR#id_line('ENTRY_NAME').
   def entry_id
     id_line('ENTRY_NAME')
   end
@@ -119,10 +139,10 @@ class SPTR < EMBLDB
   #
   # returns a String of information in the DT lines by a given key..
   #
-  # DT Line; date (3/entry)
-  #  DT DD-MMM-YYY (rel. NN, Created)
-  #  DT DD-MMM-YYY (rel. NN, Last sequence update)
-  #  DT DD-MMM-YYY (rel. NN, Last annotation update)
+  # === DT Line; date (3/entry)
+  #   DT DD-MMM-YYY (rel. NN, Created)
+  #   DT DD-MMM-YYY (rel. NN, Last sequence update)
+  #   DT DD-MMM-YYY (rel. NN, Last annotation update)
   def dt(key = nil)
     unless @data['DT']
       tmp = Hash.new
@@ -143,7 +163,7 @@ class SPTR < EMBLDB
 
   # returns the proposed official name of the protein.
   # 
-  # DE Line; description (>=1)
+  # === DE Line; description (>=1)
   #  "DE #{OFFICIAL_NAME} (#{SYNONYM})"
   #  "DE #{OFFICIAL_NAME} (#{SYNONYM}) [CONTEINS: #1; #2]."
   #  OFFICIAL_NAME  1/entry
@@ -192,7 +212,7 @@ class SPTR < EMBLDB
   # * Bio::SPTR#gn -> Array      # AND 
   # * Bio::SPTR#gn[0] -> Array   # OR
   #
-  # GN Line: Gene name(s) (>=0, optional)
+  # === GN Line: Gene name(s) (>=0, optional)
   def gn
     return @data['GN'] if @data['GN']
 
@@ -205,7 +225,7 @@ class SPTR < EMBLDB
   end
 
   # returns contents in the old style GN line.
-  # GN Line: Gene name(s) (>=0, optional)
+  # === GN Line: Gene name(s) (>=0, optional)
   #  GN   HNS OR DRDX OR OSMZ OR BGLY.
   #  GN   CECA1 AND CECA2.
   #  GN   CECA1 AND (HOGE OR FUGA).
@@ -292,7 +312,7 @@ class SPTR < EMBLDB
   # * Bio::SPTR#os[0]['name'] -> "(Human)"
   # * Bio::EPTR#os(0) -> "Homo sapiens (Human)"
   # 
-  # OS Line; organism species (>=1)
+  # === OS Line; organism species (>=1)
   #  OS   Genus species (name).
   #  OS   Genus species (name0) (name1).
   #  OS   Genus species (name0) (name1).
@@ -337,9 +357,9 @@ class SPTR < EMBLDB
 
   # returns a Hash of oraganism taxonomy cross-references.
   # * Bio::SPTR#ox -> Hash
-  #  {'NCBI_TaxID' => ['1234','2345','3456','4567'], ...}
+  #    {'NCBI_TaxID' => ['1234','2345','3456','4567'], ...}
   #
-  # OX Line; organism taxonomy cross-reference (>=1 per entry)
+  # === OX Line; organism taxonomy cross-reference (>=1 per entry)
   #  OX   NCBI_TaxID=1234;
   #  OX   NCBI_TaxID=1234, 2345, 3456, 4567;
   def ox
@@ -368,43 +388,43 @@ class SPTR < EMBLDB
     'SIMILARITY','SUBCELLULAR LOCATION','SUBUNIT','TISSUE SPECIFICITY']
   # returns contents in the CC lines.
   # * Bio::SPTR#cc -> Hash
-
-  # * Bio::SPTR#cc(Int) -> String
-  # returns an Array of contents in the TOPIC string.
+  #
+  # returns an object of contents in the TOPIC.
   # * Bio::SPTR#cc(TOPIC) -> Array w/in Hash, Hash
   #
   # returns contents of the "ALTERNATIVE PRODUCTS".
   # * Bio::SPTR#cc('ALTERNATIVE PRODUCTS') -> Hash
-  #  {'Event' => str, 
-  #   'Named isoforms' => int,  
-  #   'Comment' => str,
-  #   'Variants'=>[{'Name' => str, 'Synonyms' => str, 'IsoId' => str, 'Sequence' => []}]}
+  #    {'Event' => str, 
+  #     'Named isoforms' => int,  
+  #     'Comment' => str,
+  #     'Variants'=>[{'Name' => str, 'Synonyms' => str, 'IsoId' => str, 'Sequence' => []}]}
   # 
-  #  CC   -!- ALTERNATIVE PRODUCTS:
-  #  CC       Event=Alternative splicing; Named isoforms=15;
-  #  ...
-  #  CC         placentae isoforms. All tissues differentially splice exon 13;
-  #  CC       Name=A; Synonyms=no del;
-  #  CC         IsoId=P15529-1; Sequence=Displayed;
+  #    CC   -!- ALTERNATIVE PRODUCTS:
+  #    CC       Event=Alternative splicing; Named isoforms=15;
+  #    ...
+  #    CC         placentae isoforms. All tissues differentially splice exon 13;
+  #    CC       Name=A; Synonyms=no del;
+  #    CC         IsoId=P15529-1; Sequence=Displayed;
   #
   # returns contents of the "DATABASE".
   # * Bio::SPTR#cc('DATABASE') -> Array
-  #  [{'NAME'=>str,'NOTE'=>str, 'WWW'=>URI,'FTP'=>URI}, ...]
+  #    [{'NAME'=>str,'NOTE'=>str, 'WWW'=>URI,'FTP'=>URI}, ...]
   #
-  #  CC   -!- DATABASE: NAME=Text[; NOTE=Text][; WWW="Address"][; FTP="Address"].
+  #    CC   -!- DATABASE: NAME=Text[; NOTE=Text][; WWW="Address"][; FTP="Address"].
   #
   # returns contents of the "MASS SPECTROMETRY".
   # * Bio::SPTR#cc('MASS SPECTROMETRY') -> Array
-  #  [{'MW"=>float,'MW_ERR'=>float, 'METHOD'=>str,'RANGE'=>str}, ...]
+  #    [{'MW"=>float,'MW_ERR'=>float, 'METHOD'=>str,'RANGE'=>str}, ...]
   #
-  #  MASS SPECTROMETRY: MW=XXX[; MW_ERR=XX][; METHOD=XX][;RANGE=XX-XX].
+  #    CC   -!- MASS SPECTROMETRY: MW=XXX[; MW_ERR=XX][; METHOD=XX][;RANGE=XX-XX].
+  #
+  # === CC lines (>=0, optional)
+  #   CC   -!- TISSUE SPECIFICITY: HIGHEST LEVELS FOUND IN TESTIS. ALSO PRESENT
+  #   CC       IN LIVER, KIDNEY, LUNG AND BRAIN.
+  # 
+  #   CC   -!- TOPIC: FIRST LINE OF A COMMENT BLOCK;
+  #   CC       SECOND AND SUBSEQUENT LINES OF A COMMENT BLOCK.
   #
-  # CC lines (>=0, optional)
-  #  CC   -!- TISSUE SPECIFICITY: HIGHEST LEVELS FOUND IN TESTIS. ALSO PRESENT
-  #  CC       IN LIVER, KIDNEY, LUNG AND BRAIN.
-  #  
-  #  CC   -!- TOPIC: FIRST LINE OF A COMMENT BLOCK;
-  #  CC       SECOND AND SUBSEQUENT LINES OF A COMMENT BLOCK.
   def cc(tag = nil)
     unless @data['CC']
       cc  = Hash.new
@@ -541,7 +561,7 @@ class SPTR < EMBLDB
 
   # returns conteins in a line of the CC INTERACTION section.
   #
-  #  CC       P46527:CDKN1B; NbExp=1; IntAct=EBI-359815, EBI-519280;
+  #   CC       P46527:CDKN1B; NbExp=1; IntAct=EBI-359815, EBI-519280;
   def cc_interaction_parse(str)
     it = str.scan(/(.+?); NbExp=(.+?); IntAct=(.+?);/)
     it.map {|ent|
@@ -555,9 +575,9 @@ class SPTR < EMBLDB
   # returns databases cross-references in the DR lines.
   # * Bio::EMBLDB#dr  -> Hash w/in Array
   #
-  # DR Line; defabases cross-reference (>=0)
-  # a cross_ref pre one line
-  #  DR  database_identifier; primary_identifier; secondary_identifier.
+  # === DR Line; defabases cross-reference (>=0)
+  #    DR  database_identifier; primary_identifier; secondary_identifier.
+  #  a cross_ref pre one line
   @@dr_database_identifier = ['EMBL','CARBBANK','DICTYDB','ECO2DBASE',
     'ECOGENE',
     'FLYBASE','GCRDB','HIV','HSC-2DPAGE','HSSP','INTERPRO','MAIZEDB',
@@ -574,23 +594,23 @@ class SPTR < EMBLDB
 
   # returns conteins in the feature table.
   # * Bio::SPTR#ft -> Hash
-  #  {'feature_name' => [{'From' => str, 'To' => str,
-  #                       'Description' => str, 'FTId' => str}],...}
+  #    {'feature_name' => [{'From' => str, 'To' => str,
+  #                         'Description' => str, 'FTId' => str}],...}
   #
   # returns an Array of the information about the feature_name in the feature table.
   # * Bio::SPTR#ft(feature_name) -> Array of Hash
-  #  [{'From' => str, 'To' => str, 'Description' => str, 'FTId' => str},...]
-  #
-  # FT Line; feature table data (>=0, optional)
-  #
-  #  Col     Data item
-  #  -----   -----------------
-  #   1- 2   FT
-  #   6-13   Feature name 
-  #  15-20   `FROM' endpoint
-  #  22-27   `TO' endpoint
-  #  35-75   Description (>=0 per key)
-  #  -----   -----------------
+  #    [{'From' => str, 'To' => str, 'Description' => str, 'FTId' => str},...]
+  #
+  # == FT Line; feature table data (>=0, optional)
+  #
+  #   Col     Data item
+  #   -----   -----------------
+  #    1- 2   FT
+  #    6-13   Feature name 
+  #   15-20   `FROM' endpoint
+  #   22-27   `TO' endpoint
+  #   35-75   Description (>=0 per key)
+  #   -----   -----------------
   def ft(feature_name = nil)
     unless @data['FT']
       table        = Hash.new()
@@ -692,9 +712,9 @@ class SPTR < EMBLDB
   # * Bio::SPTRL#sq(key)  -> int or str
   # * Keys: ['MW', 'mw', 'molecular', 'weight', 'aalen', 'len', 'length', 'CRC64']
   #
-  # SQ Line; sequence header (1/entry)
-  #  SQ   SEQUENCE   233 AA;  25630 MW;  146A1B48A1475C86 CRC64;
-  #  SQ   SEQUENCE  \d+ AA; \d+ MW;  [0-9A-Z]+ CRC64;
+  # === SQ Line; sequence header (1/entry)
+  #    SQ   SEQUENCE   233 AA;  25630 MW;  146A1B48A1475C86 CRC64;
+  #    SQ   SEQUENCE  \d+ AA; \d+ MW;  [0-9A-Z]+ CRC64;
   #
   # MW, Dalton unit.
   # CRC64 (64-bit Cyclic Redundancy Check, ISO 3309).

data/lib/bio/db/embl/swissprot.rb

@@ -1,7 +1,34 @@
 #
-# bio/db/embl/swissprot.rb - SwissProt database class
+# = bio/db/embl/swissprot.rb - SwissProt database class
 # 
-#   Copyright (C) 2001, 2002 KATAYAMA Toshiaki <k@bioruby.org>
+# Copyright::   Copyright (C) 2001, 2002 KATAYAMA Toshiaki <k@bioruby.org>
+# License::     LGPL
+#
+#  $Id: swissprot.rb,v 1.4 2006/01/28 06:40:38 nakao Exp $
+#
+# == Description
+# 
+# Name space for SwissProt specific methods.
+#
+# SwissProt (before UniProtKB/SwissProt) specific methods are defined in 
+# this class. Shared methods for UniProtKB/SwissProt and TrEMBL classes 
+# are defined in Bio::SPTR class.
+#
+# == Examples
+#
+#   str = File.read("p53_human.swiss")
+#   obj = Bio::SwissProt.new(str)
+#   obj.entry_id #=> "P53_HUMAN"
+#
+# == Referencees
+#
+# * Swiss-Prot Protein knowledgebase
+#   http://au.expasy.org/sprot/
+#
+# * Swiss-Prot Protein Knowledgebase User Manual
+#   http://au.expasy.org/sprot/userman.html
+# 
+#-- 
 #
 #  This library is free software; you can redistribute it and/or
 #  modify it under the terms of the GNU Lesser General Public
@@ -17,13 +44,15 @@
 #  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: swissprot.rb,v 1.3 2004/08/23 23:40:35 k Exp $
+#++
 #
 
 require 'bio/db/embl/sptr'
 
 module Bio
 
+# Parser class for SwissProt database entry.
+# See also Bio::SPTR class.
 class SwissProt < SPTR
   # Nothing to do (SwissProt format is abstracted in SPTR)
 end

data/lib/bio/db/embl/trembl.rb

@@ -1,7 +1,34 @@
 #
-# bio/db/embl/trembl.rb - TrEMBL database class
+# = bio/db/embl/trembl.rb - TrEMBL database class
 # 
-#   Copyright (C) 2001, 2002 KATAYAMA Toshiaki <k@bioruby.org>
+# Copyright::   Copyright (C) 2001, 2002 KATAYAMA Toshiaki <k@bioruby.org>
+# License::     LGPL
+#
+#  $Id: trembl.rb,v 1.4 2006/01/28 06:40:38 nakao Exp $
+#
+# == Description
+#
+# Name space for TrEMBL specific methods.
+#
+# UniProtKB/SwissProt specific methods are defined in this class. 
+# Shared methods for UniProtKB/SwissProt and TrEMBL classes are 
+# defined in Bio::SPTR class.
+#
+# == Examples
+#
+#   str = File.read("Q2UNG2_ASPOR.trembl")
+#   obj = Bio::TrEMBL.new(str)
+#   obj.entry_id #=> "Q2UNG2_ASPOR"
+#
+# == Referencees
+#
+# * TrEMBL Computer-annotated supplement to Swiss-Prot	
+#   http://au.expasy.org/sprot/
+#
+# * TrEMBL Computer-annotated supplement to Swiss-Prot User Manual
+#   http://au.expasy.org/sprot/userman.html
+# 
+#-- 
 #
 #  This library is free software; you can redistribute it and/or
 #  modify it under the terms of the GNU Lesser General Public
@@ -17,13 +44,15 @@
 #  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: trembl.rb,v 1.3 2004/08/23 23:40:35 k Exp $
+#++
 #
 
 require 'bio/db/embl/sptr'
 
 module Bio
 
+# Parser class for TrEMBL database entry.
+# See also Bio::SPTR class.
 class TrEMBL < SPTR
   # Nothing to do (TrEMBL format is abstracted in SPTR)
 end