Final project submission: temporal MIMIC3 pipeline

[elizabethbinkina]

Name: Elizabeth Binkina
NetID: binkina2

Type of Contribution:
Full pipeline (Dataset + Task + Model)

Paper: (https://proceedings.mlr.press/v106/nestor19a.html)

Nestor, Bret, Matthew B. A. McDermott, Willie Boag, Gabriela Berner, Tristan Naumann, Michael C. Hughes, Anna Goldenberg, and Marzyeh Ghassemi. 2019. “Feature Robustness in Non-stationary Health Records: Caveats to Deployable Model Performance in Common Clinical Machine Learning Tasks.” Proceedings of Machine Learning Research 106:1–23.

Description:
This PR introduces a temporal extension of the MIMIC-III dataset, along with a hospital mortality prediction task and a neural network model that incorporates temporal features. The goal of this contribution is to enable modeling of temporal trends in patient data by incorporating admission year as a feature and supporting temporally consistent dataset splits.

Key features:

• Temporal normalization of admission year (scaled between 0 and 1)
• Temporal train/validation/test splits based on admission year
• Integration of temporal features into downstream prediction tasks
• Lightweight neural model (TemporalFusionMLP) for combining temporal and clinical features

Files Added/Modified:

• pyhealth/datasets/mimic3_temporal.py
• pyhealth/datasets/configs/mimic3_temporal.yaml
• pyhealth/tasks/temporal_hospital_mortality_prediction.py
• pyhealth/models/temporal_fusion_mlp.py
• examples/mimic3_temporal_hospital_mortality_temporalfusionmlp.py
• tests/core/test_mimic3_temporal.py
• tests/core/test_temporal_fusion_mlp.py
• tests/core/test_temporal_hospital_mortality_prediction.py
• docs/api/datasets/pyhealth.datasets.mimic3_temporal.rst
• docs/api/models/pyhealth.models.temporal_fusion_mlp.rst
• docs/api/tasks/pyhealth.tasks.temporal_hospital_mortality_prediction.rst

Example Usage:
Run the following script to reproduce results:

python examples/mimic3_temporal_hospital_mortality_temporalfusionmlp.py

This script demonstrates:

• Random vs temporal dataset splits
• Model performance with and without temporal features

Testing:
Unit tests are included for:

• Dataset utilities (normalization and temporal splitting)
• Task sample generation and modality requirements
• Model instantiation, forward pass, and gradient computation

All tests use synthetic data and run quickly.