bio 1.3.1 → 1.4.0

data/lib/bio/db/kegg/compound.rb

@@ -4,19 +4,44 @@
 # Copyright::  Copyright (C) 2001, 2002, 2004, 2007 Toshiaki Katayama <k@bioruby.org>
 # License::    The Ruby License
 #
-# $Id: compound.rb,v 0.17 2007/11/27 07:09:43 k Exp $
+# $Id:$
 #
 
 require 'bio/db'
+require 'bio/db/kegg/common'
 
 module Bio
 class KEGG
 
+# == Description
+#
+# Bio::KEGG::COMPOUND is a parser class for the KEGG COMPOUND database entry.
+# KEGG COMPOUND is a chemical structure database.
+#
+# == References
+# 
+# * http://www.genome.jp/kegg/compound/
+#
 class COMPOUND < KEGGDB
 
   DELIMITER	= RS = "\n///\n"
   TAGSIZE	= 12
 
+  include Common::DblinksAsHash
+  # Returns a Hash of the DB name and an Array of entry IDs in DBLINKS field.
+  def dblinks_as_hash; super; end if false #dummy for RDoc
+  alias dblinks dblinks_as_hash
+
+  include Common::PathwaysAsHash
+  # Returns a Hash of the pathway ID and name in PATHWAY field.
+  def pathways_as_hash; super; end if false #dummy for RDoc
+  alias pathways pathways_as_hash
+
+  # Creates a new Bio::KEGG::COMPOUND object.
+  # ---
+  # *Arguments*:
+  # * (required) _entry_: (String) single entry as a string
+  # *Returns*:: Bio::KEGG::COMPOUND object
   def initialize(entry)
     super(entry, TAGSIZE)
   end
@@ -31,6 +56,7 @@ class COMPOUND < KEGGDB
     field_fetch('NAME').split(/\s*;\s*/)
   end
 
+  # The first name recorded in the NAME field.
   def name
     names.first
   end
@@ -75,7 +101,7 @@ class COMPOUND < KEGGDB
   end
 
   # PATHWAY
-  def pathways
+  def pathways_as_strings
     lines_fetch('PATHWAY') 
   end
 
@@ -93,7 +119,7 @@ class COMPOUND < KEGGDB
   end
 
   # DBLINKS
-  def dblinks
+  def dblinks_as_strings
     lines_fetch('DBLINKS')
   end
 
@@ -112,20 +138,3 @@ end # COMPOUND
 end # KEGG
 end # Bio
 
-
-if __FILE__ == $0
-  entry = ARGF.read
-  cpd = Bio::KEGG::COMPOUND.new(entry)
-  p cpd.entry_id
-  p cpd.names
-  p cpd.name
-  p cpd.formula
-  p cpd.mass
-  p cpd.reactions
-  p cpd.rpairs
-  p cpd.pathways
-  p cpd.enzymes
-  p cpd.dblinks
-  p cpd.kcf
-end
-

data/lib/bio/db/kegg/drug.rb

@@ -4,95 +4,135 @@
 # Copyright::  Copyright (C) 2007 Toshiaki Katayama <k@bioruby.org>
 # License::    The Ruby License
 #
-# $Id: drug.rb,v 1.3 2007/06/28 11:27:24 k Exp $
+# $Id:$
 #
 
 require 'bio/db'
+require 'bio/db/kegg/common'
 
 module Bio
 class KEGG
 
+# == Description
+#
+# Bio::KEGG::DRUG is a parser class for the KEGG DRUG database entry.
+# KEGG DRUG is a drug information database.
+#
+# == References
+# 
+# * http://www.genome.jp/kegg/drug/
+#
 class DRUG < KEGGDB
 
   DELIMITER	= RS = "\n///\n"
   TAGSIZE	= 12
 
+  include Common::DblinksAsHash
+  # Returns a Hash of the DB name and an Array of entry IDs in DBLINKS field.
+  def dblinks_as_hash; super; end if false #dummy for RDoc
+  alias dblinks dblinks_as_hash
+
+  include Common::PathwaysAsHash
+  # Returns a Hash of the pathway ID and name in PATHWAY field.
+  def pathways_as_hash; super; end if false #dummy for RDoc
+  alias pathways pathways_as_hash
+
+  # Creates a new Bio::KEGG::DRUG object.
+  # ---
+  # *Arguments*:
+  # * (required) _entry_: (String) single entry as a string
+  # *Returns*:: Bio::KEGG::DRUG object
   def initialize(entry)
     super(entry, TAGSIZE)
   end
 
-  # ENTRY
+  # ID of the entry, described in the ENTRY line.
+  # ---
+  # *Returns*:: String
   def entry_id
     field_fetch('ENTRY')[/\S+/]
   end
 
-  # NAME
+  # Names described in the NAME line.
+  # ---
+  # *Returns*:: Array containing String objects
   def names
     field_fetch('NAME').split(/\s*;\s*/)
   end
 
+  # The first name recorded in the NAME field.
+  # ---
+  # *Returns*:: String
   def name
     names.first
   end
 
-  # FORMULA
+  # Chemical formula described in the FORMULA line.
+  # ---
+  # *Returns*:: String
   def formula
     field_fetch('FORMULA')
   end
 
-  # MASS
+  # Molecular weight described in the MASS line.
+  # ---
+  # *Returns*:: Float
   def mass
     field_fetch('MASS').to_f
   end
 
-  # ACTIVITY
+  # Biological or chemical activity described in the ACTIVITY line.
+  # ---
+  # *Returns*:: String
   def activity
     field_fetch('ACTIVITY')
   end
 
-  # REMARK
+  # REMARK lines.
+  # ---
+  # *Returns*:: String
   def remark
     field_fetch('REMARK')
   end
 
-  # COMMENT
-  def comment
-    field_fetch('COMMENT')
-  end
-
-  # PATHWAY
-  def pathways
-    lines_fetch('DBLINKS')
+  # List of KEGG Pathway IDs with short descriptions,
+  # described in the PATHWAY lines.
+  # ---
+  # *Returns*:: Array containing String objects
+  def pathways_as_strings
+    lines_fetch('PATHWAY') 
   end
 
-  # DBLINKS
-  def dblinks
+  # List of database names and IDs, described in the DBLINKS lines.
+  # ---
+  # *Returns*:: Array containing String objects
+  def dblinks_as_strings
     lines_fetch('DBLINKS')
   end
 
-  # ATOM, BOND
+  # ATOM, BOND lines.
+  # ---
+  # *Returns*:: String
   def kcf
     return "#{get('ATOM')}#{get('BOND')}"
   end
 
+  # COMMENT lines.
+  # ---
+  # *Returns*:: String
+  def comment
+    field_fetch('COMMENT')
+  end
+
+  # Product names described in the PRODUCTS lines.
+  # ---
+  # *Returns*:: Array containing String objects
+  def products
+    lines_fetch('PRODUCTS')
+  end
+
 end # DRUG
 
 end # KEGG
 end # Bio
 
-
-if __FILE__ == $0
-  entry = ARGF.read	# dr:D00001
-  dr = Bio::KEGG::DRUG.new(entry)
-  p dr.entry_id
-  p dr.names
-  p dr.name
-  p dr.formula
-  p dr.mass
-  p dr.activity
-  p dr.remark
-  p dr.comment
-  p dr.dblinks
-  p dr.kcf
-end
-

data/lib/bio/db/kegg/enzyme.rb

@@ -4,10 +4,11 @@
 # Copyright::  Copyright (C) 2001, 2002, 2007 Toshiaki Katayama <k@bioruby.org>
 # License::    The Ruby License
 #
-# $Id: enzyme.rb,v 0.12 2007/12/14 16:20:38 k Exp $
+# $Id:$
 #
 
 require 'bio/db'
+require 'bio/db/kegg/common'
 
 module Bio
 class KEGG
@@ -17,6 +18,26 @@ class ENZYME < KEGGDB
   DELIMITER	= RS = "\n///\n"
   TAGSIZE	= 12
 
+  include Common::DblinksAsHash
+  # Returns a Hash of the DB name and an Array of entry IDs in DBLINKS field.
+  def dblinks_as_hash; super; end if false #dummy for RDoc
+  alias dblinks dblinks_as_hash
+
+  include Common::PathwaysAsHash
+  # Returns a Hash of the pathway ID and name in PATHWAY field.
+  def pathways_as_hash; super; end if false #dummy for RDoc
+  alias pathways pathways_as_hash
+
+  include Common::OrthologsAsHash
+  # Returns a Hash of the orthology ID and definition in ORTHOLOGY field.
+  def orthologs_as_hash; super; end if false #dummy for RDoc
+  alias orthologs orthologs_as_hash
+
+  include Common::GenesAsHash
+  # Returns a Hash of the organism ID and an Array of entry IDs in GENES field.
+  def genes_as_hash; super; end if false #dummy for RDoc
+  alias genes genes_as_hash
+
   def initialize(entry)
     super(entry, TAGSIZE)
   end
@@ -102,17 +123,17 @@ class ENZYME < KEGGDB
   end
 
   # PATHWAY
-  def pathways
+  def pathways_as_strings
     lines_fetch('PATHWAY')
   end
 
   # ORTHOLOGY
-  def orthologs
+  def orthologs_as_strings
     lines_fetch('ORTHOLOGY')
   end
 
   # GENES
-  def genes
+  def genes_as_strings
     lines_fetch('GENES')
   end
 
@@ -137,7 +158,7 @@ class ENZYME < KEGGDB
   # REFERENCE
 
   # DBLINKS
-  def dblinks
+  def dblinks_as_strings
     lines_fetch('DBLINKS')
   end
 

data/lib/bio/db/kegg/genes.rb

@@ -5,7 +5,7 @@
 #               Toshiaki Katayama <k@bioruby.org>
 # License::     The Ruby License
 #
-# $Id: genes.rb,v 0.26 2007/12/14 16:20:38 k Exp $
+# $Id:$
 #
 #
 # == KEGG GENES parser
@@ -38,7 +38,7 @@
 # 
 #  # PATHWAY
 #  p entry.pathway     # => String
-#  p entry.pathways    # => Array
+#  p entry.pathways    # => Hash
 # 
 #  # POSITION
 #  p entry.position    # => String
@@ -52,6 +52,9 @@
 #  # DBLINKS
 #  p entry.dblinks     # => Hash of Array
 # 
+#  # STRUCTURE
+#  p entry.structure   # => Array
+#
 #  # CODON_USAGE
 #  p entry.codon_usage # => Hash
 #  p entry.cu_list     # => Array
@@ -73,18 +76,53 @@ module Bio
   autoload :Locations, 'bio/location'
   autoload :Sequence,  'bio/sequence'
 
+  require 'bio/db/kegg/common'
+
 class KEGG
 
+# == Description
+#
+# KEGG GENES entry parser.
+#
+# == References
+#
+# * http://www.genome.jp/kegg/genes.html
+#
 class GENES < KEGGDB
 
   DELIMITER	= RS = "\n///\n"
   TAGSIZE	= 12
 
+  include Common::DblinksAsHash
+  # Returns a Hash of the DB name and an Array of entry IDs in DBLINKS field.
+  def dblinks_as_hash; super; end if false #dummy for RDoc
+  alias dblinks dblinks_as_hash
+
+  include Common::PathwaysAsHash
+  # Returns a Hash of the pathway ID and name in PATHWAY field.
+  def pathways_as_hash; super; end if false #dummy for RDoc
+  alias pathways pathways_as_hash
+
+  include Common::OrthologsAsHash
+  # Returns a Hash of the orthology ID and definition in ORTHOLOGY field.
+  def orthologs_as_hash; super; end if false #dummy for RDoc
+  alias orthologs orthologs_as_hash
+
+  # Creates a new Bio::KEGG::GENES object.
+  # ---
+  # *Arguments*:
+  # * (required) _entry_: (String) single entry as a string
+  # *Returns*:: Bio::KEGG::GENES object
   def initialize(entry)
     super(entry, TAGSIZE)
   end
 
-
+  # Returns the "ENTRY" line content as a Hash.
+  # For example, 
+  #   {"organism"=>"E.coli", "division"=>"CDS", "id"=>"b0356"}
+  #
+  # ---
+  # *Returns*:: Hash
   def entry
     unless @data['ENTRY']
       hash = Hash.new('')
@@ -99,34 +137,59 @@ class GENES < KEGGDB
     @data['ENTRY']
   end
 
+  # ID of the entry, described in the ENTRY line.
+  # ---
+  # *Returns*:: String
   def entry_id
     entry['id']
   end
 
+  # Division of the entry, described in the ENTRY line.
+  # ---
+  # *Returns*:: String
   def division
     entry['division']			# CDS, tRNA etc.
   end
 
+  # Organism name of the entry, described in the ENTRY line.
+  # ---
+  # *Returns*:: String
   def organism
     entry['organism']			# H.sapiens etc.
   end
 
+  # Returns the NAME line.
+  # ---
+  # *Returns*:: String
   def name
     field_fetch('NAME')
   end
 
+  # Names of the entry as an Array, described in the NAME line.
+  #
+  # ---
+  # *Returns*:: Array containing String
   def genes
     name.split(', ')
   end
 
+  # Returns the first gene name described in the NAME line.
+  # ---
+  # *Returns*:: String
   def gene
     genes.first
   end
 
+  # Definition of the entry, described in the DEFINITION line.
+  # ---
+  # *Returns*:: String
   def definition
     field_fetch('DEFINITION')
   end
 
+  # Enzyme's EC numbers shown in the DEFINITION line.
+  # ---
+  # *Returns*:: Array containing String
   def eclinks
     ec_list = definition.slice(/\[EC:(.*?)\]/, 1)
     if ec_list
@@ -136,18 +199,30 @@ class GENES < KEGGDB
     end
   end
 
-  def orthologs
+  # Orthologs described in the ORTHOLOGY lines.
+  # ---
+  # *Returns*:: Array containing String
+  def orthologs_as_strings
     lines_fetch('ORTHOLOGY')
   end
 
+  # Returns the PATHWAY lines as a String.
+  # ---
+  # *Returns*:: String
   def pathway
     field_fetch('PATHWAY')
   end
 
-  def pathways
-    pathway.scan(/\[PATH:(.*?)\]/).flatten
+  # Pathways described in the PATHWAY lines.
+  # ---
+  # *Returns*:: Array containing String
+  def pathways_as_strings
+    lines_fetch('PATHWAY')
   end
 
+  # The position in the genome described in the POSITION line.
+  # ---
+  # *Returns*:: String
   def position
     unless @data['POSITION']
       @data['POSITION'] = fetch('POSITION').gsub(/\s/, '')
@@ -155,6 +230,9 @@ class GENES < KEGGDB
     @data['POSITION']
   end
 
+  # Chromosome described in the POSITION line.
+  # ---
+  # *Returns*:: String or nil
   def chromosome
     if position[/:/]
       position.sub(/:.*/, '')
@@ -165,14 +243,25 @@ class GENES < KEGGDB
     end
   end
 
+  # The position in the genome described in the POSITION line
+  # as GenBank feature table location formatted string.
+  # ---
+  # *Returns*:: String
   def gbposition
     position.sub(/.*?:/, '')
   end
 
+  # The position in the genome described in the POSITION line
+  # as Bio::Locations object.
+  # ---
+  # *Returns*:: Bio::Locations object
   def locations
     Bio::Locations.new(gbposition)
   end
 
+  # Motif information described in the MOTIF lines.
+  # ---
+  # *Returns*:: Hash
   def motif
     unless @data['MOTIF']
       hash = {}
@@ -191,18 +280,27 @@ class GENES < KEGGDB
     @data['MOTIF']		# Hash of Array of IDs in MOTIF
   end
 
-  def dblinks
-    unless @data['DBLINKS']
-      hash = {}
-      get('DBLINKS').scan(/(\S+):\s*(.*)\n?/).each do |db, str|
-        id_array = str.strip.split(/\s+/)
-        hash[db] = id_array
-      end
-      @data['DBLINKS'] = hash
+  # Links to other databases described in the DBLINKS lines.
+  # ---
+  # *Returns*:: Array containing String objects
+  def dblinks_as_strings
+    lines_fetch('DBLINKS')
+  end
+
+  # Returns structure ID information described in the STRUCTURE lines.
+  # ---
+  # *Returns*:: Array containing String
+  def structure
+    unless @data['STRUCTURE']
+      @data['STRUCTURE'] = fetch('STRUCTURE').sub(/(PDB: )*/,'').split(/\s+/)
     end
-    @data['DBLINKS']		# Hash of Array of IDs in DBLINKS
+    @data['STRUCTURE'] # ['PDB:1A9X', ...]
   end
+  alias structures structure
 
+  # Codon usage data described in the CODON_USAGE lines.
+  # ---
+  # *Returns*:: Hash
   def codon_usage(codon = nil)
     unless @data['CODON_USAGE']
       hash = Hash.new
@@ -220,6 +318,9 @@ class GENES < KEGGDB
     @data['CODON_USAGE']
   end
 
+  # Codon usage data described in the CODON_USAGE lines as an array.
+  # ---
+  # *Returns*:: Array
   def cu_list
     ary = []
     get('CODON_USAGE').sub(/.*/,'').each_line do |line|	# cut 1st line
@@ -230,6 +331,9 @@ class GENES < KEGGDB
     return ary
   end
 
+  # Returns amino acid sequence described in the AASEQ lines.
+  # ---
+  # *Returns*:: Bio::Sequence::AA object
   def aaseq
     unless @data['AASEQ']
       @data['AASEQ'] = Bio::Sequence::AA.new(fetch('AASEQ').gsub(/\d+/, ''))
@@ -237,10 +341,16 @@ class GENES < KEGGDB
     @data['AASEQ']
   end
 
+  # Returns length of the amino acid sequence described in the AASEQ lines.
+  # ---
+  # *Returns*:: Integer
   def aalen
     fetch('AASEQ')[/\d+/].to_i
   end
 
+  # Returns nucleic acid sequence described in the NTSEQ lines.
+  # ---
+  # *Returns*:: Bio::Sequence::NA object
   def ntseq
     unless @data['NTSEQ']
       @data['NTSEQ'] = Bio::Sequence::NA.new(fetch('NTSEQ').gsub(/\d+/, ''))
@@ -249,6 +359,9 @@ class GENES < KEGGDB
   end
   alias naseq ntseq
 
+  # Returns nucleic acid sequence length.
+  # ---
+  # *Returns*:: Integer
   def ntlen
     fetch('NTSEQ')[/\d+/].to_i
   end