Add SleepStagingDREAMT task for DREAMT wearable sleep dataset

[ErieMAdames]

Authors: Jash Parekh (jashrp2@illinois.edu), Tom Wang (twwang2@illinois.edu), Erie M. Adames (eadames2@illinois.edu)
Contribution Type: Standalone Task (Option 3)
Paper: Wang et al., "DREAMT: Dataset for Real-time Sleep Stage Estimation using Multisensor Wearable Technology", CHIL 2024
Paper Link: https://proceedings.mlr.press/v248/wang24a.html

Overview

This PR adds a sleep staging task (SleepStagingDREAMT) for the existing DREAMT dataset in PyHealth. The task segments overnight Empatica E4 wearable signals into 30-second epochs and assigns sleep stage labels with support for 2-class (wake/sleep), 3-class (wake/NREM/REM), and 5-class (W/N1/N2/N3/R) granularity.

Task (sleep_staging_dreamt.py)

• Processes 8 E4 signal channels (ACC x/y/z, BVP, EDA, HR, IBI, TEMP)
• Applies signal-specific preprocessing (Butterworth bandpass for ACC, Chebyshev highpass for BVP/EDA, winsorization for TEMP)
• Supports configurable signal column subsets for ablation studies
• Maps PSG-annotated sleep stages to 2, 3, or 5 classes
• Excludes artifact epochs (stage "P") and missing data
• Properly inherits from BaseTask with input_schema and output_schema

Ablation Study (examples/dreamt_sleep_wake_lstm.py)

Two ablation studies with 5-fold participant-level cross-validation:

1. Signal subset ablation — compares ACC-only, BVP+HRV, EDA+TEMP, and ALL signals using 2-class labels
2. Label granularity ablation — compares 2-class (wake vs sleep) vs 5-class (W/N1/N2/N3/R) using all signals

• Includes a single-layer LSTM classifier
• Runnable with --demo flag using fully synthetic data (no dataset download required)
• Reports F1, AUROC, Accuracy, and Cohen's Kappa

Unit Tests (tests/core/test_sleep_staging_dreamt.py)

• 26 tests using synthetic CSV data via pytest tmp_path
• Covers: initialization, label mappings (2/3/5-class), signal shape, patient ID, epoch ordering, stage exclusion (P / Missing), signal column subsets, filtering/winsorization, and edge cases
• All tests complete in ~3-5 seconds using only synthetic data

File Guide

File	Description
pyhealth/tasks/sleep_staging_dreamt.py	Core task implementation
pyhealth/tasks/__init__.py	Added SleepStagingDREAMT import (1 line)
tests/core/test_sleep_staging_dreamt.py	26 unit tests (synthetic data only)
examples/dreamt_sleep_wake_lstm.py	LSTM ablation study script with --demo mode
docs/api/tasks/pyhealth.tasks.SleepStagingDREAMT.rst	API documentation stub
docs/api/tasks.rst	Added entry to Available Tasks toctree (1 line)