alterlab-pathml

PathML

概要

PathML は、計算病理学のワークフローに対応する包括的な Python ツールキットです。機械学習や、病理学の全スライド画像の画像解析を支援することを目的としています。このフレームワークは、多様なスライド形式の読み込み、画像の前処理、空間グラフの構築、深層学習モデルのトレーニング、CODEX や多重免疫蛍光などの技術で得られた多項目画像データの解析に使える、モジュール式で組み合わせ可能なツールを提供します。

このスキルを使う場面

次の用途でこのスキルを適用します。

• さまざまな独自形式の全スライド画像（WSI）の読み込みと処理
• 染色の正規化による H&E 染色組織画像の前処理
• 核検出、セグメンテーション、分類のワークフロー
• 空間解析用の細胞グラフと組織グラフの構築
• 病理データを用いた機械学習モデル（HoVer-Net、HACTNet）のトレーニングまたはデプロイ
• 空間プロテオミクスを目的とした多項目画像（CODEX、Vectra、MERFISH）の解析
• 多重免疫蛍光によるマーカー発現の定量化
• HDF5 ストレージを使用した大規模病理データセットの管理
• タイルベースの解析とスティッチング処理

使用しない場面

シナリオ	代わりに使うもの
軽量な H&E 前処理、組織マスキング、Random/Grid/Score タイルの抽出	alterlab-histolab
Visium/Xenium/MERFISH テーブルの空間トランスクリプトミクスにおける近傍統計	alterlab-squidpy-spatial
生成された細胞 x マーカーマトリックスの単一細胞発現解析	alterlab-scanpy
病理学固有の I/O や変換を使わない汎用ビジョンモデルのトレーニング	alterlab-pytorch-lightning
すでに構築したグラフでのグラフニューラルネットワーク	alterlab-torch-geometric

主な機能

PathML には、リファレンスファイルで詳しく説明されている 6 つの主要な機能領域があります。

1. 画像の読み込みと形式

Aperio SVS、Hamamatsu NDPI、Leica SCN、Zeiss ZVI、DICOM、OME-TIFF など、160 種類以上の独自形式から全スライド画像を読み込みます。PathML はベンダー固有の形式を自動的に処理し、画像ピラミッド、メタデータ、関心領域にアクセスするための統一インターフェースを提供します。

参照先： 対応形式、読み込み方法、さまざまな種類のスライドの扱いについては、references/image_loading.md を参照してください。

2. 前処理パイプライン

画像操作、品質管理、染色の正規化、組織検出、マスク処理のための変換を組み合わせて、モジュール式の前処理パイプラインを構築します。PathML の Pipeline アーキテクチャにより、大規模なデータセット全体で再現性の高い前処理をスケーラブルに実行できます。

主な変換：

• StainNormalizationHE - Macenko/Vahadane 染色正規化
• TissueDetectionHE、NucleusDetectionHE - 組織／核のセグメンテーション
• MedianBlur、GaussianBlur - ノイズ低減
• LabelArtifactTileHE - アーティファクトの品質管理

参照先： 変換の全一覧、パイプラインの構築、前処理のワークフローについては、references/preprocessing.md を参照してください。

3. グラフ構築

細胞レベルおよび組織レベルの関係を表す空間グラフを構築します。セグメンテーションされたオブジェクトから特徴量を抽出し、グラフニューラルネットワークや空間解析に適したグラフベースの表現を作成します。

参照先： グラフ構築手法、特徴量抽出、空間解析のワークフローについては、references/graphs.md を参照してください。

4. 機械学習

核検出、セグメンテーション、分類のための深層学習モデルをトレーニングし、デプロイします。PathML は、PyTorch に加えて、事前構築済みモデル（HoVer-Net、HACTNet）、カスタム DataLoader、推論用 ONNX を統合しています。

主なモデル：

• HoVer-Net - 核のセグメンテーションと分類を同時に実行
• HACTNet - 階層的な細胞型分類

参照先： モデルのトレーニング、評価、推論のワークフロー、および公開データセットの扱いについては、references/machine_learning.md を参照してください。

5. 多重パラメータイメージング

CODEX、Vectra、MERFISH、その他の多重イメージングプラットフォームの空間プロテオミクスおよび遺伝子発現データを解析します。PathML は、多重パラメータデータの処理、Mesmer による細胞セグメンテーション、定量化ワークフローのための専用スライドクラスと変換処理を提供します。

参照： CODEX/Vectra のワークフロー、細胞セグメンテーション、マーカー定量化、AnnData との統合については、references/multiparametric.md を参照してください。

6. データ管理

HDF5 形式を使用して、大規模な病理データセットを効率的に保存、管理します。PathML は、機械学習ワークフローに最適化された統合ストレージ構造で、タイル、マスク、メタデータ、抽出済み特徴量を扱います。

参照： HDF5 との統合、タイル管理、データセットの整理、バッチ処理の方法については、references/data_management.md を参照してください。

クイックスタート

インストール

PathML では、まずネイティブ依存関係である OpenSlide と JDK（Bio-Formats は JPype/javabridge 経由で実行されます）が必要です。そのため、メンテナーは conda 環境を推奨しています。純粋な pip インストールでは、これらのネイティブ依存関係で失敗することがよくあります。

PathML 専用の環境を用意してください。PathML 3.0.8 では、科学計算スタックの多くが、特定のバージョンまたは上限付きのバージョンに固定されているためです。

PathML 3.0.8 で固定	他の環境での現行バージョン
numpy<2	2.5.x
pandas<=2.1.4	3.0.x
scanpy==1.9.6, anndata<=0.10.3	scanpy 1.12.x, anndata 0.13.x
scikit-image<=0.22.0, networkx<=3.2.1, h5py==3.10.0	いずれも新しいバージョン
torch==2.12.0, torch-geometric==2.8.0	torch 2.14.x

PathML を alterlab-scanpy または alterlab-squidpy-spatial と同じ環境にインストールすると、依存関係の解決に失敗するか、これらのスキルのスタックが警告なくダウングレードされます。両方のバージョン固定を満たそうとするのではなく、環境間ではファイル（PathML が書き出した HDF5/AnnData を現行の scanpy 環境で読み込むなど）で結果を受け渡してください。

# In a dedicated env, with OpenSlide and a JDK already installed.
uv venv .venv-pathml && source .venv-pathml/bin/activate
uv pip install pathml

基本的なワークフローの例

from pathml.core import HESlide
from pathml.preprocessing import Pipeline, StainNormalizationHE, TissueDetectionHE

# Load a whole-slide image. Use the HESlide convenience class for H&E,
# or SlideData(filepath=..., slide_type=types.HE) for the generic constructor.
# (There is no SlideData.from_slide.)
wsi = HESlide("path/to/slide.svs", name="example")

# Create preprocessing pipeline
pipeline = Pipeline([
    TissueDetectionHE(),
    StainNormalizationHE(target="normalize", stain_estimation_method="macenko"),
])

# Run the pipeline on the slide (SlideData.run handles tiling + transforms)
wsi.run(pipeline)

# Access processed tiles
for tile in wsi.tiles:
    processed_image = tile.image
    tissue_mask = tile.masks["tissue"]

一般的なワークフロー

H&E 画像解析：

1. 適切なスライドクラスを使用して WSI を読み込む
2. 組織検出と染色正規化を適用する
3. 核検出を実行するか、セグメンテーションモデルを学習する
4. 特徴量を抽出し、空間グラフを構築する
5. 下流解析を実施する

多重パラメータイメージング（CODEX）：

1. CODEXSlide を使用して CODEX スライドを読み込む
2. CollapseRunsCODEX を使用して複数ランのチャンネルデータを統合する
3. SegmentMIF（Mesmer）を使用して細胞をセグメント化する
4. QuantifyMIF を使用して細胞ごとのマーカー発現量を定量化する
5. slide.counts から生成された AnnData を読み込み、単一細胞解析を行う

ML モデルの学習：

1. pathml.datasets の DataModule（例：PanNukeDataModule）または TileDataset を使用してデータを準備する
2. 標準的な PyTorch ループで HoVerNet（または別のモデル）を学習する
3. post_process_batch_hovernet で予測結果を後処理する
4. 保留したテストセットで評価する
5. 必要に応じて推論用に ONNX へエクスポートする

リファレンスファイル

API、ワークフロー、注意点の詳細については、該当するリファレンスを読み込んでください。

• references/image_loading.md - WSI の形式、スライドクラス、読み込み方法
• references/preprocessing.md - 変換処理カタログ、パイプラインの構築、染色正規化
• references/graphs.md - グラフ構築、特徴量抽出、空間解析
• references/machine_learning.md - HoVer-Net/HACTNet、学習、データセット、ONNX 推論
• references/multiparametric.md - CODEX/Vectra/多重 IF、細胞セグメンテーション、定量化
• references/data_management.md - h5path ストレージ、タイル管理、バッチ処理

PathML の API はリリースごとに変わるため、リファレンスのコードはワークフローのひな型として扱い、使用中のバージョンの正確なクラス名やメソッド名を、python -c "import pathml; print(pathml.__version__)" および https://pathml.readthedocs.io/ の公式 API ドキュメントで確認してください。