ngoto-bio 1.2.9.9001

data/doc/KEGG_API.rd

@@ -0,0 +1,1843 @@
+=begin
+
+  $Id: KEGG_API.rd,v 1.5 2006/12/27 13:40:45 k Exp $
+
+    Copyright (C) 2003-2006 Toshiaki Katayama <k@bioruby.org>
+
+= KEGG API
+
+KEGG API is a web service to use the KEGG system from your program via
+SOAP/WSDL.
+
+We have been making the ((<KEGG|URL:/kegg/>)) system available at
+((<GenomeNet|URL:/>)).  KEGG is a suite of databases including GENES,
+SSDB, PATHWAY, LIGAND, LinkDB, etc.  for genome research and related
+research areas in molecular and cellular biology.  These databases and
+associated computation services are available via WWW and the user
+interfaces are built on web browsers.  Thus, the interfaces are
+designed to be accessed by humans, not by machines, which means that
+it is troublesome for the researchers who want to use KEGG in an
+automated manner.  Besides, from the database developer's side, it is
+impossible to prepare all the CGI programs that satisfy a variety of
+users' needs.
+
+In recent years, the Internet technology for
+application-to-application communication referred to as the
+((<web service|URL:http://www.oreillynet.com/lpt/a/webservices/2002/02/12/webservicefaqs.html>))
+is improving at a rapid rate. For exmaple, Google, a popular Internet
+search engine, provides the web service called the
+((<Google Web API|URL:http://www.google.com/apis/>)).
+The service enables users to
+develop software that accesses and manipulates a massive amount of web
+documents that are constantly refreshed. In the field of genome
+research, a similar kind of web service called
+((<DAS|URL:http://www.biodas.org/>)) (distributed annotation system)
+has been used on several web sites, including
+((<Ensembl|URL:http://www.ensembl.org/>)),
+((<Wormbase|URL:http://www.wormbase.org/>)),
+((<Flybase|URL:http://www.flybase.org/>)),
+((<SGD|URL:http://www.yeastgenome.org/>)),
+((<TIGR|URL:http://www.tigr.org/>)).
+
+With the background and the trends noted above, we have started developing
+a new web service called KEGG API using 
+((<SOAP|URL:http://www.w3.org/TR/SOAP/>)) and
+((<WSDL|URL:http://www.w3.org/TR/wsdl20/>)).
+The service has been tested with
+((<Ruby|URL:http://www.ruby-lang.org/>))
+(Ruby 1.8.2 or Ruby 1.6.8 with
+((<SOAP4R|URL:http://raa.ruby-lang.org/project/soap4r/>))
+version 1.4.8.1) and
+((<Perl|URL:http://www.perl.org/>))
+(((<SOAP::Lite|URL:http://www.soaplite.com/>)) version 0.55) languages.
+Although the service has not been tested with clients written in other
+languages, it should work if the language can treat SOAP/WSDL.
+
+The ((<BioRuby|URL:http://bioruby.org/>)) project prepared a Ruby
+library to handle the KEGG API, so users of the Ruby language should
+check out the latest release of the BioRuby distribution.
+
+For the general information on KEGG API, see the following
+page at GenomeNet:
+
+  * ((<URL:http://www.genome.jp/kegg/soap/>))
+
+== Table of contents
+
+* ((<Introduction>))
+* ((<KEGG API Quick Start>))
+  * ((<Quick Start with Perl>))
+    * ((<Perl FAQ>))
+  * ((<Quick Start with Ruby>))
+  * ((<Quick Start with Python>))
+  * ((<Quick Start with Java>))
+* ((<KEGG API Reference>))
+  * ((<WSDL file>))
+  * ((<Terminology>))
+  * ((<Returned values>))
+    * ((<SSDBRelation>)), ((<ArrayOfSSDBRelation>))
+    * ((<MotifResult>)), ((<ArrayOfMotifResult>))
+    * ((<Definition>)), ((<ArrayOfDefinition>))
+    * ((<LinkDBRelation>)), ((<ArrayOfLinkDBRelation>))
+    * ((<PathwayElement>)), ((<ArrayOfPathwayElement>))
+    * ((<PathwayElementRelation>)), ((<ArrayOfPathwayElementRelation>))
+      * ((<Subtype>)), ((<ArrayOfSubtype>))
+    * ((<StructureAlignment>)), ((<ArrayOfStructureAlignment>))
+  * ((<Methods>))
+    * ((<Meta information>))
+      * ((<list_databases>))
+      * ((<list_organisms>))
+      * ((<list_pathways>))
+    * ((<DBGET>))
+      * ((<binfo>))
+      * ((<bfind>))
+      * ((<bget>))
+      * ((<btit>))
+      * ((<bconv>))
+    * ((<LinkDB>))
+      * ((<Database cross references>))
+        * ((<get_linkdb_by_entry>))
+        * ((<get_linkdb_between_databases>))
+      * ((<Relation among genes and enzymes>))
+        * ((<get_genes_by_enzyme>))
+        * ((<get_enzymes_by_gene>))
+      * ((<Relation among enzymes, compounds and reactions>))
+        * ((<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>))
+      * ((<get_reverse_best_neighbors_by_gene>))
+      * ((<get_paralogs_by_gene>))
+    * ((<Motif>))
+      * ((<get_motifs_by_gene>))
+      * ((<get_genes_by_motifs>))
+    * ((<KO>))
+      * ((<get_ko_by_gene>))
+      * ((<get_ko_by_ko_class>))
+      * ((<get_genes_by_ko_class>))
+      * ((<get_genes_by_ko>))
+    * ((<PATHWAY>))
+      * ((<Coloring pathways>))
+        * ((<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_html_of_colored_pathway_by_elements>))
+      * ((<Relations of objects on the pathway>))
+        * ((<get_element_relations_by_pathway>))
+      * ((<Objects on the pathway>))
+        * ((<get_elements_by_pathway>))
+        * ((<get_genes_by_pathway>))
+        * ((<get_enzymes_by_pathway>))
+        * ((<get_compounds_by_pathway>))
+        * ((<get_glycans_by_pathway>))
+        * ((<get_reactions_by_pathway>))
+        * ((<get_kos_by_pathway>))
+      * ((<Pathways by objects>))
+        * ((<get_pathways_by_genes>))
+        * ((<get_pathways_by_enzymes>))
+        * ((<get_pathways_by_compounds>))
+        * ((<get_pathways_by_glycans>))
+        * ((<get_pathways_by_reactions>))
+        * ((<get_pathways_by_kos>))
+      * ((<Relation among pathways>))
+        * ((<get_linked_pathways>))
+    * ((<GENES>))
+      * ((<get_genes_by_organism>))
+    * ((<GENOME>))
+      * ((<get_number_of_genes_by_organism>))
+    * ((<LIGAND>))
+      * ((<convert_mol_to_kcf>))
+      * ((<search_compounds_by_name>))
+      * ((<search_drugs_by_name>))
+      * ((<search_glycans_by_name>))
+      * ((<search_compounds_by_composition>))
+      * ((<search_drugs_by_composition>))
+      * ((<search_glycans_by_composition>))
+      * ((<search_compounds_by_mass>))
+      * ((<search_drugs_by_mass>))
+      * ((<search_glycans_by_mass>))
+      * ((<search_compounds_by_subcomp>))
+      * ((<search_drugs_by_subcomp>))
+      * ((<search_glycans_by_kcam>))
+
+== Introduction
+
+This guide explains how to use the KEGG API in your programs for 
+searching and retrieving data from the KEGG database.
+
+== KEGG API Quick Start
+
+As always, the best way to become familar with it is by looking at an
+example.  In this document, sample codes written in several languages
+are shown.  After understanding the first exsample, try other APIs.
+
+Firstly, you have to install the SOAP related libraries for the
+programming language of your choice.
+
+=== Quick Start with Perl
+
+In the case of Perl, you need to install the following packages:
+
+  * ((<SOAP Lite|URL:http://www.soaplite.com/>)) (tested with 0.60)
+    * Note: SOAP Lite > 0.60 is reported to have errors in some methods for now.
+  * ((<MIME-Base64|URL:http://search.cpan.org/author/GAAS/MIME-Base64/>))
+  * ((<LWP|URL:http://search.cpan.org/author/GAAS/libwww-perl/>))
+  * ((<URI|URL:http://search.cpan.org/author/GAAS/URI/>))
+
+Here's a first example in Perl language.
+
+  #!/usr/bin/env perl
+  
+  use SOAP::Lite;
+  
+  $wsdl = 'http://soap.genome.jp/KEGG.wsdl';
+  
+  $serv = SOAP::Lite->service($wsdl);
+  
+  $offset = 1;
+  $limit = 5;
+  
+  $top5 = $serv->get_best_neighbors_by_gene('eco:b0002', $offset, $limit);
+  
+  foreach $hit (@{$top5}) {
+    print "$hit->{genes_id1}\t$hit->{genes_id2}\t$hit->{sw_score}\n";
+  }
+
+The output will be
+
+  eco:b0002       eco:b0002       5283
+  eco:b0002       ecj:JW0001      5283
+  eco:b0002       sfx:S0002       5271
+  eco:b0002       sfl:SF0002      5271
+  eco:b0002       ecc:c0003       5269
+
+showing that eco:b0002 has Smith-Waterman score 5271 with sfl:SF0002
+as a 4th hit among the entire KEGG/GENES database (here, "eco" means
+E. coli K-12 MG1655 and "sfl" means Shigella flexneri 2457T in the
+KEGG organism codes).
+
+The method internally searches the KEGG/SSDB (Sequence Similarity
+Database) database which contains information about the amino acid
+sequence similarities among all protein coding genes in the complete
+genomes, together with information about best hits and bidirectional
+best hits (best-best hits).  The relation of gene x in genome A and
+gene y in genome B is called bidirectional best hits, when x is the
+best hit of query y against all genes in A and vice versa, and it is
+often used as an operational definition of ortholog.
+
+Next example simply lists PATHWAYs for E. coli ("eco") in KEGG
+database.
+
+  #!/usr/bin/env perl
+
+  use SOAP::Lite;
+
+  $wsdl = 'http://soap.genome.jp/KEGG.wsdl';
+
+  $results = SOAP::Lite
+               -> service($wsdl)
+               -> list_pathways("eco");
+
+  foreach $path (@{$results}) {
+    print "$path->{entry_id}\t$path->{definition}\n";
+  }
+
+This example colors the boxes corresponding to the E. coli genes b1002
+and b2388 on a Glycolysis pathway of E. coli (path:eco00010).
+
+  #!/usr/bin/env perl
+  
+  use SOAP::Lite;
+  
+  $wsdl = 'http://soap.genome.jp/KEGG.wsdl';
+  
+  $serv = SOAP::Lite -> service($wsdl);
+
+  $genes = SOAP::Data->type(array => ["eco:b1002", "eco:b2388"]);
+
+  $result = $serv -> mark_pathway_by_objects("path:eco00010", $genes);
+
+  print $result;	# URL of the generated image
+
+=== Perl FAQ
+
+If you use the KEGG API methods which requires arguments in
+ArrayOfstring datatype, you must need following modifications
+depending on the version of SOAP::Lite.
+
+==== SOAP::Lite version <= 0.60
+
+As you see in the above example, you always need to convert a Perl's array
+into a SOAP object expicitly in SOAP::Lite by
+
+  SOAP::Data->type(array => [value1, value2, .. ])
+
+when you pass an array as the argument for any KEGG API method.
+
+==== SOAP::Lite version > 0.60
+
+You should use version >= 0.69 as the versions between 0.61-0.68 contain bugs.
+
+You need to add following code to your program to pass the array of
+string and/or int data to the SOAP server.
+
+  sub SOAP::Serializer::as_ArrayOfstring{
+    my ($self, $value, $name, $type, $attr) = @_;
+    return [$name, {'xsi:type' => 'array', %$attr}, $value];
+  }
+
+  sub SOAP::Serializer::as_ArrayOfint{
+    my ($self, $value, $name, $type, $attr) = @_;
+    return [$name, {'xsi:type' => 'array', %$attr}, $value];
+  }
+
+By adding the above, you can write
+
+  $genes = ["eco:b1002", "eco:b2388"];
+
+instead of the following (writing as follows is also permitted).
+
+  $genes = SOAP::Data->type(array => ["eco:b1002", "eco:b2388"]);
+
+==== Sample program
+
+You can test with the following script for the SOAP::Lite v0.69.
+If it works, a URL of the generated image will be returned.
+
+  #!/usr/bin/env perl
+  
+  use SOAP::Lite +trace => [qw(debug)];
+
+  print "SOAP::Lite = ", $SOAP::Lite::VERSION, "\n";
+
+  my $serv = SOAP::Lite -> service("http://soap.genome.jp/KEGG.wsdl");
+
+  my $genes = ["eco:b1002", "eco:b2388"];
+
+  my $result = $serv->mark_pathway_by_objects("path:eco00010", $genes);
+  print $result, "\n";
+
+  # sub routines implicitly used in the above code
+
+  sub SOAP::Serializer::as_ArrayOfstring{
+    my ($self, $value, $name, $type, $attr) = @_;
+    return [$name, {'xsi:type' => 'array', %$attr}, $value];
+  }
+
+  sub SOAP::Serializer::as_ArrayOfint{
+    my ($self, $value, $name, $type, $attr) = @_;
+    return [$name, {'xsi:type' => 'array', %$attr}, $value];
+  }
+
+=== Quick Start with Ruby
+
+If you are using Ruby 1.8.1 or later, you are ready to use KEGG API
+as Ruby already supports SOAP in its standard library.
+
+If your Ruby is 1.6.8 or older, you need to install followings:
+
+  * ((<SOAP4R|URL:http://raa.ruby-lang.org/list.rhtml?name=soap4r>)) 1.5.1 or later
+  * One of the following XML processing library
+    * ((<rexml|URL:http://raa.ruby-lang.org/list.rhtml?name=rexml>))
+    * ((<xmlparser|URL:http://raa.ruby-lang.org/list.rhtml?name=xmlparser>))
+    * ((<xmlscan|URL:http://raa.ruby-lang.org/list.rhtml?name=xmlscan>))
+  * ((<date2|URL:http://raa.ruby-lang.org/list.rhtml?name=date2>))
+  * ((<devel-logger|URL:http://raa.ruby-lang.org/list.rhtml?name=devel-logger>))
+  * ((<uconv|URL:http://raa.ruby-lang.org/list.rhtml?name=uconv>))
+  * ((<http-access2|URL:http://raa.ruby-lang.org/list.rhtml?name=http-access2>))
+
+Here's a sample code for Ruby having the same functionality with Perl's
+first example shown above.
+
+  #!/usr/bin/env ruby
+
+  require 'soap/wsdlDriver'
+
+  wsdl = "http://soap.genome.jp/KEGG.wsdl"
+  serv = SOAP::WSDLDriverFactory.new(wsdl).create_rpc_driver
+  serv.generate_explicit_type = true
+  # if uncommented, you can see transactions for debug
+  #serv.wiredump_dev = STDERR
+  
+  offset = 1
+  limit = 5
+
+  top5 = serv.get_best_neighbors_by_gene('eco:b0002', offset, limit)
+  top5.each do |hit|
+    print hit.genes_id1, "\t", hit.genes_id2, "\t", hit.sw_score, "\n"
+  end
+
+You may need to iterate to obtain all the results by increasing offset
+and/or limit.
+
+  #!/usr/bin/env ruby
+  
+  require 'soap/wsdlDriver'
+  
+  wsdl = "http://soap.genome.jp/KEGG.wsdl"
+  serv = SOAP::WSDLDriverFactory.new(wsdl).create_rpc_driver
+  serv.generate_explicit_type = true
+
+  offset = 1
+  limit = 100
+  
+  loop do
+    results = serv.get_best_neighbors_by_gene('eco:b0002', offset, limit)
+    break unless results
+    results.each do |hit|
+      print hit.genes_id1, "\t", hit.genes_id2, "\t", hit.sw_score, "\n"
+    end
+    offset += limit
+  end
+
+It is automatically done by using ((<BioRuby|URL:http://bioruby.org/>))
+library, which implements get_all_* methods for this.  BioRuby also
+provides filtering functionality for selecting needed fields from the
+complex data type.
+
+  #!/usr/bin/env ruby
+  
+  require 'bio'
+  
+  serv = Bio::KEGG::API.new
+  
+  results = serv.get_all_best_neighbors_by_gene('eco:b0002')
+
+  results.each do |hit|
+    print hit.genes_id1, "\t", hit.genes_id2, "\t", hit.sw_score, "\n"
+  end
+
+  # Same as above but using filter to select fields
+  fields = [:genes_id1, :genes_id2, :sw_score]
+  results.each do |hit|
+    puts hit.filter(fields).join("\t")
+  end
+
+  # Different filters to pick additional fields for each amino acid sequence
+  fields1 = [:genes_id1, :start_position1, :end_position1, :best_flag_1to2]
+  fields2 = [:genes_id2, :start_position2, :end_position2, :best_flag_2to1]
+  results.each do |hit|
+    print "> score: ", hit.sw_score, ", identity: ", hit.identity, "\n"
+    print "1:\t", hit.filter(fields1).join("\t"), "\n"
+    print "2:\t", hit.filter(fields2).join("\t"), "\n"
+  end
+
+The equivalent for the Perl's second example described above will be
+
+  #!/usr/bin/env ruby
+
+  require 'bio'
+
+  serv = Bio::KEGG::API.new
+
+  list = serv.list_pathways("eco")
+  list.each do |path|
+    print path.entry_id, "\t", path.definition, "\n"
+  end
+
+and equivalent for the last example is as follows.
+
+  #!/usr/bin/env ruby
+  
+  require 'bio'
+
+  serv = Bio::KEGG::API.new
+  
+  genes = ["eco:b1002", "eco:b2388"]
+
+  result = serv.mark_pathway_by_objects("path:eco00010", genes)
+
+  print result		# URL of the generated image
+
+=== Quick Start with Python
+
+In the case of Python, you have to install
+
+  * ((<SOAPpy|URL:http://pywebsvcs.sourceforge.net/>))
+
+plus some extra packages required for SOAPpy (
+((<fpconst|URL:http://www.analytics.washington.edu/Zope/projects/fpconst>)),
+((<PyXML|URL:http://pyxml.sourceforge.net/>)) etc.).
+
+Here's a sample code using KEGG API with Python.
+
+  #!/usr/bin/env python
+
+  from SOAPpy import WSDL
+ 
+  wsdl = 'http://soap.genome.jp/KEGG.wsdl'
+  serv = WSDL.Proxy(wsdl)
+
+  results = serv.get_genes_by_pathway('path:eco00020')
+  print results
+
+=== Quick Start with Java
+
+In the case of Java, you need to obtain Apache Axis library version
+axis-1_2alpha or newer (axis-1_1 doesn't work properly for KEGG API)
+
+  * ((<Apache Axis|URL:http://ws.apache.org/axis/>))
+
+and put required jar files in an appropriate directory.
+
+For the binary distribution of the Apache axis-1_2alpha release, copy
+the jar files stored under the axis-1_2alpha/lib/ to the directory of
+your choice.
+
+  % cp axis-1_2alpha/lib/*.jar /path/to/lib/
+
+You can use WSDL2Java coming with Apache Axis to generate classes
+needed for the KEGG API automatically.
+
+To generate classes and documents for the KEGG API, download the script
+((<axisfix.pl|URL:http://www.genome.jp/kegg/soap/support/axisfix.pl>))
+and follow the steps below:
+
+  % java -classpath /path/to/lib/axis.jar:/path/to/lib/jaxrpc.jar:/path/to/lib/commons-logging.jar:/path/to/lib/commons-discovery.jar:/path/to/lib/saaj.jar:/path/to/lib/wsdl4j.jar:. org.apache.axis.wsdl.WSDL2Java -p keggapi http://soap.genome.jp/KEGG.wsdl
+  % perl -i axisfix.pl keggapi/KEGGBindingStub.java
+  % javac -classpath /path/to/lib/axis.jar:/path/to/lib/jaxrpc.jar:/path/to/lib/wsdl4j.jar:. keggapi/KEGGLocator.java
+  % jar cvf keggapi.jar keggapi/*
+  % javadoc -classpath /path/to/lib/axis.jar:/path/to/lib/jaxrpc.jar -d keggapi_javadoc keggapi/*.java
+
+This program will do the same job as the Python's example (extended to
+accept a pathway_id as the argument).
+
+  import keggapi.*;
+  
+  class GetGenesByPathway {
+          public static void main(String[] args) throws Exception {
+                  KEGGLocator  locator = new KEGGLocator();
+                  KEGGPortType serv    = locator.getKEGGPort();
+  
+                  String   query   = args[0];
+                  String[] results = serv.get_genes_by_pathway(query);
+  
+                  for (int i = 0; i < results.length; i++) {
+                          System.out.println(results[i]);
+                  }
+          }
+  }
+
+This is another example which uses ArrayOfSSDBRelation data type. 
+
+  import keggapi.*;
+  
+  class GetBestNeighborsByGene {
+          public static void main(String[] args) throws Exception {
+                  KEGGLocator    locator  = new KEGGLocator();
+                  KEGGPortType   serv     = locator.getKEGGPort();
+  
+                  String         query    = args[0];
+                  SSDBRelation[] results  = null;
+  
+                  results = serv.get_best_neighbors_by_gene(query, 1, 50);
+  
+                  for (int i = 0; i < results.length; i++) {
+                          String gene1  = results[i].getGenes_id1();
+                          String gene2  = results[i].getGenes_id2();
+                          int    score  = results[i].getSw_score();
+                          System.out.println(gene1 + "\t" + gene2 + "\t" + score);
+                  }
+          }
+  }
+
+Compile and execute this program (don't forget to include keggapi.jar file
+in your classpath) as follows:
+
+  % javac -classpath /path/to/lib/axis.jar:/path/to/lib/jaxrpc.jar:/path/to/lib/wsdl4j.jar:/path/to/keggapi.jar GetBestNeighborsByGene.java
+
+  % java -classpath /path/to/lib/axis.jar:/path/to/lib/jaxrpc.jar:/path/to/lib/commons-logging.jar:/path/to/lib/commons-discovery.jar:/path/to/lib/saaj.jar:/path/to/lib/wsdl4j.jar:/path/to/keggapi.jar:. GetBestNeighborsByGene eco:b0002
+
+You may wish to set the CLASSPATH environmental variable.
+
+bash/zsh:
+
+  % for i in /path/to/lib/*.jar
+  do
+    CLASSPATH="${CLASSPATH}:${i}"
+  done
+  % export CLASSPATH
+
+tcsh:
+
+  % foreach i ( /path/to/lib/*.jar )
+    setenv CLASSPATH ${CLASSPATH}:${i}
+  end
+
+For the other cases, consult the javadoc pages generated by WSDL2Java.
+
+  * ((<URL:http://www.genome.jp/kegg/soap/doc/keggapi_javadoc/>))
+
+== KEGG API Reference
+
+=== WSDL file
+
+Users can use a WSDL file to create a SOAP client driver.  The WSDL file for
+the KEGG API can be found at:
+
+  * ((<URL:http://soap.genome.jp/KEGG.wsdl>))
+
+=== Terminology
+
+  * '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>))
+
+  * 'db' is a database name used in GenomeNet service. See the
+    description of the list_databases method below.
+
+  * 'entry_id' is a unique identifier of which format is the combination of
+    the database name and the identifier of an entry joined by a colon sign
+    as 'database:entry' (e.g. 'embl:J00231' means an EMBL entry 'J00231').
+    'entry_id' includes 'genes_id', 'enzyme_id', 'compound_id', 'drug_id',
+    'glycan_id', 'reaction_id', 'pathway_id' and 'motif_id' described in below.
+
+  * 'genes_id' is a gene identifier used in KEGG/GENES which consists of
+    'keggorg' and a gene name (e.g. 'eco:b0001' means an E. coli gene 'b0001').
+
+  * 'enzyme_id' is an enzyme identifier consisting of database name 'ec'
+    and an enzyme code used in KEGG/LIGAND ENZYME database.
+    (e.g. 'ec:1.1.1.1' means an alcohol dehydrogenase enzyme)
+
+  * 'compound_id' is a compound identifier consisting of database name
+    'cpd' and a compound number used in KEGG COMPOUND / LIGAND database
+    (e.g. 'cpd:C00158' means a citric acid).  Note that some compounds
+    also have 'glycan_id' and both IDs are accepted and converted internally
+    by the corresponding methods.
+
+  * 'drug_id' is a drug identifier consisting of database name 'dr'
+    and a compound number used in KEGG DRUG / LIGAND database
+    (e.g. 'dr:D00201' means a tetracycline).
+
+  * 'glycan_id' is a glycan identifier consisting of database name 'gl'
+    and a glycan number used in KEGG GLYCAN database (e.g. 'gl:G00050'
+    means a Paragloboside).  Note that some glycans also have 'compound_id'
+    and both IDs are accepted and converted internally by the corresponding
+    methods.
+
+  * 'reaction_id' is a reaction identifier consisting of database name 'rn'
+    and a reaction number used in KEGG/REACTION (e.g. 'rn:R00959' is a
+    reaction which catalyze cpd:C00103 into cpd:C00668)
+
+  * 'pathway_id' is a pathway identifier consisting of 'path' and a pathway
+    number used in KEGG/PATHWAY. Pathway numbers prefixed by 'map' specify
+    the reference pathway and pathways prefixed by the 'keggorg' specify
+    pathways specific to the organism (e.g. 'path:map00020' means a reference
+    pathway for the cytrate cycle and 'path:eco00020' means a same pathway of
+    which E. coli genes are marked).
+
+  * 'motif_id' is a motif identifier consisting of motif database names
+    ('ps' for prosite, 'bl' for blocks, 'pr' for prints, 'pd' for prodom,
+    and 'pf' for pfam) and a motif entry name. (e.g. 'pf:DnaJ' means a Pfam
+    database entry 'DnaJ').
+
+  * 'ko_id' is a KO identifier consisting of 'ko' and a ko number used in 
+    KEGG/KO. KO (KEGG Orthology) is an classification of orthologous genes 
+    defined by KEGG (e.g. 'ko:K02598' means a KO group for nitrite transporter
+    NirC genes).
+
+  * 'ko_class_id' is a KO class identifier which is used to classify
+    'ko_id' hierarchically (e.g. '01110' means a 'Carbohydrate Metabolism'
+    class).
+
+    * ((<URL:http://www.genome.jp/dbget-bin/get_htext?KO>))
+
+  * 'offset' and 'limit' are both an integer and used to control the 
+    number of the results returned at once.  Methods having these arguments
+    will return first 'limit' results starting from 'offset'th.
+
+  * 'fg_color_list' is a list of colors for the foreground (corresponding
+    to the texts and borders of the objects on the KEGG pathway map).
+
+  * 'bg_color_list' is a list of colors for the background (corresponding
+    to the inside of the objects on the KEGG pathway map).
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/kegg3.html>))
+
+=== Returned values
+
+Many of the KEGG API methods will return a set of values in a complex data
+structure as described below.  This section summarizes all kind of these
+data types.  Note that, the retuened values for the empty result will be
+  * an empty array -- for the methods which return ArrayOf'OBJ'
+  * an empty string -- for the methods which return String
+  * -1 -- for the methods which return int
+  * NULL -- for the methods which return any other 'OBJ'
+
++ SSDBRelation
+
+SSDBRelation data type contains the following fields:
+
+  genes_id1         genes_id of the query (string)
+  genes_id2         genes_id of the target (string)
+  sw_score          Smith-Waterman score between genes_id1 and genes_id2 (int)
+  bit_score         bit score between genes_id1 and genes_id2 (float)
+  identity          identity between genes_id1 and genes_id2 (float)
+  overlap           overlap length between genes_id1 and genes_id2 (int)
+  start_position1   start position of the alignment in genes_id1 (int)
+  end_position1     end position of the alignment in genes_id1 (int)
+  start_position2   start position of the alignment in genes_id2 (int)
+  end_position2     end position of the alignment in genes_id2 (int)
+  best_flag_1to2    best flag from genes_id1 to genes_id2 (boolean)
+  best_flag_2to1    best flag from genes_id2 to genes_id1 (boolean)
+  definition1       definition string of the genes_id1 (string)
+  definition2       definition string of the genes_id2 (string)
+  length1           amino acid length of the genes_id1 (int)
+  length2           amino acid length of the genes_id2 (int)
+
+
++ ArrayOfSSDBRelation
+
+ArrayOfSSDBRelation data type is a list of the SSDBRelation data type.
+
++ MotifResult
+
+MotifResult data type contains the following fields:
+
+  motif_id          motif_id of the motif (string)
+  definition        definition of the motif (string)
+  genes_id          genes_id of the gene containing the motif (string)
+  start_position    start position of the motif match (int)
+  end_position      end position of the motif match (int)
+  score             score of the motif match for TIGRFAM and PROSITE (float)
+  evalue            E-value of the motif match for Pfam (double)
+
+Note: 'score' and/or 'evalue' is set to -1 if the corresponding value is
+not applicable.
+
++ ArrayOfMotifResult
+
+ArrayOfMotifResult data type is a list of the MotifResult data type.
+
++ Definition
+
+Definition data type contains the following fields:
+
+  entry_id          database entry_id (string)
+  definition        definition of the entry (string)
+
++ ArrayOfDefinition
+
+ArrayOfDefinition data type is a list of the Definition data type.
+
++ LinkDBRelation
+
+LinkDBRelation data type contains the following fields:
+
+  entry_id1         entry_id of the starting entry (string)
+  entry_id2         entry_id of the terminal entry (string)
+  type              type of the link as "direct" or "indirect" (string)
+  path              link path information across the databases (string)
+
++ ArrayOfLinkDBRelation
+
+ArrayOfLinkDBRelation data type is a list of the LinkDBRelation data type.
+
++ PathwayElement
+
+PathwayElement represents the object on the KEGG PATHWAY map.
+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.
+
++ PathwayElementRelation
+
+PathwayElementRelation represents the relationship between PathwayElements.
+PathwayElementRelation data type contains the following fields:
+
+  element_id1       unique identifier of the object on the pathway (int)
+  element_id2       unique identifier of the object on the pathway (int)
+  type              type of relation ("ECrel", "maplink" etc.) (string)
+  subtypes          array of objects involved in the relation (ArrayOfSubtype)
+
++ ArrayOfPathwayElementRelation
+
+ArrayOfPathwayElementRelation data type is a list of
+the PathwayElementRelation data type.
+
+++ Subtype
+
+Subtype is used in the PathwayElementRelation data type to represent
+the object involved in the relation.
+Subtype data type contains the following fields:
+
+  element_id        unique identifier of the object on the pathway (int)
+  relation          kind of relation ("compound", "inhibition" etc.) (string)
+  type              type of relation ("+p", "--|" etc.) (string)
+
+++ ArrayOfSubtype
+
+ArrayOfSubtype data type is a list of the Subtype data type.
+
++ StructureAlignment
+
+StructureAlignment represents structural alignment of nodes between
+two molecules with score.
+StructureAlignment data type contains the following fields:
+
+  target_id         entry_id of the target (string)
+  score             alignment score (float)
+  query_nodes       indices of aligned nodes in the query molecule (ArrayOfint)
+  target_nodes      indices of aligned nodes in the target molecule (ArrayOfint)
+
++ ArrayOfStructureAlignment
+
+ArrayOfStructureAlignment data type is a list of the StructureAlignment
+data type.
+
+=== Methods
+
+==== Meta information
+
+This section describes the APIs for retrieving the general information 
+concerning latest version of the KEGG database.
+
+--- list_databases
+
+List of database names and its definitions available on the GenomeNet
+is returned.
+
+Return value:
+  ArrayOfDefinition (db, definition)
+
+Related site:
+  * ((<URL:http://www.genome.jp/dbget/>))
+  * ((<URL:http://www.genome.jp/about_genomenet/service.html>)) (section 2.2)
+
+--- list_organisms
+
+List up the organisms in the KEGG/GENES database. 'org' code and the
+organism's full name is returned in the Definition data type.
+
+Return value:
+  ArrayOfDefinition (org, definition)
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/catalog/org_list.html>))
+  * ((<URL:http://www.genome.jp/dbget-bin/get_htext?Organisms+-n>))
+
+--- list_pathways(string:org)
+
+List up the pathway maps of the given organism in the KEGG/PATHWAY database.
+Passing the string "map" as its argument, this method returns a list of the 
+reference pathways.
+
+Return value:
+  ArrayOfDefinition (pathway_id, definition)
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/pathway.html>))
+
+==== DBGET
+
+This section describes the wrapper methods for DBGET system developed
+at the GenomeNet.  For more details on DBGET system, see:
+
+Related site:
+  * ((<URL:http://www.genome.jp/dbget/dbget_manual.html>))
+  * ((<URL:http://www.genome.jp/dbget-bin/binfo>))
+
+--- binfo(string:db)
+
+Show the version information of the specified database.
+Passing the string "all" as its argument, this method returns the version 
+information of all databases available on the GenomeNet.
+
+Return value:
+  string
+
+Example:
+  # Show the information of the latest GenBank database.
+  binfo("gb")
+
+--- bfind(string:str)
+
+Wrapper method for bfind command. bfind is used for searching entries by 
+keywords. User need to specify a database from those which are supported 
+by DBGET system before keywords.  Number of keywords given at a time is
+restricted up to 100.
+
+Return value:
+  string
+
+Example:
+  # Returns the IDs and definitions of entries which have definition
+  # including the word 'E-cadherin' and 'human' from GenBank.
+  bfind("gb E-cadherin human")
+
+--- bget(string:str)
+
+The bget command is used for retrieving database entries specified by a list
+of 'entry_id'.  This method accepts all the bget command line options as
+a string.  Number of entries retrieved at a time is restricted up to 100.
+
+Return value:
+  string
+
+Example:
+  # retrieve two KEGG/GENES entries
+  bget("eco:b0002 hin:tRNA-Cys-1")
+  # retrieve nucleic acid sequences in a FASTA format
+  bget("-f -n n eco:b0002 hin:tRNA-Cys-1")
+  # retrieve amino acid sequence in a FASTA format
+  bget("-f -n a eco:b0002")
+
+--- btit(string:str)
+
+Wrapper method for btit command. btit is used for retrieving the definitions
+by given database entries.  Number of entries given at a time is restricted
+up to 100.
+
+Return value:
+  string
+
+Example:
+  # Returns the ids and definitions of four GENES entries "hsa:1798",
+  # "mmu:13478", "dme:CG5287-PA" and cel:Y60A3A.14".
+  btit("hsa:1798 mmu:13478 dme:CG5287-PA cel:Y60A3A.14")
+
+--- bconv(string:str)
+
+The bconv command converts external IDs to KEGG IDs.
+Currently, following external databases are available.
+
+  External database  Database prefix
+  -----------------  ---------------
+  NCBI GI            ncbi-gi:
+  NCBI GeneID        ncbi-geneid:
+  GenBank            genbank:
+  UniGene            unigene:
+  UniProt            uniprot:
+  OMIM               omim:
+
+The result is a 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")
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/genes.html>)) (Gene name conversion section)
+
+==== LinkDB
+
++ Database cross references
+
+--- get_linkdb_by_entry(string:entry_id, string:db, int:offset, int:limit)
+
+Retrieve the database entries linked from the user specified database entry.
+It can also be specified the targeted database.
+
+Return value:
+  ArrayOfLinkDBRelation
+
+Example:
+  # Get the entries of KEGG/PATHWAY database linked from the entry 'eco:b0002'.
+  get_linkdb_by_entry('eco:b0002', 'pathway', 1, 10)
+  get_linkdb_by_entry('eco:b0002', 'pathway', 11, 10)
+
+Related site:
+  * ((<URL:http://www.genome.jp/dbget-bin/www_linkdb>)) (Single entry to database)
+
+--- get_linkdb_between_databases(string:from_db, string:to_db, int:offset, int:limit)
+
+Retrieve all links between entries among the given two databases.
+
+Return value:
+  ArrayOfLinkDBRelation
+
+Example:
+  # Get all links from "eco" (KEGG GENES) to "pathway" (KEGG PATHWAY)
+  # databases.
+  get_linkdb_between_databases("eco", "pathway", 1, 100)
+
+  # Print the contents of obtained links in Ruby language
+  links = get_linkdb_between_databases("eco", "pathway", 1, 100)
+  links.each do |link|
+    puts link.entry_id1  # => "eco:b0084"
+    puts link.entry_id2  # => "path:map00550"
+    puts link.type       # => "indirect"
+    puts link.path       # => "eco->ec->path"
+  end
+
+Related site:
+  * ((<URL:http://www.genome.jp/dbget-bin/www_linkdb>)) (Database to database)
+
++ Relation among genes and enzymes
+
+--- get_genes_by_enzyme(string:enzyme_id, string: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(string: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(string: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(string: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(string: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(string: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(string: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(string: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(string: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(string: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(string: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
+on SSDB, see:
+
+  * ((<URL:http://www.genome.jp/kegg/ssdb/>))
+
+
+--- get_best_best_neighbors_by_gene(string:genes_id, int:offset, int:limit)
+
+Search best-best neighbor of the gene in all organisms.
+
+Return value:
+  ArrayOfSSDBRelation
+
+Example:
+  # List up best-best neighbors of 'eco:b0002'.
+  get_best_best_neighbors_by_gene('eco:b0002', 1, 10)
+  get_best_best_neighbors_by_gene('eco:b0002', 11, 10)
+
+--- get_best_neighbors_by_gene(string:genes_id, int:offset, int:limit)
+
+Search best neighbors in all organism.
+
+Return value:
+  ArrayOfSSDBRelation
+
+Example:
+  # List up best neighbors of 'eco:b0002'.
+  get_best_neighbors_by_gene('eco:b0002', 1, 10)
+  get_best_neighbors_by_gene('eco:b0002', 11, 10)
+
+--- get_reverse_best_neighbors_by_gene(string:genes_id, int:offset, int:limit)
+
+Search reverse best neighbors in all organisms.
+
+Return value:
+  ArrayOfSSDBRelation
+
+Example:
+  # List up reverse best neighbors of 'eco:b0002'.
+  get_reverse_best_neighbors_by_gene('eco:b0002', 1, 10)
+  get_reverse_best_neighbors_by_gene('eco:b0002', 11, 10)
+
+--- get_paralogs_by_gene(string:genes_id, int:offset, int:limit)
+
+Search paralogous genes of the given gene in the same organism.
+
+Return value:
+  ArrayOfSSDBRelation
+
+Example:
+  # List up paralogous genes of 'eco:b0002'.
+  get_paralogs_by_gene('eco:b0002', 1, 10)
+  get_paralogs_by_gene('eco:b0002', 11, 10)
+
+
+==== Motif
+
+--- get_motifs_by_gene(string:genes_id, string:db)
+
+Search motifs in the specified gene. As for 'db', 
+user can specify one of the four database; Pfam, TIGRFAM, PROSITE pattern,
+PROSITE profile as 'pfam', 'tfam', 'pspt', 'pspf', respectively.
+You can also use 'all' to specify all of the four databases above.
+
+Return value:
+  ArrayOfMotifResult
+
+Example:
+  # Returns the all pfam motifs in the E. coli gene 'b0002'
+  get_motifs_by_gene('eco:b0002', 'pfam')
+
+--- get_genes_by_motifs([string]:motif_id_list, int:offset, int:limit)
+
+Search all genes which contains all of the specified motifs.
+
+Return value:
+  ArrayOfDefinition (genes_id, definition)
+
+Example:
+  # Returns all genes which have Pfam 'DnaJ' and Prosite 'DNAJ_2' motifs.
+  list = ['pf:DnaJ', 'ps:DNAJ_2']
+  get_genes_by_motifs(list, 1, 10)
+  get_genes_by_motifs(list, 11, 10)
+
+==== KO
+
+--- get_ko_by_gene(string:genes_id)
+
+Search all KOs to which given genes_id belongs.
+
+Return value:
+  ArrayOfstring (ko_id)
+
+Example:
+  # Returns ko_ids to which GENES entry 'eco:b0002' belongs.
+  get_ko_by_gene('eco:b0002')
+
+
+--- get_ko_by_ko_class(string:ko_class_id)
+
+Return all KOs which belong to the given ko_class_id.
+
+Return value:
+  ArrayOfDefinition (ko_id, definition)
+
+Example:
+  # Returns ko_ids which belong to the KO class '01196'.
+  get_ko_by_ko_class('01196')
+
+--- get_genes_by_ko_class(string:ko_class_id, string:org, int:offset, int:limit)
+
+Retrieve all genes of the specified organism which are classified
+under the given ko_class_id.
+
+Return value:
+  ArrayOfDefinition (genes_id, definition)
+
+Example:
+  # Returns first 100 human genes which belong to the KO class '00930'
+  get_genes_by_ko_class('00903', 'hsa' , 1, 100)
+
+--- get_genes_by_ko(string:ko_id, string:org)
+
+Retrieve all genes of the specified organism which belong to the
+given ko_id.
+
+Return value:
+  ArrayOfDefinition (genes_id, definition)
+
+Example
+  # Returns E.coli genes which belong to the KO 'K00001'
+  get_genes_by_ko('ko:K00001', 'eco')
+
+  # Returns genes of all organisms which are assigned to the KO 'K00010'
+  get_genes_by_ko('ko:K00010', 'all')
+
+
+
+==== PATHWAY
+
+This section describes the APIs for PATHWAY database.  For more details
+on PATHWAY database, see:
+
+  * ((<URL:http://www.genome.jp/kegg/kegg2.html#pathway>))
+
++ Coloring pathways
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/tool/color_pathway.html>))
+
+--- mark_pathway_by_objects(string:pathway_id, [string]:object_id_list)
+
+Mark the given objects on the given pathway map and return the URL of the
+generated image.
+
+Return value:
+  string (URL)
+
+Example:
+  # Returns the URL of the generated image for the given map 'path:eco00260'
+  # with objects corresponding to 'eco:b0002' and 'cpd:C00263' colored in red.
+  obj_list = ['eco:b0002', 'cpd:C00263']
+  mark_pathway_by_objects('path:eco00260', obj_list)
+
+--- color_pathway_by_objects(string:pathway_id, [string]:object_id_list, [string]:fg_color_list, [string]:bg_color_list)
+
+Color the given objects on the pathway map with the specified colors 
+and return the URL of the colored image.  In the KEGG pathway maps,
+a gene or enzyme is represented by a rectangle and a compound is
+shown as a small circle.  'fg_color_list' is used for specifying the
+color of text and border of the given objects 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 'object_id_list' list.
+
+Return value:
+  string (URL)
+
+Example:
+  # Returns the URL for the given pathway 'path:eco00260' with genes
+  # 'eco:b0514' colored in red with yellow background and
+  # 'eco:b2913' colored in green with yellow background.
+  obj_list = ['eco:b0514', 'eco:b2913']
+  fg_list  = ['#ff0000', '#00ff00']
+  bg_list  = ['#ffff00', 'yellow']
+  color_pathway_by_objects('path:eco00260', obj_list, fg_list, bg_list)
+
+--- color_pathway_by_elements(string:pathway_id, [int]:element_id_list, [string]:fg_color_list, [string]: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(string:pathway_id, [string]:object_id_list)
+
+HTML version of the 'mark_pathway_by_objects' method.
+Mark the given objects on the given pathway map and return the URL of the
+HTML with the generated 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 the generated image of the given pathway
+  # 'path:eco00970' with three objects corresponding to 'eco:b4258',
+  # 'cpd:C00135' and 'ko:K01881' colored in red.
+  obj_list = ['eco:b4258', 'cpd:C00135', 'ko:K01881']
+  get_html_of_marked_pathway_by_objects('path:eco00970', obj_list)
+
+--- get_html_of_colored_pathway_by_objects(string:pathway_id, [string]:object_id_list, [string]:fg_color_list, [string]:bg_color_list)
+
+HTML version of the 'color_pathway_by_object' method.
+Color the given objects 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:eco00970'
+  # with a gene 'eco:b4258' colored in gray/red, a compound 'cpd:C00135'
+  # 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(string:pathway_id, [int]:element_id_list, [string]:fg_color_list, [string]: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)
+
++ Relations of objects on the pathway
+
+--- get_element_relations_by_pathway(string:pathway_id)
+
+Search all relations of the objects on the specified pathway.
+
+Return value:
+  ArrayOfPathwayElementRelation
+
+Example:
+  # Returns list of PathwayElementRelation on the pathway map 'path:bsu00010'
+  relations = get_element_relations_by_pathway('path:bsu00010')
+
+  # Print the contents of obtained relations in Ruby language
+  relations.each do |rel|
+    puts rel.element_id1
+    puts rel.element_id2
+    puts rel.type
+    rel.subtypes.each do |sub|
+      puts sub.element_id
+      puts sub.relation
+      puts sub.type
+    end  
+  end
+
++ Objects on the pathway
+
+--- get_elements_by_pathway(string: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(string:pathway_id)
+
+Search all genes on the specified pathway.  Organism name is given by
+the name of the pathway map.
+
+Return value:
+  ArrayOfstring (genes_id)
+
+Example:
+  # Returns all E. coli genes on the pathway map '00020'.
+  get_genes_by_pathway('path:eco00020')
+
+--- get_enzymes_by_pathway(string:pathway_id)
+
+Search all enzymes on the specified pathway.
+
+Return value:
+  ArrayOfstring (enzyme_id)
+
+Example:
+  # Returns all E. coli enzymes on the pathway map '00020'.
+  get_enzymes_by_pathway('path:eco00020')
+
+--- get_compounds_by_pathway(string:pathway_id)
+
+Search all compounds on the specified pathway.
+
+Return value:
+  ArrayOfstring (compound_id)
+
+Example:
+  # Returns all E. coli compounds on the pathway map '00020'.
+  get_compounds_by_pathway('path:eco00020')
+
+--- get_glycans_by_pathway(string:pathway_id)
+
+Search all glycans on the specified pathway.
+
+Return value:
+  ArrayOfstring (glycan_id)
+
+Example
+  # Returns all E. coli glycans on the pathway map '00510'
+  get_glycans_by_pathway('path:eco00510')
+
+--- get_reactions_by_pathway(string:pathway_id)
+
+Retrieve all reactions on the specified pathway.
+
+Return value:
+  ArrayOfstring (reaction_id)
+
+Example:
+  # Returns all E. coli reactions on the pathway map '00260'
+  get_reactions_by_pathway('path:eco00260')
+
+--- get_kos_by_pathway(string:pathway_id)
+
+Retrieve all KOs on the specified pathway.
+
+Return value:
+  ArrayOfstring (ko_id)
+
+Example:
+  # Returns all ko_ids on the pathway map 'path:hsa00010'
+  get_kos_by_pathway('path:hsa00010')
+
++ Pathways by objects
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/tool/search_pathway.html>))
+
+--- get_pathways_by_genes([string]:genes_id_list)
+
+Search all pathways which include all the given genes.  How to pass the
+list of genes_id will depend on the language specific implementations.
+
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example:
+  # Returns all pathways including E. coli genes 'b0077' and 'b0078'
+  get_pathways_by_genes(['eco:b0077' , 'eco:b0078'])
+
+--- get_pathways_by_enzymes([string]:enzyme_id_list)
+
+Search all pathways which include all the given enzymes.
+
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example:
+  # Returns all pathways including an enzyme '1.3.99.1'
+  get_pathways_by_enzymes(['ec:1.3.99.1'])
+
+--- get_pathways_by_compounds([string]:compound_id_list)
+
+Search all pathways which include all the given compounds.
+
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example:
+  # Returns all pathways including compounds 'C00033' and 'C00158'
+  get_pathways_by_compounds(['cpd:C00033', 'cpd:C00158'])
+
+--- get_pathways_by_glycans([string]:glycan_id_list)
+
+Search all pathways which include all the given glycans.
+ 
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example
+  # Returns all pathways including glycans 'G00009' and 'G00011'
+  get_pathways_by_glycans(['gl:G00009', 'gl:G00011'])
+
+--- get_pathways_by_reactions([string]:reaction_id_list)
+
+Retrieve all pathways which include all the given reaction_ids.
+
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example:
+  # Returns all pathways including reactions 'rn:R00959', 'rn:R02740',
+  # 'rn:R00960' and 'rn:R01786'
+  get_pathways_by_reactions(['rn:R00959', 'rn:R02740', 'rn:R00960', 'rn:R01786'])
+
+--- get_pathways_by_kos([string]:ko_id_list, string:org)
+
+Retrieve all pathways of the organisms which include all the given KO IDs.
+
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example:
+  # Returns all human pathways including 'ko:K00016' and 'ko:K00382'
+  get_pathways_by_kos(['ko:K00016', 'ko:K00382'], 'hsa')
+
+  # Returns pathways of all organisms including 'ko:K00016' and 'ko:K00382'
+  get_pathways_by_kos(['ko:K00016', 'ko:K00382'], 'all')
+
++ Relation among pathways
+
+--- get_linked_pathways(string:pathway_id)
+
+Retrieve all pathways which are linked from a given pathway_id.
+
+Return value:
+  ArrayOfstring (pathway_id)
+
+Example:
+  # Returns IDs of PATHWAY entries linked from 'path:eco00620'.
+  get_linked_pathways('path:eco00620')
+
+==== GENES
+
+This section describes the APIs for GENES database. For more details
+on GENES database, see:
+
+  * ((<URL:http://www.genome.jp/kegg/kegg2.html#genes>))
+
+--- get_genes_by_organism(string:org, int:offset, int:limit)
+
+Retrieve all genes of the specified organism.
+
+Return value:
+  ArrayOfstring (genes_id)
+
+Example:
+  # Retrive hundred H. influenzae genes at once.
+  get_genes_by_organism('hin', 1, 100)
+  get_genes_by_organism('hin', 101, 100)
+
+==== GENOME
+
+This section describes the APIs for GENOME database. For more details
+on GENOME database, see:
+
+  * ((<URL:http://www.genome.jp/kegg/kegg2.html#genome>))
+
+--- get_number_of_genes_by_organism(string:org)
+
+Get the number of genes coded in the specified organism's genome. 
+
+Return value:
+  int
+
+Example:
+  # Get the number of the genes on the E.coli genome.
+  get_number_of_genes_by_organism('eco')
+
+==== LIGAND
+
+This section describes the APIs for LIGAND database.
+
+Related site:
+  * ((<URL:http://www.genome.jp/kegg/ligand.html>))
+
+--- convert_mol_to_kcf(string:mol)
+
+Convert a MOL format into the KCF format.
+
+Return value:
+  string
+
+Example:
+  convert_mol_to_kcf(mol_str)
+
+--- search_compounds_by_name(string:name)
+
+Returns a list of compounds having the specified name.
+
+Return value:
+  ArrayOfstring (compound_id)
+
+Example:
+  search_compounds_by_name("shikimic acid")
+
+--- search_drugs_by_name(string:name)
+
+Returns a list of drugs having the specified name.
+
+Return value:
+  ArrayOfstring (drug_id)
+
+Example:
+  search_drugs_by_name("tetracyclin")
+
+--- search_glycans_by_name(string:name)
+
+Returns a list of glycans having the specified name.
+
+Return value:
+  ArrayOfstring (glycan_id)
+
+Example:
+  search_glycans_by_name("Paragloboside")
+
+--- search_compounds_by_composition(string:composition)
+
+Returns a list of compounds containing elements indicated by the composition.
+Order of the elements is insensitive.
+
+Return value:
+  ArrayOfstring (compound_id)
+
+Example:
+  search_compounds_by_composition("C7H10O5")
+
+--- search_drugs_by_composition(string:composition)
+
+Returns a list of drugs containing elements indicated by the composition.
+Order of the elements is insensitive.
+
+Return value:
+  ArrayOfstring (drug_id)
+
+Example:
+  search_drugs_by_composition("HCl")
+
+--- search_glycans_by_composition(string:composition)
+
+Returns a list of glycans containing sugars indicated by the composition.
+Order of the sugars (in parenthesis with number) is insensitive.
+
+Return value:
+  ArrayOfstring (glycan_id)
+
+Example:
+  search_glycans_by_composition("(Man)4 (GalNAc)1")
+
+--- search_compounds_by_mass(float:mass, float:range)
+
+Returns a list of compounds having the molecular weight around 'mass'
+with some ambiguity (range).
+
+Return value:
+  ArrayOfstring (compound_id)
+
+Example:
+  search_compounds_by_mass(174.05, 0.1)
+
+--- search_drugs_by_mass(float:mass, float:range)
+
+Returns a list of drugs having the molecular weight around 'mass'
+with some ambiguity (range).
+
+Return value:
+  ArrayOfstring (drug_id)
+
+Example:
+  search_drugs_by_mass(150, 1.0)
+
+--- search_glycans_by_mass(float:mass, float:range)
+
+Returns a list of glycans having a molecular weight around 'mass'
+with some ambiguity (range).
+
+Return value:
+  ArrayOfstring (glycan_id)
+
+Example:
+  search_glycans_by_mass(174.05, 0.1)
+
+--- search_compounds_by_subcomp(string:mol, int:offset, int:limit)
+
+Returns a list of compounds with the alignment having common sub-structure
+calculated by the subcomp program.
+
+You can obtain a MOL formatted structural data of matched compounds
+using bget method with the "-f m" option to confirm the alignment.
+
+Return value:
+  ArrayOfStructureAlignment
+
+Example:
+  mol = bget("-f m cpd:C00111")
+  search_compounds_by_subcomp(mol, 1, 5)
+
+Related site:
+  * ((<URL:http://www.genome.jp/ligand-bin/search_compound>))
+
+--- search_drugs_by_subcomp(string:mol, int:offset, int:limit)
+
+Returns a list of drugs with the alignment having common sub-structure
+calculated by the subcomp program.
+
+You can obtain a MOL formatted structural data of matched drugs
+using bget method with the "-f m" option to confirm the alignment.
+
+Return value:
+  ArrayOfStructureAlignment
+
+Example:
+  mol = bget("-f m dr:D00201")
+  search_drugs_by_subcomp(mol, 1, 5)
+
+Related site:
+  * ((<URL:http://www.genome.jp/ligand-bin/search_compound>))
+
+--- search_glycans_by_kcam(string:kcf, string:program, string:option, int:offset, int:limit)
+
+Returns a list of glycans with the alignment having common sub-structure
+calculated by the KCaM program.
+
+The argument 'program' can be 'gapped' or 'ungaped'.
+The next argument 'option' can be 'global' or 'local'.
+
+You can obtain a KCF formatted structural data of matched glycans
+using bget method with the "-f k" option to confirm the alignment.
+
+Return value:
+  ArrayOfStructureAlignment
+
+Example:
+  kcf = bget("-f k gl:G12922")
+  search_glycans_by_kcam(kcf, "gapped", "local", 1, 5)
+
+Related site:
+  * ((<URL:http://www.genome.jp/ligand-bin/search_glycan.cgi>))
+  * ((<URL:http://www.genome.jp/ligand/kcam/>))
+
+== Notes
+
+Last updated: December 27, 2006
+
+=end
+