How madsolsen/sleepstageprediction works
Project type and purpose
• This is a deep-learning research framework for temporal sleep-stage classification using accelerometry (ACC) and photoplethysmography (PPG) signals.
• It implements a U-Net-inspired convolutional encoder-decoder (ResUNet) plus a segment classifier to assign 30-second sleep-stage labels (wake, light, deep).
• The codebase includes data-ingestion, signal-processing, model definition, training/evaluation scripts, and a minimal example with pretrained weights.
File structure
• Top-level directories:
• datasets: data generation and I/O utilities (dataset_gen.py, utils.py)
• signal_processing: feature extraction (STFT, superlet, normalization, regularization, post-processing)
• models: CNN architectures (models/CNN/resunet.py), pretrained_weights
• functions: loss, metrics, learning rate schedules
• utils: miscellaneous helpers (IO, logging, visualization, formatting, subsampling, buffer, non-max suppression)
• minimal_example: ready-to-run example with train_and_evaluate scripts and a test_subject.h5 sample
• Configuration/dependencies folder holds library and environment specs if needed.
Key insights from the README
• Two input spectrograms (ACC & PPG) are time-aligned, concatenated, zero-padded → fed into deep CNN module.
• Encoder (M blocks) ↓ Decoder (M blocks) → segment classifier outputs per-epoch labels.
• Uses GELU activation, batch normalization, STFT front-end.
a. Main components:
1. Data Sources: raw ACC & PPG (HDF5 files)
2. Data Loader & Dataset Generator (datasets/)
3. Signal-Processing Pipeline (signal_processing/):
• Feature Extraction (STFT, Mel spectrogram, superlet)
• Normalization & Regularization
• Post-Processing & Segmentation (30 s epochs)
4. Model Module (models/):
• Concatenate & zero-pad inputs
• ResUNet Encoder-Decoder blocks
• Segment Classifier head
5. Training & Evaluation (minimal_example/train_and_evaluate.py & Jupyter notebook)
6. Loss, Metrics & Callbacks (functions/)
7. Pretrained Weights Loader (models/pretrained_weights/)
9. External Libraries (TensorFlow/Keras, NumPy, SciPy, h5py)
b. Relationships & interactions (dataflow):
Raw H5 data → Dataset Generator → Signal-Processing → Feature Tensors → Model → Predictions → Loss/Metric Computation → Logging → Checkpointing/Evaluation → Visualizations.
c. Architectural patterns & design principles:
• Modular separation: data I/O, signal processing, model definition, training logic, utilities.
• Pipeline pattern: sequential data transformation stages.
• Encoder-Decoder pattern for feature learning, plus classification head.
• Configurable components via function modules (loss, metrics, LR schedules).
d. Technologies/Frameworks:
• Python 3.x, TensorFlow/Keras (implied by .h5 model files), NumPy, SciPy
• h5py for HDF5 I/O
• Matplotlib/Seaborn for visualization
• FFmpeg or similar (if spectrogram generation outside Python)
• Data I/O (blue)
• Signal Processing (green)
• Model (orange)
• Utilities/Logging (gray)
• Parameters (e.g., window size for STFT, number of encoder blocks M, epoch length 30 s).
Essential elements
• Clear component labels and folder references (e.g., datasets/, signal_processing/feature_extraction.py).
• File/Folder modules vs. external services/libraries
• Compute modules vs. storage modules
• Where the minimal_example interfaces with the core pipeline.