# ispamm/mhyeeg architecture

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

- Interactive diagram: https://gitdiagram.com/ispamm/mhyeeg
- Repository: https://github.com/ispamm/mhyeeg

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    RawData[(Raw Data)]:::data
    Preprocessing[/"Data Preprocessing"/]:::compute
    DatasetBuilder[/"Dataset Builder"/]:::compute
    DataLoader["DataLoader"]:::compute
    subgraph "Model Library"
        H2["h2.py"]:::compute
        HF["hyperfusenet.py"]:::compute
        HFv2["hyperfusenetv2.py"]:::compute
        HN["hypernet.py"]:::compute
        BL["baselines.py"]:::compute
        HCL["hypercomplex_layers.py"]:::compute
        HCO["hypercomplex_ops.py"]:::compute
    end
    TrainingEngine["Training Engine"]:::compute
    EarlyStop["EarlyStopping & Checkpointing"]:::compute
    SweepEngine{"Hyperparameter Sweep"}:::config
    ConfigManager["Config Manager"]:::config
    CLI["CLI Entrypoint (main.py)"]:::config
    WandB[(Weights & Biases)]:::external

    RawData -->|raw files| Preprocessing
    Preprocessing -->|.csv/.npy| DatasetBuilder
    DatasetBuilder -->|.pt files| DataLoader
    DataLoader -->|batches| TrainingEngine
    H2 -->|model instance| TrainingEngine
    HF -->|model instance| TrainingEngine
    HFv2 -->|model instance| TrainingEngine
    HN -->|model instance| TrainingEngine
    BL -->|model instance| TrainingEngine
    HCL -->|model instance| TrainingEngine
    HCO -->|model instance| TrainingEngine
    TrainingEngine -->|callbacks| EarlyStop
    TrainingEngine -->|metrics| WandB
    SweepEngine -->|"invokes CLI"| CLI
    CLI -->|runs| TrainingEngine
    SweepEngine -->|logs| WandB

    ConfigManager -.->|configs| Preprocessing
    ConfigManager -.->|configs| DatasetBuilder
    ConfigManager -.->|configs| DataLoader
    ConfigManager -.->|configs| H2
    ConfigManager -.->|configs| HF
    ConfigManager -.->|configs| HFv2
    ConfigManager -.->|configs| HN
    ConfigManager -.->|configs| BL
    ConfigManager -.->|configs| HCL
    ConfigManager -.->|configs| HCO
    ConfigManager -.->|configs| TrainingEngine
    ConfigManager -.->|configs| SweepEngine

    click Preprocessing "https://github.com/ispamm/mhyeeg/blob/main/data/preprocessing.py"
    click DatasetBuilder "https://github.com/ispamm/mhyeeg/blob/main/data/create_dataset.py"
    click DataLoader "https://github.com/ispamm/mhyeeg/blob/main/data/dataloader.py"
    click ConfigManager "https://github.com/ispamm/mhyeeg/tree/main/configs/"
    click H2 "https://github.com/ispamm/mhyeeg/blob/main/models/h2.py"
    click HF "https://github.com/ispamm/mhyeeg/blob/main/models/hyperfusenet.py"
    click HFv2 "https://github.com/ispamm/mhyeeg/blob/main/models/hyperfusenetv2.py"
    click HN "https://github.com/ispamm/mhyeeg/blob/main/models/hypernet.py"
    click BL "https://github.com/ispamm/mhyeeg/blob/main/models/baselines.py"
    click HCL "https://github.com/ispamm/mhyeeg/blob/main/models/hypercomplex_layers.py"
    click HCO "https://github.com/ispamm/mhyeeg/blob/main/models/hypercomplex_ops.py"
    click TrainingEngine "https://github.com/ispamm/mhyeeg/blob/main/training.py"
    click EarlyStop "https://github.com/ispamm/mhyeeg/blob/main/earlystopping.py"
    click SweepEngine "https://github.com/ispamm/mhyeeg/blob/main/sweep.py"
    click CLI "https://github.com/ispamm/mhyeeg/blob/main/main.py"
    click RawData "https://github.com/ispamm/mhyeeg/blob/main/requirements.txt"
    click WandB "https://github.com/ispamm/mhyeeg/blob/main/README.md"

    classDef data fill:#bfd4f2,stroke:#333,stroke-width:1px
    classDef compute fill:#f2c38f,stroke:#333,stroke-width:1px
    classDef config fill:#c2f2b3,stroke:#333,stroke-width:1px
    classDef external fill:#d9b3ff,stroke:#333,stroke-width:1px
```
