Add WatchSleepNet model with synthetic example and unit tests

[T-D-X]

Summary

This PR adds a reproducibility-oriented wearable sleep staging pipeline to PyHealth based on the WatchSleepNet paper:

WatchSleepNet: A Novel Model and Pretraining Approach for Advancing Sleep Staging with Smartwatches

The contribution includes:

• a new DREAMTDataset loader for DREAMT-style sleep staging data
• a 3-class DREAMT sleep staging task
• a simplified WatchSleepNet model
• a more sequence-style DREAMT task and sequence-output model mode for closer paper alignment
• fast synthetic unit tests
• a synthetic example/ablation script
• API documentation updates

This is a best-faith implementation intended for reproducibility and educational use. It is inspired by the paper, but it is not an exact reproduction of the full original training pipeline.

Contribution Type

• New dataset
• New task
• New model
• Full pipeline contribution

Paper

• Title: WatchSleepNet: A Novel Model and Pretraining Approach for Advancing Sleep Staging with Smartwatches
• Link: https://proceedings.mlr.press/v287/wang25a.html

What Was Added

1. DREAMT dataset support

Added pyhealth/datasets/dreamt.py.

Key behavior:

• supports official DREAMT-style local directory layouts
• supports partial local subsets
• supports processed per-subject files in common formats
• creates metadata linking each patient to locally available signal files
• provides helpful validation errors for malformed or missing data

2. DREAMT sleep staging task

Added DREAMT-oriented task support in pyhealth/tasks/sleep_staging.py.

Task variants:

• SleepStagingDREAMT
  • simplified fixed-window classification
• SleepStagingDREAMTSeq
  • sequence-style epoch-level sleep staging closer to the WatchSleepNet setting

Label mapping:

• Wake -> 0
• NREM -> 1
• REM -> 2

3. WatchSleepNet model

Added pyhealth/models/watchsleepnet.py.

Implemented components:

• residual 1D convolution blocks
• optional dilated TCN blocks
• bidirectional LSTM
• optional multi-head self-attention
• pooled classification mode
• sequence-output mode for timestep/epoch-level prediction

This is a simplified and maintainable WatchSleepNet-style architecture rather than an exact line-by-line reproduction.

4. Synthetic tests

Added fast synthetic tests:

• tests/core/test_dreamt_dataset.py
• tests/core/test_sleep_staging_task.py
• tests/core/test_watchsleepnet.py

The tests use only synthetic data and do not depend on real DREAMT data.

5. Example / ablations

Added:

• examples/dreamt_sleep_staging_watchsleepnet.py

The example demonstrates:

• synthetic DREAMT data generation
• end-to-end dataset/task/model usage
• window classification and sequence-style usage
• lightweight ablations including:
  • with vs without attention
  • with vs without TCN
  • smaller hidden size
  • IBI-only vs IBI + contextual wearable features

Reported example metrics include:

• accuracy
• macro F1
• REM F1
• Cohen's kappa
• AUROC

6. Documentation

Added/updated:

• docs/api/datasets/pyhealth.datasets.DREAMTDataset.rst
• docs/api/tasks/pyhealth.tasks.sleep_staging.rst
• docs/api/models/pyhealth.models.WatchSleepNet.rst
• relevant exports in task/model init files

File Guide

Dataset

• pyhealth/datasets/dreamt.py

Task

• pyhealth/tasks/sleep_staging.py
• pyhealth/tasks/__init__.py

Model

• pyhealth/models/watchsleepnet.py
• pyhealth/models/__init__.py

Tests

• tests/core/test_dreamt_dataset.py
• tests/core/test_sleep_staging_task.py
• tests/core/test_watchsleepnet.py

Example

• examples/dreamt_sleep_staging_watchsleepnet.py

Docs

• docs/api/datasets/pyhealth.datasets.DREAMTDataset.rst
• docs/api/tasks/pyhealth.tasks.sleep_staging.rst
• docs/api/models/pyhealth.models.WatchSleepNet.rst

How To Run

Unit tests

python -m unittest tests.core.test_dreamt_dataset -v
python -m unittest tests.core.test_sleep_staging_task -v
python -m unittest tests.core.test_watchsleepnet -v

Example / ablations

PYTHONPATH=. python examples/dreamt_sleep_staging_watchsleepnet.py

Assumptions and Limitations

• This PR is a simplified reproducibility-oriented implementation, not a full exact reproduction of the paper.
• The original paper includes large-scale pretraining / transfer learning across datasets; that full pretraining pipeline is not included here.
• DREAMT parsing is designed to be robust to common local layouts and partial downloads, but unofficial local formats may still require small preprocessing adjustments.
• The sequence-style task and model mode move closer to the paper’s seq2seq formulation, but do not fully replicate all paper preprocessing details.
• Automated tests use only synthetic data, in line with the project constraints.

Notes For Reviewers

Recommended review order:

1. pyhealth/datasets/dreamt.py
2. pyhealth/tasks/sleep_staging.py
3. pyhealth/models/watchsleepnet.py
4. tests/core/test_dreamt_dataset.py
5. tests/core/test_sleep_staging_task.py
6. tests/core/test_watchsleepnet.py
7. examples/dreamt_sleep_staging_watchsleepnet.py

Authors

Name	NetID	Email
Tan Dong Xiang	dxt2	dxt2@illinois.edu