Add SHy Model and MIMIC III Diagnosis Task

[JudyTi]

Contributor name

Judy Tian

NetID/email

judyt2@illinois.edu

Type of contribution

Option 4: model + task

Link to original paper

Yu, Leisheng, et al. "Self-Explaining Hypergraph Neural Networks for Diagnosis Prediction." ArXiv.org, 2025, arxiv.org/abs/2502.10689.

High-level description of implementation

Model

This PR adds the SHy (Self-Explaining Hypergraph) model, a novel neural network architecture for patient diagnosis prediction that models medical data as a hypergraph. The implementation is designed to capture the complex, multi-relational structure of healthcare data where a single medical event can involve multiple clinical concepts (i.e. previous hospital visit with several diagnoses). It mainly contains the HierarchicalEmbedding module, the UniGINConv hypergraph convolution (idea from paper and cite 1), and the main SHy model.

Files

• pyhealth/models/shy.py
• tests/core/test_shy.py
• pyhealth/models/__init__.py
• docs/api/models.rst
• docs/api/models/pyhealth.models.SHy.rst

Task

This PR also adds a new MIMIC-III Task alongside the model: DiagnosisPredictionMIMIC3 task. This task transforms raw MIMIC-III data into a sequence-to-sequence format for diagnosis prediction, where the input is a sequence of past visits (i.e. each a list of diagnosis codes) and the label is the set of diagnosis codes in the next visit.

Files

• pyhealth/tasks/diagnosis_prediction_mimic3.py
• tests/core/test_mimic3_diagnosis_prediction.py
• pyhealth/tasks/__init__.py
• docs/api/tasks.rst
• docs/api/tasks/pyhealth.tasks.diagnosis_prediction_mimic3.rst

Other

Example file is also added to work as a demo to show end-to-end workflow and use several different statistics metrics to test model accuracy.

Files

• examples/mimic3_diagnosis_shy.py

Cite:

• Huang, J., & Yang, J. "UNIGNN: A unified framework for graph and hypergraph neural networks." ArXiv.org, 2021, arxiv.org/abs/2105.00956.

Demo data from

• mimiciii-demo 1.4

File guide listing which files to review

File	Purpose
pyhealth/models/shy.py	Core model implementation. Contains the SHy class, the UniGINConv hypergraph convolution, and the HierarchicalEmbedding module.
tests/core/test_shy.py	Unit tests. Validates the instantiation, forward pass, output shapes, gradient computation for the SHy model.
pyhealth/models/__init__.py	Integration point. Exports the SHy model for public use.
docs/api/models.rst	Documentation. Adds API references for the new SHy model.
docs/api/models/pyhealth.models.SHy.rst	Documentation. RST file.
pyhealth/tasks/diagnosis_prediction_mimic3.py	New task definition. Transforms MIMIC-III data into the format required by the SHy model.
tests/core/test_mimic3_diagnosis_prediction.py	Unit tests. Validates the data transformation logic for the MIMIC-III task.
pyhealth/tasks/__init__.py	Integration point. Exports the DiagnosisPredictionMIMIC3 task.
docs/api/tasks.rst	Documentation. Adds API references for the new task.
docs/api/tasks/pyhealth.tasks.diagnosis_prediction_mimic3.rst	Documentation. RST file.
examples/mimic3_diagnosis_shy.py	End-to-end example script. Demonstrates loading MIMIC-III data, instantiating the SHy model and diagnosis prediction mimic3 task, and running an ablation study.

Test result

Config	PR-AUC	ROC-AUC	Recall@5	Precision@5	Loss
layers_0	0.1433	0.5781	0.0919	0.2	0.2878
layers_2	0.1512	0.6135	0.0919	0.2	0.2759
layers_5	0.1535	0.5756	0.0919	0.2	0.2884
layers_7	0.1616	0.5935	0.0919	0.2	0.2752
hdim_64	0.155	0.6157	0.0919	0.2	0.3248
hdim_128	0.1514	0.5651	0.0294	0.1	0.2965
hdim_256	0.1453	0.5359	0.0294	0.1	0.3369
hdim_512	0.1425	0.5379	0.0919	0.2	0.384
phenotypes_2	0.1631	0.5742	0.0919	0.2	0.2897
phenotypes_3	0.1516	0.6	0.0919	0.2	0.2889
phenotypes_5	0.1648	0.5816	0.0919	0.2	0.2891
phenotypes_7	0.1515	0.5801	0.0919	0.2	0.2863