pathml

PathML

范围与安全边界

使用 PathML 进行本地计算病理研究。这是处于 Beta 阶段的研究软件，不是经过验证的医疗器械、诊断系统、临床决策支持工具，也不能替代病理学家。请勿使用其输出诊断、分级、分期或治疗患者。

病理文件可能包含人脸、标签、登记号、患者标识符、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 wheel 混用。
• ReadTheDocs /latest 标明自身版本为 3.0.5。此处示例已根据 v3.0.5 标签和 PyPI wheel 元数据核验，而非依据未指定版本的代码片段。
• 本技能采用 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 未声明任何软件包 extras：请勿使用 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。

运行 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 构建匹配；请使用 PyTorch 的平台选择器，不要猜测 CUDA wheel。请参阅 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. 固定数据集划分。 在生成重叠图块、图、归一化参考或特征之前，将每位患者及其所有切片分配到同一个数据集划分中。
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、避免网络访问，且无需导入 PathML 即可运行 --help：

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 等（2022），PathML 工具包： https://doi.org/10.1158/1541-7786.MCR-21-0665
• Omar 等（2025），多重检测工作流： https://doi.org/10.1016/j.labinv.2025.104220

Agent 操作流程

1. 检查环境。 确认数据访问权限、去标识化状态以及适用的法规或规程。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值都应询问确认，不要猜测。
3. 先运行小规模版本。 先使用去标识化样本或合成数据进行处理。
4. 执行完整任务，使用上述说明和参考资料。
5. 验证结果。 根据临床指南和报告标准检查输出；临床内容须由具备资质的人员审核。
6. 报告。 说明运行内容（版本、命令、参数）、检查内容以及仍不确定的事项。

如果出现这种情况	请这样处理
数据似乎包含可识别患者身份的信息	停止处理，并在继续之前询问用户。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自带的文档（help()、--help、官方文档），调整操作并告知用户。切勿捏造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明假设。

完整性规则

• 切勿编造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请明确说明。
• 输出仅供具备资质的专业人员辅助决策，不构成医疗建议；切勿将其作为诊断或医嘱呈现。
• 此处与特定版本相关的细节可能已过时：请对照已安装版本的官方文档确认。
• 涉及费用、占用共享 GPU 或云配额、接触个人或患者数据，或无法撤销的操作前，请先征求同意。

相关技能

• histolab：使用 histolab Python 库（OpenSlide）提取图块并预处理 H&E 全视野切片，涵盖切片检查、组织掩码……
• clinical-decision-support：准备并验证仅用于研究的临床决策支持评估、证据档案、队列、生存分析、生物标志物/模型、隐私及……
• ray-data：用于 ML 工作负载的可扩展数据处理。