pyhealth

PyHealth

PyHealth (https://pyhealth.dev/) 是一个用于临床深度学习的 Python 工具包。它提供了统一、模块化的流水线，涵盖电子健康记录（EHR）、生理信号和医学影像。

该库围绕一个 5 阶段流水线 构建：Dataset → Task → Model → Trainer → Metrics。每个阶段都可以替换，阶段间的接口则保持稳定。遵循这种流水线结构的代码易于组合；绕过它的代码通常会与该库格格不入。

何时使用此技能

在用户进行临床或医疗保健机器学习，且符合以下任一条件时，使用此技能：

• 用户提到了 PyHealth、MIMIC-III/IV、eICU、OMOP-CDM、EHRShot、SleepEDF、SHHS、ISRUC、COVID19-CXR、ChestX-ray14、TUEV/TUAB。
• 用户想要预测死亡率、再入院、住院时长、药物推荐、睡眠阶段、ICD 编码、EEG 事件或去标识化。
• 用户需要查询或交叉映射医学编码（ICD-9-CM、ICD-10-CM、ATC、NDC、RxNorm、CCS）。
• 用户拥有 EHR 格式的数据，并希望训练临床模型，但不想自己编写底层流程代码。

如果工作流符合 PyHealth 的 5 个阶段，PyHealth 就是合适的工具。如果用户只想在表格数据上使用通用 PyTorch，则无需此技能。

安装（uv）

PyHealth 2.0 需要 Python ≥ 3.12、< 3.14。使用 uv 管理环境——它更快且具有可复现性。

# Create a project with the right Python
uv init my-pyhealth-project
cd my-pyhealth-project
uv python pin 3.12

# Add PyHealth (this also pulls in PyTorch and friends)
uv add pyhealth

# Run scripts inside the env
uv run python train.py

对于不使用项目的一次性脚本，可使用 uv run --with pyhealth python script.py。对于旧版 1.x 系列（Python 3.9+），使用 uv add pyhealth==1.16。详细的安装说明、MIMIC 访问方式以及 GPU/CPU 设备提示，请参阅 references/installation.md。

5 阶段流水线

完整的流水线通常少于 20 行。这是标准结构——请从这里开始，再按需修改各部分：

from pyhealth.datasets import MIMIC3Dataset, split_by_patient, get_dataloader
from pyhealth.tasks import MortalityPredictionMIMIC3
from pyhealth.models import Transformer
from pyhealth.trainer import Trainer
from pyhealth.metrics.binary import binary_metrics_fn

# 1. Dataset — raw patient registry
base = MIMIC3Dataset(
    root="https://storage.googleapis.com/pyhealth/Synthetic_MIMIC-III/",
    tables=["DIAGNOSES_ICD", "PROCEDURES_ICD", "PRESCRIPTIONS"],
)

# 2. Task — converts patients into supervised samples
samples = base.set_task(MortalityPredictionMIMIC3())

# 3. Split + DataLoaders (split by patient to avoid leakage)
train_ds, val_ds, test_ds = split_by_patient(samples, [0.8, 0.1, 0.1])
train_loader = get_dataloader(train_ds, batch_size=32, shuffle=True)
val_loader   = get_dataloader(val_ds,   batch_size=32, shuffle=False)
test_loader  = get_dataloader(test_ds,  batch_size=32, shuffle=False)

# 4. Model — must be passed the SampleDataset, not the BaseDataset
model = Transformer(dataset=samples)

# 5. Train + evaluate
trainer = Trainer(model=model)
trainer.train(
    train_dataloader=train_loader,
    val_dataloader=val_loader,
    epochs=50,
    monitor="pr_auc",
)

y_true, y_prob, _ = trainer.inference(test_loader)
print(binary_metrics_fn(y_true, y_prob, metrics=["pr_auc", "roc_auc"]))

可直接复制粘贴的入门示例见 assets/starter_pipeline.py。

需要正确处理的关键事项

以下是 PyHealth 代码中最常见的错误。编写流水线前，请先牢记：

1. 模型接收的是 SampleDataset，而不是 BaseDataset。 MIMIC3Dataset(...) 返回一个 BaseDataset（可查询的患者注册表）。只有调用 .set_task(task) 后，才能获得模型、拆分器和 DataLoader 所需的 SampleDataset。如果将 base 传给模型，模型会报错或行为异常。

2. 始终按患者（或就诊）拆分，而不是按样本拆分。 随机按样本拆分会导致训练集和测试集之间的信息泄漏，因为同一患者可能同时出现在两者中。患者级预测请使用 split_by_patient，仅在就诊相互独立时使用 split_by_visit。

3. 任务必须与数据集匹配。 任务依赖于特定数据集：MortalityPredictionMIMIC3 不能用于 MIMIC-IV——请改用 MortalityPredictionMIMIC4 或 InHospitalMortalityMIMIC4。完整映射见 references/tasks.md。

4. 选择与任务类型匹配的 monitor。 二分类使用 "pr_auc" 或 "roc_auc"。多标签（药物推荐）使用 "pr_auc_samples" 或 "jaccard_samples"。多分类使用 "accuracy" 或 "f1_macro"。监控指标选错 → 检查点选择会保存错误的训练轮次。

5. MIMIC-IV 使用 ehr_root=，而不是 root=。 这是数据集构造函数中唯一不一致的地方。

6. 如需确保工作可复现，请将 cache_dir= 指向持久化位置。 PyHealth 会缓存解析后的数据集；如果不设置 cache_dir，每次运行都要重新解析。

如何使用此技能

PyHealth 的 API 范围很广，不必一次性全部加载。请根据用户的任务阅读对应的参考文件：

如果用户询问……	阅读
安装、环境设置、MIMIC 访问、GPU	references/installation.md
应使用哪个数据集类、加载方式、数据集拆分	references/datasets.md
应选择哪种预测任务（死亡率、再入院、药物推荐、睡眠等）	references/tasks.md
如何选择模型架构、特定模型的参数	references/models.md
查询或交叉映射 ICD/ATC/NDC/RxNorm/CCS 编码、分词器	references/medcode.md
常见场景的端到端方案	references/examples.md

对于多步骤任务（例如“在 MIMIC-IV 上构建药物推荐流程”），请同时阅读 tasks.md、models.md 和 examples.md，它们相互参照。

风格说明

编写简洁、符合 PyHealth 惯例的代码。该库有自己的设计理念；请充分利用其抽象，而不是用原始 PyTorch 重新实现。如果你发现自己在编写自定义训练循环，请考虑 Trainer 是否能胜任——它几乎总能胜任，还能免费处理检查点、日志记录和最佳模型选择。

如果用户拥有私有 MIMIC 访问权限，请指引他们使用本地 CSV 根目录；对于演示和学习，合成 MIMIC-III 数据集（https://storage.googleapis.com/pyhealth/Synthetic_MIMIC-III/）已足够，且无需凭据。

Agent 操作流程

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

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

诚信规则

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

相关技能

• transformers：使用 Hugging Face Transformers 加载 Hub 模型、运行管道推理、进行文本生成，以及在 NLP、视觉、音频等任务上使用 Trainer 微调……