# seanzhang99/superhugeaad architecture

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

- Interactive diagram: https://gitdiagram.com/seanzhang99/superhugeaad
- Repository: https://github.com/seanzhang99/superhugeaad

## Overview

SuperHugeAAD is a framework for auditory-attention decoding from preprocessed EEG: it supports envelope reconstruction and spatial-attention classification across multiple datasets. The main workflow configures a task and cross-validation run, selects and splits metadata, loads EEG/audio samples and applies transforms, then trains and evaluates a selected model. The README documents model families, cross-validation options, and MATLAB interoperability; some of those implementation details were not sampled, so their internal connections are not asserted here.

Main entry points: [`superhuge/data/interface/data_interface.py`](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/interface/data_interface.py) (Data module), [`train/main.py`](https://github.com/seanzhang99/superhugeaad/blob/main/train/main.py) (DNN entry point), [`superhuge/model/interface/model_interface.py`](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/model/interface/model_interface.py) (Model interface), [`train/kulavgc.py`](https://github.com/seanzhang99/superhugeaad/blob/main/train/kulavgc.py) (Linear entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Experiment orchestration"]
  node_train_entry["DNN entry point<br/>[main.py]"]
  node_linear_entry["Linear entry point<br/>[kulavgc.py]"]
  node_run_cli["Multi-run CLI<br/>[multi_run_cli.py]"]
  node_task_parser["Task and CV parser"]
end

subgraph group_data["Data pipeline"]
  node_metadata["Trial metadata<br/>[data.py]"]
  node_metadata_filters["Metadata filters<br/>[abc.py]"]
  node_classify_filter["Classification filters<br/>[classify_filter.py]"]
  node_regress_filter["Regression filters<br/>[regress_filter.py]"]
  node_filter_composer["Filter composer<br/>[composer.py]"]
  node_cv_grouping["Cross-validation grouping<br/>[group.py]"]
  node_data_interface["Data module<br/>[data_interface.py]"]
  node_eeg_dataset["EEG sample dataset<br/>[eeg_dataset.py]"]
  node_regression_dataset["Regression dataset"]
  node_classification_dataset["Classification dataset"]
  node_transform_api["Transform API<br/>[abc.py]"]
  node_transform_composer["Transform pipeline<br/>[composer.py]"]
  node_transform_catalog["EEG transforms"]
  node_matlab_interop["MATLAB interoperability<br/>[matlab_utils.py]"]
end

subgraph group_models["AAD models"]
  node_model_interface["Model interface<br/>[model_interface.py]"]
  node_deep_models["Deep architectures"]
  node_linear_models["Linear baselines"]
end

subgraph group_support["Model support"]
  node_losses["Task losses and metrics"]
  node_model_blocks["Neural building blocks"]
  node_channel_mapping["Channel mapping"]
end

node_engineer(("Experiment user"))
node_prepared_data[("Preprocessed EEG data")]

node_engineer -->|"starts DNN run"| node_train_entry
node_engineer -->|"starts linear run"| node_linear_entry
node_train_entry -->|"invokes"| node_run_cli
node_linear_entry -->|"imports"| node_run_cli
node_run_cli -->|"uses task config"| node_task_parser
node_prepared_data -->|"loads preprocessed files"| node_data_interface
node_data_interface -->|"uses metadata"| node_metadata
node_data_interface -->|"configures filters"| node_metadata_filters
node_data_interface -->|"checks filter type"| node_classify_filter
node_data_interface -->|"imports filter"| node_regress_filter
node_data_interface -->|"configures filters"| node_filter_composer
node_data_interface -->|"uses grouping"| node_cv_grouping
node_data_interface -->|"creates datasets"| node_eeg_dataset
node_data_interface -->|"supports dataset class"| node_regression_dataset
node_data_interface -->|"supports dataset class"| node_classification_dataset
node_eeg_dataset -->|"reads metadata"| node_metadata
node_eeg_dataset -->|"applies transforms"| node_transform_composer
node_transform_composer -->|"composes transforms"| node_transform_api
node_transform_composer -.->|"runs transform types"| node_transform_catalog
node_model_interface -->|"uses components"| node_model_blocks
node_train_entry -.->|"trains with data module"| node_data_interface
node_train_entry -.->|"trains model interface"| node_model_interface
node_model_interface -.->|"instantiates selected model"| node_deep_models
node_model_interface -.->|"uses configured loss"| node_losses
node_linear_entry -.->|"runs linear baseline"| node_linear_models
node_data_interface -->|"can be created via MATLAB"| node_matlab_interop

click node_train_entry "https://github.com/seanzhang99/superhugeaad/blob/main/train/main.py"
click node_linear_entry "https://github.com/seanzhang99/superhugeaad/blob/main/train/kulavgc.py"
click node_run_cli "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/utils/multi_run_cli.py"
click node_task_parser "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/utils/task_config_parser.py"
click node_metadata "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_processing/data.py"
click node_metadata_filters "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/abc.py"
click node_classify_filter "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/classify_filter.py"
click node_regress_filter "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/regress_filter.py"
click node_filter_composer "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/composer.py"
click node_cv_grouping "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_processing/group.py"
click node_data_interface "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/interface/data_interface.py"
click node_eeg_dataset "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/datasets/eeg_dataset.py"
click node_regression_dataset "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/datasets/eeg_regression_base_dataset.py"
click node_classification_dataset "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/datasets/eeg_classify_base_dataset.py"
click node_transform_api "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/transforms/abc.py"
click node_transform_composer "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/transforms/composer.py"
click node_transform_catalog "https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/data/transforms"
click node_model_interface "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/model/interface/model_interface.py"
click node_deep_models "https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model"
click node_linear_models "https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model/linear"
click node_losses "https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model/loss"
click node_model_blocks "https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model/module"
click node_channel_mapping "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/model/interface/channel_mapping_interface.py"
click node_matlab_interop "https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/interface/matlab_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_train_entry,node_linear_entry,node_run_cli,node_task_parser,node_engineer toneBlue
class node_metadata,node_metadata_filters,node_classify_filter,node_regress_filter,node_filter_composer,node_cv_grouping,node_data_interface,node_eeg_dataset,node_regression_dataset,node_classification_dataset,node_transform_api,node_transform_composer,node_transform_catalog,node_matlab_interop,node_prepared_data toneAmber
class node_model_interface,node_deep_models,node_linear_models toneMint
class node_losses,node_model_blocks,node_channel_mapping toneRose
```

## Components

### Experiment orchestration

- [DNN entry point](https://github.com/seanzhang99/superhugeaad/blob/main/train/main.py): `train/main.py`
- [Linear entry point](https://github.com/seanzhang99/superhugeaad/blob/main/train/kulavgc.py): `train/kulavgc.py`
- [Multi-run CLI](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/utils/multi_run_cli.py): `superhuge/utils/multi_run_cli.py`
- [Task and CV parser](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/utils/task_config_parser.py): `superhuge/utils/task_config_parser.py`

### Data pipeline

- [Trial metadata](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_processing/data.py): `superhuge/data/metadata_processing/data.py`
- [Metadata filters](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/abc.py): `superhuge/data/metadata_filters/abc.py`
- [Classification filters](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/classify_filter.py): `superhuge/data/metadata_filters/classify_filter.py`
- [Regression filters](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/regress_filter.py): `superhuge/data/metadata_filters/regress_filter.py`
- [Filter composer](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_filters/composer.py): `superhuge/data/metadata_filters/composer.py`
- [Cross-validation grouping](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/metadata_processing/group.py): `superhuge/data/metadata_processing/group.py`
- [Data module](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/interface/data_interface.py): `superhuge/data/interface/data_interface.py`
- [EEG sample dataset](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/datasets/eeg_dataset.py): `superhuge/data/datasets/eeg_dataset.py`
- [Regression dataset](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/datasets/eeg_regression_base_dataset.py): `superhuge/data/datasets/eeg_regression_base_dataset.py`
- [Classification dataset](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/datasets/eeg_classify_base_dataset.py): `superhuge/data/datasets/eeg_classify_base_dataset.py`
- [Transform API](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/transforms/abc.py): `superhuge/data/transforms/abc.py`
- [Transform pipeline](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/transforms/composer.py): `superhuge/data/transforms/composer.py`
- [EEG transforms](https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/data/transforms): `superhuge/data/transforms`
- [MATLAB interoperability](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/data/interface/matlab_utils.py): `superhuge/data/interface/matlab_utils.py`

### AAD models

- [Model interface](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/model/interface/model_interface.py): `superhuge/model/interface/model_interface.py`
- [Deep architectures](https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model): `superhuge/model`
- [Linear baselines](https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model/linear): `superhuge/model/linear`

### Model support

- [Task losses and metrics](https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model/loss): `superhuge/model/loss`
- [Neural building blocks](https://github.com/seanzhang99/superhugeaad/tree/main/superhuge/model/module): `superhuge/model/module`
- [Channel mapping](https://github.com/seanzhang99/superhugeaad/blob/main/superhuge/model/interface/channel_mapping_interface.py): `superhuge/model/interface/channel_mapping_interface.py`

### Other components

- **Experiment user**
- **Preprocessed EEG data**

## Connections

- Experiment user → DNN entry point: starts DNN run (evidence: `README.md`)
- Experiment user → Linear entry point: starts linear run (evidence: `README.md`)
- DNN entry point → Multi-run CLI: invokes (evidence: `train/main.py`)
- Linear entry point → Multi-run CLI: imports (evidence: `train/kulavgc.py`)
- Multi-run CLI → Task and CV parser: uses task config (evidence: `superhuge/utils/multi_run_cli.py`)
- Preprocessed EEG data → Data module: loads preprocessed files (evidence: `README.md`)
- Data module → Trial metadata: uses metadata (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Metadata filters: configures filters (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Classification filters: checks filter type (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Regression filters: imports filter (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Filter composer: configures filters (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Cross-validation grouping: uses grouping (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → EEG sample dataset: creates datasets (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Regression dataset: supports dataset class (evidence: `superhuge/data/interface/data_interface.py`)
- Data module → Classification dataset: supports dataset class (evidence: `superhuge/data/interface/data_interface.py`)
- EEG sample dataset → Trial metadata: reads metadata (evidence: `superhuge/data/datasets/eeg_dataset.py`)
- EEG sample dataset → Transform pipeline: applies transforms (evidence: `superhuge/data/datasets/eeg_dataset.py`)
- Transform pipeline → Transform API: composes transforms (evidence: `superhuge/data/transforms/composer.py`)
- Transform pipeline → EEG transforms: runs transform types (evidence: `superhuge/data/transforms/composer.py`)
- Model interface → Neural building blocks: uses components (evidence: `superhuge/model/interface/model_interface.py`)
- DNN entry point → Data module: trains with data module
- DNN entry point → Model interface: trains model interface
- Model interface → Deep architectures: instantiates selected model (evidence: `superhuge/model/interface/model_interface.py`)
- Model interface → Task losses and metrics: uses configured loss
- Linear entry point → Linear baselines: runs linear baseline
- Data module → MATLAB interoperability: can be created via MATLAB (evidence: `README.md`)
