# alegomezri/eeg-tact architecture

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

- Interactive diagram: https://gitdiagram.com/alegomezri/eeg-tact
- Repository: https://github.com/alegomezri/eeg-tact

## Overview

EEG-TACT is a research workflow for classifying children’s resting-state EEG recordings as ADHD or control. The principal path prepares subject recordings into overlapping epochs, evaluates a Keras EEGFormer with subject-grouped folds and per-fold hyperparameter selection, then produces trial/subject predictions and aggregate metrics. The repository also documents baseline comparisons, ablations, multi-seed experiments, and statistical analyses. The README and sampled files support the workflow at a high level; several notebook-driven and Keras data/model internals are not shown, so those links are documented rather than inferred from unsampled code.

Main entry points: [`src/tuning/objective.py`](https://github.com/alegomezri/eeg-tact/blob/main/src/tuning/objective.py) (Hyperparameter tuning), [`scripts/evaluate_eegformer.py`](https://github.com/alegomezri/eeg-tact/blob/main/scripts/evaluate_eegformer.py) (EEGFormer evaluation), [`scripts/rebuild_eegformer_5fold_all_trial_probs.py`](https://github.com/alegomezri/eeg-tact/blob/main/scripts/rebuild_eegformer_5fold_all_trial_probs.py) (Trial probability rebuild), [`experiments`](https://github.com/alegomezri/eeg-tact/tree/main/experiments) (Experiment runs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["EEG preparation"]
  node_preprocess["Signal preprocessing<br/>[preprocessing.py]"]
  node_dataset_build["Dataset builder<br/>[build_dataset.py]"]
  node_dataset["Epoch dataset<br/>[dataset.py]"]
end

subgraph group_models["Models and training"]
  node_eegformer["EEG-TACT model<br/>[eegformer.py]"]
  node_baselines["Baseline models"]
  node_conformer["EEGConformer<br/>[eegconformer.py]"]
  node_trainer["Training and metrics<br/>[trainer.py]"]
  node_seeding["Seed control<br/>[seed.py]"]
end

subgraph group_evaluation["Evaluation workflow"]
  node_tuning["Hyperparameter tuning<br/>[objective.py]"]
  node_evaluate["EEGFormer evaluation"]
  node_rebuild["Trial probability rebuild"]
  node_predictions["Trial predictions"]
  node_results["Evaluation outputs"]
end

subgraph group_analysis["Research analysis"]
  node_experiments["Experiment runs"]
  node_many_seed["Multi-seed results"]
  node_ablation["Ablation results"]
  node_statistics["Statistical tests"]
  node_exploration["Embedding exploration"]
end

node_researcher(("Researcher"))
node_recordings[("EEG recordings")]

node_researcher -->|"prepares data"| node_dataset_build
node_recordings -->|"loads recordings"| node_dataset_build
node_dataset_build -->|"filters and epochs"| node_preprocess
node_dataset_build -.->|"builds samples"| node_dataset
node_researcher -->|"runs evaluation"| node_evaluate
node_evaluate -.->|"loads epochs"| node_dataset
node_evaluate -->|"evaluates folds"| node_eegformer
node_evaluate -->|"reads split data"| node_predictions
node_evaluate -->|"writes metrics"| node_results
node_researcher -->|"selects parameters"| node_tuning
node_tuning -->|"creates fold datasets"| node_dataset
node_tuning -->|"constructs model"| node_conformer
node_tuning -->|"trains and evaluates"| node_trainer
node_tuning -->|"sets seed"| node_seeding
node_researcher -->|"rebuilds probabilities"| node_rebuild
node_rebuild -->|"builds fold model"| node_eegformer
node_rebuild -->|"reads fold assignments"| node_predictions
node_rebuild -->|"writes probabilities"| node_results
node_researcher -->|"runs comparisons"| node_experiments
node_experiments -.->|"compares models"| node_baselines
node_experiments -->|"tests components"| node_ablation
node_experiments -->|"records seed runs"| node_many_seed
node_researcher -->|"analyzes results"| node_statistics
node_statistics -.->|"tests model differences"| node_many_seed
node_researcher -->|"explores embeddings"| node_exploration
node_exploration -.->|"uses saved embeddings"| node_results

click node_preprocess "https://github.com/alegomezri/eeg-tact/blob/main/src/data/preprocessing.py"
click node_dataset_build "https://github.com/alegomezri/eeg-tact/blob/main/src/data/build_dataset.py"
click node_dataset "https://github.com/alegomezri/eeg-tact/blob/main/src/data/dataset.py"
click node_eegformer "https://github.com/alegomezri/eeg-tact/blob/main/src/models/keras/eegformer.py"
click node_baselines "https://github.com/alegomezri/eeg-tact/tree/main/src/models/keras"
click node_conformer "https://github.com/alegomezri/eeg-tact/blob/main/src/models/torch/eegconformer.py"
click node_trainer "https://github.com/alegomezri/eeg-tact/blob/main/src/training/trainer.py"
click node_seeding "https://github.com/alegomezri/eeg-tact/blob/main/src/utils/seed.py"
click node_tuning "https://github.com/alegomezri/eeg-tact/blob/main/src/tuning/objective.py"
click node_evaluate "https://github.com/alegomezri/eeg-tact/blob/main/scripts/evaluate_eegformer.py"
click node_rebuild "https://github.com/alegomezri/eeg-tact/blob/main/scripts/rebuild_eegformer_5fold_all_trial_probs.py"
click node_predictions "https://github.com/alegomezri/eeg-tact/blob/main/results/eegformer_5fold_run/trial_predictions_5fold.csv"
click node_results "https://github.com/alegomezri/eeg-tact/tree/main/results/evaluation"
click node_experiments "https://github.com/alegomezri/eeg-tact/tree/main/experiments"
click node_many_seed "https://github.com/alegomezri/eeg-tact/tree/main/results/many_seed_experiments"
click node_ablation "https://github.com/alegomezri/eeg-tact/tree/main/results/ablation"
click node_statistics "https://github.com/alegomezri/eeg-tact/blob/main/statistical_tests/proportion_tests.py"
click node_exploration "https://github.com/alegomezri/eeg-tact/blob/main/notebooks/tsne_projection.ipynb"

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_preprocess,node_dataset_build,node_dataset toneBlue
class node_eegformer,node_baselines,node_conformer,node_trainer,node_seeding,node_recordings toneAmber
class node_tuning,node_evaluate,node_rebuild,node_predictions,node_results toneMint
class node_experiments,node_many_seed,node_ablation,node_statistics,node_exploration toneRose
class node_researcher toneIndigo
```

## Components

### EEG preparation

- [Signal preprocessing](https://github.com/alegomezri/eeg-tact/blob/main/src/data/preprocessing.py): `src/data/preprocessing.py`
- [Dataset builder](https://github.com/alegomezri/eeg-tact/blob/main/src/data/build_dataset.py): `src/data/build_dataset.py`
- [Epoch dataset](https://github.com/alegomezri/eeg-tact/blob/main/src/data/dataset.py): `src/data/dataset.py`

### Models and training

- [EEG-TACT model](https://github.com/alegomezri/eeg-tact/blob/main/src/models/keras/eegformer.py): `src/models/keras/eegformer.py`
- [Baseline models](https://github.com/alegomezri/eeg-tact/tree/main/src/models/keras): `src/models/keras`
- [EEGConformer](https://github.com/alegomezri/eeg-tact/blob/main/src/models/torch/eegconformer.py): `src/models/torch/eegconformer.py`
- [Training and metrics](https://github.com/alegomezri/eeg-tact/blob/main/src/training/trainer.py): `src/training/trainer.py`
- [Seed control](https://github.com/alegomezri/eeg-tact/blob/main/src/utils/seed.py): `src/utils/seed.py`

### Evaluation workflow

- [Hyperparameter tuning](https://github.com/alegomezri/eeg-tact/blob/main/src/tuning/objective.py): `src/tuning/objective.py`
- [EEGFormer evaluation](https://github.com/alegomezri/eeg-tact/blob/main/scripts/evaluate_eegformer.py): `scripts/evaluate_eegformer.py`
- [Trial probability rebuild](https://github.com/alegomezri/eeg-tact/blob/main/scripts/rebuild_eegformer_5fold_all_trial_probs.py): `scripts/rebuild_eegformer_5fold_all_trial_probs.py`
- [Trial predictions](https://github.com/alegomezri/eeg-tact/blob/main/results/eegformer_5fold_run/trial_predictions_5fold.csv): `results/eegformer_5fold_run/trial_predictions_5fold.csv`
- [Evaluation outputs](https://github.com/alegomezri/eeg-tact/tree/main/results/evaluation): `results/evaluation`

### Research analysis

- [Experiment runs](https://github.com/alegomezri/eeg-tact/tree/main/experiments): `experiments`
- [Multi-seed results](https://github.com/alegomezri/eeg-tact/tree/main/results/many_seed_experiments): `results/many_seed_experiments`
- [Ablation results](https://github.com/alegomezri/eeg-tact/tree/main/results/ablation): `results/ablation`
- [Statistical tests](https://github.com/alegomezri/eeg-tact/blob/main/statistical_tests/proportion_tests.py): `statistical_tests/proportion_tests.py`
- [Embedding exploration](https://github.com/alegomezri/eeg-tact/blob/main/notebooks/tsne_projection.ipynb): `notebooks/tsne_projection.ipynb`

### Other components

- **Researcher**
- **EEG recordings**

## Connections

- Researcher → Dataset builder: prepares data (evidence: `README.md`)
- EEG recordings → Dataset builder: loads recordings (evidence: `src/data/build_dataset.py`)
- Dataset builder → Signal preprocessing: filters and epochs (evidence: `src/data/build_dataset.py`)
- Dataset builder → Epoch dataset: builds samples
- Researcher → EEGFormer evaluation: runs evaluation (evidence: `README.md`)
- EEGFormer evaluation → Epoch dataset: loads epochs
- EEGFormer evaluation → EEG-TACT model: evaluates folds (evidence: `scripts/evaluate_eegformer.py`)
- EEGFormer evaluation → Trial predictions: reads split data (evidence: `scripts/evaluate_eegformer.py`)
- EEGFormer evaluation → Evaluation outputs: writes metrics (evidence: `scripts/evaluate_eegformer.py`)
- Researcher → Hyperparameter tuning: selects parameters (evidence: `README.md`)
- Hyperparameter tuning → Epoch dataset: creates fold datasets (evidence: `src/tuning/objective.py`)
- Hyperparameter tuning → EEGConformer: constructs model (evidence: `src/tuning/objective.py`)
- Hyperparameter tuning → Training and metrics: trains and evaluates (evidence: `src/tuning/objective.py`)
- Hyperparameter tuning → Seed control: sets seed (evidence: `src/tuning/objective.py`)
- Researcher → Trial probability rebuild: rebuilds probabilities (evidence: `README.md`)
- Trial probability rebuild → EEG-TACT model: builds fold model (evidence: `scripts/rebuild_eegformer_5fold_all_trial_probs.py`)
- Trial probability rebuild → Trial predictions: reads fold assignments (evidence: `scripts/rebuild_eegformer_5fold_all_trial_probs.py`)
- Trial probability rebuild → Evaluation outputs: writes probabilities (evidence: `scripts/rebuild_eegformer_5fold_all_trial_probs.py`)
- Researcher → Experiment runs: runs comparisons (evidence: `README.md`)
- Experiment runs → Baseline models: compares models
- Experiment runs → Ablation results: tests components (evidence: `README.md`)
- Experiment runs → Multi-seed results: records seed runs (evidence: `README.md`)
- Researcher → Statistical tests: analyzes results (evidence: `README.md`)
- Statistical tests → Multi-seed results: tests model differences
- Researcher → Embedding exploration: explores embeddings (evidence: `README.md`)
- Embedding exploration → Evaluation outputs: uses saved embeddings
