embl-ebi-ols

EMBL-EBI オントロジールックアップサービス（OLS）

前提条件

1. uv：uv スキルを読み、そのセットアップ手順に従って、uv がインストールされ、PATH に含まれていることを確認してください。
2. ユーザーへの通知：.licenses/embl_ebi_ols_LICENSE.txt がワークスペースのルートディレクトリに存在しない場合は、（1）https://www.ebi.ac.uk/ols4/api-docs の利用規約を確認するようユーザーに目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。

基本ルール

• [!IMPORTANT] ユーティリティスクリプトを使用する：ステータスの確認を含むすべての API 操作には、必ず scripts/ 内の提供されたユーティリティスクリプトを使用してください。API に直接クエリを送るために curl や独自の Python リクエストを使用してはいけません。

• レート制限と耐障害性：EBI の利用規約を遵守し、リクエストは最大 1 秒あたり 5 件にしてください。提供されたユーティリティスクリプトは、この制限を自動的に適用します。

• 通知：このスキルを使用した場合は、そのことを出力に記載してください。

使用する場面 — クイックレシピ

ユーザーのクエリが次のいずれかに該当する場合は、このスキルを使用してください。

• 疾患、表現型、または用語の定義 → get_term.py --obo_id <ID> --summary
• 用語のサブタイプまたは子 → get_term.py --obo_id <ID> --relations children
• 用語の親 → get_term.py --obo_id <ID> --relations parents
• 祖先／疾患のカテゴリ／分類先 → get_term.py --obo_id <ID> --relations ancestors
• オントロジーのルート用語 → get_term.py --ontology <id> --roots
• 階層上の親（is-a + part-of）→ get_term.py --obo_id <ID> --relations hierarchicalParents
• 一部を構成する構造／階層上の子 → get_term.py --obo_id <ID> --relations hierarchicalChildren
• 直接の親と階層上の親を比較 → get_term.py --obo_id <ID> --relations parents,hierarchicalParents
• 用語を検索する（例：GO で「apoptosis」を検索）→ search_ols.py --query "..." --ontology <id>
• 機能に該当するGO 用語を検索する → search_ols.py --query "..." --ontology go --exact
• MONDO、CHEBI、CL、UBERONを検索する → search_ols.py --query "..." --ontology <id> --defining
• 検索結果をページ分割する／次のページを取得する → search_ols.py --query "..." --rows N --start <offset>
• 部分的な名称をオートコンプリートする → suggest_ols.py --query "..."
• オントロジーのメタデータ（例：EFO 情報）→ get_ontology.py --id <id>
• OLS インデックスの統計情報 → get_stats.py

複数ステップのクエリ（例：「心筋梗塞の親は何ですか？」）： ユーザーが用語を指定していても OBO ID が分からない場合は、複数のオントロジーを検索せず、必ず 2 ステップで完了してください。

1. 最も適切な単一のオントロジーを検索します：search_ols.py --query "myocardial infarction" --ontology doid --exact --rows 1 --output /tmp/step1.json
2. ステップ 1 の OBO ID を使用して関連情報を取得します：get_term.py --obo_id DOID:5844 --relations parents --output /tmp/step2.json

オントロジー選択ルール：一般的なヒトの疾患（例：糖尿病、がん）には必ず doid、表現型には hp、遺伝子機能には go、化学物質には chebi、解剖学には uberon、細胞型には cl を使用してください。mondo は、種をまたぐ文脈が明示されているか、必要な場合にのみ使用してください。

ユーティリティスクリプト

1. オントロジー全体から用語を検索する

キーワードでオントロジー用語を検索し、整形済みの JSON を返します。

uv run scripts/search_ols.py --query "diabetes" \
  --rows 5 --output /tmp/ols_search_results.json 2>/dev/null

重要：すべてのスクリプトで --output が必須です。結果は常に指定したファイルに書き込まれます。出力が大きい場合は、--rows（例：5-10）で件数を制限するか、--start を使用してページ分割できます。

返されるフィールド： JSON の結果には、iri、label、description、 ontology_name、ontology_prefix、obo_id、short_form、type、 is_defining_ontology、exact_synonyms が含まれます。

ページ分割： 出力には start、rows、has_more を含む pagination ブロックがあり、さらに結果を取得するかどうかを判断できます。 オプション：

• --query：検索文字列（必須）。ラベル、同義語、説明、識別子を検索します。
• --ontology：オントロジー ID で絞り込みます（例：go、doid、efo、hp）。 検索するオントロジーがわかっている場合は、使用をおすすめします。250 以上のオントロジーからのノイズを回避できます。
• --type：エンティティタイプで絞り込みます：class、property、individual、ontology。
• --exact：ラベルが完全一致するものだけを対象とするフラグです。ユーザーの文字列を特定のオントロジー用語 ID にマッピングするエンティティ解決に使用してください。
• --defining：定義元（権威ある）オントロジーの用語のみを返します。例：GO:0005634 は GO からのみ返され、相互参照された複製は返されません。
• --obsolete：結果に廃止された用語を含めるフラグです。
• --local：定義元のオントロジーに含まれる用語のみを返します。
• --childrenOf：指定した用語の IRI の子に制限します。複数指定する場合はカンマで区切ります。
• --allChildrenOf：推移的な関係（「part of」、「develops from」）を含むすべての子に制限します。IRI はカンマで区切ります。
• --queryFields：検索するフィールドをカンマ区切りで指定します（例： label,synonym,description）。
• --fieldList：返すフィールドをカンマ区切りで指定します。
• --groupField：一意の IRI ごとに結果をグループ化します。
• --isLeaf：末端の用語（子を持たない用語）のみを返します。
• --rows：返す結果の数（デフォルトは 10）。
• --start：ページネーションのオフセット（デフォルトは 0）。
• --output：結果を保存するファイルパス（必須）。

2. オートコンプリート／候補表示

用語名の一部からオートコンプリート候補を取得します。

uv run scripts/suggest_ols.py --query "diabet" --rows 5 \
  --output /tmp/ols_suggest.json 2>/dev/null

オプション：

• --query：オートコンプリートする用語の一部（必須）。
• --ontology：オントロジー ID で絞り込みます。複数指定する場合はカンマで区切ります。
• --rows：候補の数（デフォルトは 10）。
• --start：ページネーションのオフセット（デフォルトは 0）。
• --output：結果を保存するファイルパス（デフォルト：標準出力）。

3. 用語の詳細を取得

OBO ID または IRI で指定したオントロジー用語の詳細を取得します。

uv run scripts/get_term.py --obo_id "GO:0005634" \
  --output /tmp/ols_term.json 2>/dev/null

返されるフィールド： JSON には、iri、label、description、obo_id、 synonyms、ontology_name、is_obsolete、is_defining_ontology、 has_children、is_root、annotation、in_subset、および要求した 関係が含まれます。

要約モード： --summary を使用すると、読みやすい形式のブロック（ラベル、OBO ID、オントロジー、定義、同義語）が標準出力に表示されます。完全な JSON は常に --output ファイルに保存されます。

uv run scripts/get_term.py --obo_id "GO:0005634" --summary \
  --output /tmp/nucleus_full.json

オプション：

• --obo_id：OBO 形式の識別子（例：GO:0005634、DOID:9351）。--iri とは同時に指定できません。二重エンコードして IRI に自動変換します。

• --iri：用語の完全な IRI。--obo_id とは同時に指定できません。

• --ontology：オントロジー ID（指定されていない場合は --obo_id から自動的に導出されます）。

• --relations：取得する関係のリストをカンマ区切りで指定します。

  • 直接（is-a のみ）： parents、children、ancestors、 descendants
  • 階層（is-a + 「part of」、「develops from」などの推移的な関係）： hierarchicalParents、hierarchicalChildren、hierarchicalAncestors、 hierarchicalDescendants
  • グラフ： graph — 用語の完全なグラフ JSON

  注：解剖学／発生学のオントロジー（UBERON、CL）では、階層をたどる際に「part of」や「develops from」などの推移的な関係が重要になるため、階層型のバリアントを使用してください。

• --roots：オントロジーのルート用語を一覧表示します（--ontology が必要です）。

• --preferred_roots：推奨されるルート用語を一覧表示します（--ontology が必要です）。

• --summary：読みやすい形式の要約を標準出力に、完全な JSON を --output に出力します。

• --output：結果を保存するファイルパス（デフォルト：標準出力）。

4. プロパティの詳細を取得

階層を含むオントロジープロパティ（関係タイプ）の詳細を取得します。

uv run scripts/get_property.py --obo_id "BFO:0000051" --ontology go \
  --output /tmp/ols_property.json 2>/dev/null

オプション：

• --obo_id: プロパティのOBO形式のIDです。--iriとは相互に排他的です。
• --iri: プロパティの完全なIRIです。--obo_idとは相互に排他的です。
• --ontology: オントロジーIDです（--iriと併用する場合は必須）。
• --relations: カンマ区切りで指定します：parents、children、ancestors、 descendants。
• --roots: オントロジーのルートプロパティを一覧表示します（--ontologyが必要です）。
• --output: 結果を保存するファイルパスです（デフォルト：標準出力）。

5. 個体の詳細を取得

オントロジーの個体（インスタンス）の詳細を取得します。

uv run scripts/get_individual.py --obo_id "IAO:0000103" --ontology iao --types \
  --output /tmp/ols_individual.json 2>/dev/null

オプション：

• --obo_id: OBO形式のIDです。--iriとは相互に排他的です。
• --iri: 完全なIRIです。--obo_idとは相互に排他的です。
• --ontology: オントロジーIDです（--iriと併用する場合は必須）。
• --types: この個体の直接の型（クラス）を取得します。
• --alltypes: 祖先クラスを含むすべての型を取得します。
• --output: 結果を保存するファイルパスです（デフォルト：標準出力）。

6. オントロジー情報を取得

利用可能なオントロジーを一覧表示するか、特定のオントロジーの詳細を取得します。

uv run scripts/get_ontology.py --id go \
  --output /tmp/ols_ontology.json 2>/dev/null

オプション：

• --id: 特定のオントロジーID（例：go、efo、doid）です。省略すると、すべてのオントロジーを一覧表示します。
• --page: ページネーションのページ番号です（デフォルトは0）。
• --size: 1ページあたりのオントロジー数です（デフォルトは20）。
• --output: 結果を保存するファイルパスです（デフォルト：標準出力）。

7. OLS統計情報を取得

インデックスの統計情報（オントロジー、クラス、プロパティ、個体の合計数）を取得します。

uv run scripts/get_stats.py --output /tmp/ols_stats.json 2>/dev/null

オプション：

• --output: 結果を保存するファイルパスです（デフォルト：標準出力）。

リファレンス

• APIリファレンス：一般的なオントロジーID、OBO IDの形式、主要なAPIエンドポイントについては、 references/api_reference.mdを参照してください。

ワークフロー

1. 部分的な用語名から補完候補を取得するには、suggest_ols.pyを使用します。
2. search_ols.pyを使用して用語を検索します。信頼できる定義を優先するには、--definingを使用します。エンティティの解決には、--exactを使用します。
3. 詳細情報が必要な場合は、OBO IDまたはIRIを指定してget_term.pyを使用します。簡潔な表示には、--summaryを使用します。
4. 用語の階層を調べるには、is-aのみの場合はget_term.py --relations parents,childrenを使用し、「一部である」なども含める場合は--relations hierarchicalParents,hierarchicalChildrenを使用します。
5. 上位から下位へ調べるには、get_term.py --ontology go --rootsを使用します。
6. プロパティまたは個体については、get_property.pyまたはget_individual.pyを使用します。
7. 利用可能なオントロジーを確認するには、get_ontology.pyを使用します。
8. OLSインデックスの状態を確認するには、get_stats.pyを使用します。