pyhealth

PyHealth

PyHealth（https://pyhealth.dev/）は、臨床向けディープラーニングのための Python ツールキットです。電子健康記録（EHR）、生理学的信号、医用画像に対応する、統一されたモジュール式のパイプラインを提供します。

このライブラリは、Dataset → Task → Model → Trainer → Metrics という5 段階のパイプラインを中心に構築されています。各段階は置き換え可能で、段階間のインターフェースは安定しています。このパイプラインの形に沿ったコードはうまく組み合わせられますが、これを迂回するコードはたいていライブラリとの相性に問題が生じます。

このスキルを使う場面

ユーザーが臨床・医療分野の ML に取り組んでいて、以下のいずれかに該当する場合は、このスキルを使用してください。

• 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. モデルが受け取るのは BaseDataset ではなく SampleDataset です。 MIMIC3Dataset(...) は BaseDataset（クエリ可能な患者レジストリ）を返します。.set_task(task) を実行して初めて SampleDataset が得られます。これはモデル、スプリッター、DataLoader が想定するデータセットです。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" を使用します。適切でない monitor を指定すると、チェックポイントの選択で誤ったエポックが保存されます。

5. MIMIC-IV では root= ではなく ehr_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/）を利用できます。認証情報は不要です。