{"slug":"alterlab-pyhealth","title":"alterlab-pyhealth","summary":"Develops, tests, and validates clinical machine learning models with the PyHealth 2.x healthcare AI toolkit. Use when working with electronic health records (EHR), clinical prediction tasks (mortality, readmission, length of stay, drug recommendation), medical coding systems (ICD","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:57:01.115221Z","repo":{"url":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","stars":68,"forks":13,"license":"MIT","updatedAt":"2026-09-23T13:42:59Z"},"bodyHtml":"
\n

name: alterlab-pyhealth\ndescription: Develops, tests, and validates clinical machine learning models with the PyHealth 2.x healthcare AI toolkit. Use when working with electronic health records (EHR), clinical prediction tasks (mortality, readmission, length of stay, drug recommendation), medical coding systems (ICD, NDC, ATC, CCS), physiological signals (EEG, ECG), healthcare datasets (MIMIC-III/IV, eICU, OMOP), or implementing deep learning models for healthcare (RETAIN, SafeDrug, GAMENet, Transformer, GAT/GCN). Part of the AlterLab Academic Skills suite.\nlicense: MIT\nallowed-tools: Read Write Edit Bash(python:*)\ncompatibility: \"Self-contained — runs under uv run python with PyHealth >= 2.0.2 (Python 3.12-3.13) in its own environment; no API key required. MIMIC-III/IV and eICU data need the user's own PhysioNet credentialed access.\"\nmetadata:\nskill-author: AlterLab\nversion: \"1.2.0\"\nlast_updated: \"2026-09-23\"

\n

PyHealth: Healthcare AI Toolkit

\n

Overview

\n

PyHealth is a Python library for healthcare AI that provides datasets, task definitions, models, trainers, and medical-code utilities for clinical machine learning. Use this skill when developing healthcare prediction models, processing clinical data, working with medical coding systems, or validating models before any clinical use.

\n
\n

Version gotcha (read first). This skill targets PyHealth 2.x (current release 2.0.2, Sept 2026). The 2.0 rewrite changed the API in ways most tutorials and pre-2025 snippets get wrong:

\n\n

When unsure of a class or argument name, check the installed source rather than trusting older snippets.

\n
\n

When to Use This Skill

\n

Invoke this skill when:

\n\n

Does NOT Trigger

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ScenarioUse Instead
Cleaning a raw ECG/EEG/EDA trace and computing HRV or SCR features (no model training)alterlab-neurokit2
Reading, anonymizing, or converting DICOM image filesalterlab-pydicom
Kaplan-Meier / Cox time-to-event modeling on a tabular clinical datasetalterlab-scikit-survival
Biomarker-stratified cohort report with GRADE-graded treatment recommendationsalterlab-clinical-decision
General tabular ML on non-EHR data (scikit-learn pipelines)alterlab-scikit-learn
\n

Core Capabilities

\n

PyHealth operates through a modular 5-stage pipeline:

\n
    \n
  1. Data Loading: Standardized loaders for EHR, signal, imaging, and text datasets
    2. \n
  2. Task Definition: Predefined clinical prediction tasks (task classes) or custom BaseTask subclasses
    3. \n
  3. Model Selection: Baselines, general deep learning, and healthcare-specific models
    4. \n
  4. Training: Trainer with best-checkpoint selection, monitoring, and evaluation
    5. \n
  5. Validation: Calibration, conformal prediction, fairness metrics, and interpretability methods
    6. \n
\n

PyHealth 2.x uses a polars-backed data layer and caches task samples, which keeps large EHR tables memory-efficient.

\n

Quick Start Workflow

\n
from pyhealth.datasets import MIMIC4EHRDataset, split_by_patient, get_dataloader\nfrom pyhealth.tasks import MortalityPredictionMIMIC4\nfrom pyhealth.models import Transformer\nfrom pyhealth.trainer import Trainer\n\n# 1. Load dataset (declare the tables the task needs) and set the task (a class instance)\ndataset = MIMIC4EHRDataset(\n    root=\"/path/to/mimic-iv/2.2\",\n    tables=[\"diagnoses_icd\", \"procedures_icd\", \"prescriptions\"],\n)\nsample_dataset = dataset.set_task(MortalityPredictionMIMIC4())\n\n# 2. Split data by patient (no leakage across splits)\ntrain, val, test = split_by_patient(sample_dataset, [0.7, 0.1, 0.2], seed=42)\n\n# 3. Create data loaders\ntrain_loader = get_dataloader(train, batch_size=64, shuffle=True)\nval_loader = get_dataloader(val, batch_size=64, shuffle=False)\ntest_loader = get_dataloader(test, batch_size=64, shuffle=False)\n\n# 4. Initialize the model: inputs, label (\"mortality\"), and mode (\"binary\")\n#    all come from the task schema, so only hyperparameters are passed\nmodel = Transformer(dataset=sample_dataset, embedding_dim=128)\n\ntrainer = Trainer(model=model, metrics=[\"pr_auc\", \"roc_auc\", \"f1\"])  # device auto-detected\ntrainer.train(\n    train_dataloader=train_loader,\n    val_dataloader=val_loader,\n    epochs=50,\n    monitor=\"pr_auc\",            # AUPRC — robust for the rare-mortality class\n    monitor_criterion=\"max\",\n)\n\n# 5. Evaluate (uses the metrics passed to the Trainer)\nresults = trainer.evaluate(test_loader)\n
\n

Detailed Documentation

\n

Read the reference file that matches the step you are on:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FileRead whenKey topics
references/datasets.mdLoading MIMIC/eICU/OMOP/signal datasets, splitting dataPatient/Event structures, loaders, split_by_patient / split_by_visit / split_by_sample
references/medical_coding.mdTranslating or grouping ICD, NDC, RxNorm, ATC, CCS codesInnerMap lookups and hierarchy, CrossMap translation
references/tasks.mdChoosing a predefined task or writing a custom one2.x task classes, input_schema / output_schema, custom BaseTask
references/models.mdSelecting and configuring a modelBaselines, RNN/CNN/Transformer, RETAIN, SafeDrug, GAMENet, StageNet, GAT/GCN
references/preprocessing.mdUnderstanding how raw events become tensorsSchema-string processors (\"sequence\", \"timeseries\", \"binary\", ...)
references/training_evaluation.mdTraining, metrics, calibration, uncertainty, interpretabilityTrainer, metric strings, conformal prediction, Chefer/IG attributions
\n

Installation

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

Requirements (PyHealth 2.0.2):

\n\n

Common Use Cases

\n

Use Case 1: ICU Mortality Prediction

\n

Objective: Predict patient mortality in intensive care unit

\n

Approach:

\n
    \n
  1. Load MIMIC-IV dataset → Read references/datasets.md
    2. \n
  2. Apply mortality prediction task → Read references/tasks.md
    3. \n
  3. Select an interpretable model (RETAIN) or an attribution-friendly one (Transformer) → Read references/models.md
    4. \n
  4. Train and evaluate → Read references/training_evaluation.md
    5. \n
  5. Interpret predictions for clinical review → Read references/training_evaluation.md
    6. \n
\n

Use Case 2: Safe Medication Recommendation

\n

Objective: Recommend medications while avoiding drug-drug interactions

\n

Approach:

\n
    \n
  1. Load EHR dataset (MIMIC-III/IV, eICU, or OMOP) → Read references/datasets.md
    2. \n
  2. Apply a DrugRecommendation* task → Read references/tasks.md
    3. \n
  3. Use SafeDrug or GAMENet, which build their DDI graphs from the dataset → Read references/models.md
    4. \n
  4. Preprocess medication codes → Read references/medical_coding.md
    5. \n
  5. Evaluate with multi-label metrics (jaccard_samples, f1_samples, pr_auc_samples) → Read references/training_evaluation.md
    6. \n
\n

Use Case 3: Hospital Readmission Prediction

\n

Objective: Identify patients at risk of readmission

\n

Approach:

\n
    \n
  1. Load multi-site EHR data (eICU or OMOP) → Read references/datasets.md
    2. \n
  2. Apply a ReadmissionPrediction* task → Read references/tasks.md
    3. \n
  3. Handle class imbalance (report AUPRC, not only AUROC) → Read references/training_evaluation.md
    4. \n
  4. Train a Transformer or RNN model → Read references/models.md
    5. \n
  5. Calibrate predictions and assess fairness → Read references/training_evaluation.md
    6. \n
\n

Use Case 4: Sleep Staging

\n

Objective: Classify sleep stages from EEG signals

\n

Approach:

\n
    \n
  1. Load a sleep EEG dataset (SleepEDF, SHHS, ISRUC) → Read references/datasets.md
    2. \n
  2. Apply sleep staging (SleepStagingSleepEDF or the legacy sleep_staging_*_fn functions) → Read references/tasks.md
    3. \n
  3. Preprocess EEG signals (filtering, segmentation) → Read references/preprocessing.md
    4. \n
  4. Train a CNN, SparcNet, or ContraWR model → Read references/models.md
    5. \n
  5. Evaluate per-stage performance (f1_macro, cohen_kappa) → Read references/training_evaluation.md
    6. \n
\n

Use Case 5: Medical Code Translation

\n

Objective: Standardize diagnoses across different coding systems

\n

Approach:

\n
    \n
  1. Read references/medical_coding.md for comprehensive guidance
    2. \n
  2. Use CrossMap to translate between ICD-9, ICD-10, and CCS
    3. \n
  3. Group codes into clinically meaningful categories
    4. \n
  4. Integrate with dataset processing
    5. \n
\n

Use Case 6: Clinical Text to ICD Coding

\n

Objective: Automatically assign ICD codes from clinical notes

\n

Approach:

\n
    \n
  1. Load MIMIC-III with clinical notes → Read references/datasets.md
    2. \n
  2. Apply the MIMIC3ICD9Coding task → Read references/tasks.md
    3. \n
  3. Preprocess clinical text → Read references/preprocessing.md
    4. \n
  4. Use TransformersModel(dataset=..., model_name=\"emilyalsentzer/Bio_ClinicalBERT\") → Read references/models.md
    5. \n
  5. Evaluate with multi-label metrics → Read references/training_evaluation.md
    6. \n
\n

Best Practices

\n

Data Handling

\n
    \n

  1. Always split by patient: Prevent data leakage by ensuring no patient appears in multiple splits

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

  2. Check dataset statistics: Understand your data before modeling

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

  3. Use appropriate preprocessing: Match processors to data types (see references/preprocessing.md)

    \n
    4. \n
\n

Model Development

\n
    \n

  1. Start with baselines: Establish baseline performance with simple models

    \n\n
    2. \n

  2. Choose task-appropriate models:

    \n\n
    3. \n

  3. Monitor validation metrics: Use appropriate metrics for the task and handle class imbalance. PyHealth metric strings (pass to Trainer(metrics=[...]) / monitor=):

    \n\n
    4. \n
\n

Clinical Validation

\n
    \n
  1. Calibrate predictions: Ensure probabilities are reliable (see references/training_evaluation.md)
    2. \n
  2. Assess fairness: Evaluate across demographic groups to detect bias
    3. \n
  3. Quantify uncertainty: Provide confidence estimates for predictions (conformal prediction sets)
    4. \n
  4. Interpret predictions: Attention/relevance maps, SHAP, or integrated gradients for clinician review
    5. \n
  5. Validate thoroughly: Use held-out test sets from different time periods or sites
    6. \n
  6. Report transparently: Follow TRIPOD+AI (BMJ 2024;385:e078378) when publishing a clinical prediction model
    7. \n
\n

Limitations and Considerations

\n

Data Requirements

\n\n

Clinical Validation

\n\n

Computational Resources

\n\n

Troubleshooting

\n

Common Issues

\n

TypeError: ... unexpected keyword argument 'feature_keys' (or 'root'):

\n\n

ImportError or missing tables:

\n\n

Out of memory:

\n\n

Poor performance:

\n\n

Slow training:

\n\n

Getting Help

\n\n

Example: Complete Workflow

\n
# Complete mortality prediction pipeline (PyHealth 2.0.x)\nimport torch\nfrom pyhealth.datasets import MIMIC4EHRDataset, split_by_patient, get_dataloader\nfrom pyhealth.tasks import MortalityPredictionMIMIC4\nfrom pyhealth.models import Transformer\nfrom pyhealth.trainer import Trainer\nfrom pyhealth.interpret.methods import CheferRelevance\n\n# 1. Load dataset (declare the tables the task needs)\ndataset = MIMIC4EHRDataset(\n    root=\"/data/mimic-iv/2.2\",\n    tables=[\"diagnoses_icd\", \"procedures_icd\", \"prescriptions\"],\n)\ndataset.stats()\n\n# 2. Define task (instantiate the task class)\nsample_dataset = dataset.set_task(MortalityPredictionMIMIC4())\nprint(f\"Generated {len(sample_dataset)} samples\")\n\n# 3. Split data (by patient to prevent leakage)\ntrain_ds, val_ds, test_ds = split_by_patient(sample_dataset, [0.7, 0.1, 0.2], seed=42)\n\n# 4. Create data loaders\ntrain_loader = get_dataloader(train_ds, batch_size=64, shuffle=True)\nval_loader = get_dataloader(val_ds, batch_size=64)\ntest_loader = get_dataloader(test_ds, batch_size=64)\n\n# 5. Initialize the model (schema-driven; swap in RETAIN(dataset=sample_dataset,\n#    embedding_dim=128) for a model that is interpretable by design)\nmodel = Transformer(dataset=sample_dataset, embedding_dim=128, heads=2, num_layers=2)\n\n# 6. Train, keeping the best checkpoint by validation AUPRC\ntrainer = Trainer(model=model, metrics=[\"accuracy\", \"pr_auc\", \"roc_auc\", \"f1\"])\ntrainer.train(\n    train_dataloader=train_loader,\n    val_dataloader=val_loader,\n    epochs=50,\n    optimizer_class=torch.optim.Adam,\n    optimizer_params={\"lr\": 1e-3},\n    weight_decay=1e-5,\n    monitor=\"pr_auc\",          # AUPRC for the imbalanced (rare-mortality) outcome\n    monitor_criterion=\"max\",\n    patience=5,                # early stopping\n)\n\n# 7. Evaluate on the test set (uses the metrics passed to the Trainer)\nfor metric, value in trainer.evaluate(test_loader).items():\n    print(f\"  {metric}: {value:.4f}\")\n\n# 8. Predictions with patient IDs: inference() returns (y_true, y_prob, loss),\n#    extended with patient_ids when return_patient_ids=True\ny_true, y_prob, loss, patient_ids = trainer.inference(test_loader, return_patient_ids=True)\npositive_prob = y_prob if y_prob.ndim == 1 else y_prob[..., -1]\nhigh_risk_idx = int(positive_prob.argmax())\nprint(f\"Highest-risk patient: {patient_ids[high_risk_idx]} ({float(positive_prob[high_risk_idx]):.3f})\")\n\n# 9. Token-level relevance (Chefer; supported by Transformer and StageAttentionNet)\nrelevance = CheferRelevance(model)\nbatch = next(iter(get_dataloader(test_ds, batch_size=1, shuffle=False)))\nfor feature_key, rel in relevance.attribute(**batch).items():\n    print(f\"{feature_key}: top tokens -> {rel[0].topk(min(5, rel.shape[-1])).indices.tolist()}\")\n\n# 10. Save the trained weights\ntrainer.save_ckpt(\"./models/mortality_transformer.pt\")\n
\n

Resources

\n

For detailed information on each component, see the reference files in references/: datasets.md, medical_coding.md, tasks.md, models.md, preprocessing.md, and training_evaluation.md (see the table under Detailed Documentation for when to read each).

\n

Part of the AlterLab Academic Skills suite.

\n","files":[{"path":"evals/evals.json","sizeBytes":6353,"isText":true},{"path":"references/datasets.md","sizeBytes":6466,"isText":true},{"path":"references/medical_coding.md","sizeBytes":9171,"isText":true},{"path":"references/models.md","sizeBytes":16133,"isText":true},{"path":"references/preprocessing.md","sizeBytes":15407,"isText":true},{"path":"references/tasks.md","sizeBytes":14031,"isText":true},{"path":"references/training_evaluation.md","sizeBytes":20874,"isText":true},{"path":"SKILL.md","sizeBytes":19326,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:58:28.593476Z","sha256":"480E230A82F974A1E2414B8501801A9910057D8B9C739D8821756BCD93636126","sizeBytes":39434},"review":null,"source":{"repositoryUrl":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","path":"skills/clinical-research/alterlab-pyhealth","license":"MIT","commit":"e4836c08a20da195a11f30f203a8cf23ec30aa95","subtreeSha":"008FD0B54D2F68CFE8D80D2A86F87CB3EE491A21A6D163CD9F6B6A008C15E8BF","lastSyncedAt":"2026-09-23T18:56:52.297238Z"},"reviewedAt":"2026-09-23T19:01:10.355126Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/clinical-research/alterlab-pyhealth"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart"},{"target":"git","command":"git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git"}]}