OBO ファイルと OLS4 によるオントロジー用語ラベル

v2.13.0 で追加

radio、multiselect、span、image_annotation のスキームに label_source ブロックを加えると、オントロジーを対象とした検索ボックスが追加されます。アノテーターは、固定のラベルリストをスクロールする代わりに、名前、同義語、ID を入力して用語を選びます。選ばれた各用語は、用語の ID、名前、IRI、その用語が属していたオントロジーのリリースとともに保存されます。バイオキュレーターは、この機能を、Cell Ontology による細胞タイプのアノテーション、Human Phenotype Ontology（HPO）による表現型のアノテーション、MONDO による疾患の正規化、さらに、ChEBI の用語による化学物質の言及のタグ付け、UBERON の用語によるスライド上の組織領域のタグ付け、GO の用語による遺伝子産物のタグ付けに使います。Potato の一致度指標とエクスポートは、用語 ID を読み取ります。「B cell」を検索したアノテーターと、ID の CL:0000236 を入力したアノテーターは、どちらの回答も同じ ID を保存するため、一致します。

OBO フラットファイル形式は、OBO Foundry のオントロジーのプレーンテキストのリリース形式です。Potato は OBO 1.4 を読み込みます。Ontology Lookup Service（OLS4）は、EMBL-EBI の生物医学オントロジー用の検索サービスと API で、組織が独自の OLS4 サーバーを運用することもできます。

• ローカルファイル: service: file では、Potato は、タスクディレクトリ内の OBO 1.4 ファイルを検索します。ファイルをソースとする場合は、オフラインで動作します。
• OLS4: service: ols4 では、Potato は OLS4 サーバーを検索します。検索のたびに、入力されたテキストがそのサーバーに送られ、スキームが allow_network: true を設定していない限り、Potato は起動を拒否します。リクエストを行うのは Potato サーバーで、アノテーターのブラウザは Potato とだけ通信します。
• 保存されるレコード: 選ばれた各用語は、{obo_id, label, iri, ontology_version} として保存されます。Potato の一致度指標は obo_id を比較します。
• エクスポート: --format ontology_terms を付けた python -m potato.export は、選ばれた用語ごとに1行を書き出します。
• 追加のインストールなし: Potato は独自のリーダーで OBO を解析し、OLS4 の呼び出しには、Potato がすでに依存している requests パッケージを使います。

設定

次の設定は、Potato の例にある合成のサンプルオントロジーを対象とした、3つのスキームを構成します。最初のスキームは、検索ボックスだけで主な細胞タイプを1つ尋ね、2つ目のスキームは、検索ボックスの上に固定の None の選択肢を提示し、3つ目のスキームは、免疫細胞の用語だけでテキストのスパンにタグを付けます。

annotation_task_name: "Cell types from an ontology"
task_dir: .
output_annotation_dir: annotation_output
data_files: [data/cell-descriptions.jsonl]
item_properties: {id_key: id, text_key: text}
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: radio
    name: main_cell_type
    description: "Which cell type does the description mainly talk about?"
    labels: []                  # search box only
    label_requirement: {required: true}
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo
 
  - annotation_type: multiselect
    name: other_cell_types
    description: "Which other cell types are mentioned?"
    labels: [None]              # a fixed option above the search box
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo
 
  - annotation_type: span
    name: immune_cell_mentions
    description: "Highlight each immune cell mention and tag its type"
    labels: []
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo
      root: SCL:0000001         # immune cell and its is_a descendants

labels: [] の場合、または labels キーがない場合、検索ボックスが唯一の回答手段です。リストがある場合は、固定のラベルが通常どおり表示され、検索ボックスは固定のラベルの下に置かれます。固定のラベルは、単なるラベル名として保存され、検索から選ばれた用語だけが、オントロジーの用語として保存されます。最初のスキームは required を設定しているため、アノテーターが用語を選ぶまで、Potato は「次へ」をブロックしたままにします。3つ目のスキームでは、Potato は検索を、root の免疫細胞の用語と、その用語の下に is_a で連なるすべての用語に限定します。ニューロンの用語が、スパンの検索に現れることはありません。

Potato は、オントロジーファイルを同梱していません。必要な .obo のリリースを、タスクディレクトリにダウンロードし、そのファイルをプロジェクトとともに保管してください。HPO のリリースは http://purl.obolibrary.org/obo/hp.obo、Cell Ontology のリリースは http://purl.obolibrary.org/obo/cl.obo です。例の scl-sample.obo は、現行の用語が19個、廃止された用語が1個あり、接頭辞が SCL の、作り物のオントロジーです。SCL の ID は、Cell Ontology の ID ではありません。

画像アノテーションのスキームでは、同じブロックを描画ツールの隣に置きます。次の部分的なブロックは、上の設定に4つ目のスキームを追加します。

  - annotation_type: image_annotation
    name: cells_in_image
    description: "Box each cell and name its type"
    tools: [bbox, polygon]
    labels: []
    label_source:
      ontology: scl
      service: file
      file: ontologies/scl-sample.obo

ファイルの代わりに OLS4 を検索する

次の部分的なブロックは、上の設定の annotation_schemes を、EBI の OLS4 サーバー上の Cell Ontology を検索する1つのスキームに置き換えます。ontology の値は、cl、hp、go、mondo、chebi、uberon などの、OLS4 のオントロジー ID です。

annotation_schemes:
  - annotation_type: radio
    name: cell_type
    description: "Which cell type is described?"
    labels: []
    label_source:
      ontology: cl
      service: ols4
      allow_network: true       # required for ols4
      root: CL:0000000          # optional, sent to OLS4 as childrenOf
      timeout_s: 5

自前でホストした OLS4 サーバーを検索するには、base_url を設定します。allow_network キーは、意図的なオプトインです。検索テキストをネットワーク内にとどめる必要がある調査は、service: file を使います。OLS4 のブロックに allow_network: true がない場合、Potato は起動を拒否します。

オプション

label_source が受け付けるすべてのキーです。

次のいずれかの条件に当てはまる場合、サーバーと python -m potato.validate_cli は設定を拒否し、問題のキーを示します。

• label_source が、radio、multiselect、span、image_annotation 以外のスキームタイプにある
• service が file でも ols4 でもない、または、キーがもう一方のサービスのものである（file に base_url）
• 未知のキーがある
• ファイルがない、task_dir の外にある、max_file_mb より大きい、OWL ファイルである、または用語がない
• root がファイル内の用語でない、または廃止の印が付いている
• allow_network: true がないまま service: ols4 が設定されている

OBO ファイルの解析

Potato は、ヘッダータグの data-version、ontology、default-namespace を読み取ります。各 [Term] スタンザでは、リーダーは id、name、namespace、synonym、def、is_a、alt_id、is_obsolete に加えて、古いファイルにある exact_synonym などの OBO 1.0 の同義語タグを取り込みます。[Typedef] スタンザはスキップされ、relationship: と intersection_of: の行はエッジではありません。そのため、Potato は、root のサブツリーを is_a だけから構築します。たとえば、UBERON のサブツリーには、ルートのサブクラスは含まれますが、ルートと part_of だけでつながっている構造は含まれません。

保存される ontology_version は、サンプルの scl/releases/2026-10-01 のような、ファイルの data-version ヘッダーです。ヘッダーのないファイルには、sha256: に続けて、ファイルのハッシュの最初の16進数12桁が付きます。ファイルは1回解析され、メモリに保持されます。Potato は、ファイルのサイズまたは更新時刻が変わったときに、ファイルを再び解析します。古いファイルの上にコピーした新しいリリースは、再起動なしで、次の検索から有効になります。

廃止された用語は、検索とすべてのサブツリーから除外され、Potato は、replaced_by タグをたどって新しい用語へ進むことはしません。alt_id の検索は、主たる用語を見つけ、Potato は主たる ID を保存します。OWL ファイルは、メッセージとともに拒否されます。OBO Foundry のオントロジーの多くは、.owl ファイルの隣に .obo のリリースを公開しています。.obo のリリースをダウンロードするか、ROBOT で OWL ファイルを変換してください。

robot convert --input cl.owl --output cl.obo

NCBITaxon のような大きなオントロジーでは、スリムなファイルやサブセットのファイルを使うか、max_file_mb を上げるか、OLS4 を通じてオントロジーを検索してください。

用語を検索して選ぶ

アノテーターは、名前、同義語、用語 ID の少なくとも2文字を入力します。ファイルの検索は、まず用語 ID（CL:0000236、CL_0000236、alt_id、または完全な PURL）を、次に名前の完全一致、入力したテキストで始まる名前、入力した各単語で単語が始まる名前の順に並べます。同義語も同じ3通りで照合され、そのあとに、名前のどこかにあるテキスト、次に同義語のどこかにあるテキストが続きます。すべての同義語のスコープ（EXACT、BROAD、NARROW、RELATED）が数えられ、同義語を通じて見つかった一致では、用語名の下にその同義語が表示されます。結果には、用語 ID と、定義の最初の240文字も表示されます。サンプルのオントロジーでは、white blood と入力すると、同義語「white blood cell」を通じて leukocyte が見つかり、SCL:0000099 と入力すると、その用語の alt_id を通じて T cell が見つかります。

一致する用語が max_results より多い場合、ステータス行が、表示している数と総数を示し、アノテーターにさらに入力するよう促します。ボックスの下の行は、ソースの名前を示します。この行は、ファイルがソースの場合は、オントロジーとファイルのバージョンを示し、OLS4 がソースの場合は、オントロジー名に続けて「via OLS4」を示します。

• キーボード: 上と下の矢印キーで一致を移動し、Enter で強調表示された一致を選び、Escape でリストを閉じ、もう一度 Escape でボックスを消去します。一致をクリックまたはタップしても選べ、各一致は、高さが少なくとも44ピクセルのタップ対象です。
• radio: 選ばれた用語は、選択された選択肢として表示され、別の用語を選ぶと、前の用語が置き換わります。
• multiselect: 選ばれた各用語は、チェック済みのチェックボックスとして表示され、チェックを外すと、その用語が削除されます。
• span: 選ばれた用語が、アクティブなスパンのラベルになり、アノテーターはそのあとでテキストをハイライトします。ハイライトの上のチップに、用語名が表示されます。
• image_annotation: 選ばれた用語が、ラベルボタンとアクティブなラベルになり、アノテーターはそのあとで描画します。画像上ですでに使われた用語は、ページの読み込み時に、ボタンとして表示されます。

ポケットモードには、検索ボックスがありません。そのため、label_source のスキームを持つタスクは、常に通常のアノテーションページを使います。通常のページは、スマートフォンでも動作します。

ネットワークアクセスと OLS4 のキャッシュ

Potato は、service: file のスキームについては、どの時点でもネットワークリクエストを行いません。.obo ファイルがタスクディレクトリに置かれていれば、ファイルをソースとする場合は、エアギャップ環境のデプロイで動作します。検索は、Potato サーバー上の解析済みファイルに対して実行されます。allow_network: true のない OLS4 のスキームは、その設定ではサーバーが起動を拒否し、代わりにローカルファイルを提案するため、ネットワークに到達できません。

service: ols4 と allow_network: true では、Potato サーバーは、各検索を obsoletes=false を付けて OLS4 に送ります。すると OLS4 は、廃止された用語を結果から除外します。検索の回答は、サーバーのメモリに6時間キャッシュされ、最大512個の個別の検索が保持され、オントロジーのリリース文字列も6時間キャッシュされます。ブラウザは、回答を5分間再利用することがあります。OLS4 が返したすべての用語は、<output_annotation_dir>/ontology_cache/<ontology>-ols4-terms.json にも書き込まれます。再読み込みのあと、Potato は、スパンのチップと画像のラベルボタンの用語名を、そのファイルから読み取り、エクスポートも同じファイルを読み取ります。

OLS4 が遅いか到達できないとき、検索ボックスには、「Search failed: OLS4 did not answer within 5 s.」、または「Search failed: OLS4 request failed」で始まるメッセージが表示され、アノテーターは、固定のラベルには引き続き回答できます。直前の6時間以内に回答された検索は、キャッシュから提供されます。radio や multiselect の回答はレコード全体を保持し、スパンと画像の回答は、ディスク上の用語ファイルを通じて解決されるため、すでに選ばれた用語は、保存されたままです。Potato が OLS4 からオントロジーのリリースを読み取れない場合、選択は、最長で6時間後の次のリリース照会まで、空の ontology_version で保存されます。ネットワークの障害中も動作しなければならない調査では、.obo ファイルをダウンロードして、service: file に切り替えてください。

保存される回答

選ばれた用語は、次のレコードとして保存されます。

{"obo_id": "SCL:0000005", "label": "CD4-positive T cell",
 "iri": "http://purl.obolibrary.org/obo/SCL_0000005",
 "ontology_version": "scl/releases/2026-10-01"}

ファイルをソースとする場合、iri は ID から作られる OBO の PURL で、OLS4 では、iri は OLS4 が返す IRI です。radio や multiselect の回答は、選んだ時点の ontology_version を保持します。.obo ファイルが置き換えられたあとも、回答には、アノテーターが検索したリリースが示されたままです。

スパンと図形は、ID だけを保存します。エクスポートは、service: file では .obo ファイルから、service: ols4 では ontology_cache 内の OLS4 の用語ファイルから、名前、IRI、バージョンを調べます。ファイルモードでのスパンと図形については、エクスポートは、エクスポート時点での .obo ファイルのバージョンを書き出します。

エクスポート

ontology_terms 形式は、ontology_terms.csv と ontology_terms.jsonl を書き出し、選ばれた用語ごとに1行です。

python -m potato.export --config config.yaml --format ontology_terms --output out/

上の設定の最初の項目に対する1人のアノテーターについて、ontology_terms.csv は次のようになります。

user_id,instance_id,schema,annotation_type,ontology,obo_id,label,iri,ontology_version,start,end,text,shape_index,shape_type,known
ana,cells_01,main_cell_type,radio,scl,SCL:0000005,CD4-positive T cell,http://purl.obolibrary.org/obo/SCL_0000005,scl/releases/2026-10-01,,,,,,true
ana,cells_01,other_cell_types,multiselect,scl,SCL:0000011,macrophage,http://purl.obolibrary.org/obo/SCL_0000011,scl/releases/2026-10-01,,,,,,true
ana,cells_01,immune_cell_mentions,span,scl,SCL:0000011,macrophage,http://purl.obolibrary.org/obo/SCL_0000011,scl/releases/2026-10-01,128,150,large phagocytic cells,,,true

start、end、text の列はスパンで埋められ、shape_index と shape_type は画像の図形で埋められます。known の列は、その ID が現在のファイルまたは OLS4 の用語ファイルにない場合、false になります。新しいリリースで削除された、または廃止された用語も、false になります。エクスポートは、そのような行の数を示す警告を出力します。同じスキーム上の固定のラベルは、ontology_terms の行にはなりません。汎用の csv エクスポートは、radio や multiselect の用語を、JSON レコードを保持する <schema>.<obo_id> という名前の列として書き出し、スパンと図形は、obo_id をそのラベルとして保持します。ほかの形式については、エクスポート形式を参照してください。

一致度

Potato の一致度指標は、obo_id を比較します。radio スキームは、名義ラベルとして採点され（一致率、Cohen のカッパ、Fleiss のカッパ、Krippendorff のアルファ）、multiselect スキームは、用語 ID の集合に対する Jaccard の重なりと MASI 重み付きのアルファで、span スキームは、スパンの位置と obo_id で、image_annotation スキームは、各図形のジオメトリと用語 ID で採点されます。同じ用語を選んだ2人のアノテーターは、レコードの ontology_version の値が異なっていても、一致します。親の用語と子の用語は異なるラベルとして数えられ、一致度のコードは、オントロジーの階層に沿った部分点を与えません。たとえば、T cell と CD4-positive T cell は、不一致として採点されます。階層を考慮した比較には、ontology_terms をエクスポートし、同じ .obo のリリースに対して、obo_id 列から尺度を計算してください。

例

python potato/flask_server.py start examples/classification/ontology-labels/config.yaml -p 8000

この例には、4つの短い細胞の説明、合成の scl-sample.obo オントロジー、上の設定の3つのスキームがあります。

関連資料

• ライフサイエンス - バイオキュレーションとライフサイエンスのアノテーションのための Potato
• ヘルスケア - 臨床および生物医学のアノテーションのための Potato
• エンティティリンキング - 言及を知識ベースのエントリーにリンクします。ここではスパンのラベルは固定のカテゴリのままです
• ラジオとマルチセレクト - label_source を受け付ける、単一選択と複数選択のスキーム
• エクスポート形式 - Potato のエクスポート形式とエクスポートコマンド

実装の詳細については、ソースドキュメントを参照してください。