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 提供六大功能领域，详情记录在参考文件中：

1. 图像加载与格式

从 160 多种专有格式加载全切片图像，包括 Aperio SVS、Hamamatsu NDPI、Leica SCN、Zeiss ZVI、DICOM 和 OME-TIFF。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 进行细胞分割以及执行定量工作流。

参见： references/multiparametric.md，了解 CODEX/Vectra 工作流、细胞分割、标记物定量以及与 AnnData 的集成。

6. 数据管理

使用 HDF5 格式高效存储和管理大型病理学数据集。PathML 以统一的存储结构处理图块、掩码、元数据和提取的特征，并针对机器学习工作流进行了优化。

参见： references/data_management.md，了解 HDF5 集成、图块管理、数据集组织和批处理策略。

快速开始

安装

PathML 需要先安装原生依赖项——OpenSlide 和 JDK（Bio-Formats 通过 JPype/javabridge 驱动）——因此维护者建议使用 conda 环境；纯 pip 安装通常会在这些原生依赖项上失败。

请为 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__)"）以及官方 API 文档 https://pathml.readthedocs.io/ 确认准确的类名和方法名。