How ispamm/mhyeeg works
Project type and purpose
• This is a research‐oriented machine‐learning codebase (full pipeline) for multimodal emotion recognition from EEG and peripheral physiological signals.
• Core functionality:
• Data preprocessing & augmentation
• Dataset creation
• Config‐driven model training (multiple hypercomplex architectures)
• Hyperparameter sweeps
• Experiment tracking (Weights & Biases)
File structure
• Top‐level scripts:
• main.py: entry point for training/evaluation
• training.py: core training loop, loss, optimizer, checkpointing, early stopping
• earlystopping.py: callback logic
• sweep.py: orchestrates hyperparameter sweeps
• Directories:
• data/: preprocessing (preprocessing.py), dataset creation (create_dataset.py), loader (dataloader.py)
• models/: implementations of architectures (h2.py, hyperfusenet.py/v2.py, phemonet.py, plus supporting hypercomplex layers & ops)
• configs/: YAML files specifying model‐ and task‐specific hyperparameters
• Other:
• requirements.txt for dependencies
• README.md for usage & paper references
Extract architectural insights from the README
• Configuration‐first design: models, data paths, logging, training hyperparameters all driven by YAML
• Sequential pipeline: raw data → preprocessing → torch datasets → training → evaluation → logging
• Multiple model variants share common training/inference routines
Main components & interactions
a. Components:
1) Raw Data Storage (CSV, EDF files)
2) Data Preprocessing Module (data/preprocessing.py)
3) Dataset Builder & Augmentation (data/create_dataset.py)
4) Torch DataLoader (data/dataloader.py)
5) Configuration Manager (YAML under configs/)
6) Model Library (models/)
7) Training Engine (training.py)
8) Early Stopping & Checkpointing (earlystopping.py)
9) Sweep Engine (sweep.py)
10) Experiment Tracker (Weights & Biases API)
11) CLI Entrypoint (main.py)
b. Relationships & Data Flow:
• Preprocessed data → Dataset Builder → .pt dataset files
• .pt files + Config → DataLoader + Model instantiation
• DataLoader + Model → Training Engine → Loss/Metric computations
• Training Engine uses Early Stopping & Checkpoint callbacks
• Training Engine & Sweep Engine push logs/metrics to W&B
• Sweep Engine re‐invokes CLI with varying configs
c. Architectural patterns & principles:
• Modular separation: data, models, training logic, configs
• Config‐driven behavior: no hard‐coding of hyperparams or paths
• Callback pattern: early stopping, checkpointing
• Sweep orchestration: automated hyperparameter exploration
• Reusable model components: hypercomplex layers shared across multiple model definitions
d. Key technologies & frameworks:
• Python & PyTorch (deep learning)
• YAML (Hydra‐like config files)
• Weights & Biases (experiment logging)
• Standard Python scripts as pipeline steps