ontology-term-resolution

オントロジー用語の解決

使用するタイミング

メタデータ列への注釈付け、提出用テンプレートへの記入、他の人が作成した表の監査、古いファイル内の ID が現在も有効かどうかの確認など、オントロジー識別子を記録しようとするとき、または信頼しようとするときはいつでも使用します。

ルール

オントロジー ID を記憶だけで書かず、確認せずに受け入れないでください。

オントロジー ID は形式を覚えやすい一方、細部は恣意的です。一見もっともらしい UBERON:0002108 は実在する用語（小腸）ですが、肝臓ではありません。この置き換えは後続のどの処理でも検出されません。ID の形式は正しく、オントロジーも正しいため、メタデータが気付かれないまま誤った状態になります。査読者にも見抜けないため、このような誤りは公開済みのデータセットにまで残ります。

このスキルが出力する ID はすべて、OLS のライブ検索から取得されます。渡された ID はすべて検証されます。Bioregistry、Identifiers.org、ZOOMA、Ontobee は、プレフィックス、ランディングページ、略記に関する質問に答えますが、OLS による確認の代わりにはなりません。

使用するサービス

質問	スクリプト	権威ある情報源
「左心室」に該当する用語は何ですか？	scripts/resolve_terms.py	OLS
OLS でラボの略記（PBMC、WT）が見つからなかった場合	scripts/map_terms.py、続いて validate_terms.py	ZOOMA が候補を提示し、OLS が判定
EFO:0001067 は実在し、現在も有効で、ラベルも正しいですか？	scripts/validate_terms.py	OLS
HPO は実在するプレフィックスですか？HP:notanid はパターンに一致しますか？	scripts/lookup_prefix.py	Bioregistry
この CURIE を開くランディングページはどれですか？	scripts/lookup_prefix.py	Identifiers.org と Ontobee の URL

4 つのスクリプトはいずれも単一の値またはファイルを受け取り、TSV または JSON を出力します。また、標準ライブラリ以外のパッケージは必要ありません。OLS 以外のサービスの注意点については、references/companion-apis.md を参照してください。

テキストから用語を解決する

cd skills/ontology-term-resolution/scripts

# one string, constrained to the ontology that should define it
python3 resolve_terms.py "liver" --ontology uberon

query   rank  curie           label  ontology  match_type   strategy  defining_ontology
liver   1     UBERON:0002107  liver  uberon    exact_label  exact     true

# a column of tissue names; anything not an exact hit is reported, not guessed
python3 resolve_terms.py --input tissues.txt --ontology uberon \
    --exact-only --format tsv -o resolved.tsv

# accept fuzzy fallbacks, then review the partial hits by hand
python3 resolve_terms.py "left ventrical of heart" --ontology uberon --top 3

検索は exact（ラベルと同義語）→ token → fulltext の順に段階を進め、結果が返された最初の戦略で停止し、どの戦略が使われたかを報告します。--exact-only を指定すると、この段階的な検索は無効になります。--branch UBERON:0000465 を指定すると、候補をある用語の子孫に限定できます。

結果を使う前に match_type を確認してください。 exact_label と exact_synonym は安全です。partial は、入力どおりの文字列が存在しないため、OLS が最も近い候補を返したことを意味し、人間による判断が必要です。unresolved は正当な出力です。まず試す価値のある正規化については、references/curation-rules.md を参照してください。

既存の ID を検証する

python3 validate_terms.py UBERON:0002107 EFO:0001067 UBERON:9999999

id              status     actual_label                  ontology  replacement     detail
UBERON:0002107  ok         liver                         uberon
EFO:0001067     obsolete   obsolete_parasitic infection  efo       MONDO:0005135   obsolete; replaced by MONDO:0005135
UBERON:9999999  not_found                                                          no such term in the ontology this prefix names

処理に失敗した項目がある場合は終了コード 1、すべて成功した場合は 0、使用方法またはネットワークに問題がある場合は 2 になります。そのため、メタデータファイルの CI ゲートとして使用できます。

# id + label columns; catches IDs that exist but are labelled as something else
python3 validate_terms.py --input metadata.tsv --strict

# a tissue column must hold UBERON anatomical entities and nothing else
python3 validate_terms.py --input tissue_ids.tsv \
    --branch UBERON:0000465 --expect-ontology uberon

ステータス	意味	判定
ok	実在し、現在も有効で、主張されたすべての内容と一致しています	合格
matched_synonym	主張されたラベルは同義語で、優先ラベルとは異なります	警告
imported_only	ホームオントロジーではこの ID がすでに主張されていません	警告
not_a_class	用語はプロパティまたは個体です	警告
not_found	該当する用語がありません	不合格
obsolete	廃止されています。後継がある場合は replacement に示されます	不合格
label_mismatch	ID と主張されたラベルが異なるものを表しています	不合格
wrong_ontology	ID の種類は正しいものの、この列に対するオントロジーが異なります	不合格
wrong_branch	必須のルートの子孫ではありません	不合格
malformed_curie	PREFIX:local の形式ではありません	不合格

--strict を指定すると、警告が不合格に引き上げられます。

プレフィックスまたはコンパクト識別子を確認する

python3 lookup_prefix.py HP HPO HP:0001250 HPO:0001250

query        status          preferred_prefix  canonical_curie  pattern    detail
HP           ok              HP                                 ^\d{7}$
HPO          synonym_prefix  HP                                 ^\d{7}$    'HPO' is a synonym of preferred prefix HP
HP:0001250   ok              HP                HP:0001250       ^\d{7}$
HPO:0001250  synonym_prefix  HP                HP:0001250       ^\d{7}$    'HPO' is a synonym of preferred prefix HP

Bioregistry は同義語のプレフィックスを受け付けます。Identifiers.org は受け付けません。HPO:0001250 は HTTP 400 になります。CURIE を OLS に渡す前に、優先プレフィックスに書き換えてください。ランディングページの列は Bioregistry のマッピング（providers.miriam、mappings.ontobee）から取得され、優先プレフィックスをテンプレートに当てはめたものではありません。ORPHA:558 は 400、orphanet:558 は 200 になり、OBA には Identifiers.org の名前空間がありません。セルが空の場合、そのサービスはそのプレフィックスをホストしていません。このスクリプトは用語の実在を示すものではありません。それは引き続き validate_terms.py で確認します。

マップ作成時の略記（ZOOMA）

# after resolve_terms.py returned unresolved / partial
python3 map_terms.py PBMC --ontology cl --exact-only

--ontology は必須です。フィルターなしで ZOOMA にアノテーションさせると、liver に対して UBERON に加え、FOODON、XAO、BTO も HIGH 信頼度で返されます。HIGH/GOOD のヒットは候補にすぎません。記録する前に、すべての CURIE に対して validate_terms.py を実行してください。

誤解を招く API の挙動

以下は稼働中のサービスで検証済みの挙動であり、このスキルが手順ではなくスクリプトを提供する理由です。詳細は references/ols4-api.md を参照してください。

落とし穴	結果
exact=true はトークンの完全一致です	liver は UBERON で 161 件のヒットを返します。queryFields=label を追加すると 1 件になります
/search は is_obsolete や term_replaced_by を返しません	fieldList に指定しても黙って除外されます。「この ID は現在も有効か」という確認には、用語の詳細情報のみが答えられます
ontology=efo は MONDO と CL のヒットを返します	オントロジー同士は相互にインポートしています。CURIE のプレフィックスで自分でフィルターしてください
同じ用語が、インポート元のオントロジーごとに 1 回ずつ表示されます	obo_id で重複を除き、is_defining_ontology: true を保持してください
obo_id のインデックスには欠落があります	MONDO:0000001 は有効ですが、obo_id ではインデックス化されていません。誤った not_found を避けるには IRI へのフォールバックが必要です
IRI はすべて OBO PURL ではありません	EFO と Orphanet は独自の名前空間を使用します。テンプレートを使わず、IRI を解決してください
OxO は廃止されています	HTTP 200 で HTML を返します。代わりに用語の相互参照または SSSOM を使用してください
ブランチの確認だけでは、解剖学から細胞型を除外できません	CARO では cell が anatomical structure の下にあります。プレフィックスでも制約してください
オントロジーをフィルターしない ZOOMA	liver に対して、FOODON、XAO、BTO、UBERON 全体から 100 件以上の HIGH ヒットを返します
Identifiers.org の同義語プレフィックス	HPO:0001250 は HTTP 400 になります。同じ CURIE は Bioregistry では受け付けられます
Identifiers.org でエンコードされたコロン	HP%3A0001250 は HTTP 400 になります。パスでは : をそのまま使用する必要があります
Bioregistry の preferred_prefix は Identifiers.org の名前空間ではありません	ORPHA:558 は 400、orphanet:558 は 200 です。hp:0001250 と chebi:15377 は、これらの名前空間では LUI にプレフィックスが含まれるため 400 になります。/api/reference/{CURIE} の providers.miriam を使用してください。その対応付けがない場合（OBA、XAO、ECTO）は URL を省略してください
Ontobee の検索	HTML ページのみで、JSON API はありません。スクレイピングしないでください

オントロジーの選択

疾患には MONDO、表現型には HP、組織には UBERON、細胞型には CL、アッセイには EFO、化合物には ChEBI、生物には NCBITaxon、性別および normal には PATO を使用してください。プレフィックスから OLS ID への対応（HP は hp、Orphanet は ordo として提供されます）、--branch 用のブランチルート、オントロジーが重複する場合の判断基準については、references/ontology-registry.md を参照してください。

結果の報告

ID とラベルを示し、それぞれどのように一致したかを説明してください。ID だけの表はレビューできません。未解決の用語は、最も近いヒットで埋めず、未解決であることを明記してください。

参考資料

• references/ols4-api.md — エンドポイント、パラメーター、レスポンスフィールド、および検証済みの OLS の落とし穴。
• references/companion-apis.md — Bioregistry、Identifiers.org、ZOOMA、Ontobee。それぞれの使いどころと、フィルターなしの検索や同義語プレフィックスでの呼び出しが成功したように見える原因となる落とし穴。
• references/ontology-registry.md — プレフィックスとオントロジー ID の対応表、ブランチルート、各概念を所有するオントロジー。
• references/curation-rules.md — 候補の選定手順、再試行する正規化、既存の表の監査、廃止された用語、オントロジー間のマッピング。

エージェントの作業手順

1. 環境を確認します。 ネットワークにアクセスできること、API キー（必要な場合）、データベースの最新の API ドキュメントとレート制限を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問します。
3. まず小規模に実行します。 既知のレコードを1件取得し、一括クエリの前にレスポンス形式を確認します。
4. 上記の手順と参考情報を使用して、タスク全体を実行します。
5. 結果を検証します。 識別子が解決できること、レコード数が報告されていること、データベースのバージョンまたはアクセス日が記録されていることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の点を明示します。

次のことが起きた場合	対応
HTTP 429 または 5xx エラー	バックオフを伴うレート制限を守り、リクエストをバッチ処理し、部分的な結果を正直に報告します。
これらの手順にある関数、フラグ、エンドポイントがインストール済みバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を決して捏造しません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に前提を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しません。実行または検証できないことがあれば、明確に伝えます。
• アクセッション番号、ID、レコードを決して捏造しません。見つからない場合は「見つかりません」と報告します。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 金銭が発生する操作、共有 GPU またはクラウドクォータを消費する操作、個人データまたは患者データを扱う操作、元に戻せない操作の前には、確認を求めます。