feat: add SleepWakeDetectionDREAMT and SleepStagingDREAMT tasks for DREAMT dataset

[Pstack-maker]

Contributors

• Prachi Pradhan (prachip3@illinois.edu)
• Ashton Su (ivysu2@illinois.edu)
• Ellen Yang (yaweny2@illinois.edu)

Type of Contribution

Standalone Task

Original Paper

Wang et al. (2024). Addressing wearable sleep tracking inequity: a new dataset
and novel methods for a population with sleep disorders. CHIL 2024, PMLR 248:380-396.
https://proceedings.mlr.press/v248/wang24a.html

Description

Adds two PyHealth tasks for the existing DREAMTDataset:

1. SleepWakeDetectionDREAMT — binary wake/sleep detection per 30-second epoch
2. SleepStagingDREAMT — 5-class sleep staging (W/N1/N2/N3/REM) per epoch

Feature engineering follows paper section 2.5 (ACC bandpass filtering,
TEMP winsorization, BVP filtering, EDA detrending, HR stats). AHI and BMI
are attached to each epoch as clinical metadata to support mixed-effects
modeling (paper section 2.6).

Ablation Study

Mirrors paper Table 2 using 3 LightGBM configurations on real DREAMT data:

• Ablation A: Baseline LightGBM — F1: 0.249, AUROC: 0.718
• Ablation B: LightGBM + AHI (apnea severity) — F1: 0.259, AUROC: 0.709
• Ablation C: LightGBM + BMI (obesity) — F1: 0.380, AUROC: 0.624

Results confirm the paper's finding that adding clinical metadata improves
sleep/wake detection.

File Guide

• pyhealth/tasks/sleep_wake_dreamt.py — main task implementation
• tests/test_sleep_wake_dreamt.py — 19 unit tests with synthetic data
• docs/api/tasks/pyhealth.tasks.sleep_wake_dreamt.rst — documentation
• docs/api/tasks.rst — updated index
• examples/dreamt_sleep_wake_detection.py — ablation study

Running the Example

Demo mode (no data needed):

python examples/dreamt_sleep_wake_detection.py --demo

Real data:

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