# emadeldeen24/eval_ssl_ssc architecture

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

- Interactive diagram: https://gitdiagram.com/emadeldeen24/eval_ssl_ssc
- Repository: https://github.com/emadeldeen24/eval_ssl_ssc

## Overview

##### Project type & purpose
- This is a research-oriented machine-learning pipeline for EEG‐based sleep-stage classification, leveraging self-supervised learning (SSL) and few-label fine-tuning.
- It orchestrates data splitting, pre-processing, augmentation, SSL pretraining, supervised/fine-tuning, evaluation, and results storage.

##### File structure
Top‐level directories & scripts:
- configs/            – data_configs.py, hparams.py (hyperparameters & dataset specs)
- data/               – raw/processed datasets, README.md
- dataloader/         – dataloader.py, ts_augmentations.py
- models/             – TC.py, attention.py, helpers.py, loss.py, models.py
- main.py             – entry point coordinating training/evaluation
- trainer.py          – training loops & evaluation logic
- algorithms.py       – implementations of SSL algorithms (SimCLR, CPC, TS-TCC, etc.)
- split_k-fold_and_few_labels.py – creates k-fold splits and few-label subsets
- single_run.sh, multiple_runs.sh – shell scripts to kick off experiments
- utils.py            – helper functions
- multiple_runs.sh    – batch orchestration

##### Extract architecture insights from README
- Three SSC models (DeepSleepNet, AttnSleep, 1D-CNN) implemented in models/models.py as “feature_extractor” + “temporal_encoder” + shared classifier.
- Four SSL algorithms coded in algorithms.py.
- Data splitting utility for k-fold + few-labels.
- Training modes: supervised, SSL pretraining, fine-tuning.

##### Main components & interactions
A. Config Manager
- Reads data_configs.py & hparams.py → supplies dataset paths, augmentation params, model/SSL hyperparameters.
B. Data Layer
- Raw Data (data/) → split script → k-fold/few-label splits.
- Dataloader (dataloader/dataloader.py) + augmentations (ts_augmentations.py) → batched time-series windows.
C. SSL Algorithms Module (algorithms.py)
- Receives batches → applies two augmentations → computes contrastive/predictive loss.
D. SSC Model Module (models/)
- Implements feature extractors + temporal encoders + classifier → defines forward pass & loss (models/loss.py).
E. Trainer & Orchestrator (trainer.py + main.py)
- Selects mode (supervised, ssl, ft) → initializes config, data loader, models, SSL algorithms.
- Drives training loop: feed batches → forward → loss → backward → metrics.
- Handles k-fold loop, logging, saving checkpoints, final evaluation.
F. Experiment Scripts
- single_run.sh / multiple_runs.sh invoke main.py with appropriate arguments for folds, models, modes.
G. Results Storage
- Outputs per-run folders with metrics, logs, checkpoints.

##### Architectural patterns & design principles
- Modular separation by concern: config, data ingestion, augmentation, algorithm, model, training.
- Strategy pattern for SSL algorithms & SSC models: easily extendable via algorithms.py and models/models.py.
- Script-based orchestration wraps the Python modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Config
    CM["Config Manager<br/>(data_configs.py, hparams.py)"]:::config

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        Raw["Raw Data<br/>(data/)"]:::data
        Split["Split Script<br/>(split_k-fold_and_few_labels.py)"]:::data
        DLoader["Dataloader<br/>(dataloader.py)"]:::data
        Aug["Augmentations<br/>(ts_augmentations.py)"]:::data
    end

    %% SSL Algorithms
    SSL["SSL Algorithms Module<br/>(algorithms.py)"]:::algo

    %% SSC Model Module
    subgraph "SSC Model Module" 
        direction TB
        FE["Feature Extractors<br/>(models.py, TC.py, attention.py)"]:::model
        Helper["Helpers<br/>(helpers.py)"]:::model
        Loss["Loss<br/>(loss.py)"]:::model
    end

    %% Training Orchestration
    subgraph "Training Orchestration" 
        direction TB
        Main["main.py"]:::train
        Trainer["trainer.py<br/>(for each fold)"]:::train
    end

    %% Scripts
    subgraph "Experiment Scripts" 
        direction TB
        SR["single_run.sh"]:::script
        MR["multiple_runs.sh"]:::script
    end

    %% Utils and Results
    Utils["Utilities<br/>(utils.py)"]:::util
    Results["Results Storage"]:::data

    %% Connections
    CM -->|"config"| Raw
    CM -->|"config"| Split
    CM -->|"config"| DLoader
    CM -->|"config"| Aug
    CM -->|"config"| SSL
    CM -->|"config"| FE
    CM -->|"config"| Loss
    CM -->|"config"| Main
    CM -->|"config"| Trainer

    Raw -->|"raw data"| Split
    Split -->|"split data"| DLoader
    DLoader -->|"batch"| Aug
    Aug -->|"augmented batch"| SSL
    SSL -->|"pretrained features"| FE
    FE -->|"features"| Loss
    SSL -->|"ssl loss"| Trainer
    DLoader -->|"batch"| FE
    FE -->|"features"| Loss
    Loss -->|"supervised loss"| Trainer

    Main -->|"start"| Trainer
    Trainer -->|"checkpoint & metrics"| Results

    SR -->|"invoke"| Main
    MR -->|"invoke"| Main

    Utils -->|"helpers"| Trainer
    Utils -->|"helpers"| DLoader

    %% Click Events
    click CM "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/configs/data_configs.py"
    click CM "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/configs/hparams.py"
    click Raw "https://github.com/emadeldeen24/eval_ssl_ssc/tree/main/data/"
    click Split "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/split_k-fold_and_few_labels.py"
    click DLoader "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/dataloader/dataloader.py"
    click Aug "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/dataloader/ts_augmentations.py"
    click SSL "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/algorithms.py"
    click FE "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/models/models.py"
    click FE "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/models/TC.py"
    click FE "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/models/attention.py"
    click Helper "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/models/helpers.py"
    click Loss "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/models/loss.py"
    click Main "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/main.py"
    click Trainer "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/trainer.py"
    click SR "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/single_run.sh"
    click MR "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/multiple_runs.sh"
    click Utils "https://github.com/emadeldeen24/eval_ssl_ssc/blob/main/utils.py"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef algo fill:#DFFFD0,stroke:#7CB342,color:#000
    classDef model fill:#E8D0FF,stroke:#8E24AA,color:#000
    classDef train fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef config fill:#ECECEC,stroke:#9E9E9E,color:#000
    classDef script fill:#F5E0D0,stroke:#A1887F,color:#000
    classDef util fill:#F0F0F0,stroke:#616161,color:#000
```
