How emadeldeen24/eval_ssl_ssc works
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.