PyHealth: Open-source Healthcare AI Toolkit

• PyHealth is an open-source Python library and healthcare AI framework that enables reproducible predictive modeling with a unified, patient-centered data abstraction.
• It integrates modules for data preprocessing, model development, evaluation, interpretability, and uncertainty quantification across EHR, imaging, signals, genomics, and text.
• The toolkit standardizes complex clinical workflows and reduces computational burdens, facilitating efficient benchmarking and method development in healthcare AI.

PyHealth is an open-source Python library and healthcare AI framework for developing predictive models on healthcare data. It was introduced as a toolbox organized around data preprocessing, predictive modeling, and evaluation, and later expanded in PyHealth 2.0 into a clinical deep learning toolkit that unifies 15+ datasets, 20+ clinical tasks, 25+ models, 5+ interpretability methods, uncertainty quantification including conformal prediction, and translation of 5+ medical coding standards across signals, imaging, electronic health records, genomics, and text (Zhao et al., 2021, Wu et al., 23 Jan 2026).

1. Historical development and scope

PyHealth emerged from a reproducibility and benchmarking problem in healthcare AI. The 2021 formulation emphasizes that even when research groups use the same datasets, inconsistent preprocessing and evaluation make it hard to reproduce results or compare methods fairly. In response, PyHealth was developed as an open-source Python toolbox for “developing various predictive models on healthcare data,” with target users identified as both computer science researchers and healthcare data scientists, and with an explicit goal of enabling complex machine learning pipelines in fewer than ten lines of code (Zhao et al., 2021).

PyHealth 2.0 reframes the project around three persistent barriers: difficulty replicating baselines, high computational costs, and required domain expertise. In that formulation, the toolkit is installable via pip install pyhealth and is described as enabling predictive modeling in as few as 7 lines of code, while also emphasizing accessibility across computational settings ranging from 16GB laptops to production systems (Wu et al., 23 Jan 2026). This progression indicates a shift from a model-and-benchmark library toward a broader platform for clinical deep learning workflows.

A recurrent misunderstanding is that PyHealth is only a model repository. The papers instead describe a framework spanning raw data ingestion, task construction, model training, evaluation, interpretability, calibration, and benchmark reproducibility. Later studies also use PyHealth as the implementation substrate for interpretability benchmarking in clinical time series, conformal prediction under healthcare distribution shift, and synthetic EHR evaluation, which suggests that its role extends beyond baseline reproduction to method development infrastructure (Fan et al., 25 Mar 2026, Chatterjee et al., 23 Feb 2026, Jiang et al., 5 Jun 2026).

2. Internal architecture and programming model

The original PyHealth paper organizes the library into three major modules: a data preprocessing module, a predictive modeling module, and an evaluation module (Zhao et al., 2021). PyHealth 2.0 preserves this logic but makes the architecture more explicit through nine core modules: pyhealth.data, pyhealth.processors, pyhealth.datasets, pyhealth.tasks, pyhealth.models, pyhealth.metrics, pyhealth.interpret, pyhealth.calib, and pyhealth.medcode (Wu et al., 23 Jan 2026).

At the data layer, PyHealth 2.0 adopts a patient-centered event abstraction. Patient objects contain lists of Event objects, and each Event stores fields such as event_type, timestamp, and attr_dict. This datatype-agnostic representation is central to the toolkit’s ability to host structured EHR, time-series biosignals, images, genomics, and text within one API (Wu et al., 23 Jan 2026). The processing layer then converts these heterogeneous event streams into tensor representations through processors such as SequenceProcessor, NestedSequenceProcessor, TimeseriesProcessor, SignalProcessor, ImageProcessor, TextProcessor, MultiHotProcessor, and specialized StageNetProcessor variants (Wu et al., 23 Jan 2026).

Task definition is separated from dataset loading. In PyHealth 2.0, a task is implemented as a subclass of BaseTask with input_schema, output_schema, and __call__(self, patient); applying dataset.set_task(task) iterates over patients, constructs samples, runs processors, and returns a SampleDataset backed by a streaming data interface (Wu et al., 23 Jan 2026). This separation makes cohort construction, label generation, and modality-specific preprocessing explicit program objects rather than ad hoc scripts.

The modeling layer follows a unified interface in both the 2021 and 2026 accounts. The earlier paper highlights fit(train_data, valid_data), load_model(), inference(test_data), and get_results() as common methods across models (Zhao et al., 2021). Later work generalizes this into forward(**kwargs) compatibility with the PyHealth Trainer, enabling external PyTorch-style composition while preserving a library-wide training and evaluation workflow (Wu et al., 23 Jan 2026).

3. Supported modalities, datasets, tasks, and coding systems

PyHealth is explicitly multimodal. The 2021 paper lists longitudinal EHR, medical images, continuous signals such as ECG and EEG, and clinical notes as first-class data types (Zhao et al., 2021). PyHealth 2.0 extends this to genomics and multimodal dataset/task constructions, while retaining the same patient-centered abstraction (Wu et al., 23 Jan 2026).

Dimension	Coverage in PyHealth 2.0	Representative examples
Datasets	15+	MIMIC-III, MIMIC-IV, eICU, OMOP, ChestXray14, MIMIC-CXR, TUAB, TUEV, SleepEDF, ClinVar, COSMIC
Tasks	20+	Mortality, readmission, length of stay, drug recommendation, sleep staging, EEG abnormality, EEG event detection
Models	25+	RNN, Transformer, RETAIN, StageNet, AdaCare, ConCare, SafeDrug, GAMENet
Interpretability	5+	Integrated Gradients, DeepLIFT, GIM, LIME, SHAP, CheferRelevance
Medical coding standards	5+	ICD-9-CM, ICD-10-CM, CCS, NDC, RxNorm, ATC

The dataset catalog in PyHealth 2.0 includes EHR resources such as MIMIC3Dataset, MIMIC4Dataset, eICUDataset, OMOPDataset, and MIMICExtractDataset; imaging datasets such as ChestXray14Dataset, COVID19CXRDataset, and MIMICCXRDataset; physiological signal datasets such as SleepEDFDataset, ISRUCDataset, SHHSDataset, DREAMTDataset, TUABDataset, TUEVDataset, CardiologyDataset, and BMDHSDataset; genomics datasets such as ClinVarDataset, COSMICDataset, and TCGAPRADDataset; and clinical text datasets such as MedicalTranscriptionsDataset (Wu et al., 23 Jan 2026).

Task coverage is similarly broad. The library provides predefined mortality, readmission, and length-of-stay tasks across MIMIC-III, MIMIC-IV, eICU, and OMOP; drug recommendation tasks on MIMIC; sleep staging; EEG abnormality and event classification; chest X-ray binary and multilabel classification; multiple cardiology classifiers; variant classification and cancer tasks in genomics; medical transcription classification; ICD-9 coding from notes; patient linkage; and multimodal mortality prediction that combines codes, text, labs, and images (Wu et al., 23 Jan 2026).

PyHealth 2.0 also formalizes medical code translation through pyhealth.medcode. CrossMap.map(code) enables translation across standards, and InnerMap.lookup(code) retrieves descriptions and metadata. Supported standards include ICD-9-CM, ICD-10-CM, CCS for diagnoses, ICD-9-Proc, ICD-10-Proc, CCS procedures, NDC, RxNorm, and ATC (Wu et al., 23 Jan 2026). This coding layer is technically significant because it places ontology normalization and crosswalk logic inside the framework rather than in external preprocessing notebooks.

4. Model zoo and end-to-end workflows

The original paper reports more than 30 predictive models in version 0.0.6, spanning classical machine learning and deep learning (Zhao et al., 2021). Classical models include Random Forests and XGBoost. Deep model families include sequence architectures such as LSTM, GRU, RETAIN, Dipole, tLSTM, RAIM, StageNet, and Bidirectional-GRU; image backbones such as Vggnet, Inception, Resnet, Resnext, Densenet, and Mobilenet; signal models such as DBLSTM-WS, DenseConv, DeepRes1D, Autoencoder+BiLSTM, KRCRnet, and MINA; and text models such as DR-CAML, DCAN, JointLAAT, and MultiResCNN (Zhao et al., 2021).

PyHealth 2.0 reorganizes this landscape into a contemporary model zoo with general sequence models, healthcare-specific architectures, drug recommendation models, graph models, generative models, and wrappers around external ecosystems (Wu et al., 23 Jan 2026). General architectures include RNN, Transformer, CNN, TCN, and MLP. Healthcare-specific models include RETAIN, StageNet, StageAttentionNet, AdaCare, ConCare, GRASP, Dr. Agent, Deepr, SparcNet, and ContraWR. Drug recommendation models include SafeDrug, GAMENet, MICRON, and MoleRec. The toolkit also exposes TorchvisionModel, TransformersModel, LogisticRegression, VAE, GAN, GCN, and GAT wrappers, and a SdohClassifier based on Llama 3.1 with LoRA fine-tuning (Wu et al., 23 Jan 2026).

The workflow is deliberately standardized. In the 2021 formulation, a user initializes experiment data, selects a task, loads preprocessed splits, instantiates a model such as LSTM, calls fit, then runs inference and get_results, followed by evaluation through a shared function (Zhao et al., 2021). In PyHealth 2.0, the same pattern is recast around dataset classes, task objects, SampleDataset, model construction, and Trainer, with the heavy work of table joins, cohort construction, encoding, and label generation delegated to the framework (Wu et al., 23 Jan 2026).

This standardized interface has methodological consequences. Because multiple architectures consume the same processed task object, architectural comparison is less confounded by bespoke cohort logic. This is especially visible in downstream studies that compare StageNet, Transformer, and StageAttn on the same MIMIC-IV time-series tasks using shared loaders and shared evaluation code (Fan et al., 25 Mar 2026).

5. Interpretability, calibration, and uncertainty quantification

PyHealth 2.0 treats interpretability and uncertainty quantification as first-class modules rather than auxiliary scripts. The interpretability stack includes gradient-based attribution, Integrated Gradients, DeepLIFT, GIM, LIME, SHAP, CheferRelevance, and visualization utilities such as visualize_image_attr (Wu et al., 23 Jan 2026). The calibration stack includes Temperature Scaling, Histogram Binning, Dirichlet Calibration, and KCal, while prediction-set methods include LABEL, SCRIB, FavMac, and CovariateLabel (Wu et al., 23 Jan 2026). For prediction sets, the framework follows the conformal target

$$\mathbb{P}\left(Y \in \Gamma(X)\right) \ge 1 - \alpha .$$

A concrete demonstration of PyHealth’s interpretability machinery appears in the reproducibility study on time-series deep clinical predictive models. There, PyHealth is the implementation backbone for loading and preprocessing MIMIC-IV EHR time series, training StageNet, Transformer, and StageAttn, plugging in seven attribution methods, and benchmarking them across mortality prediction, length-of-stay prediction, and diabetic ketoacidosis prediction (Fan et al., 25 Mar 2026). The study standardizes attribution through a common API returning an attribution map $\mathbf{A} \in \mathbb{R}^d$ and evaluates explanations using comprehensiveness, sufficiency, runtime, and the combined score

$$\text{Score} = \text{Comprehensiveness} \times (1 - \text{Sufficiency}).$$

Within this framework, the authors report that attention when leveraged properly is a highly efficient approach for faithfully interpreting model predictions; Chefer’s gradient-weighted attention interpretability achieves the most faithful explanations across tasks and models and is about 15× faster than Integrated Gradients; Kernel SHAP and LIME are computationally infeasible at scale, with estimated runtimes of ~300 hours and ~64 hours, respectively, for 137,778 mortality prediction samples; and DeepLIFT, GIM, and LIME can be unreliable, sometimes losing to a random baseline (Fan et al., 25 Mar 2026).

A second example appears in the EEG conformal prediction study, which implements Naive CP, Covariate CP, K-means CP, and Neighborhood Conformal Prediction in PyHealth on TUAB and TUEV (Chatterjee et al., 23 Feb 2026). In that work, conformal prediction is exposed as a model-agnostic wrapper around a probabilistic classifier with nonconformity score

$V(x, y) := 1 - p_\theta(y \mid x),$

and prediction set

$$\widehat{C}(x) = \left\{ y \in \mathcal{Y}: V(x,y) \le \hat{q}_{1-\alpha} \right\}.$$

The key empirical result is that personalized calibration strategies can improve coverage by over 20 percentage points while maintaining comparable prediction set sizes; at $\alpha = 0.2$, NCP achieves about 25 percentage points higher coverage than Naive CP with only modest increase in prediction set size. At the same time, even NCP fails to hit target coverage at $\alpha = 0.01$, showing that conformal methods remain vulnerable under severe patient distribution shift and label uncertainty (Chatterjee et al., 23 Feb 2026).

6. Reproducibility, systems performance, and the surrounding ecosystem

Reproducibility is a foundational theme across PyHealth papers. The 2021 library already emphasized standardized experiment generators, common train/validation/test splits, task-type inference, unit testing, continuous integration, code coverage, and documentation hosted through Read the Docs (Zhao et al., 2021). PyHealth 2.0 extends this through configuration-driven datasets, shared task APIs, caching, trainer-based execution, and a research initiative oriented toward peer-reviewed community contributions (Wu et al., 23 Jan 2026).

The systems work in PyHealth 2.0 is unusually prominent for a research toolkit. On MIMIC-IV 2.2, it reports up to 39× faster task processing and more than 20× lower memory usage than older versions, with support for machines ranging from 16GB laptops to production systems (Wu et al., 23 Jan 2026). The implementation achieves this through lazy loading, a multi-stage caching pipeline, Dask and Narwhals for out-of-core table joins, Polars-based task transformation, and LitData-backed streaming datasets (Wu et al., 23 Jan 2026). This systems emphasis is consequential because many clinical ML benchmarks are bottlenecked by preprocessing rather than by model fitting.

PyHealth’s extensibility is also illustrated by external-but-related benchmarks built on top of it. The synthetic EHR generation framework for longitudinal ICD diagnosis codes is explicitly built on the community-maintained PyHealth library and uses PyHealth-style dataset abstractions, model interfaces, training utilities, and evaluation patterns to unify MedGAN, CorGAN, PromptEHR, HALO, and a GPT-2 baseline under a single privacy-utility evaluation suite with bootstrapped confidence intervals (Jiang et al., 5 Jun 2026). This suggests that PyHealth functions not only as an end-user toolkit but also as a substrate for domain-specific benchmark packages.

The broader ecosystem described in PyHealth 2.0 includes an active open-source community of 400+ members, 50+ tutorials and examples, collaborations with academic health systems and industry partners, and multi-language support via RHealth (Wu et al., 23 Jan 2026). A plausible implication is that PyHealth has evolved into a benchmark-centered software ecosystem rather than a fixed library release. Even so, the papers are also clear about current boundaries: interpretability support is strongest for tabular time-series and image models, conformal guarantees can break under strong shift, and off-the-shelf multimodal model coverage remains more limited than the data-loading stack (Wu et al., 23 Jan 2026, Chatterjee et al., 23 Feb 2026).

In aggregate, PyHealth occupies a distinctive position in the healthcare ML tooling landscape. It combines dataset ingestion, task formalization, model development, evaluation, interpretability, calibration, coding-system translation, and benchmark engineering within one framework. The available evidence presents it as a reusable infrastructure layer for clinical predictive modeling, interpretability research, uncertainty quantification, and synthetic health data benchmarking rather than as a narrow package for a single modality or task family (Zhao et al., 2021, Wu et al., 23 Jan 2026).