OME-Zarr と OME-TIFF の蛍光顕微鏡アノテーション

v2.13.0 で追加

microscopy アノテーションスキームは、OME-Zarr または OME-TIFF として保存された多チャンネルの顕微鏡画像を表示し、アノテーターが画像上で割り当てる関心領域と細胞クラスを記録します。アノテーターは、チャンネルのオンとオフを切り替え、各チャンネルの色とコントラスト限界を設定し、z スライスと時点を順に移動し、ファイル自身の解像度ピラミッドを通してズームします。細胞生物学者やイメージングコアは、このスキームを、既存のセグメンテーションに対する細胞分類に使います。たとえば、免疫蛍光のパネルでは、アノテーターが各核を、マーカー陽性かマーカー陰性かに判定します。スクリーニングのグループは、同じスキームをハイコンテントスクリーニングの視野での表現型のスコアリングに使い、組織のプロジェクトでは、損傷した領域や破片を領域としてマークします。複数のアノテーターが同じ画像にラベルを付けられ、エクスポートは、各アノテーターの領域とクラスを分けて保持します。

OME-Zarr（OME-NGFF とも呼ばれます）は、Open Microscopy Environment の、チャンク化されたマルチスケール画像形式です。OME-TIFF は、OME-XML ヘッダーにチャンネルと次元の名前が書かれた TIFF ファイルです。ラベル画像は、整数として保存されたセグメンテーションで、細胞ごとに1つの ID、背景は 0 です。Cellpose や StarDist などのセグメンテーションツールは、ラベル画像を書き出します。Potato は、別の場所で作られたラベル画像を読み込み、セグメンテーションモデルは実行しません。

チャンネルの色とコントラストのコントロールは、細胞ビューの横にあります

• 形式: Potato は、zarr-python を通じて OME-Zarr 0.4（Zarr v2）と 0.5（Zarr v3）を読み込みます。これには、現行の NGFF 開発仕様のように、coordinateSystems の下に軸が列挙されたマルチスケールも含まれます。Potato は tifffile を通じて OME-TIFF を読み込み、tifffile は SubIFD として保存されたピラミッドも読み込みます。
• 軸: 画像は、t、c、z の任意の軸と、y、x を持てます。ほかの軸があるファイルは、メッセージとともに拒否されます。C 軸のない RGB の TIFF は、RGB のサンプルをチャンネルとして読み込まれます。
• チャンネル: 名前、色、表示ウィンドウは、OME-Zarr の omero ブロック、または OME-XML の Channel 要素から取得されます。表示ウィンドウのないファイルは、最も粗いピラミッドレベルの 0.5 パーセンタイルと 99.8 パーセンタイルから始まり、スライダーは、データに収まる最小のビット深度まで動きます（uint16 に保存された12ビットのデータでは 4095）。色のないチャンネルには、青、緑、赤、マゼンタ、シアン、黄、白、オレンジが順に割り当てられます。
• ラベル画像: OME-Zarr 画像の labels/ グループは、設定なしで見つかります。OME-TIFF には、ラベル画像の標準的な置き場所がありません。そのため、OME-TIFF の項目では、別の整数のラベル TIFF を指定します。
• オフライン: ビューアは、Potato サーバーの外から何も読み込みません。HTTP や S3 経由のリモートの OME-Zarr には対応していません。

Potato は、表示されているチャンネルと、そのコントラスト限界から、サーバー上で各タイルを合成します。ブラウザは、合成された JPEG タイルを OpenSeadragon で表示し、WebGL を必要とせず、生のチャンネルデータを受け取りません。アノテーターがチャンネルやコントラストの設定を変えるたびに、ブラウザは、表示されているタイルを1回の往復で再取得します。

リーダーには、microscopy エクストラが必要です。

pip install 'potato-annotation[microscopy]'

このエクストラは、Python 3.11 以降では zarr-python 3 を、それより古い Python では zarr-python 2 を、そして tifffile をインストールします。zarr-python 2 は OME-Zarr 0.5 を読めないため、OME-Zarr 0.5 のストアには Python 3.11 以降が必要です。

設定

次の設定は、3人のアノテーターに、各画像の細胞を分類し、損傷した組織や破片を囲むよう求めます。細胞は画像のラベル画像から取得され、アノテーターは領域を手作業で描きます。

annotation_task_name: "Cell classification"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/images.json]
item_properties: {id_key: id, text_key: note}
num_annotators_per_item: 3
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: microscopy
    name: cells
    description: "Classify the cells, and outline any region that looks damaged."
    image_key: image              # item field naming the OME-Zarr or OME-TIFF
    labels_key: cells             # item field naming a label TIFF (OME-TIFF items)
    tools: [bbox, polygon, landmark]
    labels:                       # classes for regions
      - {name: damaged, color: "#e8590c"}
      - {name: debris, color: "#868e96"}
    cell_labels:                  # classes for cells
      - {name: "marker positive", color: "#f03e3e"}
      - {name: "marker negative", color: "#4dabf7"}
      - {name: dividing, color: "#fab005"}
    channels:                     # overrides of the file's own settings
      - {name: DAPI, label: "DAPI (nuclei)"}
      - {index: 2, contrast: [100, 3000]}
    min_cells: 1
    label_requirement: {required: true}

labels は領域のクラスを、cell_labels は細胞のクラスを列挙します。cell_labels がない場合、細胞は領域のクラスを使います。最初の channels のエントリーは、ファイルが DAPI と呼ぶチャンネルの名前を変更し、2つ目のエントリーは、3番目のチャンネルの開始時のコントラストウィンドウを設定します（インデックスは 0 から数えます）。min_cells と label_requirement を併用すると、アノテーターが少なくとも1つの細胞を分類するまで、「次へ」はブロックされたままです。Potato は、サーバーの起動時にスキームのすべての値を検査し、不正な値があれば、そのキーを示すメッセージとともにサーバーを停止します。

細胞のみのタスク

スクリーニングでの表現型のスコアリングは、通常、細胞クラスが必要で、領域は必要ありません。次の部分的なブロックは、上の設定の annotation_schemes を置き換えます。

annotation_schemes:
  - annotation_type: microscopy
    name: phenotype
    description: "Give every cell in the field a phenotype."
    tools: []                     # no region tools
    label_image: cells            # entry of the OME-Zarr labels/ group
    labels: [normal, enlarged, multinucleated, apoptotic]
    channels:
      - {index: 0, color: "#0000ff"}
      - {index: 1, visible: false}
    min_cells: 20
    label_requirement: {required: true}

tools: [] では、領域ツールが非表示になり、クラスのリストは細胞に適用されます。OME-Zarr の labels/ グループに複数のセグメンテーション（核と細胞全体など）がある場合は、label_image キーで1つのエントリーを選びます。2番目のチャンネルは非表示で始まり、アノテーターは、そのチャンネルを再びオンにできます。

データ形式

各項目は、media_directory からの相対パスで画像のパスを指定します。

{"id": "well_A01", "image": "screen/A01.ome.zarr"}
{"id": "tissue_b", "image": "tissue_b.ome.tif", "cells": "tissue_b_cells.tif"}

Potato は、media_directory の中、次に task_dir の中でパスを探し、絶対パス、URL、どちらのディレクトリの外にも解決されるパスは拒否します。HCS プレートや bioformats2raw コンテナーでは、plate.ome.zarr/A/1/0 のように、ストア内の1つの画像を指定します。プレートのルートを指定すると、Potato は内側のパスを提案するエラーを表示します。

ラベル TIFF は整数を含み、画像のフル解像度の幅と高さを持ち、画像が持つ T、Z、Y、X の軸だけを使います。小さいラスターから描かれた細胞の輪郭は、画像上の誤った位置に置かれてしまうため、Potato は、サイズが異なるラベル TIFF を拒否します。TIFF の平面は全体がデコードされ、max_pixels を超える平面は拒否されます。大きな画像は、タイル化されたピラミッド型の OME-TIFF、または OME-Zarr として保存してください。これらの形式では、リーダーは、タイルが覆うチャンクだけを取得します。

オプション

ブラウザはクリックをラベルラスターに照らして判定し、エクスポートは同じラベル画像から細胞 ID を読み取ります。したがって、クリックは、エクスポートが名前を挙げる ID を選びます。label_max_side より大きいラベル画像は、収まるもののうち、ラベル画像の最も細かいピラミッドレベルから表示され、収まるレベルがない場合は数ピクセルおきにサンプリングされます。サンプリングの間隔より細い細胞は、ラスターから欠けることがあります。50,000個を超える細胞を持つラベル画像は、細胞リストでは拒否されます。

細胞を分類し、領域を描く

アノテーターは、ドラッグでパンし、スクロールまたはピンチでズームします。各チャンネルの行には、チャンネルを表示または非表示にするチェックボックス、色見本、Min と Max のコントラストスライダー、ファイルまたは設定の値を復元する Reset ボタンがあります。Potato は、ブラウザセッション内で、項目から項目へチャンネルの設定を保持します。画像に z スライスまたは時点が複数ある場合、画像の下にそのスライダーが表示されます。

細胞を分類するには、アノテーターは Pan / select cell（キー V）を選び、細胞をクリックします。選択した細胞は黄色で輪郭が描かれ、1から9のキーまたはクラスボタンで、その細胞にクラスを付けます。分類された細胞は、クラスの色で塗りつぶされます。細胞は、その ID を入力して選択することもできます。クラスは、すべての z スライスと時点にわたって、その細胞の ID に適用され、保存される z と t は、アノテーターが細胞を分類した平面を記録します。

領域を描くには、アノテーターは Rectangle（R）、Polygon（P）、Point（O）のいずれかと、「Region class」の下のクラスを選びます。長方形はドラッグで描きます。ポリゴンは、頂点ごとに1回クリックし、最初の頂点のクリック、ダブルクリック、Enter、または「Finish polygon」ボタンで終了します。Escape は描画中のポリゴンをキャンセルし、Backspace は最後の頂点を削除します。領域は、それが描かれた z スライスと時点に属し、そこでだけ表示されます。Regions リストで領域を選択すると、ビューアはその領域の平面へ移動し、リストの各エントリーには、クラスメニューと削除ボタンが付きます。

保存される回答

各スキームは、項目ごとに1つの JSON オブジェクトを保存します。

{"image": {"width": 256, "height": 256},
 "rois": [{"type": "polygon", "label": "damaged", "color": "#e8590c",
           "coordinates": [{"x": 0.58, "y": 0.08}, {"x": 0.86, "y": 0.12}, {"x": 0.78, "y": 0.35}],
           "z": 1, "t": 0}],
 "cells": [{"label_id": 1, "class": "marker positive", "z": 1, "t": 0}],
 "label_image": "cells"}

領域の座標は、image_annotation スキームと同じ形式での、フル解像度の画像に対する割合です。bbox は {x, y, width, height}、polygon は点のリスト、landmark は1つの点です。

エクスポート

microscopy エクスポートは、各アノテーターの回答を別々に、コマンドのあとに挙げるファイルへ書き出します。

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

領域を QuPath で開くには、画像を開いた状態で microscopy_rois.geojson をインポートします。この GeoJSON には、すべての項目とアノテーターが含まれます。複数の画像やアノテーターが1つのファイルを共有している場合は、インポートの前に、item_id と user_id でフィーチャーを絞り込んでください。

ラベル配列は、元の画像が OME-Zarr 0.5 の場合は OME-Zarr 0.5 として、それ以外の場合は 0.4 として書き出されます。--option zarr_format=2 または --option zarr_format=3 でバージョンを上書きでき、--option label_arrays=false でラベル配列を省略できます。各ラベル配列のストアには labels/ グループしかなく、ほとんどのビューアは、そのストア単体では開きません。labels/<schema>__<user> を元の画像の labels/ ディレクトリへコピーし、その名前を、元の画像の labels/ グループの labels リストに追加してください。ラベル配列には、zarr-python と、media_directory 内の元の画像が必要です。zarr-python や元の画像がない場合、エクスポートは GeoJSON と CSV を書き出し、警告を一覧します。

Potato の一致度指標は、microscopy スキームを対象にしません。エクスポートのあとで細胞ごとの一致度を計算するには、microscopy_cells.csv の行を、instance_id、label_image、label_id で対応づけます。そして、対応づけたクラスに対して、Fleiss のカッパまたは Cohen のカッパを計算します。

全スライド病理画像

SVS、NDPI、MRXS、その他 openslide が読み込むスライド形式の明視野の全スライドスキャンには、wsi エクストラを使って、ディープズームビューアで image_annotation スキームを使ってください。microscopy スキームは、SVS、NDPI、MRXS のファイルを開きません。Potato 2.13 以降では、全スライド画像上の領域を、potato import -i case_01.geojson --image-dir /data/slides -o case-project で QuPath GeoJSON または ASAP XML からインポートできます。インポーターは形式を検出し、-f qupath_geojson または -f asap_xml で形式を明示できます。インポートされた領域は、事前アノテーションになります。アノテーターの領域は、python -m potato.export -c config.yaml -f qupath_geojson -o out/qupath で、レベル0のスライドピクセルによる QuPath GeoJSON にエクスポートでき、-f asap_xml は、代わりに ASAP XML を書き出します。

例

python potato/flask_server.py start examples/image/multichannel-microscopy/config.yaml -p 8000

この例には、2つの合成画像があります。1つは、3チャンネル、3つの z スライス、labels/cells グループを持つ OME-Zarr 0.5 のストアで、もう1つは、3チャンネル、3つの時点、別のラベル TIFF を持つ OME-TIFF です。同じディレクトリの generate_data.py が、両方の画像を書き出します。

コーディングエージェントで調査を設定する

potato-skill 1.2.0 は Potato 2.13.1 を対象としており、microscopy を名前で認識します。このスキルは、アノテーターに何を尋ねるか、各画像を何人のアノテーターが分類するか、トレーニングと注意チェック、エクスポートなど、調査設計の側面を支援します。このスキルは、OME-Zarr と OME-TIFF のデータ形式、スキームのオプション、microscopy エクストラを、まだ文書化していません。potato-skill をインストールし、エージェントに調査を説明して、形式とオプションについては、このページの Markdown 版をエージェントに参照させてください。Markdown 版は https://www.potatoannotator.com/docs/annotation-types/microscopy.md にあります。

関連資料

• 画像アノテーション - 通常の画像上のボックス、ポリゴン、マスク
• ディープズームによるギガピクセル画像のアノテーション - タイルピラミッドと全スライド画像
• エクスポート形式 - Potato のエクスポート形式とエクスポートコマンド
• アノテーターは何人必要か - 項目あたりのアノテーター数の選び方
• ライフサイエンス - ライフサイエンスとバイオキュレーションのための Potato

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