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 は、ヘルスケア AI 向けに最適化されたモジュール式の 5 段階パイプラインで動作します:

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、信号、画像、またはテキストベースのタスクを扱うとき
• カスタム予測タスクを作成するとき
• モデルの入力/出力スキーマを設定するとき
• タスク固有のフィルタリングロジックを適用するとき

主要トピック:

• 20 以上の定義済み臨床タスク
• EHR タスク(死亡、再入院、入院期間、薬剤推奨)
• 信号タスク(睡眠段階判定、EEG 解析、発作検出)
• 画像タスク(COVID-19 胸部 X 線分類)
• テキストタスク(医療コーディング、診療科分類)
• カスタムタスク作成のパターン

4. モデルとアーキテクチャ

ファイル: references/models.md

参照するタイミング:

• 臨床予測のためのモデルを選定するとき
• モデルのアーキテクチャと機能を理解するとき
• 汎用モデルとヘルスケア特化モデルのどちらを選ぶか検討するとき
• 解釈可能なモデル（RETAIN、AdaCare）を実装するとき
• 薬剤推奨（SafeDrug、GAMENet）を扱うとき
• ヘルスケア向けのグラフニューラルネットワークを使うとき
• モデルのハイパーパラメーターを設定するとき

主なトピック:

• 33種類以上の利用可能なモデル
• 汎用: ロジスティック回帰、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）
• 学習パイプラインの完全な例

インストール

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. ベースラインから始める：単純なモデルで基準性能を確立する

   • 二値分類・多クラス分類にはロジスティック回帰
   • 深層学習の初期ベースラインとして 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 が必要になる場合がある
• ストレージ：医療データセットは数十〜数百 GB になる場合がある

トラブルシューティング

よくある問題

データセットの ImportError:

• データセットファイルがダウンロードされており、パスが正しいことを確認してください
• PyHealth のバージョン互換性を確認してください

メモリ不足 (Out of memory):

• バッチサイズを小さくしてください
• シーケンス長 (max_seq_length) を短くしてください
• 勾配累積を使用してください
• データをチャンクに分けて処理してください

性能が低い:

• クラスの不均衡を確認し、適切な指標 (AUPRC と AUROC) を使用してください
• 前処理 (正規化、欠損データの処理) を検証してください
• モデルの容量や訓練エポック数を増やしてください
• 訓練/テストの分割でデータリークがないか確認してください

訓練が遅い:

• GPU を使用してください (device="cuda")
• (メモリに余裕があれば) バッチサイズを大きくしてください
• シーケンス長を短くしてください
• より効率的なモデルを使用してください (Transformer より CNN)

ヘルプの入手先

• ドキュメント: 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 語。