# stanford-stages/sleep-staging architecture

> Architecture diagram of the GitHub repository stanford-stages/sleep-staging, 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/stanford-stages/sleep-staging
- Repository: https://github.com/stanford-stages/sleep-staging

## Overview

##### Project Type and Purpose
- This is a research-oriented, command-line Python tool for sleep staging classification using neural networks.
- It also includes MATLAB scripts for initial data extraction from raw EEG files.
- No web UI or database—just data-processing modules, model definitions, and training/testing scripts.

##### High-Level Components
a. Data Extraction Layer (MATLAB)
- Folder: `matlab_training_data_scripts/`
- Scripts: `extractCC.m`, `get_cc_data.m`, `loadEDF.m`, etc.
- Output: preprocessed .mat or CSV files containing EEG features or channel data.

b. Configuration Module
- File: `sc_config.py`
- Role: Defines file paths (training/test directories), hyperparameters, window lengths, model types (e.g., “ac_lh_ls_lstm”).

c. Data Reader & Preprocessor
- File: `sc_reader.py` (+ validation/test variants)
- Role: Loads extracted data files, applies any final preprocessing (normalization, window slicing).

d. Neural Network Definition
- Files: `sc_network.py`, `sc_conv.py`
- Role: Build Keras/TensorFlow or PyTorch model architectures (e.g., convolutional layers, LSTM memory layers).

e. Training Orchestration
- File: `sc_train.py`
- Role: Reads config, calls reader to fetch batches, feeds data into model, manages epochs, checkpoints, and logs.

f. Evaluation & Validation
- Files: `sc_validate.py`, `sc_test.py`, plus `sc_reader_validate.py`, `sc_reader_test.py`
- Role: Load trained model, run on held-out data, compute performance metrics.

g. External Dependencies
- MATLAB (for data extraction).
- Python 3.6+ and scientific stack (NumPy, SciPy, TensorFlow/Keras or PyTorch).
- File system for data storage and model checkpoints.

##### Relationships & Data Flow
- Raw EEG files (.edf, .hdr) → MATLAB Scripts → Extracted feature files
- Extracted files → Python sc_reader → Batch tensors
- Batches + sc_config → sc_train → sc_network/sc_conv → Model checkpoints
- Checkpoints + sc_reader_test → sc_test/sc_validate → Metrics & Reports

##### Architectural Patterns & Design Principles
- Modular layering: separate data-extraction, reading, modeling, training, and evaluation.
- Configuration-driven runs: `sc_config.py` enables reproducibility and easy switching of datasets or hyperparameters.
- Single-responsibility scripts: each script has a clear, isolated purpose (train vs. test vs. validate).

##### Must-Include Elements
- Component names (e.g., sc_reader.py)
- Data flows with artifacts (e.g., “Normalized EEG windows”)
- MATLAB scripts vs. Python modules
- Code vs. Data vs. Models vs. External

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Dependencies"
        MATLAB["MATLAB Runtime"]:::external
        Python["Python 3.6+"]:::external
    end

    subgraph "Data Extraction Layer"
        MScripts["MATLAB Scripts"]:::matlab
    end

    MScripts -->|".edf/.hdr → .mat/.csv"| Extracted["Extracted Feature Files"]:::datastore
    MATLAB --> MScripts

    click MScripts "https://github.com/stanford-stages/sleep-staging/tree/master/matlab_training_data_scripts/"

    subgraph "Python Modules"
        Config["sc_config.py"]:::config
        Reader["sc_reader.py"]:::reader
        ReaderV["sc_reader_validate.py"]:::reader
        ReaderT["sc_reader_test.py"]:::reader
        Net["sc_network.py"]:::model
        Conv["sc_conv.py"]:::model
        Train["sc_train.py"]:::trainer
        Validate["sc_validate.py"]:::evaluator
        Test["sc_test.py"]:::evaluator
    end

    click Config "https://github.com/stanford-stages/sleep-staging/blob/master/sc_config.py"
    click Reader "https://github.com/stanford-stages/sleep-staging/blob/master/sc_reader.py"
    click ReaderV "https://github.com/stanford-stages/sleep-staging/blob/master/sc_reader_validate.py"
    click ReaderT "https://github.com/stanford-stages/sleep-staging/blob/master/sc_reader_test.py"
    click Net "https://github.com/stanford-stages/sleep-staging/blob/master/sc_network.py"
    click Conv "https://github.com/stanford-stages/sleep-staging/blob/master/sc_conv.py"
    click Train "https://github.com/stanford-stages/sleep-staging/blob/master/sc_train.py"
    click Validate "https://github.com/stanford-stages/sleep-staging/blob/master/sc_validate.py"
    click Test "https://github.com/stanford-stages/sleep-staging/blob/master/sc_test.py"

    Extracted -->|"Feature batches"| Reader
    Reader -->|"Normalized EEG windows"| Train
    ReaderV -->|"Validation batches"| Validate
    ReaderT -->|"Test batches"| Test
    Config -->|"hyperparams & paths"| Train
    Net -->|"defines architecture"| Train
    Conv -->|"defines conv layers"| Train
    Train -->|"model weights"| Check["Model Checkpoints"]:::datastore
    Check -->|"load for eval"| Validate
    Check -->|"load for test"| Test

    subgraph "Outputs"
        Metrics["Performance Metrics & Reports"]:::datastore
    end

    Validate -->|"metrics"| Metrics
    Test -->|"metrics"| Metrics

    Python --> Config
    Python --> Reader
    Python --> ReaderV
    Python --> ReaderT
    Python --> Net
    Python --> Conv
    Python --> Train
    Python --> Validate
    Python --> Test

    classDef external fill:#dddddd,stroke:#888888;
    classDef matlab fill:#f2f2f2,stroke:#999999;
    classDef config fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef reader fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef model fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef trainer fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef evaluator fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef datastore fill:#d1c4e9,stroke:#4a148c,color:#4a148c;
```
