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/）を使用できます。認証情報がなくても利用できます。

エージェントの作業手順

1. 環境を確認します。 データへのアクセス権限、匿名化の状態、および適用される規制やプロトコルを確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値を推測するのではなく、質問してください。
3. まず小規模なバージョンを実行します。 匿名化済みのサンプルまたは合成データを使用します。
4. 上記の手順とリファレンスに従って、タスク全体を実行します。
5. 結果を検証します。 出力を臨床ガイドラインおよび報告基準と照合し、臨床内容を有資格者に確認してもらいます。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

次のことが起きた場合	対応
データに患者を特定できる情報が含まれているように見える	処理を中止し、続行する前にユーザーに確認します。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えます。API をでっち上げてはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに確認するか、実行前に仮定を明示します。

完全性に関するルール

• 結果、パラメーター、識別子、引用、統計情報を捏造してはいけません。実行または検証できないことがあれば、明確に伝えてください。
• 出力は有資格者向けの意思決定支援であり、医療上の助言ではありません。診断や指示として提示してはいけません。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントと照合してください。
• 費用が発生する操作、共有 GPU やクラウドクォータを消費する操作、個人データや患者データを扱う操作、または元に戻せない操作を行う前に、必ず確認してください。

関連スキル

• transformers：Hugging Face Transformers を使用した Hub モデルの読み込み、パイプラインによる推論、テキスト生成、および NLP、ビジョン、オーディオ向けの Trainer ファインチューニング…