PyHealth 2.1.0

[jhnwu3]

PyHealth 2.1.0 focuses on making results trustworthy: leakage-free preprocessing with split-aware set_task, reproducible training, and calibration metrics with patient-level confidence intervals. It also adds an XGBoost model with exact TreeSHAP, Synthea synthetic-patient generation, ICD-9 ↔ ICD-10 translation, and a nine-notebook tutorial series.

pip install -U pyhealth==2.1.0
pip install -U "pyhealth[xgboost]==2.1.0"   # with XGBoostModel

Warning

Rebuild caches built with more than 10 workers. Before this release, set_task with more than 10 workers could misorder its sample index, so patient-level splits shared patients between train and val/test (on full MIMIC-IV with 32 workers, ~3.6k patients). 2.1.0 fixes this, but caches built that way are still reused as-is. Delete them and rebuild. (#1273)

Before you upgrade

• Dependencies:
  • Requires torch>=2.10, pyarrow>=23.0.1, dask[complete]>=2026.1.0 and litdata>=0.2.64,<0.2.68. (Unpin dependencies that block security fixes; drop unused urllib3 #1254, Fit processors on the training split in set_task (split=PatientSplit) #1273)
  • numpy, pandas, pydantic, scikit-learn and narwhals use bounded ranges, so installs on Google Colab no longer downgrade packages it has already loaded. (Loosen numpy/pandas/pydantic/scikit-learn/narwhals pins so Colab installs don't downgrade #1287)
  • icd-mappings is a new dependency; urllib3 is no longer one. (medcode: ICD-9 <-> ICD-10 translation and grouper vocabularies via icd-mappings #1257, Unpin dependencies that block security fixes; drop unused urllib3 #1254)
• EHR-generation tasks: the EHRGeneration base class is removed and there is one task per encoding and dataset (Add NestedMultiHotProcessor and vectorise HALO's visit encoding #1233):
  • EHRGenerationMIMIC3/4: per-visit multi-hot rows, for HALO. These now emit nested_multihot instead of nested_sequence.
  • EHRSequenceGenerationMIMIC3/4: per-visit code indices, for GPT-2 and PromptEHR.
  • EHRCodeSetGenerationMIMIC3/4: one code set per patient, for MedGAN and CorGAN.
• Event timestamps: a missing timestamp is now None. It used to be datetime.now(), which sorted before every real event and slipped through time-window filters. (Keep missing Event timestamps as None; make Event copyable and picklable #1247)
• Caches: dataset and sample caches rebuild once on first use, because their cache keys changed. Old cache folders stay on disk and can be deleted. (Key the dataset cache on the config and source files #1265, Store non-tensor sample fields as one opaque value per sample (fix variable-length raw fields on the disk cache) #1277)
• Shuffles and splits: runs are now reproducible from a seed, but the same seed selects different batches and patients than in 2.0.2. (Make training reproducible: seeded per-loader shuffles, no global RNG side effects #1280, Make split_by_patient independent of sample order #1286)
• Logging: the pyhealth logger no longer propagates to the root logger, so each message prints once in Jupyter and Colab. (Print each PyHealth log line once in Jupyter and Colab #1285)
• Default cache location: building a dataset without cache_dir logs a warning naming the folder it writes to. Set PYHEALTH_REQUIRE_CACHE_DIR=1 to make it an error. (Warn about the default dataset cache; allow requiring cache_dir #1264)
• Removed: the unmaintained 2023 chat-assistant/ demo. (Remove the unmaintained chat-assistant demo #1252)

New features

• Split-aware preprocessing (Fit processors on the training split in set_task (split=PatientSplit) #1273):
  • dataset.set_task(task, split=PatientSplit(...)) fits every processor on the training patients only and returns (train, val, test) views of one processed cache.
  • PatientSplit takes two or more ratios, for example train/val/calibration/test.
  • Custom splits implement the new Split interface.
  • Processors that learn statistics warn when they are fitted on all samples.
• Reproducible training (Make training reproducible: seeded per-loader shuffles, no global RNG side effects #1280):
  • get_dataloader(..., seed=...) gives each loader its own seeded, per-epoch shuffle, in memory and on disk.
  • torch.manual_seed alone now makes runs repeatable.
  • New pyhealth.utils.preserve_rng_state(). set_task, dataset creation and the interpretability methods no longer change global random state, and importing pyhealth.models no longer reseeds numpy and torch.
  • Trainer.train restores the best epoch even with logging off (keep_best_in_memory).
• Calibration and confidence intervals (Add calibration metrics and patient-clustered bootstrap CIs #1268):
  • binary_metrics_fn adds brier, oe_ratio, calibration_slope and calibration_intercept.
  • New pyhealth.metrics.bootstrap with bootstrap_ci and paired_bootstrap_diff. Pass groups= to resample whole patients.
• Imbalanced outcomes: BaseModel.set_pos_weight(...) takes a number, one number per label, or "balanced" computed from a training dataset. (Add BaseModel.set_pos_weight for imbalanced binary/multilabel outcomes #1267)
• XGBoostModel (Add XGBoostModel (gradient-boosted trees) with exact TreeSHAP #1278):
  • Gradient-boosted trees for binary, multiclass, multilabel and regression tasks.
  • Train with model.fit(train, val=None), then evaluate with the usual Trainer.
  • Accepts tensor, timeseries, multi-hot and nested multi-hot inputs; bag_of_codes=True turns code sequences into per-patient code counts.
  • Supports scale_pos_weight and early stopping.
  • Exact TreeSHAP through explain() and the new pyhealth.interpret.methods.TreeSHAP.
• Synthea (Integrate Synthea with PyHealth #1244):
  • pyhealth.models.Synthea runs the Synthea synthetic-patient generator. It needs Java 17+ and downloads and caches the Synthea JAR.
  • SyntheaCSVDataset loads Synthea's CSV output.
• Medical codes (medcode: ICD-9 <-> ICD-10 translation and grouper vocabularies via icd-mappings #1257):
  • CrossMap translates ICD-9 ↔ ICD-10 and maps codes to CCSR categories, chapters and blocks, and chronic-condition indicators, using the icd-mappings package.
  • Existing mappings such as ICD9CM → CCSCM are unchanged.
  • ICD-9 ↔ ICD-10 follows each code's primary mapping only, so some codes map to nothing or don't round-trip. Those are reported through a warning and CrossMap.unmapped_codes.
• Processors:
  • New NestedMultiHotProcessor ("nested_multihot"): one multi-hot row per visit, 8.6× smaller per patient on eICU. (Add NestedMultiHotProcessor and vectorise HALO's visit encoding #1233)
  • TensorProcessor.size() returns the fitted feature width. (Size tensor embeddings without re-processing samples #1262)
• HALO: visit encoding is vectorised, removing a loop that took ~85% of each training step on GPU. (Add NestedMultiHotProcessor and vectorise HALO's visit encoding #1233)

Fixes

• Leakage and labels:
  • MultimodalMortalityPredictionMIMIC4 used chest X-rays taken after the prediction time. (Prevent future X-ray leakage #1229)
  • T1DDKAPredictionMIMIC4 counted DKA events recorded before a separate T1DM diagnosis. (Fix T1D DKA timing #1230)
  • Patient-level splits with more than 10 workers mixed patients across parts (see the warning above). (Fit processors on the training split in set_task (split=PatientSplit) #1273)
  • Supplying fitted processors for only some fields left the others unprocessed. (Fit processors on the training split in set_task (split=PatientSplit) #1273)
• Datasets and caching:
  • Editing a source file or the dataset's YAML config reused the stale cache. (Key the dataset cache on the config and source files #1265)
  • Sample fields whose length varies between samples failed or were misread on the disk cache. (Store non-tensor sample fields as one opaque value per sample (fix variable-length raw fields on the disk cache) #1277)
  • Visits longer than the fitted width produced batches with mismatched widths; they are now truncated with a warning. (Truncate nested inputs longer than the fitted width #1263)
  • Event objects could not be copied or unpickled. (Keep missing Event timestamps as None; make Event copyable and picklable #1247)
  • Each dataset build leaked file descriptors, causing "Too many open files" on macOS. (Fix file descriptor leak when building global_event_df #1245)
  • Interrupted downloads left truncated files that later runs reused, and stalled downloads hung. (Make downloads atomic with a timeout; harden ChestX-ray14 extraction #1255)
  • Patient splitters chose different patients for the same seed depending on sample order. (Make split_by_patient independent of sample order #1286)
• Models:
  • 16 models crashed in Trainer.evaluate when output_schema used a processor class or tuple. (Resolve model.mode for every output_schema form (fixes Trainer.evaluate crash, #914) #1246, fixes PyHealth trainer uses deprecated model.mode attribute instead of checking its output or label processors #914)
  • GRASP never built its similar-patient graph. (Fix GRASP's dead similar-patient graph #1194)
  • TransformerDeID ignored its configured feature and label keys. (Fix: Use configured TransformerDeID field names #1224)
• Interpretability: comprehensiveness and sufficiency crashed for every model with code-sequence inputs. (Fix comprehensiveness/sufficiency crash on code-sequence inputs #1284)

Docs, examples and infrastructure

• Nine-notebook tutorial series under examples/tutorials/series/, from a first model to contributing, each runnable on a CPU Colab runtime. (Add a nine-notebook tutorial series, from first model to contributing #1281)
• New docs sections and example scripts for reproducible runs, split-aware set_task, reusing fitted processors, imbalanced outcomes, calibration and bootstrap CIs, cache behaviour, identified data, and logging setup.
• SECURITY.md describes private vulnerability reporting and which files must come from trusted sources. (Add SECURITY.md and least-privilege workflow permissions #1253)
• Dependency minimums were raised past known security issues; pip-audit reports none on a fresh install. (Unpin dependencies that block security fixes; drop unused urllib3 #1254)
• CI now reports test coverage. (CICD: Add test coverage reporting.  #1299)

See CHANGELOG.md for full details on every change.

Full Changelog: v2.0.2...v2.1.0

---

This discussion was created from the release PyHealth 2.1.0.