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/）就足够了，无需凭据。