bio 0.7.1 → 1.0.0

data/bin/bioruby

@@ -2,32 +2,12 @@
 #
 # = BioRuby shell - command line interface for the BioRuby library
 #
-# Copyright::	Copyright (C) 2005
-#		Toshiaki Katayama <k@bioruby.org>
-# License::	LGPL
+# Copyright::   Copyright (C) 2005, 2006
+#               Toshiaki Katayama <k@bioruby.org>
+# License::     Ruby's
 #
-# $Id: bioruby,v 1.10 2005/12/07 05:12:06 k Exp $
+# $Id: bioruby,v 1.15 2006/02/27 09:41:54 k 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.
-#
-#  This library is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#  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
-#
-#++
-#
-
-# $: << File.dirname(__FILE__)+'/../lib'
 
 begin
   require 'rubygems'
@@ -35,13 +15,41 @@ begin
 rescue LoadError
 end
 
+
+### BioRuby shell setup
+
 require 'bio/shell'
 
 include Bio::Shell
 
+# command line argument (working directory or bioruby shell script file)
+script = nil
+if arg = ARGV.shift
+  if File.directory?(arg)
+    # directory or symlink to directory
+    Dir.chdir(arg)
+  elsif File.exists?(arg)
+    # BioRuby shell script (load script after the previous session is restored)
+    dir = File.dirname(arg)
+    script = File.basename(arg)
+    Dir.chdir(dir)
+  elsif arg
+    Dir.mkdir(arg)
+    Dir.chdir(arg)
+  end
+else
+  unless File.exists?(Bio::Shell.history)
+    message = "Are you sure to start new session in this directory? [y/n] "
+    unless Bio::Shell.ask_yes_or_no(message)
+      exit
+    end
+  end
+end
+
 # loading configuration and plugins
 Bio::Shell.setup
 
+
 ### IRB setup
 
 require 'irb'
@@ -84,7 +92,8 @@ IRB.conf[:ECHO] = Bio::Shell.config[:echo] || false
 # not beautifully works
 #IRB.conf[:AUTO_INDENT] = true
 
-### IRB main loop
+
+### Start IRB
 
 irb = IRB::Irb.new
 
@@ -92,8 +101,32 @@ irb = IRB::Irb.new
 IRB.conf[:MAIN_CONTEXT] = irb.context
 
 # loading workspace and command history
-Bio::Shell.load
+Bio::Shell.load_session
 
+if script
+  load script
+  exit
+end
+
+Bio::Shell.create_save_dir
+
+$history_file = File.open(Bio::Shell.history, "a")
+$history_file.sync = true
+
+# overwrite gets to store history with time stamp
+io = IRB.conf[:MAIN_CONTEXT].io
+
+io.class.class_eval do
+  alias_method :irb_original_gets, :gets
+end
+
+def io.gets
+  line = irb_original_gets
+  $history_file.puts "#{Time.now}\t#{line}" if line
+  line
+end
+
+# main loop
 Signal.trap("SIGINT") do
   irb.signal_handle
 end
@@ -102,6 +135,17 @@ catch(:IRB_EXIT) do
   irb.eval_input
 end
 
+$history_file.close if $history_file
+
+# shut down the rails server
+if $web_server
+  $web_server.each do |io|
+    io.close
+  end
+  $web_access_log.close if $web_access_log
+  $web_error_log.close if $web_error_log
+end
+
 # saving workspace, command history and configuration before exit
-Bio::Shell.save
+Bio::Shell.save_session
 

data/bin/br_biofetch.rb

@@ -1,24 +1,12 @@
 #!/usr/bin/env ruby
 #
-# biofetch - BioFetch client
+# = biofetch - BioFetch client
 #
-#   Copyright (C) 2002 KATAYAMA Toshiaki <k@bioruby.org>
+# Copyright::   Copyright (C) 2002
+#               Toshiaki Katayama <k@bioruby.org>
+# License::     Ruby's
 #
-#  This program is free software; you can redistribute it and/or modify
-#  it under the terms of the GNU General Public License as published by
-#  the Free Software Foundation; either version 2 of the License, or
-#  (at your option) any later version.
-#
-#  This program is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#  GNU General Public License for more details.
-#
-#  You should have received a copy of the GNU General Public License
-#  along with this program; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-#
-#  $Id: br_biofetch.rb,v 1.2 2002/12/03 18:54:43 k Exp $
+# $Id: br_biofetch.rb,v 1.3 2006/02/09 16:29:41 k Exp $
 #
 
 require 'bio/io/fetch'

data/bin/br_bioflat.rb

@@ -1,24 +1,12 @@
 #!/usr/bin/env ruby
 # 
-# bioflat - OBDA flat file indexer (executable)
+# = bioflat - OBDA flat file indexer (executable)
 # 
-#   Copyright (C) 2002 GOTO Naohisa <ngoto@gen-info.osaka-u.ac.jp> 
-# 
-#  This program is free software; you can redistribute it and/or modify 
-#  it under the terms of the GNU General Public License as published by 
-#  the Free Software Foundation; either version 2 of the License, or 
-#  (at your option) any later version. 
-# 
-#  This program is distributed in the hope that it will be useful, 
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of 
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
-#  GNU General Public License for more details. 
-# 
-#  You should have received a copy of the GNU General Public License 
-#  along with this program; if not, write to the Free Software 
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
-# 
-#  $Id: br_bioflat.rb,v 1.14 2003/08/27 17:28:30 ng Exp $ 
+# Copyright::   Copyright (C) 2002
+#               Naohisa Goto <ng@bioruby.org>
+# License::     Ruby's
+#
+# $Id: br_bioflat.rb,v 1.16 2006/02/22 07:01:05 ngoto Exp $ 
 # 
 
 require 'bio'
@@ -151,7 +139,7 @@ def do_index(mode = :create)
       options['renew'] = true
 
     else
-      STDERR.print "Warning: ignoring invalid option #{x.inspect}\n"
+      $stderr.print "Warning: ignoring invalid option #{x.inspect}\n"
     end
   end
 
@@ -191,9 +179,9 @@ def do_search
   dbname = File.join(location, dbname) unless location.to_s.empty?
   db = Bio::FlatFileIndex.open(dbname)
   ARGV.each do |key|
-    STDERR.print "Searching for \'#{key}\'...\n"
+    $stderr.print "Searching for \'#{key}\'...\n"
     #r = db.search(key)
-    #STDERR.print "OK, #{r.size} entry found\n"
+    #$stderr.print "OK, #{r.size} entry found\n"
     #if r.size > 0 then
     #  print r
     #end
@@ -204,11 +192,11 @@ def do_search
 	r = db.include_in_namespaces?(key, *names)
       end
     rescue RuntimeError
-      STDERR.print "ERROR: #{$!}\n"
+      $stderr.print "ERROR: #{$!}\n"
       next
     end
     r = [] unless r
-    STDERR.print "OK, #{r.size} entry found\n"
+    $stderr.print "OK, #{r.size} entry found\n"
     r.each do |i|
       print db.search_primary(i)
     end
@@ -252,14 +240,14 @@ def do_show_namespaces
       break if k
     end
     if k then
-      STDERR.print "Format: #{k.to_s}\n"
+      $stderr.print "Format: #{k.to_s}\n"
       format = k
     else
-      STDERR.print "ERROR: couldn't determine file format\n"
+      $stderr.print "ERROR: couldn't determine file format\n"
       return
     end
   end
-  STDERR.print "Namespaces: (first line: primary namespace)\n"
+  $stderr.print "Namespaces: (first line: primary namespace)\n"
   if format then
     parser = Bio::FlatFileIndex::Indexer::Parser.new(format)
     print parser.primary.name, "\n"

data/bin/br_biogetseq.rb

@@ -1,24 +1,12 @@
 #!/usr/bin/env ruby
 # 
-# biogetseq - OBDA sequence data retrieval (executable)
+# = biogetseq - OBDA sequence data retrieval (executable)
 # 
-#   Copyright (C) 2003 KATAYAMA Toshiaki <k@bioruby.org>
-# 
-#  This program is free software; you can redistribute it and/or modify 
-#  it under the terms of the GNU General Public License as published by 
-#  the Free Software Foundation; either version 2 of the License, or 
-#  (at your option) any later version. 
-# 
-#  This program is distributed in the hope that it will be useful, 
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of 
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
-#  GNU General Public License for more details. 
-# 
-#  You should have received a copy of the GNU General Public License 
-#  along with this program; if not, write to the Free Software 
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
-# 
-#  $Id: br_biogetseq.rb,v 1.2 2003/02/21 02:44:22 k Exp $
+# Copyright::   Copyright (C) 2003
+#               Toshiaki Katayama <k@bioruby.org>
+# License::     Ruby's
+#
+# $Id: br_biogetseq.rb,v 1.3 2006/02/09 16:29:41 k Exp $
 # 
 
 require 'bio'

data/bin/br_pmfetch.rb

@@ -1,25 +1,15 @@
 #!/usr/bin/env ruby
 #
-# pmfetch - PubMed client
+# = pmfetch - PubMed client
 #
-#  Copyright (C) 2004, 2005 Toshiaki Katayama <k@bioruby.org>
+# Copyright::   Copyright (C) 2004, 2005
+#               Toshiaki Katayama <k@bioruby.org>
+# License::     Ruby's
 #
-#  This program is free software; you can redistribute it and/or modify
-#  it under the terms of the GNU General Public License as published by
-#  the Free Software Foundation; either version 2 of the License, or
-#  (at your option) any later version.
-#
-#  This program is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#  GNU General Public License for more details.
-#
-#  You should have received a copy of the GNU General Public License
-#  along with this program; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# $Id: br_pmfetch.rb,v 1.6 2006/02/09 16:29:41 k Exp $
 #
 
-PROG_VER  = '$Id: br_pmfetch.rb,v 1.5 2005/07/11 09:31:32 k Exp $'
+PROG_VER  = '$Id: br_pmfetch.rb,v 1.6 2006/02/09 16:29:41 k Exp $'
 PROG_NAME = File.basename($0)
 
 

data/doc/Changes-0.7.rd

@@ -49,6 +49,19 @@ or newly added.
 
 --- Bio::Sequence
 
+Bio::Sequence is completely refactored to be a container class for
+any sequence annotations.  Functionalities are separated into several
+files under the lib/bio/sequence/ directory as
+
+  * common.rb : module provides common methods for NA and AA sequences
+  * compat.rb : methods for backward compatibility
+  * aa.rb     : Bio::Sequence::AA class
+  * na.rb     : Bio::Sequence::NA class
+  * format.rb : module for format conversion
+
+Bio::Sequence is no longer a sub-class of String, instead,
+Bio::Sequence::NA and AA inherits String directly.
+
 * Bio::Sequence::NA#gc_percent returns integer instead of float
 * Bio::Sequence::NA#gc (was aliased to gc_percent) is removed
 
@@ -226,6 +239,28 @@ In 0.7.1:
   a nucleic acid sequence.
 * There are more and more changes to be written...
 
+--- Bio::FlatFile
+
+In 0.7.2:
+
+* Bio::FlatFile.open, Bio::FlatFile.auto and Bio::FlatFile.new are changed
+  not to accept the last argument to specify raw mode, e.g. :raw => true,
+  :raw => false, true or false. Instead, please use Bio::FlatFile#raw=
+  method after creating a new object.
+* Now, first argument of Bio::FlatFile.open, which shall be a database
+  class or nil, can be omitted, and you can do
+  Bio::FlatFile.open(filename, ...). Note that 
+  Bio::FlatFile.open(dbclass, filaname, ...) is still available.
+* Bio::FlatFile#io is obsoleted. Please use Bio::FlatFile#to_io instead.
+* When reading GenBank or GenPept files, comments at the  head of the file
+  before the first "LOCUS" lines are now skipped by default.
+  When reading other file formats, white space characters are skipped.
+* File format autodetection routine is completely rewritten.
+  If it fails to determine data format which was previously determined,
+  please report us with the data.
+* Internal structure is now completely changed. Codes depend on the internal
+  structure (which is not recommended) would not work.
+
 === Deleted files
 
 : lib/bio/db/genbank.rb

data/doc/KEGG_API.rd

@@ -1,8 +1,8 @@
 =begin
 
-  $Id: KEGG_API.rd,v 1.1 2005/08/31 13:29:01 k Exp $
+  $Id: KEGG_API.rd,v 1.2 2006/02/23 04:51:23 k Exp $
 
-    Copyright (C) 2003-2005 Toshiaki Katayama <k@bioruby.org>
+    Copyright (C) 2003-2006 Toshiaki Katayama <k@bioruby.org>
 
 = KEGG API
 
@@ -79,6 +79,7 @@ page at GenomeNet:
     * ((<MotifResult>)), ((<ArrayOfMotifResult>))
     * ((<Definition>)), ((<ArrayOfDefinition>))
     * ((<LinkDBRelation>)), ((<ArrayOfLinkDBRelation>))
+    * ((<PathwayElement>)), ((<ArrayOfPathwayElement>))
   * ((<Methods>))
     * ((<Meta information>))
       * ((<list_databases>)),
@@ -88,9 +89,22 @@ page at GenomeNet:
       * ((<binfo>)),
         ((<bfind>)),
         ((<bget>)),
-        ((<btit>))
+        ((<btit>)),
+        ((<bconv>))
     * ((<LinkDB>))
       * ((<get_linkdb_by_entry>))
+      * ((<get_genes_by_enzyme>)),
+        ((<get_enzymes_by_gene>))
+      * ((<get_enzymes_by_compound>)),
+        ((<get_enzymes_by_glycan>)),
+        ((<get_enzymes_by_reaction>)),
+        ((<get_compounds_by_enzyme>)),
+        ((<get_compounds_by_reaction>)),
+        ((<get_glycans_by_enzyme>)),
+        ((<get_glycans_by_reaction>)),
+        ((<get_reactions_by_enzyme>)),
+        ((<get_reactions_by_compound>)),
+        ((<get_reactions_by_glycan>))
     * ((<SSDB>))
       * ((<get_best_best_neighbors_by_gene>)),
         ((<get_best_neighbors_by_gene>)),
@@ -112,9 +126,12 @@ page at GenomeNet:
     * ((<PATHWAY>))
       * ((<mark_pathway_by_objects>)),
         ((<color_pathway_by_objects>)),
+        ((<color_pathway_by_elements>)),
         ((<get_html_of_marked_pathway_by_objects>)),
-        ((<get_html_of_colored_pathway_by_objects>))
-      * ((<get_genes_by_pathway>)),
+        ((<get_html_of_colored_pathway_by_objects>)),
+        ((<get_html_of_colored_pathway_by_elements>))
+      * ((<get_elements_by_pathway>)),
+        ((<get_genes_by_pathway>)),
         ((<get_enzymes_by_pathway>)),
         ((<get_compounds_by_pathway>)),
         ((<get_glycans_by_pathway>)),
@@ -127,18 +144,6 @@ page at GenomeNet:
         ((<get_pathways_by_reactions>)),
         ((<get_pathways_by_kos>))
       * ((<get_linked_pathways>))
-      * ((<get_genes_by_enzyme>)),
-        ((<get_enzymes_by_gene>))
-      * ((<get_enzymes_by_compound>)),
-        ((<get_enzymes_by_glycan>)),
-        ((<get_enzymes_by_reaction>)),
-        ((<get_compounds_by_enzyme>)),
-        ((<get_compounds_by_reaction>)),
-        ((<get_glycans_by_enzyme>)),
-        ((<get_glycans_by_reaction>)),
-        ((<get_reactions_by_enzyme>)),
-        ((<get_reactions_by_compound>)),
-        ((<get_reactions_by_glycan>))
     * ((<GENES>))
       * ((<get_genes_by_organism>))
     * ((<GENOME>))
@@ -507,8 +512,9 @@ the KEGG API can be found at:
 
 === Terminology
 
-  * 'org' is a three-letter organism code used in KEGG.  The list can be
-    found at (see the description of the list_organisms method below):
+  * 'org' is a three-letter (or four-letter) organism code used in KEGG.
+    The list can be found at (see the description of the list_organisms
+    method below):
 
     * ((<URL:http://www.genome.jp/kegg/catalog/org_list.html>))
 
@@ -622,7 +628,7 @@ The following methods had been affected by this bug:
   * get_paralogs_by_gene
 # * get_similarity_between_genes
 
-This problem is fixed in the version 3.2.
+This problem is fixed in the KEGG API version 3.2.
 
 + ArrayOfSSDBRelation
 
@@ -671,6 +677,20 @@ LinkDBRelation data type contains the following fields:
 
 ArrayOfLinkDBRelation data type is a list of the LinkDBRelation data type.
 
++ PathwayElement
+
+PathwayElement data type contains the following fields:
+
+  element_id        unique identifier of the object on the pathway (int)
+  type              type of the object ("gene", "enzyme" etc.) (string)
+  names             array of names of the object (ArrayOfstring)
+  components        array of element_ids of the group components (ArrayOfint)
+
++ ArrayOfPathwayElement
+
+ArrayOfPathwayElement data type is a list of the PathwayElement data type.
+
+
 === Methods
 
 ==== Meta information
@@ -769,6 +789,19 @@ Example:
   # "mmu:13478", "dme:CG5287-PA" and cel:Y60A3A.14".
   btit("hsa:1798 mmu:13478 dme:CG5287-PA cel:Y60A3A.14")
 
+--- bconv(string)
+
+The bconv command converts external IDs (NCBI GI, NCBI GeneID, GenBank ID,
+and UniProt ID) to KEGG IDs.  The result is the tab separated pair of the
+given ID and the converted ID in each line.
+
+Return value:
+  string
+
+Example:
+  # Convert NCBI GI and NCBI GeneID to KEGG genes_id
+  serv.bconv("ncbi-gi:10047086 ncbi-gi:10047090 ncbi-geneid:14751")
+
 ==== LinkDB
 
 --- get_linkdb_by_entry(entry_id, db, start, max_results)
@@ -784,6 +817,155 @@ Example:
   get_linkdb_by_entry('eco:b0002', 'pathway', 1, 10)
   get_linkdb_by_entry('eco:b0002', 'pathway', 11, 10)
 
++ Relation among genes and enzymes
+
+--- get_genes_by_enzyme(enzyme_id, org)
+
+Retrieve all genes of the given organism.
+
+Return value:
+  ArrayOfstring (genes_id)
+
+Example:
+  # Returns all the GENES entry IDs in E.coli genome which are assigned 
+  # EC number ec:1.2.1.1
+  get_genes_by_enzyme('ec:1.2.1.1', 'eco')
+
+--- get_enzymes_by_gene(genes_id)
+
+Retrieve all the EC numbers which are assigned to the given gene.
+
+Return value:
+  ArrayOfstring (enzyme_id)
+
+Example:
+  # Returns the EC numbers which are assigned to E.coli genes b0002
+  get_enzymes_by_gene('eco:b0002')
+
+
++ Relation among enzymes, compounds and reactions
+
+--- get_enzymes_by_compound(compound_id)
+
+Retrieve all enzymes which have a link to the given compound_id.
+
+Return value:
+  ArrayOfstring (enzyme_id)
+
+Example:
+  # Returns the ENZYME entry IDs which have a link to the COMPOUND entry,
+  # 'cpd:C00345'
+  get_enzymes_by_compound('cpd:C00345')
+
+--- get_enzymes_by_glycan(glycan_id)
+
+Retrieve all enzymes which have a link to the given glycan_id.
+
+Return value:
+  ArrayOfstring (enzyme_id)
+
+Example
+  # Returns the ENZYME entry IDs which have a link to the GLYCAN entry,
+  # 'gl:G00001'
+  get_enzymes_by_glycan('gl:G00001')
+
+--- get_enzymes_by_reaction(reaction_id)
+
+Retrieve all enzymes which have a link to the given reaction_id.
+
+Return value:
+  ArrayOfstring (enzyme_id)
+
+Example:
+  # Returns the ENZYME entry IDs which have a link to the REACTION entry, 
+  # 'rn:R00100'.
+  get_enzymes_by_reaction('rn:R00100')
+
+--- get_compounds_by_enzyme(enzyme_id)
+
+Retrieve all compounds which have a link to the given enzyme_id.
+
+Return value:
+  ArrayOfstring (compound_id)
+
+Example:
+  # Returns the COMPOUND entry IDs which have a link to the ENZYME entry, 
+  # 'ec:2.7.1.12'.
+  get_compounds_by_enzyme('ec:2.7.1.12')
+ 
+--- get_compounds_by_reaction(reaction_id)
+
+Retrieve all compounds which have a link to the given reaction_id.
+
+Return value:
+  ArrayOfstring (compound_id)
+
+Example:
+  # Returns the COMPOUND entry IDs which have a link to the REACTION entry, 
+  # 'rn:R00100'
+  get_compounds_by_reaction('rn:R00100')
+
+--- get_glycans_by_enzyme(enzyme_id)
+
+Retrieve all glycans which have a link to the given enzyme_id.
+
+Return value:
+  ArrayOfstring (glycan_id)
+
+Example
+  # Returns the GLYCAN entry IDs which have a link to the ENZYME entry,
+  # 'ec:2.4.1.141'
+  get_glycans_by_enzyme('ec:2.4.1.141')
+
+--- get_glycans_by_reaction(reaction_id)
+
+Retrieve all glycans which have a link to the given reaction_id.
+
+Return value:
+  ArrayOfstring (glycan_id)
+
+Example
+  # Returns the GLYCAN entry IDs which have a link to the REACTION entry,
+  # 'rn:R06164'
+  get_glycans_by_reaction('rn:R06164')
+
+--- get_reactions_by_enzyme(enzyme_id)
+
+Retrieve all reactions which have a link to the given enzyme_id.
+
+Return value:
+  ArrayOfstring (reaction_id)
+
+Example:
+  # Returns the REACTION entry IDs which have a link to the ENZYME entry,
+  # 'ec:2.7.1.12'
+  get_reactions_by_enzyme('ec:2.7.1.12')
+
+--- get_reactions_by_compound(compound_id)
+
+Retrieve all reactions which have a link to the given compound_id.
+
+Return value:
+  ArrayOfstring (reaction_id)
+
+Example:
+  # Returns the REACTION entry IDs which have a link to the COMPOUND entry,
+  # 'cpd:C00199'
+  get_reactions_by_compound('cpd:C00199')
+
+--- get_reactions_by_glycan(glycan_id)
+
+Retrieve all reactions which have a link to the given glycan_id.
+
+Return value:
+  ArrayOfstring (reaction_id)
+
+Example
+  # Returns the REACTION entry IDs which have a link to the GLYCAN entry,
+  # 'gl:G00001'
+  get_reactions_by_glycan('gl:G00001')
+
+
 ==== SSDB
 
 This section describes the APIs for SSDB database.  For more details
@@ -1030,6 +1212,42 @@ Example:
   bg_list  = ['#ffff00', 'yellow']
   color_pathway_by_objects('path:eco00260', obj_list, fg_list, bg_list)
 
+--- color_pathway_by_elements(pathway_id, element_id_list, fg_color_list, bg_color_list)
+
+Color the objects (rectangles and circles on a pathway map) corresponding
+to the given 'element_id_list' with the specified colors and return the
+URL of the colored image.  'fg_color_list' is used for specifying the
+color of text and border of the objects with given 'element_id_list' and
+'bg_color_list' is used for its background area. The order of colors in
+these lists correspond with the order of objects in the 'element_id_list'
+list.
+
+This method is useful to specify which graphical object on the pathway
+to be colored as there are some cases that multiple genes are assigned to
+one rectangle or a gene is assigned to more than one rectangle on the
+pathway map. The 'element_id' is an unique numerical identifier on the
+pathway defined by the KGML (XML represeentation of the KEGG PATHWAY)
+in the <entry> tag.  List of the 'element_id's can be obtained by the
+'get_elements_by_pathway' method. 
+
+For more details on KGML, see:
+
+  * ((<URL:http://www.genome.jp/kegg/xml/>))
+
+Return value:
+  string (URL)
+
+Example:
+  # Returns the URL of the colored image of given pathway 'path:bsu00010' with
+  # * gene bsu:BG11350 (element_id 78, ec:3.2.1.86) colored in red on yellow
+  # * gene bsu:BG11203 (element_id 79, ec:3.2.1.86) colored in blue on yellow
+  # * gene bsu:BG11685 (element_id 51, ec:2.7.1.2)  colored in red on orange
+  # * gene bsu:BG11685 (element_id 47, ec:2.7.1.2)  colored in blue on orange
+  element_id_list = [ 78, 79, 51, 47 ]
+  fg_list  = [ '#ff0000', '#0000ff', '#ff0000', '#0000ff' ]
+  bg_list  = [ '#ffff00', '#ffff00', '#ffcc00', '#ffcc00' ]
+  color_pathway_by_elements('path:bsu00010', element_id_list, fg_list, bg_list)
+
 --- get_html_of_marked_pathway_by_objects(pathway_id, object_id_list)
 
 HTML version of the 'mark_pathway_by_objects' method.
@@ -1059,17 +1277,63 @@ Return value:
 
 Example:
   # Returns the URL of the HTML which can be passed to the web browser
-  # as a clickable map of coloerd image of the given pathway 'path:eco00970'
+  # as a clickable map of colored image of the given pathway 'path:eco00970'
   # with a gene 'eco:b4258' colored in gray/red, a compound 'cpd:C00135'
-  # coloerd in green/yellow and a KO 'ko:K01881' colored in blue/orange.
+  # colored in green/yellow and a KO 'ko:K01881' colored in blue/orange.
   obj_list = ['eco:b4258', 'cpd:C00135', 'ko:K01881']
   fg_list  = ['gray', '#00ff00', 'blue']
   bg_list  = ['#ff0000', 'yellow', 'orange']
   get_html_of_colored_pathway_by_objects('path:eco00970', obj_list, fg_list, bg_list)
 
+--- get_html_of_colored_pathway_by_elements(pathway_id, element_id_list, fg_color_list, bg_color_list)
+
+HTML version of the 'color_pathway_by_elements' method.
+Color the objects corresponding to the given 'element_id_list' on the pathway
+map with the specified colors and return the URL of the HTML containing the
+colored image as a clickable map.
+
+Return value:
+  string (URL)
+
+Example:
+  # Returns the URL of the HTML which can be passed to the web browser as a
+  # clickable map of colored image of the given pathway 'path:bsu00010' with
+  # * gene bsu:BG11350 (element_id 78, ec:3.2.1.86) colored in red on yellow
+  # * gene bsu:BG11203 (element_id 79, ec:3.2.1.86) colored in blue on yellow
+  # * gene bsu:BG11685 (element_id 51, ec:2.7.1.2)  colored in red on orange
+  # * gene bsu:BG11685 (element_id 47, ec:2.7.1.2)  colored in blue on orange
+  element_id_list = [ 78, 79, 51, 47 ]
+  fg_list  = [ '#ff0000', '#0000ff', '#ff0000', '#0000ff' ]
+  bg_list  = [ '#ffff00', '#ffff00', '#ffcc00', '#ffcc00' ]
+  get_html_of_colored_pathway_by_elements('path:bsu00010', element_id_list, fg_list, bg_list)
 
 + Objects on the pathway
 
+--- get_elements_by_pathway(pathway_id)
+
+Search all objects on the specified pathway.  This method will be used in
+combination with the color_pathway_by_elements method to distingish graphical
+objects on the pathway sharing the same name.
+
+Return value:
+  ArrayOfPathwayElement
+
+Example:
+  # Returns list of PathwayElement on the pathway map 'path:bsu00010'
+  get_elements_by_pathway('path:bsu00010')
+
+  # Find entry_ids for genes 'bsu:BG11350', 'bsu:BG11203' and 'bsu:BG11685'
+  # in Ruby language
+  elems = serv.get_elements_by_pathway('path:bsu00010')
+  genes = [ 'bsu:BG11350', 'bsu:BG11203', 'bsu:BG11685' ]
+  elems.each do |elem|
+    genes.each do |gene|
+      if elem.names.include?(gene)
+        puts gene, elem.element_id
+      end
+    end
+  end
+
 --- get_genes_by_pathway(pathway_id)
 
 Search all genes on the specified pathway.  Organism name is given by
@@ -1226,155 +1490,6 @@ Example:
   get_linked_pathways('path:eco00620')
 
 
-+ Relation among genes and enzymes
-
---- get_genes_by_enzyme(enzyme_id, org)
-
-Retrieve all genes of the given organism.
-
-Return value:
-  ArrayOfstring (genes_id)
-
-Example:
-  # Returns all the GENES entry IDs in E.coli genome which are assigned 
-  # EC number ec:1.2.1.1
-  get_genes_by_enzyme('ec:1.2.1.1', 'eco')
-
---- get_enzymes_by_gene(genes_id)
-
-Retrieve all the EC numbers which are assigned to the given gene.
-
-Return value:
-  ArrayOfstring (enzyme_id)
-
-Example:
-  # Returns the EC numbers which are assigned to E.coli genes b0002
-  get_enzymes_by_gene('eco:b0002')
-
-
-+ Relation among enzymes, compounds and reactions
-
---- get_enzymes_by_compound(compound_id)
-
-Retrieve all enzymes which have a link to the given compound_id.
-
-Return value:
-  ArrayOfstring (enzyme_id)
-
-Example:
-  # Returns the ENZYME entry IDs which have a link to the COMPOUND entry,
-  # 'cpd:C00345'
-  get_enzymes_by_compound('cpd:C00345')
-
---- get_enzymes_by_glycan(glycan_id)
-
-Retrieve all enzymes which have a link to the given glycan_id.
-
-Return value:
-  ArrayOfstring (enzyme_id)
-
-Example
-  # Returns the ENZYME entry IDs which have a link to the GLYCAN entry,
-  # 'gl:G00001'
-  get_enzymes_by_glycan('gl:G00001')
-
---- get_enzymes_by_reaction(reaction_id)
-
-Retrieve all enzymes which have a link to the given reaction_id.
-
-Return value:
-  ArrayOfstring (enzyme_id)
-
-Example:
-  # Returns the ENZYME entry IDs which have a link to the REACTION entry, 
-  # 'rn:R00100'.
-  get_enzymes_by_reaction('rn:R00100')
-
---- get_compounds_by_enzyme(enzyme_id)
-
-Retrieve all compounds which have a link to the given enzyme_id.
-
-Return value:
-  ArrayOfstring (compound_id)
-
-Example:
-  # Returns the COMPOUND entry IDs which have a link to the ENZYME entry, 
-  # 'ec:2.7.1.12'.
-  get_compounds_by_enzyme('ec:2.7.1.12')
- 
---- get_compounds_by_reaction(reaction_id)
-
-Retrieve all compounds which have a link to the given reaction_id.
-
-Return value:
-  ArrayOfstring (compound_id)
-
-Example:
-  # Returns the COMPOUND entry IDs which have a link to the REACTION entry, 
-  # 'rn:R00100'
-  get_compounds_by_reaction('rn:R00100')
-
---- get_glycans_by_enzyme(enzyme_id)
-
-Retrieve all glycans which have a link to the given enzyme_id.
-
-Return value:
-  ArrayOfstring (glycan_id)
-
-Example
-  # Returns the GLYCAN entry IDs which have a link to the ENZYME entry,
-  # 'ec:2.4.1.141'
-  get_glycans_by_enzyme('ec:2.4.1.141')
-
---- get_glycans_by_reaction(reaction_id)
-
-Retrieve all glycans which have a link to the given reaction_id.
-
-Return value:
-  ArrayOfstring (glycan_id)
-
-Example
-  # Returns the GLYCAN entry IDs which have a link to the REACTION entry,
-  # 'rn:R06164'
-  get_glycans_by_reaction('rn:R06164')
-
---- get_reactions_by_enzyme(enzyme_id)
-
-Retrieve all reactions which have a link to the given enzyme_id.
-
-Return value:
-  ArrayOfstring (reaction_id)
-
-Example:
-  # Returns the REACTION entry IDs which have a link to the ENZYME entry,
-  # 'ec:2.7.1.12'
-  get_reactions_by_enzyme('ec:2.7.1.12')
-
---- get_reactions_by_compound(compound_id)
-
-Retrieve all reactions which have a link to the given compound_id.
-
-Return value:
-  ArrayOfstring (reaction_id)
-
-Example:
-  # Returns the REACTION entry IDs which have a link to the COMPOUND entry,
-  # 'cpd:C00199'
-  get_reactions_by_compound('cpd:C00199')
-
---- get_reactions_by_glycan(glycan_id)
-
-Retrieve all reactions which have a link to the given glycan_id.
-
-Return value:
-  ArrayOfstring (reaction_id)
-
-Example
-  # Returns the REACTION entry IDs which have a link to the GLYCAN entry,
-  # 'gl:G00001'
-  get_reactions_by_glycan('gl:G00001')
-
-
 ==== GENES
 
 This section describes the APIs for GENES database. For more details
@@ -1431,7 +1546,7 @@ Example:
 
 == Notes
 
-Last updated: May 31, 2005
+Last updated: Feb 17, 2006
 
 =end