=begin

   $Id: KEGG_API.rd.ja,v 1.11 2006/12/27 13:40:45 k Exp $

       Copyright (C) 2003-2006 Toshiaki Katayama <k@bioruby.org>

= KEGG API

KEGG API はプログラムなどから KEGG を利用するためのウェブサービスです。
前半では、KEGG データベースから情報を取得したり検索したりするために 
KEGG API を使う方法を説明します。後半のリファレンスで KEGG API の全機能を
解説します。例として主に Ruby 言語を使って解説しますが、SOAP と WSDL を
扱うことのできる言語（Perl, Python, Java など）であれば簡単に KEGG API を
利用することができます。

== 目次

* ((<イントロダクション>))
* ((<KEGG API の使い方>))
  * ((<Ruby の場合>))
  * ((<Perl の場合>))
    * ((<Perl の注意点>))
  * ((<Python の場合>))
  * ((<Java の場合>))
* ((<KEGG API リファレンス>))
  * ((<WSDL ファイル>))
  * ((<用語の凡例>))
  * ((<戻り値のデータ型>))
    * ((<SSDBRelation 型>)), ((<ArrayOfSSDBRelation 型>))
    * ((<MotifResult 型>)), ((<ArrayOfMotifResult 型>))
    * ((<Definition 型>)), ((<ArrayOfDefinition 型>))
    * ((<LinkDBRelation 型>)), ((<ArrayOfLinkDBRelation 型>))
    * ((<PathwayElement 型>)), ((<ArrayOfPathwayElement 型>))
    * ((<PathwayElementRelation 型>)), ((<ArrayOfPathwayElementRelation 型>))
      * ((<Subtype 型>)), ((<ArrayOfSubtype 型>))
    * ((<StructureAlignment 型>)), ((<ArrayOfStructureAlignment 型>))
  * ((<メソッド一覧>))
    * ((<メタ情報>))
      * ((<list_databases>))
      * ((<list_organisms>))
      * ((<list_pathways>))
    * ((<DBGET>))
      * ((<binfo>))
      * ((<bfind>))
      * ((<bget>))
      * ((<btit>))
      * ((<bconv>))
    * ((<LinkDB>))
      * ((<データベース間のリンク>))
        * ((<get_linkdb_by_entry>))
        * ((<get_linkdb_between_databases>))
      * ((<遺伝子と酵素番号の関係>))
        * ((<get_genes_by_enzyme>))
        * ((<get_enzymes_by_gene>))
      * ((<酵素、化合物、リアクションの関係>))
        * ((<get_enzymes_by_compound>))
        * ((<get_enzymes_by_glycan>))
        * ((<get_enzymes_by_reaction>))
        * ((<get_compounds_by_enzyme>))
        * ((<get_compounds_by_reaction>))
        * ((<get_glycans_by_enzyme>))
        * ((<get_glycans_by_reaction>))
        * ((<get_reactions_by_enzyme>))
        * ((<get_reactions_by_compound>))
        * ((<get_reactions_by_glycan>))
    * ((<SSDB>))
      * ((<get_best_best_neighbors_by_gene>))
      * ((<get_best_neighbors_by_gene>))
      * ((<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>))
      * ((<パスウェイへの色づけ>))
        * ((<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>))
      * ((<パスウェイ上のオブジェクト間の関係>))
        * ((<get_element_relations_by_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>))
      * ((<オブジェクトからパスウェイ検索>))
        * ((<get_pathways_by_genes>))
        * ((<get_pathways_by_enzymes>))
        * ((<get_pathways_by_compounds>))
        * ((<get_pathways_by_glycans>))
        * ((<get_pathways_by_reactions>))
        * ((<get_pathways_by_kos>))
      * ((<パスウェイ間の関係>))
        * ((<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>))

== イントロダクション

ウェブサービスとは、クライアントからの要求をインターネットを介してサーバに
送り、サーバがプログラムの実行結果をクライアントに返す仕組みで、一般的には
ウェブページで使われる HTTP プロトコルと、構造を持つデータの表現方法として
普及している XML マークアップ文書形式を用いたものを指します。

ウェブサービスはプログラムから利用できるため、定期的に検索を行ったり、
少しずつ値を変えた様々な要求を自動的に処理したりするのに向いています。
このため、株価や天気情報の問い合わせ、Google への複合検索などでも使われて
います。

HTTP を用いるメリットには、誰でも使えることやファイアウォールなどの制限を
受けにくいことがあり、XML の方には関連技術が揃っていることや複雑なデータ
構造を表現できるといったポイントがあります。

ウェブサービスでは XML 関連技術の中でも SOAP と WSDL を使うことが多くなって
います。SOAP はクライアントとサーバがやりとりするメッセージの表現方法を
標準化したもので、以前は Simple Object Access Method の略とされていました
(今は Service Oriented Access Protocol ということもあるようです)。
WSDL は SOAP に基づくサービスをコンピュータが簡単に利用できるようにする
ためのもので、Web Service Description Language の略となっています。

KEGG API はこれらの技術を使って、自分の興味ある遺伝子やパスウェイなどの
情報を自由に検索したり解析に用いたりするための手段を提供します。ユーザは
KEGG の多くの機能を、ウェブページをクリックする代わりに自分のプログラムの
中から次々と実行することができるようになります。

KEGG API に関する最新の情報は以下の URL から得ることができます。

  * ((<URL:http://www.genome.jp/kegg/soap/>))

== KEGG API の使い方

以下では Ruby, Perl, Python, Java の各言語による KEGG API の簡単な使い方を
紹介します。各言語で SOAP と WSDL を扱えるライブラリを追加インストールする
必要があります。

=== Ruby の場合

Ruby 1.8.1 以降では、標準で SOAP を使う事ができますので追加インストー
ルは必要ありません。

Ruby 1.8.0 では
((<SOAP4R|URL:http://raa.ruby-lang.org/list.rhtml?name=soap4r>)),
((<devel-logger|URL:http://raa.ruby-lang.org/list.rhtml?name=devel-logger>)),
((<http-access2|URL:http://raa.ruby-lang.org/list.rhtml?name=http-access2>))
などのライブラリをインストールする必要があります。

Ruby 1.6.8 の場合はさらに SOAP4R が必要とする他のライブラリ (date2, uconv,
XML のパーザなど) もインストールする必要がありますので、あらかじめ SOAP4R
のドキュメントに従って入れておきます。

以下のサンプルコードは、大腸菌の b0002 遺伝子と最も相同性の高い遺伝子
を、Smith-Waterman スコアの高い順に 5 個検索して表示するプログラムです。

  #!/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	# SOAP と Ruby の型変換を有効にする
  
  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

プログラムの中で 'get_best_neighbors_by_gene' は、KEGG の SSDB データ
ベースを使って KEGG の GENES に含まれている各生物種の中から最も相同性
の高い遺伝子を探してくる API です。結果は次のように表示されます。

  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

うまく動かない場合は、

  serv = SOAP::WSDLDriverFactory.new(wsdl).create_rpc_driver
  serv.wiredump_dev = STDERR	# ←この行を書き足す
  serv.generate_explicit_type = true

のように wiredump_dev に STDERR を指定した行を追加して実行することで、
サーバとのやり取りが標準エラーに出力されます。

KEGG API v3.0 から、サーバの負担を軽くしたりタイムアウトを防ぐ目的で、
大量の結果を返すメソッドには offset, limit 引数が導入され、一度に
得られる結果の数が制限されるようになりました（KEGG API v3.0〜v5.0 では
それぞれ start, max_results と呼ばれていましたが、KEGG API v6.0 で
offset, 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

WSDL を用いているため、これらの例でも Ruby の場合は十分に簡単に書けま
すが、((<BioRuby|URL:http://bioruby.org/>)) を使うとさらにスッキリ書く
ことができます。

  #!/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

BioRuby では 'get_all_best_neighbors_by_gene' メソッドが定義されており、
自動で上記の例のループを回して全ての結果を返してくれます。また、取り出
したい名前のリストを渡すと対応する値を配列で返してくれる filter メソッ
ドを使うこともできます。

  #!/usr/bin/env ruby
  
  require 'bio'
  
  serv = Bio::KEGG::API.new
  
  results = serv.get_all_best_neighbors_by_gene('eco:b0002')
  
  # 欲しい値が遺伝子名のペアと SW スコアだけの場合の例
  fields = [:genes_id1, :genes_id2, :sw_score]
  results.each do |hit|
    puts hit.filter(fields).join("\t")
  end
  
  # それぞれの遺伝子でアライメントされたポジションなども表示させる例
  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

次は、大腸菌 (eco) に対する KEGG パスウェイの一覧を返す例です。

  #!/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

ArrayOfDefinition 型が返されるので、それぞれについて Definition 型の要
素 entry_id (パスウェイのID) と definition (パスウェイのタイトル) を取
り出します（先の SSDB の例も、実は SSDBRelation 型の要素 genes_id1 や
sw_score などを取り出していたのでした）。

最後の例は、大腸菌の遺伝子 b1002 と b2388 に対応するボックスに色を付け
たパスウェイ eco00010 の画像を生成して、ファイルに保存する例です。

  #!/usr/bin/env ruby
  
  require 'bio'
  
  serv = Bio::KEGG::API.new
  
  genes = ["eco:b1002", "eco:b2388"]
  url = serv.mark_pathway_by_objects("path:eco00010", genes)
  
  puts url

  # BioRuby の場合、画像を取得して保存するのに save_image メソッドが使える
  serv.save_image(url, "filename.gif")

=== Perl の場合

Perl では、以下のライブラリを追加インストールしておく必要があります。

  * ((<SOAP::Lite|URL://www.soaplite.com/>)) (Ver. 0.60 で動作確認)
    * 注：現在 0.60 より新しいバージョンではいくつかのメソッドが使えないようです
  * ((<MIME-Base64|URL:http://search.cpan.org/author/GAAS/MIME-Base64/>))
  * ((<libwww-perl|URL:http://search.cpan.org/author/GAAS/libwww-perl/>))
  * ((<URI|URL:http://search.cpan.org/author/GAAS/URI/>))

以下、Ruby の最初の例と同じ処理を実行するサンプルコードです。

  #!/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";
  }

同じく、大腸菌の KEGG パスウェイのリストを返す例です。

  #!/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";
  }

SOAP::Lite では引数に配列を渡す時には、

  SOAP::Data->type(array => [value1, value2, .. ])

のように変換する必要があるので注意が必要です。たとえばパスウェイへの色
づけで遺伝子のリストを渡す場合は、

  #!/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;

のようになります。

=== Perl の注意点

KEGG API には文字列や数値の配列を引数に取るメソッドがいくつかありますが、
利用する SOAP::Lite のバージョンに応じて、必ず以下のどちらかの対処が必要です。

==== SOAP::Lite v0.60 まで

Perl の配列 (array) オブジェクトを引数として KEGG API に渡す場合は、
必ず以下のように SOAP オブジェクトに明示的に変換する必要があります。

  SOAP::Data->type(array => [value1, value2, ... ])

==== SOAP::Lite v0.61 以降

SOAP::Lite v0.68 まではバグがありますので v0.69 以降の利用をお勧めします。

Perl の文字列 (string) や数値 (int) の配列 (array) オブジェクトを
ArrayOfstring や ArrayOfint 型の SOAP オブジェクトに変換する
サブルーチンを自前で追加する必要があります。

  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];
  }

また、スクリプト中にこの定義を書いておくことで、

  $genes = SOAP::Data->type(array => ["eco:b1002", "eco:b2388"]);

ではなく

  $genes = ["eco:b1002", "eco:b2388"];

のように省略して書くことができるようになります（省略しなくても構いません）。

==== テストプログラム

SOAP::Lite v0.69 で ArrayOfstring の変換がうまく働いているかどうかは
以下のプログラムでテストできます。画像の URL が表示されれば OK です。

  #!/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 $result = $serv->mark_pathway_by_objects("map: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];
  }

=== Python の場合

Python では以下のライブラリを追加インストールしておく必要があります。

  * ((<SOAPpy|URL:http://pywebsvcs.sourceforge.net/>))

また、SOAPpy が依存しているいくつかのパッケージ (fpconst, PyXML など) も
必要になります。

以下、KEGG/PATHWAY の 00020 番のパスウェイに載っている大腸菌の遺伝子を
リストで返すサンプルコードです。

  #!/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

=== Java の場合

Java では Apache Axis ライブラリの axis-1.2alpha より新しいバージョン
(axis-1_1 ではうまく動きません）を入手して、必要な jar ファイルを適切
なディレクトリに置いておく必要があります。

  * ((<Apache Axis|URL:http://ws.apache.org/axis/>))

たとえば Apache Axis バージョン axis-1_2beta のバイナリ配布の場合、
axis-1_2beta/lib 以下にある jar ファイルをインストール先のディレクト
リにコピーします。

  % cp axis-1_2beta/lib/* /path/to/lib/

以下のように実行して WSDL から KEGG API 用のクラスを自動生成します。
また、生成されたファイルの不具合を直すために、
((<axisfix.pl|URL:http://www.genome.jp/kegg/soap/support/axisfix.pl>))
スクリプトを入手しておきます。

  % 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

javadoc の英語版が必要な場合は javadoc に -locale en_US オプションを
つけて実行します。

以下は、Python の例と同様に、指定した KEGG/PATHWAY に載っている遺伝子の
リストを表示するサンプルコードです。

  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]);
                  }
          }
  }

次は、SSDBRelation 型の配列が戻ってくる例です。

  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);
                  }
          }
  }

このプログラムは以下のように -classpath オプションに keggapi.jar ファ
イルも加えてコンパイル、実行します。

  % 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

環境変数 CLASSPATH を指定しておくと、長いオプションを毎回書く必要がな
くなります。

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

他の戻り値と型ごとの値の取り出し方などについては、WSDL2Java により生成
された以下のドキュメントを参照してください。

  * ((<URL:http://www.genome.jp/kegg/soap/doc/keggapi_javadoc_ja/>))

== KEGG API リファレンス

以下では、KEGG API を使うのに必要な情報と全てのメソッドを解説します。

=== WSDL ファイル

SOAP では、サーバがどのようなメソッドを持っているか知っておく必要が
ありますが、WSDL を使うとこの手順を自動化できます。WSDL ファイルを
取得してクライアントドライバを生成するところまで、通常は SOAP/WSDL の
ライブラリが処理してくれるはずです。KEGG API の WSDL ファイルは以下の
URL にあります。

  * ((<URL:http://soap.genome.jp/KEGG.wsdl>))

=== 用語の凡例

以下の解説で出てくる KEGG 関連用語の説明をしておきます。

  * org は KEGG に含まれている生物種をそれぞれ３文字コードで
    表記したもので、eco が大腸菌、sce が出芽酵母などとなっています。
    ３文字コードのリストは list_organisms メソッドや以下のページを
    参照してください。

    * ((<URL:http://www.genome.jp/kegg/catalog/org_list.html>))

  * db は GenomeNet で提供されているデータベース名です。データベース名の
    リストについては list_databases メソッドを参照してください。

  * entry_id は db_name とエントリ名を ':' で結合した全てのデータベース間で
    ユニークな ID です。たとえば embl:J00231 で EMBL のエントリ J00231 を
    指します。entry_id は、以下の genes_id, enzyme_id, compound_id,
    drug_id, glycan_id, reaction_id, pathway_id, motif_id などを含みます。

  * genes_id は keggorg と遺伝子名を ':' で結合した KEGG の遺伝子 ID です。
    eco:b0001 は大腸菌の遺伝子 b0001 を指します。

  * enzyme_id は ec: をつけた酵素番号の ID です。ec:1.1.1.1 は酵素番号
    1.1.1.1 の酵素であるアルコール・デヒドロゲナーゼを指します。

  * compound_id は cpd: をつけた化合物の ID です。cpd:C00158 は化合物番号
    C00158 の化合物であるクエン酸を指します。

  * drug_id は dr: をつけた化合物の ID です。dr:D00201 はドラッグ番号
    D00201 のドラッグであるテトラサイクリンを指します。

  * glycan_id は gl: をつけた化合物の ID です。gl:G00050 は糖鎖番号
    G00050 の糖鎖である Paragloboside を指します。

  * reaction_id は REACTION データベースのエントリ番号で、rn:R00959 は
    リアクション番号 R00959 の反応 (cpd:C00103 と cpd:00668 間の変換) を
    指します。

  * pathway_id は KEGG/PATHWAY データベースのパスウェイ番号で、パスウェイ
    番号のプレフィックスが map の場合はリファレンスパスウェイを、keggorg の
    場合はその生物種の持つ遺伝子の載ったパスウェイを表します。例えば
    path:map00020 はリファレンスパスウェイの 00020 番を、path:eco00020 は
    大腸菌のパスウェイ 00020 番を指します。

  * motif_id はモチーフデータベースのエントリ名で、pf:DnaJ で Pfam のエントリ
    DnaJ を指します。'pf' の他、'ps' で PROSITE, 'bl' で BLOCS, 'pr' で
    PRINTS, 'pd' で PRODOM を指します。

  * ko_id は KO (KEGG Orthology) データベースのエントリ番号で、ko:K02598
    は KO 番号 K02598 の nitrite transporter NirC のオーソロガスな遺伝子
    グループを指します。

  * ko_class_id は KO を階層的に分類した各階層（クラス）の ID で、
    '01110' は Carbohydrate Metabolism クラスになります。
    KO クラスや KO 番号のリストは以下のページを参照してください。

    * ((<URL:http://www.genome.jp/dbget-bin/get_htext?KO>))

  * offset, limit は一度に返ってくる結果の数を指定するオプションで、
    offset 番目から limit 個の結果を受け取ります。全ての結果を得るには
    offset = offset + limit として空の配列が返ってくるまで繰り返し
    メソッドを呼びます。

  * fg_color_list はパスウェイへの色づけでオブジェクトごとに文字や枠線の
    色を指定する配列です。

  * fg_color_list はパスウェイへの色づけでオブジェクトごとに背景の
    色を指定する配列です。

関連 URL：
  * ((<URL:http://www.genome.jp/kegg/kegg3.html>))

=== 戻り値のデータ型

KEGG API のメソッドは文字列など単純な値を返すものだけでなく、複雑なデータ
構造を持った値を返す場合もあり、そのためのデータ型が定義されています。
API のメソッドによる（検索などの）結果がなかった場合、型によって以下の
戻り値が返されます。
  * 空の配列 -- もともと ArrayOfOBJ （オブジェクトの配列）を返すメソッドの場合
  * 空の文字列 -- もともと String （文字列）を返すメソッドの場合
  * -1 -- もともと int （数値）を返すメソッドの場合
  * NULL -- もともと以下で定義されたオブジェクトのどれかを返すメソッドの場合

+ SSDBRelation 型

SSDB データベースの各フィールドに対応する値が入ったデータ型です。

  genes_id1         クエリーの genes_id (string)
  genes_id2         ターゲットの genes_id (string)
  sw_score          genes_id1 と genes_id2 間の Smith-Waterman スコア (int)
  bit_score         genes_id1 と genes_id2 間の bit スコア (float)
  identity          genes_id1 と genes_id2 間の アイデンティティ (float)
  overlap           genes_id1 と genes_id2 のオーバーラップ領域の長さ (int)
  start_position1   genes_id1 のアライメントの開始残基位置 (int)
  end_position1     genes_id1 のアライメントの終端残基位置 (int)
  start_position2   genes_id2 のアライメントの開始残基位置 (int)
  end_position2     genes_id2 のアライメントの終端残基位置 (int)
  best_flag_1to2    genes_id1 から見て genes_id2 がベストヒットか (boolean)
  best_flag_2to1    genes_id2 から見て genes_id1 がベストヒットか (boolean)
  definition1       genes_id1 のデフィニション文字列 (string)
  definition2       genes_id2 のデフィニション文字列 (string)
  length1           genes_id1 のアミノ酸配列の長さ (int)
  length2           genes_id2 のアミノ酸配列の長さ (int)

+ ArrayOfSSDBRelation 型

複数の SSDBRelation 型データを含む配列です。

+ MotifResult 型

  motif_id          モチーフデータベースのエントリ ID (string)
  definition        モチーフのデフィニション (string)
  genes_id          モチーフを持っている遺伝子の genes_id (string)
  start_position    モチーフの開始残基位置 (int)
  end_position      モチーフの終了残基位置 (int)
  score             モチーフ (PROSITE Profile, TIGRFAM) のスコア (float)
  evalue            モチーフ (Pfam) の E-value (double)

注：score と evalue のうち、対応する値が無いものについては -1 を返します。

+ ArrayOfMotifResult 型

複数の MotifResult 型データを含む配列です。

+ Definition 型

  entry_id          データベースエントリーのID (string)
  definition        エントリーのデフィニション情報 (string)

+ ArrayOfDefinition 型

複数の Definitioin 型データを含む配列です。

+ LinkDBRelation 型

  entry_id1         データベースのエントリ ID (string)
  entry_id2         データベースのエントリ ID (string)
  type              "direct" または "indirect" のリンクの種類 (string)
  path              リンクの経路 (string)

+ ArrayOfLinkDBRelation 型

複数の LinkDBRelation 型データを含む配列です。

+ PathwayElement 型

パスウェイ上に描かれている個々の箱や丸などのオブジェクトを表すデータ型です。

  element_id        パスウェイ上のオブジェクトを指すユニークな ID (int)
  type              オブジェクトの種類 ("gene", "enzyme" など) (string)
  names             オブジェクトにつけられた名前のリスト (ArrayOfstring)
  components        グループの場合など含まれるオブジェクトのリスト (ArrayOfint)

+ ArrayOfPathwayElement 型

複数の PathwayElement 型データを含む配列です。

+ PathwayElementRelation 型

PathwayElement 間の関係を表すデータ型です。

  element_id1       パスウェイ上のオブジェクトを指すユニークな ID (int)
  element_id2       パスウェイ上のオブジェクトを指すユニークな ID (int)
  type              関係の種類 ("ECrel", "maplink" など) (string)
  subtypes          関係に関わるオブジェクトの配列 (ArrayOfSubtype)

+ ArrayOfPathwayElementRelation 型

複数の PathwayElementRelation 型データを含む配列です。

++ Subtype 型

PathwayElementRelation 型の中で使われる子要素で、PathwayElement 間を
関係づけるオブジェクト（化合物など）を表すデータ型です。

  element_id        パスウェイ上のオブジェクトを指すユニークな ID (int)
  relation          関係の種別 ("compound", "inhibition" など) (string)
  type              関係の記号 ("+p", "--|" など) (string)

++ ArrayOfSubtype 型

複数の PathwayElementRelation 型データを含む配列です。

+ StructureAlignment 型

ユーザの指定した化学構造とデータベース中の構造を比較した時の
アラインメントのスコアと対応するノード（元素）のリストを表す
データ型です。

  target_id         構造比較対象のエントリ ID (string)
  score             構造比較のスコア (float)
  query_nodes       入力構造中でアラインメントされたノード番号 (ArrayOfint)
  target_nodes      対象構造中で対応するノード番号 (ArrayOfint)

+ ArrayOfStructureAlignment 型

複数の StructureAlignment 型データを含む配列です。

=== メソッド一覧

以下、KEGG API の全メソッドのリストです。メソッドにはメタ情報を返すものと
各データベースに対するものがあります。現在、KEGG にあるデータベースのうち
KEGG API の対象となっているものは SSDB, PATHWAY, GENES, LIGAND です。これ
以外のデータベースへの対応やメソッドの追加も順次おこなう予定です。

以下の例では、引数などが Ruby 言語の表記に倣って書かれていますが、実際の
引数（特にリストの渡し方など）は使用する言語によって異なる可能性があります。

==== メタ情報

最新のデータベース情報などを返すためのメソッドです。

--- list_databases

KEGG を提供しているゲノムネットで現在利用できるデータベースの一覧を返します。

戻値：
  ArrayOfDefinition (db, definition)

関連 URL：
  * ((<URL:http://www.genome.jp/dbget/>))
  * ((<URL:http://www.genome.jp/about_genomenet/service.html>)) (section 2.2)

--- list_organisms

現在 KEGG に含まれている生物種 (org) のリストを返します。

戻値：
  ArrayOfDefinition (org, definition)

関連 URL：
  * ((<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)

現在 KEGG に含まれている指定した生物のパスウェイのリストを返します。引数に
'map' という文字列を与えるとリファレンスパスウェイのリストを返します。

戻値：
  ArrayOfDefinition (pathway_id, definition)

関連 URL：
  * ((<URL:http://www.genome.jp/kegg/pathway.html>))

==== DBGET

DBGET システムに対するメソッドの一覧です。DBGET について詳しくは以下の
ページを参照してください。

関連 URL：
  * ((<URL:http://www.genome.jp/dbget/dbget_manual.html>))
  * ((<URL:http://www.genome.jp/dbget-bin/binfo>))

--- binfo(string:db)

指定したデータベースのエントリ数や更新日など詳しい最新情報を返します。
'all' を渡すと利用可能な全てのデータベースの情報を返します。
binfo コマンドへの引数を文字列で渡します。

戻値：
  string

例：
  # GenBank データベースの最新情報
  binfo('gb')
  # 全てのデータベースの最新情報
  binfo('all')

--- bfind(string:str)

DBGET の bfind コマンドへのラッパーです。キーワードによりエントリを
検索することができます。一度に与えられるキーワードの数は 100 個以下に
制限されています。

戻値：
  string

例：
  # デフィニションに E-cadherin と human を持つ GenBank のエントリを検索
  bfind("gb E-cadherin human")


--- bget(string:str)

指定した entry_id のエントリを返します。GENES の遺伝子エントリをはじめ、
ゲノムネットの DBGET システムで提供されている様々なデータベース
(list_databases を参照) のエントリを全て取得できます。bget コマンドへの
コマンドラインオプションを文字列で渡します。一度に取得できるエントリの
数は 100 個以下に制限されています。

戻値：
  string

例：
  # 複数のエントリを取得
  bget("eco:b0002 bsu:BG10065 cpd:C00209")
  # FASTA フォーマットのアミノ酸配列を取得
  bget("-f -n a eco:b0002 bsu:BG10065")
  # FASTA フォーマットの塩基配列を取得
  bget("-f -n n eco:b0002 hin:tRNA-Cys-1")

--- btit(string:str)

DBGET の btit コマンドへのラッパーです。指定したエントリの ID に対応す
るデフィニションを返します。一度に与えられるエントリの数は 100 個以下に
制限されています。

戻値：
  string

例：
  # これら４つの遺伝子のデフィニションを検索
  btit("hsa:1798 mmu:13478 dme:CG5287-PA cel:Y60A3A.14")

--- bconv(string:str)

外部データベースの ID を KEGG の ID に変換します。
結果は、１行毎に問い合わせ ID と変換 ID のタブ切り文字列として返されます。
現在、以下の外部データベースに対応しています。

  外部データベース  データベース名の prefix
  ----------------  -----------------------
  NCBI GI           ncbi-gi:
  NCBI GeneID       ncbi-geneid:
  GenBank           genbank:
  UniGene           unigene:
  UniProt           uniprot:
  OMIM              omim:

たとえば UniProt ID は、すでに KEGG GENES に記載されている UniProt
へのリンクの他、EBI の Genome Reviews に記載されている UniProt ID
とローカスタグ ID の対応を用いて、NCBI と共通のローカスタグ ID と
KEGG GENES の対応表をもとに変換されています。

戻値：
  string

例：
  # NCBI GI と Gene ID を KEGG genes_id に変換
  serv.bconv("ncbi-gi:10047086 ncbi-gi:10047090 ncbi-geneid:14751")

関連 URL：
  * ((<URL:http://www.genome.jp/kegg/genes.html>)) (Gene name conversion)

==== LinkDB

+ データベース間のリンク

--- get_linkdb_by_entry(string:entry_id, string:db, int:offset, int:limit)

指定した entry_id から直接または間接的にリンクされているエントリの経路を、
db で指定したデータベースにたどれるまで検索します。

戻値：
  ArrayOfLinkDBRelation

例：
  # E. coli の遺伝子 b0002 からリンクのたどれる KEGG/PATHWAY のエントリを検索
  get_linkdb_by_entry('eco:b0002', 'pathway', 1, 10)
  get_linkdb_by_entry('eco:b0002', 'pathway', 11, 10)

関連 URL：
  * ((<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)

指定した２つのデータベースで、エントリ間のリンクを全て検索します。

戻値：
  ArrayOfLinkDBRelation

例：
  # 大腸菌の KEGG GENES と KEGG PATHWAY の間のリンクを全て検索
  get_linkdb_between_databases("eco", "pathway", 1, 100)

  # Ruby で取得したリンクの中を表示する例
  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

関連 URL：
  * ((<URL:http://www.genome.jp/dbget-bin/www_linkdb>)) (Database to database)

+ 遺伝子と酵素番号の関係

--- get_genes_by_enzyme(string:enzyme_id, string:org)

対象生物種において、指定した酵素番号を持つ遺伝子のリストを返します。

戻値：
  ArrayOfstring (genes_id)

例：
  # 酵素番号 1.1.1.1 を持つ大腸菌の遺伝子のリスト
  get_genes_by_enzyme('ec:1.1.1.1', 'eco')

--- get_enzymes_by_gene(string:genes_id)

指定した遺伝子に対応する酵素番号のリストを返します。

戻値：
  ArrayOfstring (enzyme_id)

例：
  # 大腸菌遺伝子 'eco:b0002' の酵素番号のリスト
  get_enzymes_by_gene(eco:b0002)

+ 酵素、化合物、リアクションの関係

--- get_enzymes_by_compound(string:compound_id)

指定した化合物に対応する酵素番号のリストを返します。

戻値：
  ArrayOfstring (compound_id)

例：
  # 化合物 'cpd:C00345' の代謝に関わる酵素のリスト
  get_enzymes_by_compound('cpd:C00345')

--- get_enzymes_by_glycan(string:compound_id)

指定した糖鎖に対応する酵素番号のリストを返します。

戻値：
  ArrayOfstring (glycan_id)

例：
  # 糖鎖 'gl:G00001' の代謝に関わる酵素のリスト
  get_enzymes_by_glycan('gl:G00001')

--- get_enzymes_by_reaction(string:reaction_id)

指定したリアクション番号に対応する酵素番号のリストを返します。

戻値：
  ArrayOfstring (reaction_id)

例：
  # リアクション番号 R00100 を持つ酵素のリスト
  get_enzymes_by_reaction('rn:R00100')

--- get_compounds_by_enzyme(string:enzyme_id)

指定した酵素番号に対応する化合物のリストを返します。

戻値：
  ArrayOfstring (compound_id)

例：
  # 酵素番号 'ec:2.7.1.12' の代謝に関わる化合物のリスト
  get_compounds_by_enzyme('ec:2.7.1.12')

--- get_compounds_by_reaction(string:reaction_id)

指定したリアクションに対応する化合物のリストを返します。

戻値：
  ArrayOfstring (compound_id)

例：
  # リアクション番号 'rn:R00100' の反応に関わる化合物のリスト
  get_compounds_by_reaction('rn:R00100')

--- get_glycans_by_enzyme(string:enzyme_id)

指定した酵素番号に対応する糖鎖のリストを返します。

戻値：
  ArrayOfstring (glycan_id)

例：
  # 酵素番号 'ec:2.4.1.141' の代謝に関わる糖鎖のリスト
  get_glycans_by_enzyme('ec:2.4.1.141')

--- get_glycans_by_reaction(string:reaction_id)

指定したリアクションに対応する糖鎖のリストを返します。

戻値：
  ArrayOfstring (glycan_id)

例：
  # リアクション番号 'rn:R06164' の反応に関わる糖鎖のリスト
  get_glycans_by_reaction('rn:R06164')

--- get_reactions_by_enzyme(string:enzyme_id)

指定した酵素番号に対応するリアクションのリストを返します。

戻値：
  ArrayOfstring (reaction_id)

例：
  # 酵素番号 'ec:2.7.1.12' の反応に関わるリアクション番号のリスト
  get_reactions_by_enzyme('ec:2.7.1.12')

--- get_reactions_by_compound(string:compound_id)

指定した化合物に対応するリアクションのリストを返します。

戻値：
  ArrayOfstring (reaction_id)

例：
  # 化合物 'cpd:C00199' の触媒反応に関わるリアクション番号のリスト
  get_reactions_by_compound('cpd:C00199')

--- get_reactions_by_glycan(string:glycan_id)

指定した糖鎖に対応するリアクションのリストを返します。

戻値：
  ArrayOfstring (reaction_id)

例：
  # 糖鎖 'gl:G00001' の触媒反応に関わるリアクション番号のリスト
  get_reactions_by_glycan('gl:G00001')

==== SSDB

SSDB データベースに対するメソッドの一覧です。SSDB は KEGG/GENES に含まれる
全生物種・全遺伝子間で ssearch を用いた Smith-Waterman アルゴリズムに
よる検索を行った結果と、全遺伝子のモチーフ検索結果を登録したデータベースで、
時間のかかる計算があらかじめ終わっているため高速な検索が可能になっています。

KEGG がゲノム配列の決まった生物種を中心に対象としていることと、Smith-
Waterman スコアによる比較ができることからオーソログやパラログ関係にある
遺伝子の探索や生物種固有の遺伝子の検索をはじめ様々な応用が考えられます。

SSDB データベースについて詳しくは以下のページを参照してください。

  * ((<URL:http://www.genome.jp/kegg/ssdb/>))

  
--- get_best_best_neighbors_by_gene(string:genes_id, int:offset, int:limit)

クエリとターゲットが best-best の関係にある遺伝子だけを検索します。

戻値：
  ArrayOfSSDBRelation

例：
  # 大腸菌の遺伝子 b0002 から全生物種で best-best の関係にある遺伝子
  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)

クエリから見てベストヒットの関係にある遺伝子だけを検索します。

戻値：
  ArrayOfSSDBRelation

例：
  # 大腸菌の遺伝子 b0002 から全生物種で best neighbor の関係にある遺伝子
  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)

ターゲット側の生物種から見てクエリがベストヒットとなる遺伝子を検索します。

戻値：
  ArrayOfSSDBRelation

例：
  # 大腸菌の遺伝子 b0002 が reverse best neighbor の関係にある遺伝子
  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)

クエリと同じ生物種内でパラログ遺伝子を検索します。

戻値：
  ArrayOfSSDBRelation

例：
  # 大腸菌の遺伝子 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)

指定した遺伝子に存在するモチーフのリストを返します。モチーフデータベース
のリストには、Pfam (pfam), TIGRFAM (tfam), PROSITE pattern (pspt), PROSITE
profile (pspf) またはこれら全て (all) を指定出来ます。

戻値：
  ArrayOfMotifResult

例：
  # 大腸菌の遺伝子 b0002 持つPfamモチーフのリスト
  get_motifs_by_gene('eco:b0002', 'pfam')

--- get_genes_by_motifs([string]:motif_id_list, int:offset, int:limit)

指定したモチーフを全て持つ遺伝子を検索します。

戻値：
  ArrayOfDefinition (genes_id, definition)

例：
  # Pfam の DnaJ と Prosite の DNAJ_2 にヒットする遺伝子を検索
  list = ['pf:DnaJ', 'ps:DNAJ_2']
  get_genes_by_motifs(list, 1, 10)
  get_genes_by_motifs(list, 11, 10)

==== KO

KO (KEGG orthology), OC (KEGG ortholog cluster), PC (KEGG paralog cluster) の
情報を得るためのメソッドです。KO はキュレーションされたオーソログ遺伝子群、
OC と PC は機械的にクラスタリングされた相同性のある遺伝子群のデータベースです。

--- get_ko_by_gene(string:genes_id)

指定した遺伝子にアサインされている KO のエントリ番号を全て返します。

戻値：
  ArrayOfstring (ko_id)

例：
  # eco:b0002 遺伝子にアサインされている KO のリスト
  get_ko_by_gene('eco:b0002')


--- get_ko_by_ko_class(string:ko_class_id)

指定した ko_class_id に含まれる ko_id のリストを返します。

戻値：
  ArrayOfDefinition (ko_id)

例：
  # KO class '01196' に含まれる KO のリスト
  get_ko_by_ko_class('01196')

--- get_genes_by_ko_class(string:ko_class_id, string:org, int:offset, int:limit)

指定した生物種の ko_class_id に含まれる遺伝子のリストを返します。

 戻値：
  ArrayOfDefinition (genes_id, definition)

例：
  # KO クラス '00930' に含まれるヒト遺伝子のリスト
  get_genes_by_ko_class('00903', 'hsa' , 1, 100)

--- get_genes_by_ko(string:ko_id, string:org)

指定した生物種の ko_id に含まれる遺伝子のリストを返します。
生物種コードに all を指定すると全生物種の遺伝子を返します。

戻値：
  ArrayOfDefinition (genes_id, definition)

例：
  # KO 番号 'K00001' に含まれる大腸菌遺伝子のリスト
  get_genes_by_ko('ko:K00010', 'eco')

  # KO 番号 'K00010' に含まれる全生物種の遺伝子リスト
  get_genes_by_ko('ko:K00010', 'all')



==== PATHWAY

PATHWAY データベースに対するメソッドの一覧です。PATHWAY データベースに
ついて詳しくは以下のページを参照してください。

  * ((<URL:http://www.genome.jp/kegg/kegg2.html#pathway>))

+ パスウェイへの色づけ

関連 URL：
  * ((<URL:http://www.genome.jp/kegg/tool/color_pathway.html>))

--- mark_pathway_by_objects(string:pathway_id, [string]:object_id_list)

指定した生物種で、与えられたパスウェイマップの与えられたオブジェクト
（遺伝子、化合物、酵素番号）の対応する枠に色をつけた画像を生成、
画像の URL を返します。

戻値：
  string (URL)

例：
  # 大腸菌のパスウェイ path:eco00260 上の遺伝子 eco:b0002 と Homoserine
  # の cpd:C00263 に対応するボックスを赤く着色した画像の URL
  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)

指定したパスウェイの与えられたオブジェクト（遺伝子、化合物、酵素）に対し、
文字と枠に fg_color_list で指定した色、背景に bg_color_list で指定した色を
つけた画像を生成、画像の URL を返します。object_id_list と fg_color_list,
bg_color_list の要素の数と順番を揃えるように注意する必要があります。

戻値：
  string (URL)

例：
  # パスウェイ path:eco00053 上に載っている大腸菌の遺伝子 eco:b0207 を
  # 背景が赤、文字と枠を青で着色し、eco:b1300 の背景を黄色、文字と枠を緑で
  # 着色した画像の URL を返します。
  obj_list = ['eco:b0207', 'eco:b1300']
  fg_list  = ['blue', '#00ff00']
  bg_list  = ['#ff0000', 'yellow']
  color_pathway_by_objects('path:eco00053', 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)

指定した element_id に対応するパスウェイ上のオブジェクト（長方形や丸など）
に対し、文字と枠に fg_color_list で指定した色、背景に bg_color_list で
指定した色をつけた画像を生成、画像の URL を返します。object_id_list と
fg_color_list, bg_color_list の要素の数と順番を揃えるように注意する
必要があります。

KEGG PATHWAY では、複数の遺伝子が一つのボックスに割り当てられていたり、
逆に１つの遺伝子が複数のボックスに割り当てられていることがあります。
このような場合 color_pathway_by_objects メソッドでは塗り分けることが
出来ませんが、color_pathway_by_elements を使うことで解決できます。

element_id は KEGG PATHWAY の XML 表現である KGML の <entry> タグで
指定される、パスウェイ上のグラフィカルな要素毎につけられたユニークな
数値です。パスウェイ上の element_id は get_elements_by_pathway メソッドで
PathwayElement オブジェクトのリストとして得ることができます。
PathwayElement の type や name 属性により遺伝子、酵素、化合物などと
対応を取り、element_id の値を使ってオブジェクトを特定します。

KGML について詳しくは下記のページを参照してください。

  * ((<URL:http://www.genome.jp/kegg/xml/>))

戻り値：
  string (URL)

例：
  # 枯草菌のパスウェイ path:bsu00010 上に載っている、
  # 遺伝子 bsu:BG11350 (element_id 78, ec:3.2.1.86) を赤枠/黄背景で
  # 遺伝子 bsu:BG11203 (element_id 79, ec:3.2.1.86) を青枠/黄背景で
  # 遺伝子 bsu:BG11685 (element_id 51, ec:2.7.1.2)  を赤枠/橙背景で
  # 遺伝子 bsu:BG11685 (element_id 47, ec:2.7.1.2)  を青枠/橙背景で
  # それぞれ着色した画像の URL を返します。
  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 ページの URL を返す
バージョンの 'mark_pathway_by_objects' メソッドです。

戻値：
  string (URL)

例：
  # 大腸菌のパスウェイ '00970' の、遺伝子 'eco:b4258'、化合物 'cpd:C00135'
  # KO 番号 'ko:K01881' に赤色でマークをつけた画像のクリッカブルマップを
  # 表示する HTML の URL を返す
  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 ページの URL を返す
バージョンの 'color_pathway_by_objects' メソッドです。

戻値：
  string (URL)

例：
  # 大腸菌のパスウェイ '00970' の、遺伝子 'eco:b4258' を赤地に灰色、化合物
  # 'cpd:C00135' を黄色地に緑、KO 番号 'ko:K01881' を橙地に青の色づけをした
  # 画像のクリッカブルマップを表示する HTML の URL を返す
  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 ページの URL を返す
バージョンの 'color_pathway_by_elements' メソッドです。

戻値：
  string (URL)

例：
  # 枯草菌のパスウェイ path:bsu00010 上に載っている、
  # 遺伝子 bsu:BG11350 (element_id 78, ec:3.2.1.86) を赤枠/黄背景で
  # 遺伝子 bsu:BG11203 (element_id 79, ec:3.2.1.86) を青枠/黄背景で
  # 遺伝子 bsu:BG11685 (element_id 51, ec:2.7.1.2)  を赤枠/橙背景で
  # 遺伝子 bsu:BG11685 (element_id 47, ec:2.7.1.2)  を青枠/橙背景で
  # 着色した画像のクリッカブルマップを表示する HTML の URL を返します。
  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_element_relations_by_pathway(string:pathway_id)

指定したパスウェイ上に載っているオブジェクト要素の間の関係を返します。
パスウェイ上で矢印により描かれている関係を表し、KGML における
<relation> に相当する情報（グラフ）を取得することができます。
次の get_elements_by_pathway メソッドも参照。

戻値：
  ArrayOfPathwayElementRelation

例：
  # 枯草菌のパスウェイ path:bsu00010 上に載っている PathwayElement 間の
  # 関係である PathwayElementRelation のリストを取得する。
  relations = get_element_relations_by_pathway('path:bsu00010')

  # 取得したリストの中身を表示する。
  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

+ パスウェイ上のオブジェクト検索

--- get_elements_by_pathway(string:pathway_id)

指定したパスウェイ上に載っているオブジェクト要素のリストを返します。
利用法については color_pathway_by_elements メソッドを参照してください。

戻値：
  ArrayOfPathwayElement

例：
  # 枯草菌のパスウェイ path:bsu00010 上に載っている PathwayElement の
  # リストを取得する。
  get_elements_by_pathway('path:bsu00010')

  # Ruby で遺伝子 bsu:BG11350, bsu:BG11203 と bsu:BG11685 の element_id を
  # 調べる例。
  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)

指定したパスウェイ上に載っている遺伝子のリストを返します。生物種名は
pathway_id に含まれる keggorg で指定します。

戻値：
  ArrayOfstring (genes_id)

例：
  # 大腸菌のパスウェイ 00020 番に載っている遺伝子のリスト
  get_genes_by_pathway('path:eco00020')

--- get_enzymes_by_pathway(string:pathway_id)

指定したパスウェイに載っている酵素番号のリストを返します。

戻値：
  ArrayOfstring (enzyme_id)

例：
  # 大腸菌のパスウェイ 00020 番に載っている酵素番号のリスト
  get_enzymes_by_pathway('path:eco00020')

--- get_compounds_by_pathway(string:pathway_id)

指定したパスウェイに載っている化合物のリストを返します。

戻値：
  ArrayOfstring (compound_id)

例：
  # 大腸菌のパスウェイ 00020 に載っている化合物のリスト
  get_compounds_by_pathway('path:eco00020')

--- get_glycans_by_pathway(string:pathway_id)

指定したパスウェイに載っている糖鎖のリストを返します。

戻値：
  ArrayOfstring (glycan_id)

例：
  # 大腸菌のパスウェイ 00510 に載っている糖鎖のリスト
  get_glycans_by_pathway('path:eco00510')

--- get_reactions_by_pathway(string:pathway_id)

指定したパスウェイに載っているリアクション番号のリストを返します。

戻値：
  ArrayOfstring (reaction_id)

例：
  # 大腸菌のパスウェイ 00260 番に載っているリアクションのリスト
  get_reactions_by_pathway('path:eco00260')

--- get_kos_by_pathway(string:pathway_id)

指定したパスウェイに載っている KO 番号のリストを返します。

戻値：
  ArrayOfstring (ko_id)

例：
  # ヒトのパスウェイ 00010 に載っている KO 番号のリスト
  get_kos_by_pathway('path:hsa00010')

+ オブジェクトからパスウェイ検索

関連 URL：
  * ((<URL:http://www.genome.jp/kegg/tool/search_pathway.html>))

--- get_pathways_by_genes([string]:genes_id_list)

指定した遺伝子が全て載っているパスウェイのリストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # 大腸菌の遺伝子 b0077 と b0078 が両方載っているパスウェイのリスト
  get_pathways_by_genes(['eco:b0077', 'eco:b0078'])

--- get_pathways_by_enzymes([string]:enzyme_id_list)

指定した酵素番号が全て載っているパスウェイのリストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # 酵素番号 1.3.99.1 の酵素が載っているパスウェイのリスト
  get_pathways_by_enzymes(['ec:1.3.99.1'])

--- get_pathways_by_compounds([string]:compound_id_list)

指定した化合物が全て載っているパスウェイのリストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # 化合物 C00033 と C00158 が両方載っているパスウェイのリスト
  get_pathways_by_compounds(['cpd:C00033', 'cpd:C00158'])

--- get_pathways_by_glycans([string]:compound_id_list)

指定した糖鎖が全て載っているパスウェイのリストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # 糖鎖 G00009 と G00011 が両方載っているパスウェイのリスト
  get_pathways_by_glycans(['gl:G00009', 'gl:G00011'])

--- get_pathways_by_reactions([string]:reaction_id_list)

指定したリアクション番号が全て載っているパスウェイのリストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # リアクション番号 rn:R00959, rn:R02740, rn:R00960, rn:R01786 の全ての
  # 反応を含むパスウェイのリスト
  get_pathways_by_reactions(['rn:R00959', 'rn:R02740', 'rn:R00960', 'rn:R01786'])

--- get_pathways_by_kos([string]:ko_id_list, string:org)

指定した生物の KO 番号が全て載っているパスウェイのリストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # KO 番号 'ko:K00016' と 'ko:K00382' を含むヒトのパスウェイのリスト
  get_pathways_by_kos(['ko:K00016', 'ko:K00382'], 'hsa')

  # KO 番号 'ko:K00016' と 'ko:K00382' を含む全生物種のパスウェイのリスト
  get_pathways_by_kos(['ko:K00016', 'ko:K00382'], 'all')

+ パスウェイ間の関係

--- get_linked_pathways(string:pathway_id)

指定したパスウェイ番号のパスウェイからリンクされているパスウェイの
リストを返します。

戻値：
  ArrayOfstring (pathway_id)

例：
  # パスウェイ path:eco00620 からリンクされているパスウェイのリスト
  get_linked_pathways('path:eco00620')

==== GENES

GENES データベースに対するメソッドの一覧です。GENES データベースについて
詳しくは以下のページを参照してください。

  * ((<URL:http://www.genome.jp/kegg/kegg2.html#genes>))

--- get_genes_by_organism(string:org, int:offset, int:limit)

指定した生物種の全 GENES エントリのうち、offset 番目から limit 分の
結果を返します。

戻値：
  ArrayOfstring (genes_id)

例：
  # インフルエンザ菌の遺伝子リストを 100 個ずつ得る
  get_genes_by_organism('hin', 1, 100)
  get_genes_by_organism('hin', 101, 100)

==== GENOME

GENOME データベースに対するメソッドの一覧です。GENOME データベースについて
詳しくは以下のページを参照してください。

  * ((<URL:http://www.genome.jp/kegg/kegg2.html#genome>))

--- get_number_of_genes_by_organism(string:org)

指定した生物種が持つ遺伝子数を返します。

戻値：
  int

例：
  # 大腸菌が持つ遺伝子の数
  get_number_of_genes_by_organism('eco')

==== LIGAND

LIGAND データベースに対するメソッドの一覧です。

関連 URL：
  * ((<URL:http://www.genome.jp/kegg/ligand.html>))

--- convert_mol_to_kcf(string:mol)

MOL フォーマットのエントリを KCF フォーマットに変換します。

戻値：
  string

例：
  convert_mol_to_kcf(mol_str)

--- search_compounds_by_name(string:name)

化合物を名前で検索します。

戻値：
  ArrayOfstring (compound_id)

例：
  search_compounds_by_name("shikimic acid")

--- search_drugs_by_name(string:name)

ドラッグを名前で検索します。

戻値：
  ArrayOfstring (drug_id)

例：
  search_drugs_by_name("tetracyclin")

--- search_glycans_by_name(string:name)

糖鎖を名前で検索します。

戻値：
  ArrayOfstring

例：
  search_glycans_by_name("Paragloboside")

--- search_compounds_by_composition(string:composition)

化合物を組成で検索します。
組成は元素と個数をつなげた文字列で指定します。
元素の順番は無関係です。

戻値：
  ArrayOfstring (compound_id)

例：
  search_compounds_by_composition("C7H10O5")

--- search_drugs_by_composition(string:composition)

ドラッグを組成で検索します。
組成は元素と個数をつなげた文字列で指定します。
元素の順番は無関係です。

戻値：
  ArrayOfstring (drug_id)

例：
  search_drugs_by_composition("HCl")

--- search_glycans_by_composition(string:composition)

糖鎖を組成で検索します。
組成はカッコで括った糖と個数をスペースで区切った文字列で指定します。
糖の順番は自由です。

戻値：
  ArrayOfstring

例：
  search_glycans_by_composition("(Man)4 (GalNAc)1")

--- search_compounds_by_mass(float:mass, float:range)

化合物を分子量で検索します。
mass を中心として ±range の重さの化合物が検索されます。

戻値：
  ArrayOfstring (compound_id)

例：
  search_compounds_by_mass(174.05, 0.1)

--- search_drugs_by_mass(float:mass, float:range)

ドラッグを分子量で検索します。
mass を中心として ±range の重さのドラッグが検索されます。

戻値：
  ArrayOfstring (drug_id)

例：
  search_drugs_by_mass(150, 1.0)

--- search_glycans_by_mass(float:mass, float:range)

糖鎖を分子量で検索します。
mass を中心として ±range の重さの糖鎖が検索されます。

戻値：
  ArrayOfstring

例：
  search_glycans_by_mass(1200, 0.5)

--- search_compounds_by_subcomp(string:mol, int:offset, int:limit)

共通部分構造を持つ化合物を subcomp プログラムを使って検索します。

アラインメントされた共通部分のノード番号が配列で返されるので、
アラインメントされた化合物の構造を bget コマンドに "-f m"
オプションをつけて MOL フォーマットで取得し、対応を確認します。

戻値：
  ArrayOfStructureAlignment

例：
  mol = bget("-f m cpd:C00111")
  search_compounds_by_subcomp(mol, 1, 5)

関連 URL：
  * ((<URL:http://www.genome.jp/ligand-bin/search_compound>))

--- search_drugs_by_subcomp(string:mol, int:offset, int:limit)

共通部分構造を持つドラッグを subcomp プログラムを使って検索します。

アラインメントされた共通部分のノード番号が配列で返されるので、
アラインメントされたドラッグの構造を bget コマンドに "-f m"
オプションをつけて MOL フォーマットで取得し、対応を確認します。

戻値：
  ArrayOfStructureAlignment

例：
  mol = bget("-f m dr:D00201")
  search_drugs_by_subcomp(mol, 1, 5)

関連 URL：
  * ((<URL:http://www.genome.jp/ligand-bin/search_compound>))

--- search_glycans_by_kcam(string:kcf, string:program, string:option, int:offset, int:limit)

共通部分構造を持つ糖鎖を KCaM プログラムを使って検索します。

引数の program には approximate マッチを行う "gapped" または
exact マッチを行う "ungapped" を指定します。また option には
"global" または "local" を指定します。

アラインメントされた共通部分のノード番号が配列で返されるので、
アラインメントされた糖鎖の構造を bget コマンドに "-f k"
オプションをつけて KCF フォーマットで取得し、対応を確認します。

戻値：
  ArrayOfStructureAlignment

例：
  kcf = bget("-f k gl:G12922")
  search_glycans_by_kcam(kcf, "gapped", "local", 1, 5)

関連 URL：
  * ((<URL:http://www.genome.jp/ligand-bin/search_glycan.cgi>))
  * ((<URL:http://www.genome.jp/ligand/kcam/>))

== Notes

Last updated: December 27, 2006

=end