pathml

PathML

対象範囲と安全上の境界

PathML は、ローカルでの計算病理学研究に使用してください。これはベータ版の研究用ソフトウェアであり、検証済みの医療機器、診断システム、臨床意思決定支援ツール、または病理医の代替ではありません。患者の診断、グレード判定、ステージ判定、治療に出力を使用しないでください。

病理ファイルには、顔、ラベル、受付番号、患者識別情報、DICOM タグ、ファイル名、または関連する臨床データが含まれる場合があります。処理を始める前に、次の手順を実施してください。

1. 承認、同意／免除、データ利用規約、および所属機関のポリシーを確認してください。
2. ピクセルとメタデータを匿名化し、再識別キーは分析ワークスペースの外部に保管してください。
3. 仮名の patient_id、slide_id、specimen_id の値を使用してください。ファイル名、ログ、.h5path ラベル、モデルカード、レポートに直接識別情報を含めないでください。
4. 入力、中間データ、出力は、承認済みのローカル暗号化ストレージに保管してください。
5. タイル分割や前処理の適用を行う前に、患者単位（次にスライド単位）でデータを分割してください。

バージョンの基準、2026-07-23 に確認

• インストール可能な安定版リリース： PyPI の pathml==3.0.5、2026-03-24 公開。
• v3.0.5 のリリースノートには、Python 3.10-3.12 と 3.9 のサポート終了が記載されています。PyPI では Requires-Python が宣言されておらず、古い 3.8 の分類情報も残っているため、リリースの記載に従い、実際の環境でテストしてください。
• GitHub リリースとして v3.0.6（2026-04-14）と v3.0.7（2026-07-09）が存在しますが、このレビュー時点で PyPI にそれらのアーティファクトはありません。v3.0.7 では Torch／TorchVision／torch-geometric と ONNX のエクスポートコードが更新されています。これらのソース依存関係を 3.0.5 のホイールと混在させないでください。
• ReadTheDocs の /latest は、自身を 3.0.5 と示しています。ここにある例は、バージョン指定のないスニペットではなく、v3.0.5 タグと PyPI のホイールメタデータに照らして確認済みです。
• このスキルは MIT ライセンスです。PathML 自体は GPL-2.0 で、上流には商用ライセンスの選択肢があります。再配布する前に上流の規約を確認してください。

再現可能なインストール

プロジェクトで別の対応インタープリターがテスト済みでない限り、Python 3.11 を使用してください。

uv venv --python 3.11
source .venv/bin/activate
uv pip install "pathml==3.0.5"
python -c "import importlib.metadata as m; print(m.version('pathml'))"

PathML 3.0.5 ではパッケージのエクストラは宣言されていません。pathml[all] は使用しないでください。基本ディストリビューションでは、Torch 2.8.0、ONNX 1.17.0、ONNX Runtime 1.17.x、OpenSlide Python 1.3.1、python-bioformats 4.1.0、python-javabridge 4.0.4 など、多数の科学技術／ML スタックのバージョンが固定されています。

uv コマンドを実行する前に、ネイティブの前提条件をインストールしてください。

# Debian/Ubuntu
sudo apt-get install openslide-tools gcc g++ libblas-dev liblapack-dev openjdk-17-jdk

# macOS
brew install openslide openjdk@17

# Windows OpenSlide option documented upstream
vcpkg install openslide

幅広い多次元フォーマットのバックエンドには Java／Bio-Formats が必要です。OpenSlide は、一般的な明視野 WSI フォーマットをより効率的に処理します。CUDA は任意ですが、固定された PyTorch ビルドに適合させる必要があります。CUDA ホイールを推測で選ぶのではなく、PyTorch のプラットフォームセレクターに従ってください。references/image_loading.md を参照してください。

安定した最小限のワークフロー

PathML 3.0.5 では、スライドの便利なクラスと SlideData.run() を使用します。SlideData.from_slide() は提供されておらず、Pipeline に run() はありません。

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

slide = HESlide("data/pseudonymous_slide.svs", backend="openslide")
pipeline = Pipeline(
    [
        BoxBlur(kernel_size=5),
        TissueDetectionHE(mask_name="tissue", min_region_size=5000),
    ]
)
slide.run(
    pipeline,
    distributed=False,
    tile_size=512,
    tile_stride=512,
    level=0,
    tile_pad=False,
)
slide.write("derived/pseudonymous_slide.h5path")

全件を実行する前に、上限を設けた手動サンプルから始めてください。

from itertools import islice

for tile in islice(slide.generate_tiles(shape=512, stride=512, level=0), 8):
    pipeline.apply(tile)
    assert tile.masks["tissue"].shape[:2] == tile.image.shape[:2]

タイルでは、選択したピラミッドレベルにおける座標に (i, j) = (行, 列) を使用します。OpenSlide の場合、PathML は内部でこれらをレベル 0 の座標に対応付けます。レベルとダウンサンプル値を記録し、後続の処理で明示的に (x, y) またはマイクロメートルに変換してください。

研究ワークフロー

1. ローカルで目録を作成します。 マニフェストを検証し、URL／シンボリックリンクを拒否して、許可リストにある技術メタデータのみを確認し、識別子を削除します。
2. 分割を確定します。 重複するタイル、グラフ、正規化参照情報、特徴量を生成する前に、すべての患者とその全スライドを1つの分割に割り当てます。
3. 上限を計画します。 タイル数、RAM、出力サイズ、パイプラインの各段階を見積もります。
4. 前処理を試験します。 代表的な学習スライドで、組織マスク、空白／アーティファクトのラベル、染色の挙動、端のパディング、マスクが空の場合の処理を確認します。テストスライドを基に調整しないでください。
5. 実行し、座標を保持します。 タイルのレベル、(i, j)、ダウンサンプル率、MPP、マスク名、QC の判定、失敗またはスキップされたタイルを保持します。
6. 空間データを慎重に構築します。 チャネル順、物理単位、インスタンスラベル、ノード特徴量の対応関係、グラフエッジ、細胞と組織の割り当てを検証します。
7. 上限を設けてバッチ推論します。 不明な pickle チェックポイントを読み込まずに、モデルの来歴とチェックサムを確認します。予測をスライド／タイルの座標と関連付け、文書化されたルールで重複領域を統合します。
8. 来歴と制限を報告します。 パッケージロック、ソースハッシュ、スキャナー、染色、パラメーター、シード、分割マニフェスト、モデルカード、除外項目、QC を含めます。

ネットワーク接続を既定で無効にし、明示的な同意を必須にする

エンドポイントと開示事項を提示したうえでユーザーが明示的に許可しない限り、ダウンロード機能を持つクラスをインスタンス化したり、データセットの download=True を設定したりしないでください。

• SegmentMIFRemote は、構築時に https://huggingface.co/pathml/test/resolve/main/mesmer.onnx から ONNX ファイルをダウンロードし、その後ローカルで推論を実行します。安定版のソースでは、画像ピクセルはアップロードされません。それでもリクエストにより、IP アドレスやヘッダーなどのネットワークメタデータが開示され、temp.onnx が作成されます。組み込みのチェックサム機能やオフラインフラグはありません。
• 非推奨の SegmentMIF はローカルの DeepCell Mesmer をインポートしますが、DeepCell のモデル初期化には別途用意された重みが必要になる場合があります。これは PathML のエクストラではなく、推奨される安定版 API でもありません。
• RemoteTestHoverNet は Hugging Face からモデルをダウンロードします。
• PanNukeDataModule(download=True) は Warwick に接続し、DeepFocusDataModule は Zenodo に接続します。どちらも既定値は download=False です。

今後、ホストされた予測を呼び出す前には、正確な送信先、ピクセルのチャンネル／領域、メタデータ、識別子、保持期間、法的根拠、安全対策を明示してください。明示的な同意を得て、既定では PHI を決して送信しないでください。レビュー済みでチェックサム付きのローカルモデルアーティファクトとローカル推論を優先してください。

モデルコードのセキュリティ

• PyTorch の model.eval() はモジュールを評価モードにするものであり、Python の危険な組み込み評価関数ではありません。Python の動的な評価や実行は決して使用しないでください。
• ローカルファイルに pathml.py、torch.py、onnx.py や標準ライブラリと同じ名前を付けないでください。モジュールのシャドーイングにより、インポートが気付かないうちに変わることがあります。
• PathML の EntityDataset は weights_only=False で .pt オブジェクトを読み込みます。信頼できないグラフ／チェックポイントは決して開かないでください。pickle ベースのパイプラインと .pt ファイルは実行可能コードとして扱ってください。
• ONNX は pickle より安全ですが、本質的に信頼できるわけではありません。ソース、SHA-256、想定される入出力スキーマ、ファイルサイズ、ランタイムの制限を確認し、サードパーティ製モデルには隔離環境を使用してください。

同梱のローカル CLI

すべてのヘルパーは URL とシンボリックリンクを拒否し、入力／処理量に上限を設け、厳格な JSON を使用し、ネットワークアクセスを回避します。また、--help の実行に PathML のインポートは不要です。

python scripts/slide_manifest.py validate --manifest manifest.csv --root .
python scripts/slide_manifest.py inspect --slide data/example.svs --root .
python scripts/plan_pipeline.py --width 100000 --height 80000 --tile-size 512 --stride 512
python scripts/image_qc.py synthetic --width 256 --height 256
python scripts/validate_spatial_schema.py graph --input graph.json --root .
python scripts/validate_spatial_schema.py multiplex --input cells.csv --root .
python scripts/plan_inference.py --tile-count 4000 --batch-size 16 --height 256 --width 256

推論プランナーは数値または上限付きの JSON モデルカードのみを読み込み、モデルフレームワークのインポートやチェックポイントのオープンは行いません。

詳細なリファレンス

• references/image_loading.md — スライドのクラス、バックエンド、形式、レベル、座標、技術メタデータ、プライバシー。
• references/preprocessing.md — 安定した変換、マスク／QC、染色処理、パイプラインの実行、データリークの防止。
• references/data_management.md — .h5path、マニフェスト、データセット、来歴、分割、安全なダウンロード。
• references/multiparametric.md — 多次元レイアウト、CODEX／Vectra、定量化、AnnData、DeepCell／Mesmer、ネットワークへの情報開示。
• references/graphs.md — インスタンスマップ、特徴量の整列、KNN／RAG／HACT グラフ、空間単位、スキーマ、検証。
• references/machine_learning.md — HoVer-Net／HACTNet、ローカル ONNX 推論、バッチ処理、チェックポイントの信頼性、評価、モデルの来歴。

主な情報源

すべて 2026-07-23 に確認済み：

• PyPI メタデータ：https://pypi.org/project/pathml/3.0.5/
• 安定版ソースタグ：https://github.com/Dana-Farber-AIOS/pathml/tree/v3.0.5
• リリース：https://github.com/Dana-Farber-AIOS/pathml/releases
• 安定版ドキュメント：https://pathml.readthedocs.io/en/stable/
• Rosenthal et al. (2022), PathML toolkit： https://doi.org/10.1158/1541-7786.MCR-21-0665
• Omar et al. (2025), multiplex workflows： https://doi.org/10.1016/j.labinv.2025.104220

エージェントの運用手順

1. 環境を確認します。 データへのアクセス権限、匿名化の状態、適用される規制やプロトコルを確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 最初に匿名化済みサンプルまたは合成データで作業します。
4. 上記の手順とリファレンスに従って、タスク全体を実行します。
5. 結果を検証します。 出力を臨床ガイドラインと報告基準に照らして確認し、臨床に関する内容は有資格者にレビューしてもらいます。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定事項を明記します。

発生した場合	対応
データに患者を特定できる情報が含まれているように見える	それ以上の処理を行う前に停止し、ユーザーに確認します。
手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

完全性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• 出力は有資格者の意思決定を支援するものであり、医療上の助言ではありません。診断や指示として提示してはいけません。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データまたは患者データに触れる操作、取り消せない操作の前には確認してください。

関連スキル

• histolab：histolab Python ライブラリ（OpenSlide）を使用して、H&E 全スライド画像からタイルを抽出し、前処理を行います。スライドの検査、組織マスクなどを扱います…
• clinical-decision-support：研究目的に限定した臨床意思決定支援の評価、エビデンスプロファイル、コホート、生存分析、バイオマーカー／モデル、プライバシーなどを準備し、検証します…
• ray-data：ML ワークロード向けのスケーラブルなデータ処理。