alterlab-pyhealth

PyHealth：医療 AI ツールキット

概要

PyHealth は、臨床機械学習向けにデータセット、タスク定義、モデル、トレーナー、医療コードユーティリティを提供する、医療 AI 用の Python ライブラリです。このスキルは、医療予測モデルの開発、臨床データの処理、医療コーディングシステムの利用、または臨床で使用する前のモデル検証に利用してください。

バージョンに関する注意（最初にお読みください）。 このスキルは PyHealth 2.x（現行リリース 2.0.2、2026 年 9 月）を対象としています。2.0 での書き換えにより API が変更されており、多くのチュートリアルや 2025 年以前のコードスニペットは正しく動作しません。

• タスクはインスタンス化するクラスです。例：MortalityPredictionMIMIC4()、DrugRecommendationMIMIC3()。旧式のスネークケース関数 mortality_prediction_mimic4_fn ではありません。インスタンスを dataset.set_task(task) に渡してください。
• データセットには明示的なテーブルリストが必要です。 単一ソースのローダーでは root= + tables=[...] を使用します（MIMIC3Dataset、MIMIC4EHRDataset、eICUDataset、OMOPDataset）。マルチモーダルの MIMIC4Dataset では ehr_root= + ehr_tables=[...] を使用し、必要に応じて note_root／cxr_root も指定します。
• モデルに渡すのは SampleDataset とハイパーパラメーターのみです。例：Transformer(dataset=samples, embedding_dim=128)。特徴キー、ラベルキー、モードはタスクの input_schema／output_schema から読み取られます。1.x の feature_keys=／label_key=／mode= 引数を指定すると TypeError が発生します。
• メトリクス名に _score サフィックスは付きません。pr_auc、roc_auc、f1 を使用します。マルチラベル／薬剤推薦では *_samples 系（jaccard_samples、f1_samples、pr_auc_samples）を使用します。metrics=[...] は Trainer のコンストラクターに渡し、monitor= にはそのいずれかの名前を指定してください。
• チェックポイントには trainer.save_ckpt(path)／trainer.load_ckpt(path) を使用します（trainer.save はありません）。
• 2.0.2 では Python 3.12 または 3.13 が必要で、依存スタック（numpy 2.2、pandas 2.3、torch 2.7、transformers 4.53）が固定されています。そのため、pandas 3／transformers 5 と同じ環境ではなく、専用環境にインストールしてください。

クラス名や引数名が不確かな場合は、古いコードスニペットを頼りにせず、インストール済みのソースを確認してください。

このスキルを使用する場面

以下の場合にこのスキルを呼び出してください。

• 医療データセットを扱う場合：MIMIC-III、MIMIC-IV、eICU、OMOP、睡眠 EEG データ、医療画像
• 臨床予測タスク：死亡予測、再入院予測、在院日数、薬剤推薦
• 医療コーディング：ICD-9/10、NDC、RxNorm、ATC、CCS コーディングシステム間の変換
• 臨床データを処理する場合：時系列イベント、生理信号、臨床テキスト、医療画像
• 医療モデルを実装する場合：RETAIN、SafeDrug、GAMENet、StageNet、EHR 向け Transformer
• 臨床モデルを評価する場合：公平性メトリクス、キャリブレーション、解釈可能性、不確実性の定量化

該当しないケース

ケース	代わりに使用
生の ECG／EEG／EDA 波形のクリーニングと、HRV または SCR 特徴量の計算（モデルのトレーニングなし）	alterlab-neurokit2
DICOM 画像ファイルの読み込み、匿名化、または変換	alterlab-pydicom
表形式の臨床データセットに対する Kaplan-Meier／Cox 生存時間モデリング	alterlab-scikit-survival
GRADE で等級付けされた治療推奨を含む、バイオマーカーで層別化したコホートレポート	alterlab-clinical-decision
EHR 以外のデータに対する一般的な表形式 ML（scikit-learn パイプライン）	alterlab-scikit-learn

主な機能

PyHealth は、モジュール式の 5 段階パイプラインで動作します。

1. データの読み込み：EHR、信号、画像、テキストの各データセット向けの標準化されたローダー
2. タスク定義：事前定義された臨床予測タスク（タスククラス）、またはカスタムの BaseTask サブクラス
3. モデル選択：ベースライン、汎用ディープラーニング、医療分野に特化したモデル
4. トレーニング：最良チェックポイントの選択、モニタリング、評価に対応する Trainer
5. 検証：キャリブレーション、コンフォーマル予測、公平性メトリクス、解釈可能性の手法

PyHealth 2.x は polars ベースのデータ層を使用し、タスクサンプルをキャッシュするため、大規模な EHR テーブルをメモリ効率よく扱えます。

クイックスタートのワークフロー

from pyhealth.datasets import MIMIC4EHRDataset, split_by_patient, get_dataloader
from pyhealth.tasks import MortalityPredictionMIMIC4
from pyhealth.models import Transformer
from pyhealth.trainer import Trainer

# 1. Load dataset (declare the tables the task needs) and set the task (a class instance)
dataset = MIMIC4EHRDataset(
    root="/path/to/mimic-iv/2.2",
    tables=["diagnoses_icd", "procedures_icd", "prescriptions"],
)
sample_dataset = dataset.set_task(MortalityPredictionMIMIC4())

# 2. Split data by patient (no leakage across splits)
train, val, test = split_by_patient(sample_dataset, [0.7, 0.1, 0.2], seed=42)

# 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 the model: inputs, label ("mortality"), and mode ("binary")
#    all come from the task schema, so only hyperparameters are passed
model = Transformer(dataset=sample_dataset, embedding_dim=128)

trainer = Trainer(model=model, metrics=["pr_auc", "roc_auc", "f1"])  # device auto-detected
trainer.train(
    train_dataloader=train_loader,
    val_dataloader=val_loader,
    epochs=50,
    monitor="pr_auc",            # AUPRC — robust for the rare-mortality class
    monitor_criterion="max",
)

# 5. Evaluate (uses the metrics passed to the Trainer)
results = trainer.evaluate(test_loader)

詳細ドキュメント

現在の手順に対応するリファレンスファイルをお読みください。

ファイル	読むタイミング	主なトピック
references/datasets.md	MIMIC／eICU／OMOP／信号データセットを読み込む、またはデータを分割する場合	Patient／Event の構造、ローダー、split_by_patient／split_by_visit／split_by_sample
references/medical_coding.md	ICD、NDC、RxNorm、ATC、CCS コードを変換またはグループ化する場合	InnerMap の検索と階層構造、CrossMap による変換
references/tasks.md	定義済みタスクを選ぶ、またはカスタムタスクを作成する場合	2.x のタスククラス、input_schema／output_schema、カスタム BaseTask
references/models.md	モデルを選択して設定する場合	ベースライン、RNN／CNN／Transformer、RETAIN、SafeDrug、GAMENet、StageNet、GAT／GCN
references/preprocessing.md	生イベントがテンソルになる仕組みを理解する場合	スキーマ文字列プロセッサ（"sequence"、"timeseries"、"binary" など）
references/training_evaluation.md	トレーニング、メトリクス、キャリブレーション、不確実性、解釈可能性を扱う場合	Trainer、メトリクス文字列、コンフォーマル予測、Chefer／IG によるアトリビューション

インストール

uv venv --python 3.13 .venv-pyhealth      # PyHealth 2.0.2 supports Python 3.12-3.13
source .venv-pyhealth/bin/activate
uv pip install "pyhealth>=2.0.2"

要件（PyHealth 2.0.2）：

• Python 3.12 または 3.13（>=3.12,<3.14）。デフォルトのインタープリターが 3.14 の場合は、--python 3.13 を指定して環境を作成してください。
• PyTorch、polars、pandas、scikit-learn、transformers は固定バージョンの依存関係としてインストールされます。これらのバージョン指定が他のプロジェクトと競合しないよう、PyHealth は専用の環境にインストールしてください。
• PyPI には 2.1 のアルファ版系列があります。アルファ版限定の機能が必要でない限り、2.0.x リリースをお使いください。

よくあるユースケース

ユースケース 1：ICU 死亡予測

目的：集中治療室の患者の死亡を予測します。

アプローチ：

1. MIMIC-IV データセットを読み込む → references/datasets.md を参照
2. 死亡予測タスクを適用する → references/tasks.md を参照
3. 解釈可能なモデル（RETAIN）またはアトリビューションに適したモデル（Transformer）を選択する → references/models.md を参照
4. トレーニングと評価を行う → references/training_evaluation.md を参照
5. 臨床レビューのために予測を解釈する → references/training_evaluation.md を参照

ユースケース 2：安全な投薬レコメンデーション

目的：薬物間相互作用を避けながら、薬剤を推奨します。

アプローチ：

1. EHR データセット（MIMIC-III／IV、eICU、または OMOP）を読み込む → references/datasets.md を参照
2. DrugRecommendation* タスクを適用する → references/tasks.md を参照
3. データセットから DDI グラフを構築する SafeDrug または GAMENet を使用する → references/models.md を参照
4. 薬剤コードを前処理する → references/medical_coding.md を参照
5. マルチラベルメトリクス（jaccard_samples、f1_samples、pr_auc_samples）で評価する → references/training_evaluation.md を参照

ユースケース 3：病院再入院予測

目的：再入院のリスクがある患者を特定します。

アプローチ：

1. 複数施設の EHR データ（eICU または OMOP）を読み込む → references/datasets.md を参照
2. ReadmissionPrediction* タスクを適用する → references/tasks.md を参照
3. クラス不均衡に対処する（AUROC だけでなく、AUPRC も報告する）→ references/training_evaluation.md を参照
4. Transformer または RNN モデルをトレーニングする → references/models.md を参照
5. 予測をキャリブレーションし、公平性を評価する → references/training_evaluation.md を参照

ユースケース 4：睡眠段階分類

目的：EEG 信号から睡眠段階を分類します。

アプローチ：

1. 睡眠 EEG データセット（SleepEDF、SHHS、ISRUC）を読み込む → references/datasets.md を参照
2. 睡眠段階分類（SleepStagingSleepEDF またはレガシーの sleep_staging_*_fn 関数）を適用する → references/tasks.md を参照
3. EEG 信号を前処理する（フィルタリング、セグメンテーション）→ references/preprocessing.md を参照
4. CNN、SparcNet、または ContraWR モデルをトレーニングする → references/models.md を参照
5. 段階ごとの性能（f1_macro、cohen_kappa）を評価する → 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. MIMIC3ICD9Coding タスクを適用します → references/tasks.md を読みます
3. 臨床テキストを前処理します → references/preprocessing.md を読みます
4. TransformersModel(dataset=..., model_name="emilyalsentzer/Bio_ClinicalBERT") を使用します → references/models.md を読みます
5. マルチラベル指標で評価します → references/training_evaluation.md を読みます

ベストプラクティス

データの取り扱い

1. 常に患者単位で分割します：患者が複数の分割に含まれないようにして、データリークを防ぎます

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

2. データセットの統計を確認します：モデリングの前にデータを理解します

   dataset.stats()  # prints patient and event counts (returns None)
   

3. 適切な前処理を使用します：データ型に合ったプロセッサを選びます（references/preprocessing.md を参照）

モデル開発

1. ベースラインから始めます：シンプルなモデルでベースライン性能を確立します

   • 二値／多クラスのタスクには LogisticRegression
   • 初期のディープラーニングのベースラインには MLP

2. タスクに適したモデルを選びます：

   • 解釈可能性が必要 → RETAIN、AdaCare（設計上）；Transformer（事後的な帰属分析）
   • 薬剤の推薦 → SafeDrug、GAMENet
   • 長いシーケンス → Transformer
   • グラフの関係性 → GAT / GCN

3. 検証指標をモニタリングします：タスクに適した指標を使用し、クラスの不均衡に対処します。PyHealth の指標文字列（Trainer(metrics=[...]) / monitor= に渡します）：

   • 二値：roc_auc、pr_auc（希少事象には pr_auc を推奨）、f1、accuracy
   • 多クラス：f1_macro、f1_weighted、accuracy、cohen_kappa
   • マルチラベル／薬剤推薦：jaccard_samples、f1_samples、pr_auc_samples、ddi（ddi_score として報告）
   • 回帰：mae、mse、kl_divergence

臨床検証

1. 予測を較正します：確率の信頼性を確保します（references/training_evaluation.md を参照）
2. 公平性を評価します：バイアスを検出するため、人口統計学的グループごとに評価します
3. 不確実性を定量化します：予測の信頼度推定値を提示します（コンフォーマル予測セット）
4. 予測を解釈します：臨床医によるレビューのため、注意／関連度マップ、SHAP、または統合勾配を使用します
5. 十分に検証します：異なる期間または施設のホールドアウトテストセットを使用します
6. 透明性をもって報告します：臨床予測モデルを公開する際は、TRIPOD+AI（BMJ 2024;385:e078378）に従います

制限事項と考慮点

データ要件

• 大規模なデータセット：ディープラーニングモデルには十分なデータ（数千人の患者）が必要です
• データ品質：欠損データやコーディングエラーは性能に影響します
• 時間的な一貫性：必要に応じて、訓練／テスト分割が時間順序を尊重するようにします
• アクセス：MIMIC と eICU の利用には、PhysioNet の認証とデータ使用契約が必要です。契約で認められていないプロンプト、ノートブック、リポジトリには、利用制限のある記録を決してコピーしないでください

臨床検証

• 外部検証：異なる病院／システムのデータでテストします
• 前向き評価：導入前に実際の臨床環境で検証します
• 臨床レビュー：臨床医に予測と解釈をレビューしてもらいます
• 診断ではなく意思決定支援：モデル出力は、資格を持つ臨床医向けの研究段階のリスク推定値として提示します。医療機器として導入する場合は、機器規制（例：FDA SaMD、EU MDR）の対象となります
• 倫理的配慮：プライバシー（HIPAA/GDPR）、公平性、安全性に対処します

計算リソース

• GPU を推奨：ディープラーニングモデルを効率的にトレーニングするため
• メモリ要件：大規模なデータセットでは、16GB 以上の RAM が必要になる場合があります
• ストレージ：医療データセットは数十〜数百 GB に及ぶ場合があり、タスクサンプルのキャッシュも必要です

トラブルシューティング

よくある問題

TypeError: ... unexpected keyword argument 'feature_keys'（または 'root'）：

• 1.x 形式の呼び出しを使用しています。モデルには dataset= とハイパーパラメーターのみを渡し、MIMIC4EHRDataset(root=..., tables=...) または MIMIC4Dataset(ehr_root=..., ehr_tables=...) を使用してください

ImportError またはテーブルが見つからない：

• データセットファイルがダウンロード済みで、ルートパスがバージョン付きフォルダーを指していることを確認してください
• テーブル名がデータセットの YAML 設定に存在することを確認してください

メモリ不足：

• バッチサイズを小さくしてください
• 系列長を短くしてください（Transformer の max_seq_len）
• データセットローダーに dev=True を渡し（例：MIMIC4EHRDataset(..., dev=True)）、最初の 1,000 人の患者を使ってプロトタイプを作成してください
• データをチャンク単位で処理してください

性能が低い：

• クラスの不均衡を確認し、適切な指標（pr_auc と roc_auc のどちらか）を使用してください
• 前処理（正規化、欠損データの処理）を確認してください
• モデルの容量またはトレーニングエポック数を増やしてください
• トレーニング／テストの分割でデータリークがないか確認してください

トレーニングが遅い：

• GPU を使用してください（Trainer(..., device="cuda")）
• メモリに余裕があれば、バッチサイズを大きくしてください
• 系列長を短くしてください
• より軽量なモデルを使用してください（Transformer の代わりに CNN または RNN）

ヘルプ

• ドキュメント：https://pyhealth.readthedocs.io/
• GitHub の課題：https://github.com/sunlabuiuc/PyHealth/issues
• 例／ノートブック：https://github.com/sunlabuiuc/PyHealth/tree/master/examples

例：完全なワークフロー

# Complete mortality prediction pipeline (PyHealth 2.0.x)
import torch
from pyhealth.datasets import MIMIC4EHRDataset, split_by_patient, get_dataloader
from pyhealth.tasks import MortalityPredictionMIMIC4
from pyhealth.models import Transformer
from pyhealth.trainer import Trainer
from pyhealth.interpret.methods import CheferRelevance

# 1. Load dataset (declare the tables the task needs)
dataset = MIMIC4EHRDataset(
    root="/data/mimic-iv/2.2",
    tables=["diagnoses_icd", "procedures_icd", "prescriptions"],
)
dataset.stats()

# 2. Define task (instantiate the task class)
sample_dataset = dataset.set_task(MortalityPredictionMIMIC4())
print(f"Generated {len(sample_dataset)} samples")

# 3. Split data (by patient to prevent leakage)
train_ds, val_ds, test_ds = split_by_patient(sample_dataset, [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 the model (schema-driven; swap in RETAIN(dataset=sample_dataset,
#    embedding_dim=128) for a model that is interpretable by design)
model = Transformer(dataset=sample_dataset, embedding_dim=128, heads=2, num_layers=2)

# 6. Train, keeping the best checkpoint by validation AUPRC
trainer = Trainer(model=model, metrics=["accuracy", "pr_auc", "roc_auc", "f1"])
trainer.train(
    train_dataloader=train_loader,
    val_dataloader=val_loader,
    epochs=50,
    optimizer_class=torch.optim.Adam,
    optimizer_params={"lr": 1e-3},
    weight_decay=1e-5,
    monitor="pr_auc",          # AUPRC for the imbalanced (rare-mortality) outcome
    monitor_criterion="max",
    patience=5,                # early stopping
)

# 7. Evaluate on the test set (uses the metrics passed to the Trainer)
for metric, value in trainer.evaluate(test_loader).items():
    print(f"  {metric}: {value:.4f}")

# 8. Predictions with patient IDs: inference() returns (y_true, y_prob, loss),
#    extended with patient_ids when return_patient_ids=True
y_true, y_prob, loss, patient_ids = trainer.inference(test_loader, return_patient_ids=True)
positive_prob = y_prob if y_prob.ndim == 1 else y_prob[..., -1]
high_risk_idx = int(positive_prob.argmax())
print(f"Highest-risk patient: {patient_ids[high_risk_idx]} ({float(positive_prob[high_risk_idx]):.3f})")

# 9. Token-level relevance (Chefer; supported by Transformer and StageAttentionNet)
relevance = CheferRelevance(model)
batch = next(iter(get_dataloader(test_ds, batch_size=1, shuffle=False)))
for feature_key, rel in relevance.attribute(**batch).items():
    print(f"{feature_key}: top tokens -> {rel[0].topk(min(5, rel.shape[-1])).indices.tolist()}")

# 10. Save the trained weights
trainer.save_ckpt("./models/mortality_transformer.pt")

リソース

各コンポーネントの詳細については、references/ にあるリファレンスファイル（datasets.md、medical_coding.md、tasks.md、models.md、preprocessing.md、training_evaluation.md）を参照してください（それぞれを読むタイミングについては、詳細なドキュメントの表をご覧ください）。

AlterLab Academic Skills スイートの一部です。