pyhealth

PyHealth：医疗 AI 工具包

概述

PyHealth 是一个面向医疗 AI 的综合性 Python 库，为临床机器学习提供专用工具、模型和数据集。在开发医疗预测模型、处理临床数据、使用医疗编码系统或在医疗场景中部署 AI 解决方案时，可使用本技能。

何时使用本技能

在以下情况下调用本技能：

• 处理医疗数据集：MIMIC-III、MIMIC-IV、eICU、OMOP、睡眠 EEG 数据、医学图像
• 临床预测任务：死亡率预测、再入院、住院时长、用药推荐
• 医疗编码：在 ICD-9/10、NDC、RxNorm、ATC 编码系统之间转换
• 处理临床数据：序列事件、生理信号、临床文本、医学图像
• 实现医疗模型：RETAIN、SafeDrug、GAMENet、StageNet、用于 EHR 的 Transformer
• 评估临床模型：公平性指标、校准、可解释性、不确定性量化

核心能力

PyHealth 通过模块化的 5 阶段流水线运行，专为医疗 AI 优化：

1. 数据加载：通过标准化接口访问 10+ 个医疗数据集
2. 任务定义：应用 20+ 个预定义临床预测任务或创建自定义任务
3. 模型选择：从 33+ 个模型中选择（基线模型、深度学习、医疗专用）
4. 训练：训练时自动进行检查点保存、监控和评估
5. 部署：为临床使用进行校准、解释和验证

性能：处理医疗数据比 pandas 快 3 倍

快速开始工作流

from pyhealth.datasets import MIMIC4Dataset
from pyhealth.tasks import mortality_prediction_mimic4_fn
from pyhealth.datasets import split_by_patient, get_dataloader
from pyhealth.models import Transformer
from pyhealth.trainer import Trainer

# 1. Load dataset and set task
dataset = MIMIC4Dataset(root="/path/to/data")
sample_dataset = dataset.set_task(mortality_prediction_mimic4_fn)

# 2. Split data
train, val, test = split_by_patient(sample_dataset, [0.7, 0.1, 0.2])

# 3. Create data loaders
train_loader = get_dataloader(train, batch_size=64, shuffle=True)
val_loader = get_dataloader(val, batch_size=64, shuffle=False)
test_loader = get_dataloader(test, batch_size=64, shuffle=False)

# 4. Initialize and train model
model = Transformer(
    dataset=sample_dataset,
    feature_keys=["diagnoses", "medications"],
    mode="binary",
    embedding_dim=128
)

trainer = Trainer(model=model, device="cuda")
trainer.train(
    train_dataloader=train_loader,
    val_dataloader=val_loader,
    epochs=50,
    monitor="pr_auc_score"
)

# 5. Evaluate
results = trainer.evaluate(test_loader)

详细文档

本技能包含按功能组织的全面参考文档。根据需要阅读特定参考文件：

1. 数据集与数据结构

文件：references/datasets.md

在以下情况阅读：

• 加载医疗数据集（MIMIC、eICU、OMOP、睡眠 EEG 等）
• 理解 Event、Patient、Visit 数据结构
• 处理不同数据类型（EHR、信号、图像、文本）
• 划分训练/验证/测试数据
• 使用 SampleDataset 进行任务特定格式化

关键主题：

• 核心数据结构（Event、Patient、Visit）
• 10+ 个可用数据集（EHR、生理信号、影像、文本）
• 数据加载与迭代
• 训练/验证/测试划分策略
• 大型数据集的性能优化

2. 医疗编码转换

文件：references/medical_coding.md

在以下情况阅读：

• 在医疗编码系统之间转换
• 处理诊断代码（ICD-9-CM、ICD-10-CM、CCS）
• 处理用药代码（NDC、RxNorm、ATC）
• 标准化操作代码（ICD-9-PROC、ICD-10-PROC）
• 将代码分组到临床类别
• 处理分层药物分类

关键主题：

• 用于系统内查询的 InnerMap
• 用于跨系统转换的 CrossMap
• 支持的编码系统（ICD、NDC、ATC、CCS、RxNorm）
• 代码标准化与层级遍历
• 按治疗类别进行药物分类
• 与数据集集成

3. 临床预测任务

文件：references/tasks.md

在以下情况阅读：

• 定义临床预测目标
• 使用预定义任务（死亡率、再入院、用药推荐）
• 处理基于 EHR、信号、影像或文本的任务
• 创建自定义预测任务
• 为模型设置输入/输出 schema
• 应用任务特定的过滤逻辑

关键主题：

• 20+ 个预定义临床任务
• EHR 任务（死亡率、再入院、住院时长、用药推荐）
• 信号任务（睡眠分期、EEG 分析、癫痫检测）
• 影像任务（COVID-19 胸部 X 光分类）
• 文本任务（医疗编码、专科分类）
• 自定义任务创建模式

4. 模型与架构

文件：references/models.md

阅读时机：

• 为临床预测选择模型
• 理解模型架构与能力
• 在通用模型与医疗专用模型之间进行选择
• 实现可解释模型（RETAIN、AdaCare）
• 处理用药推荐（SafeDrug、GAMENet）
• 将图神经网络用于医疗
• 配置模型超参数

关键主题：

• 33+ 个可用模型
• 通用：Logistic Regression、MLP、CNN、RNN、Transformer、GNN
• 医疗专用：RETAIN、SafeDrug、GAMENet、StageNet、AdaCare
• 按任务类型和数据类型选择模型
• 可解释性考量
• 计算资源需求
• 超参数调优指南

5. 数据预处理

文件：references/preprocessing.md

阅读时机：

• 为模型预处理临床数据
• 处理序列事件和时间序列数据
• 处理生理信号（EEG、ECG）
• 对化验值和生命体征进行归一化
• 为不同任务类型准备标签
• 构建特征词表
• 管理缺失数据和离群值

关键主题：

• 15+ 种处理器类型
• 序列处理（填充、截断）
• 信号处理（滤波、分段）
• 特征提取与编码
• 标签处理器（二分类、多分类、多标签、回归）
• 文本和图像预处理
• 常见预处理工作流

6. 训练与评估

文件：references/training_evaluation.md

阅读时机：

• 使用 Trainer 类训练模型
• 评估模型性能
• 计算临床指标
• 评估模型在不同人群间的公平性
• 校准预测以提高可靠性
• 量化预测不确定性
• 解释模型预测
• 为临床部署准备模型

关键主题：

• Trainer 类（训练、评估、推理）
• 用于二分类、多分类、多标签、回归任务的指标
• 用于偏差评估的公平性指标
• 校准方法（Platt scaling、temperature scaling）
• 不确定性量化（conformal prediction、MC dropout）
• 可解释性工具（注意力可视化、SHAP、ChEFER）
• 完整的训练流水线示例

安装

uv pip install pyhealth

要求：

• Python ≥ 3.7
• PyTorch ≥ 1.8
• NumPy、pandas、scikit-learn

常见用例

用例 1：ICU 死亡率预测

目标：预测重症监护病房中的患者死亡率

方法：

1. 加载 MIMIC-IV 数据集 → 阅读 references/datasets.md
2. 应用死亡率预测任务 → 阅读 references/tasks.md
3. 选择可解释模型（RETAIN）→ 阅读 references/models.md
4. 训练并评估 → 阅读 references/training_evaluation.md
5. 解释预测结果以供临床使用 → 阅读 references/training_evaluation.md

用例 2：安全用药推荐

目标：推荐药物，同时避免药物-药物相互作用

方法：

1. 加载 EHR 数据集（MIMIC-IV 或 OMOP）→ 阅读 references/datasets.md
2. 应用药物推荐任务 → 阅读 references/tasks.md
3. 使用带 DDI 约束的 SafeDrug 模型 → 阅读 references/models.md
4. 预处理药物编码 → 阅读 references/medical_coding.md
5. 使用多标签指标进行评估 → 阅读 references/training_evaluation.md

用例 3：医院再入院预测

目标：识别有 30 天再入院风险的患者

方法：

1. 加载多站点 EHR 数据（eICU 或 OMOP）→ 阅读 references/datasets.md
2. 应用再入院预测任务 → 阅读 references/tasks.md
3. 在预处理中处理类别不平衡 → 阅读 references/preprocessing.md
4. 训练 Transformer 模型 → 阅读 references/models.md
5. 校准预测并评估公平性 → 阅读 references/training_evaluation.md

用例 4：睡眠障碍诊断

目标：从 EEG 信号中对睡眠阶段进行分类

方法：

1. 加载睡眠 EEG 数据集（SleepEDF、SHHS）→ 阅读 references/datasets.md
2. 应用睡眠分期任务 → 阅读 references/tasks.md
3. 预处理 EEG 信号（滤波、分段）→ 阅读 references/preprocessing.md
4. 训练 CNN 或 RNN 模型 → 阅读 references/models.md
5. 评估各阶段性能 → 阅读 references/training_evaluation.md

用例 5：医学编码转换

目标：在不同编码系统之间标准化诊断

方法：

1. 阅读 references/medical_coding.md 获取全面指导
2. 使用 CrossMap 在 ICD-9、ICD-10、CCS 之间转换
3. 将编码分组为具有临床意义的类别
4. 与数据集处理集成

用例 6：临床文本转 ICD 编码

目标：从临床记录中自动分配 ICD 编码

方法：

1. 加载带临床文本的 MIMIC-III → 阅读 references/datasets.md
2. 应用 ICD 编码任务 → 阅读 references/tasks.md
3. 预处理临床文本 → 阅读 references/preprocessing.md
4. 使用 TransformersModel（ClinicalBERT）→ 阅读 references/models.md
5. 使用多标签指标评估 → 阅读 references/training_evaluation.md

最佳实践

数据处理

1. 始终按患者划分：确保没有患者出现在多个划分中，防止数据泄漏

   from pyhealth.datasets import split_by_patient
   train, val, test = split_by_patient(dataset, [0.7, 0.1, 0.2])
   

2. 检查数据集统计信息：在建模前了解你的数据

   print(dataset.stats())  # Patients, visits, events, code distributions
   

3. 使用适当的预处理：将处理器与数据类型匹配（参见 references/preprocessing.md）

模型开发

1. 从基线开始：用简单模型建立基线性能

   • 二分类/多分类任务使用 Logistic Regression
   • 初步深度学习基线使用 MLP

2. 选择适合任务的模型：

   • 需要可解释性 → RETAIN、AdaCare
   • 药物推荐 → SafeDrug、GAMENet
   • 长序列 → Transformer
   • 图关系 → GNN

3. 监控验证指标：使用适合任务的指标并处理类别不平衡

   • 二分类：AUROC、AUPRC（尤其针对罕见事件）
   • 多分类：macro-F1（用于不平衡情况）、weighted-F1
   • 多标签：Jaccard、example-F1
   • 回归：MAE、RMSE

临床部署

1. 校准预测：确保概率可靠（参见 references/training_evaluation.md）

2. 评估公平性：跨人口群体进行评估以检测偏差

3. 量化不确定性：为预测提供置信度估计

4. 解释预测：使用注意力权重、SHAP 或 ChEFER 以建立临床信任

5. 彻底验证：使用来自不同时间段或机构的留出测试集

局限性与注意事项

数据要求

• 大型数据集：深度学习模型需要足够的数据（数千名患者）
• 数据质量：缺失数据和编码错误会影响性能
• 时间一致性：在需要时确保训练/测试划分遵循时间顺序

临床验证

• 外部验证：在不同医院/系统的数据上进行测试
• 前瞻性评估：在部署前于真实临床环境中验证
• 临床审查：让临床医生审查预测和解释
• 伦理考量：处理隐私（HIPAA/GDPR）、公平性和安全性

计算资源

• 推荐使用 GPU：以高效训练深度学习模型
• 内存要求：大型数据集可能需要 16GB+ RAM
• 存储：医疗数据集可能达到 10s-100s GB

故障排除

常见问题

数据集出现 ImportError：

• 确保数据集文件已下载且路径正确
• 检查 PyHealth 版本兼容性

内存不足：

• 减小 batch size
• 缩短序列长度（max_seq_length）
• 使用梯度累积
• 分块处理数据

性能不佳：

• 检查类别不平衡并使用合适的指标（AUPRC 与 AUROC）
• 验证预处理（归一化、缺失数据处理）
• 增加模型容量或训练轮数
• 检查训练/测试划分中是否存在数据泄漏

训练缓慢：

• 使用 GPU（device="cuda"）
• 增大 batch size（如果内存允许）
• 缩短序列长度
• 使用更高效的模型（CNN 与 Transformer）

获取帮助

• 文档：https://pyhealth.readthedocs.io/
• GitHub Issues：https://github.com/sunlabuiuc/PyHealth/issues
• 教程：在线提供 7 个核心教程 + 5 个实用流水线

示例：完整工作流

# Complete mortality prediction pipeline
from pyhealth.datasets import MIMIC4Dataset
from pyhealth.tasks import mortality_prediction_mimic4_fn
from pyhealth.datasets import split_by_patient, get_dataloader
from pyhealth.models import RETAIN
from pyhealth.trainer import Trainer

# 1. Load dataset
print("Loading MIMIC-IV dataset...")
dataset = MIMIC4Dataset(root="/data/mimic4")
print(dataset.stats())

# 2. Define task
print("Setting mortality prediction task...")
sample_dataset = dataset.set_task(mortality_prediction_mimic4_fn)
print(f"Generated {len(sample_dataset)} samples")

# 3. Split data (by patient to prevent leakage)
print("Splitting data...")
train_ds, val_ds, test_ds = split_by_patient(
    sample_dataset, ratios=[0.7, 0.1, 0.2], seed=42
)

# 4. Create data loaders
train_loader = get_dataloader(train_ds, batch_size=64, shuffle=True)
val_loader = get_dataloader(val_ds, batch_size=64)
test_loader = get_dataloader(test_ds, batch_size=64)

# 5. Initialize interpretable model
print("Initializing RETAIN model...")
model = RETAIN(
    dataset=sample_dataset,
    feature_keys=["diagnoses", "procedures", "medications"],
    mode="binary",
    embedding_dim=128,
    hidden_dim=128
)

# 6. Train model
print("Training model...")
trainer = Trainer(model=model, device="cuda")
trainer.train(
    train_dataloader=train_loader,
    val_dataloader=val_loader,
    epochs=50,
    optimizer="Adam",
    learning_rate=1e-3,
    weight_decay=1e-5,
    monitor="pr_auc_score",  # Use AUPRC for imbalanced data
    monitor_criterion="max",
    save_path="./checkpoints/mortality_retain"
)

# 7. Evaluate on test set
print("Evaluating on test set...")
test_results = trainer.evaluate(
    test_loader,
    metrics=["accuracy", "precision", "recall", "f1_score",
             "roc_auc_score", "pr_auc_score"]
)

print("\nTest Results:")
for metric, value in test_results.items():
    print(f"  {metric}: {value:.4f}")

# 8. Get predictions with attention for interpretation
predictions = trainer.inference(
    test_loader,
    additional_outputs=["visit_attention", "feature_attention"],
    return_patient_ids=True
)

# 9. Analyze a high-risk patient
high_risk_idx = predictions["y_pred"].argmax()
patient_id = predictions["patient_ids"][high_risk_idx]
visit_attn = predictions["visit_attention"][high_risk_idx]
feature_attn = predictions["feature_attention"][high_risk_idx]

print(f"\nHigh-risk patient: {patient_id}")
print(f"Risk score: {predictions['y_pred'][high_risk_idx]:.3f}")
print(f"Most influential visit: {visit_attn.argmax()}")
print(f"Most important features: {feature_attn[visit_attn.argmax()].argsort()[-5:]}")

# 10. Save model for deployment
trainer.save("./models/mortality_retain_final.pt")
print("\nModel saved successfully!")

资源

有关每个组件的详细信息，请参阅 references/ 目录中的综合参考文件：

• datasets.md：数据结构、加载和划分（4,500 词）
• medical_coding.md：代码转换和标准化（3,800 词）
• tasks.md：临床预测任务和自定义任务创建（4,200 词）
• models.md：模型架构和选择指南（5,100 词）
• preprocessing.md：数据处理器和预处理工作流（4,600 词）
• training_evaluation.md：训练、指标、校准、可解释性（5,900 词）

综合文档总计：约 28,000 词，分布在多个模块化参考文件中。