bio 1.4.3.0001 → 1.5.0

data/doc/KEGG_API.rd

@@ -1,1843 +0,0 @@
-=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
-