# madsolsen/sleepstageprediction architecture

> Architecture diagram of the GitHub repository madsolsen/sleepstageprediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/madsolsen/sleepstageprediction
- Repository: https://github.com/madsolsen/sleepstageprediction

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data I/O Layer
    subgraph "Data I/O" 
        direction TB
        RawData["Raw ACC & PPG (HDF5)"]:::db
        DatasetGen["Dataset Generator"]:::dataio
        DataUtils["I/O Utilities"]:::dataio
    end

    %% Signal Processing Layer
    subgraph "Signal Processing Pipeline"
        direction TB
        FeatureExt["Feature Extraction"]:::signal
        Spec["Spectrogram (STFT)"]:::signal
        Superlet["Superlet Transform"]:::signal
        Norm["Normalization"]:::signal
        Reg["Regularization"]:::signal
        PostProc["Post-Processing & Segmentation"]:::signal
    end

    %% Model Layer
    subgraph "Model Module"
        direction TB
        ConcatPad["Concatenate & Zero-Pad"]:::model
        ResUNet["ResUNet Encoder-Decoder"]:::model
        Classifier["Segment Classifier"]:::model
        Pretrained["Pretrained Weights"]:::db
    end

    %% Utilities Layer
    subgraph "Utilities & Callbacks"
        direction TB
        Loss["Loss Functions"]:::util
        Metrics["Metrics"]:::util
        LRSchedule["Learning-Rate Schedules"]:::util
        Viz["Visualization"]:::util
        Logger["Logging"]:::util
        H5Utils["HDF5 I/O Utils"]:::util
    end

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        direction TB
        TrainScript["train_and_evaluate.py"]:::dataio
        Notebook["train_and_evaluate.ipynb"]:::dataio
        ToH5["to_h5.py"]:::dataio
        TestH5["test_subject.h5"]:::db
    end

    %% Data Flow
    RawData -->|"Raw ACC/PPG frames"| DatasetGen
    DatasetGen -->|"Frame batches"| FeatureExt
    DataUtils --> FeatureExt

    FeatureExt -->|"Spectrogram tensor"| Spec
    FeatureExt --> Superlet
    Spec --> Norm
    Superlet --> Norm
    Norm --> Reg
    Reg --> PostProc
    PostProc -->|"Epoch segments"| ConcatPad

    ConcatPad --> ResUNet
    ResUNet --> Classifier
    Pretrained --> ResUNet

    Classifier -->|"Epoch predictions"| Loss
    Classifier --> Metrics
    Loss --> Logger
    Metrics --> Logger
    LRSchedule --> TrainScript
    Logger --> TrainScript
    Viz --> TrainScript
    H5Utils --> DatasetGen

    TrainScript --> Notebook
    TrainScript --> ToH5
    ToH5 --> TestH5

    %% Click Events
    click DatasetGen "https://github.com/madsolsen/sleepstageprediction/blob/master/datasets/dataset_gen.py"
    click DataUtils "https://github.com/madsolsen/sleepstageprediction/blob/master/datasets/utils.py"
    click FeatureExt "https://github.com/madsolsen/sleepstageprediction/blob/master/signal_processing/feature_extraction.py"
    click Spec "https://github.com/madsolsen/sleepstageprediction/blob/master/signal_processing/spectrogram.py"
    click Superlet "https://github.com/madsolsen/sleepstageprediction/blob/master/signal_processing/superlet.py"
    click Norm "https://github.com/madsolsen/sleepstageprediction/blob/master/signal_processing/normalization.py"
    click Reg "https://github.com/madsolsen/sleepstageprediction/blob/master/signal_processing/regularization.py"
    click PostProc "https://github.com/madsolsen/sleepstageprediction/blob/master/signal_processing/postprocessing.py"
    click ResUNet "https://github.com/madsolsen/sleepstageprediction/blob/master/models/CNN/resunet.py"
    click Pretrained "https://github.com/madsolsen/sleepstageprediction/blob/master/models/pretrained_weights/model-best.h5"
    click Pretrained "https://github.com/madsolsen/sleepstageprediction/blob/master/models/pretrained_weights/model.059.h5"
    click Loss "https://github.com/madsolsen/sleepstageprediction/blob/master/functions/loss.py"
    click Metrics "https://github.com/madsolsen/sleepstageprediction/blob/master/functions/metrics.py"
    click LRSchedule "https://github.com/madsolsen/sleepstageprediction/blob/master/functions/learning_rate.py"
    click TrainScript "https://github.com/madsolsen/sleepstageprediction/blob/master/minimal_example/train_and_evaluate.py"
    click Notebook "https://github.com/madsolsen/sleepstageprediction/blob/master/minimal_example/train_and_evaluate.ipynb"
    click ToH5 "https://github.com/madsolsen/sleepstageprediction/blob/master/minimal_example/to_h5.py"
    click TestH5 "https://github.com/madsolsen/sleepstageprediction/blob/master/minimal_example/test_subject.h5"
    click Viz "https://github.com/madsolsen/sleepstageprediction/blob/master/utils/visualize.py"
    click Logger "https://github.com/madsolsen/sleepstageprediction/blob/master/utils/logger.py"
    click H5Utils "https://github.com/madsolsen/sleepstageprediction/blob/master/utils/data_from_h5.py"

    %% Styles
    classDef dataio fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef signal fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef model fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef util fill:#cfd8dc,stroke:#546e7a,color:#263238;
    classDef db fill:#ffe082,stroke:#ff8f00,color:#e65100,stroke-dasharray: 5 5;
    class DatasetGen,DataUtils dataio
    class FeatureExt,Spec,Superlet,Norm,Reg,PostProc signal
    class ConcatPad,ResUNet,Classifier model
    class Loss,Metrics,LRSchedule,Viz,Logger,H5Utils util
    class RawData,Pretrained,TestH5 db
```
