pyhealth

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

用途

PyHealth 适用于临床/医疗机器学习场景。当用户涉及以下情况时可以使用：提到 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 形态的数据并希望训练临床模型而无需自行编写底层管道。如果只是想在表格数据上使用通用 PyTorch，则不需要此技能。

主要能力：五阶段流水线

库围绕 Dataset → Task → Model → Trainer → Metrics 五阶段构建，每个阶段可替换，阶段间接口稳定。遵循该流水线形态的代码组合良好；绕过它的代码通常会与库产生冲突。

一个完整流水线通常少于 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 — 原始患者登记
base = MIMIC3Dataset(
    root="https://storage.googleapis.com/pyhealth/Synthetic_MIMIC-III/",
    tables=["DIAGNOSES_ICD", "PROCEDURES_ICD", "PRESCRIPTIONS"],
)

# 2. Task — 将患者转换为监督样本
samples = base.set_task(MortalityPredictionMIMIC3())

# 3. 划分 + DataLoader（按患者划分以避免泄漏）
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 — 必须传入 SampleDataset，而非 BaseDataset
model = Transformer(dataset=samples)

# 5. 训练 + 评估
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"]))

使用方式

安装（uv）

PyHealth 2.0 要求 Python ≥ 3.12 且 < 3.14。推荐使用 uv 管理环境，更快且可复现。

# 使用正确的 Python 创建项目
uv init my-pyhealth-project
cd my-pyhealth-project
uv python pin 3.12

# 添加 PyHealth（同时会拉取 PyTorch 等依赖）
uv add pyhealth

# 在环境中运行脚本
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。

关键注意事项

模型接收 SampleDataset，而非 BaseDataset。MIMIC3Dataset(...) 返回 BaseDataset（可查询的患者登记），只有调用 .set_task(task) 后才得到 SampleDataset，模型、划分器和 DataLoader 都期望后者。
始终按患者（或就诊）划分，而非按样本。随机样本级划分会因同一患者同时出现在训练/测试中而泄漏信息。患者级预测用 split_by_patient，仅当就诊相互独立时才用 split_by_visit。
任务需与数据集匹配。任务是数据集特定的：MortalityPredictionMIMIC3 不能用于 MIMIC-IV，应使用 MortalityPredictionMIMIC4 或 InHospitalMortalityMIMIC4。完整映射见 references/tasks.md。
根据任务类型选择 monitor。二分类用 "pr_auc" 或 "roc_auc"；多标签（药物推荐）用 "pr_auc_samples" 或 "jaccard_samples"；多分类用 "accuracy" 或 "f1_macro"。monitor 选错会导致检查点选择保存错误的 epoch。
MIMIC-IV 使用 ehr_root=，而非 root=。这是数据集构造函数中唯一的不一致之处。
为可复现工作，将 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/）即可，无需认证。

适用场景

临床/医疗机器学习研究，尤其是基于 EHR 的预测建模。
需要快速搭建死亡率、再入院、住院时长、药物推荐、睡眠分期、ICD 编码、EEG 事件等任务的流水线。
需要查询或交叉映射医学编码。
拥有 EHR 形态数据并希望避免自行编写底层管道。

限制

仅当工作流符合其五阶段流水线时才是合适工具；通用表格数据的 PyTorch 任务不需要它。
版本特定细节可能过时，需对照已安装版本的官方文档确认。
输出是面向合格专业人员的决策支持，不是医疗建议，绝不能作为诊断或医嘱呈现。
涉及费用、共享 GPU/云配额、个人或患者数据、不可撤销操作时，需先询问。
若数据疑似包含可识别患者信息，应停止并询问用户。
若指令中的函数、标志或端点在实际安装版本中缺失，应查阅该版本自身文档并告知用户，绝不虚构 API。
若必需输入、标识符或参数不明确，应询问用户或明确说明假设后再运行。
绝不捏造结果、参数、标识符、引用或统计。无法运行或验证时应如实说明。

智能体操作流程

检查环境：确认数据访问权限、去标识化状态及适用法规或协议。
确定输入：从数据或用户处确认格式、标识符和参数。对任何会改变结果的取值应询问而非猜测。
先运行小版本：先在去标识化样本或合成数据上工作。
使用上述说明和参考执行完整任务。
验证结果：对照临床指南和报告标准检查输出；由合格人员审查临床内容。
报告：说明运行了什么（版本、命令、参数）、检查了什么、还有什么不确定。

技能介绍

用途