Add DREAMTSleepClassification standalone task with ablation study

[suraj2498]

Standalone Task: DREAMTSleepClassification

Contributors: Suraj Kumar, Rahul Grover
Course: CS598 Deep Learning for Healthcare, UIUC

---

Type of Contribution

Standalone Task for existing PyHealth dataset (DREAMTDataset)

---

Related Paper

Wang et al., WatchSleepNet: A Novel Model and Pretraining Approach for Advancing Sleep Staging with Smartwatches, 2025.
https://proceedings.mlr.press/v287/wang25a.html

---

High-Level Description

This PR implements DREAMTSleepClassification, an IBI-based sleep staging task for the DREAMT wearable dataset that reproduces the preprocessing pipeline from WatchSleepNet (Wang et al., 2025).

The task segments each patient's full-night 64 Hz wrist-worn PPG recording into non-overlapping 30-second epochs, extracts non-zero Inter-Beat Interval (IBI) values per window, and assigns a majority-vote sleep stage label. Two label configurations are supported:

• 3-class (paper default): Wake / NREM / REM
• 4-class (novel ablation): Wake / N1 / N2 / N3 / REM

An optional accelerometer augmentation (use_accelerometer=True) appends raw ACC_X/Y/Z signals to each sample for wake-detection ablation studies.

Three novel ablation studies not present in the original paper are demonstrated in the example script:

1. Label granularity — 3-class vs 4-class staging, revealing severe N1/N3 class imbalance that justifies the paper's 3-class default
2. Accelerometer augmentation — IBI-only vs IBI + ACC, setting up a Wake F1 comparison
3. Epoch duration — 15s / 30s / 60s windows, confirming the linear tradeoff between temporal resolution and IBI context per window

Validated end-to-end on 7 patients from DREAMT v2.1.0 using PyHealth's built-in RNN model (test accuracy: 72.5%).

---

Files to Review

• pyhealth/tasks/dreamt_sleep_classification.py — core task implementation
• docs/api/tasks/pyhealth.tasks.DREAMTSleepClassification.rst — API documentation
• docs/api/tasks.rst — updated table of contents
• examples/dreamt_sleep_classification.py — ablation study script (runnable with --demo)
• examples/dreamt_sleep_classification.ipynb — Jupyter notebook version
• tests/core/test_dreamt.py — task + dataset tests (42 tests, synthetic data only)
• pyhealth/tasks/__init__.py — export added

---

Running the Example

No data download required

python examples/dreamt_sleep_classification.py --demo

With real DREAMT data

python examples/dreamt_sleep_classification.py --root /path/to/dreamt/2.1.0

Running the Tests

python -m unittest tests/core/test_dreamt.py -v

42 tests, ~1.2 seconds, all synthetic data