Tutorials

PyHealth Tutorials

Learn PyHealth in Colab

Nine hands-on notebooks for PyHealth 2.1, from your first clinical prediction model to calibration, interpretability, clinical text and contributing. Every notebook runs on a free Colab runtime with synthetic or public data, so no credentials are needed.

Start with the Quickstart → Documentation

The series

Open a notebook and choose Runtime > Run all. The first cell installs pyhealth==2.1.0. Each tutorial lists what it assumes, so you can also jump straight to the topic you need. Tested end to end on Colab with PyHealth 2.1.0.

00

Quickstart: your first clinical prediction model

  • The five steps every PyHealth project follows: dataset, task, split, model, evaluation
  • How to predict in-hospital mortality from diagnosis, procedure and drug codes
  • How to read the results, and why PR-AUC matters for rare outcomes

about 15 minutes on a free Colab CPU runtime · Before this: nothing. This is the place to start

Open in Colab →
01

Datasets: patients, events and your own data

  • The difference between a dataset and a task, and why PyHealth keeps them apart
  • How to explore patients and their events, filter by type, time or admission
  • What the YAML config does, and how caching works
  • How to load your own CSV files with a short config, no new class needed

about 20 minutes on a free Colab CPU runtime · Before this: Tutorial 00 (Quickstart) is helpful but not required

Open in Colab →
02

Tasks and processors: from patients to model-ready samples

  • What a task is: a function from one patient to a list of samples
  • How input and output schemas pick a processor for each field
  • What each common processor produces (sequence, nested sequence, multi-hot, tensor, labels)
  • How to write your own task, filter patients early, and use it with any model

about 25 minutes on a free Colab CPU runtime · Before this: Tutorial 01 (Datasets)

Open in Colab →
03

Training and evaluating models properly

  • How to split so that nothing about the test patients leaks into training
  • How to control training: epochs, early stopping, learning rate, checkpoints
  • How to handle a rare outcome with a positive-class weight, and what it costs
  • How to report discrimination and calibration with patient-level confidence intervals

about 25 minutes on a free Colab CPU runtime · Before this: Tutorials 00 and 02

Open in Colab →
04

Choosing a model: from logistic regression to XGBoost

  • What the main PyHealth models assume about the data, and when to pick each
  • How to compare several models fairly on the same patients
  • How to add a gradient-boosted tree baseline (XGBoost) to a PyHealth benchmark

about 15 minutes on a free Colab CPU runtime · Before this: Tutorial 03. A GPU runtime adds the sequence models

Open in Colab →
05

Interpreting predictions

  • Which inputs drive a model overall (global importance) and for one patient (local explanation)
  • Exact TreeSHAP for XGBoost, and Integrated Gradients for neural models
  • How to check whether an explanation is faithful to the model, not just plausible

about 20 minutes on a free Colab CPU runtime · Before this: Tutorial 04 (we reuse its heart-failure task)

Open in Colab →
06

Medical codes: lookups, mappings and groupers

  • What the common code systems are (ICD-9, ICD-10, CCS, ATC, NDC) and how they relate
  • How to look up a code's name, parents and children
  • How to translate between ICD-9 and ICD-10 and group codes into broader categories
  • How to use a grouping inside a task to shrink the vocabulary a model must learn

about 15 minutes on a free Colab CPU runtime · Before this: Tutorial 02 (processors and vocabularies)

Open in Colab →
07

Clinical text: classification and medical coding

  • How to fine-tune a Hugging Face language model on clinical notes with PyHealth
  • Multiclass text classification: which specialty wrote this report?
  • Multilabel medical coding: which ICD codes does this note support?
  • Why a simple TF-IDF baseline belongs next to every language model

about 25 minutes on a free Colab CPU runtime · Before this: Tutorials 00 and 02. A GPU runtime (Runtime > Change runtime type > T4 GPU) makes training much faster

Open in Colab →
08

Contributing a dataset or task to PyHealth

  • Whether your idea is a dataset, a task, or both
  • How a dataset class is built: config, default tables, per-table preprocessing, a default task
  • How to handle data that is not a table (files on disk)
  • How to test it with tiny synthetic data, and what a PR needs to pass review

about 25 minutes on a free Colab CPU runtime · Before this: Tutorials 01 and 02

Open in Colab →