# ml4sci/neurodyads architecture

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

- Interactive diagram: https://gitdiagram.com/ml4sci/neurodyads
- Repository: https://github.com/ml4sci/neurodyads

## Overview

NeuroDyads is a research toolkit for analyzing paired EEG hyperscanning data with CEBRA. Its documented core workflow prepares dyad inputs, trains supervised or time-only embeddings, then evaluates decoding and embedding quality. The repository also contains a 250 Hz analysis suite covering preprocessing, AQ decoding and permutation controls, embedding geometry, frequency-band and aperiodic analyses, and gender/state extensions. The older preprocessing pipeline’s calls are visible in source; many newer scripts are represented by their documented capabilities and paths, but their internal wiring was not sampled.

Main entry points: [`PreprocessingPipeline/run_pipeline.py`](https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/run_pipeline.py) (Pair preprocessing), [`Preprocessing250Hz/downsample_and_filter_edf.py`](https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/downsample_and_filter_edf.py) (250 Hz processing), [`CEBRAInputs/batch_stack_edfs_for_cebra.py`](https://github.com/ml4sci/neurodyads/blob/main/CEBRAInputs/batch_stack_edfs_for_cebra.py) (Dyad input building), [`EmbeddingGeometry/analyze_cebra_longitude_latitude.py`](https://github.com/ml4sci/neurodyads/blob/main/EmbeddingGeometry/analyze_cebra_longitude_latitude.py) (Embedding geometry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preprocessing["EEG preprocessing"]
  node_legacy_runner["Pair preprocessing<br/>[run_pipeline.py]"]
  node_rename["Channel renaming<br/>[rename_channels.py]"]
  node_align["Mutual alignment"]
  node_individual["Individual cleaning"]
  node_uniform250["250 Hz processing"]
  node_filterqc["Filter QC"]
  node_aperiodic["Aperiodic extraction"]
end

subgraph group_inputs["Input preparation"]
  node_inputprep["Dyad input building"]
  node_nonoscinput["Nonoscillatory inputs"]
  node_npy["Stacked EEG arrays"]
end

subgraph group_training["CEBRA training"]
  node_supervised["Supervised training"]
  node_unsupervised["Time-only training"]
end

subgraph group_analysis["Decoding and geometry"]
  node_aqdelta["AQ difference pipeline"]
  node_individualaq["Participant AQ mapping"]
  node_permutations["Permutation controls"]
  node_geometry["Embedding geometry"]
  node_gmm["GMM identity analysis"]
  node_evaluation["Results and figures"]
end

subgraph group_extensions["Analysis extensions"]
  node_bands["Band comparison"]
  node_gender["Gender and states"]
  node_valence["Female valence"]
  node_stateperm["State permutation"]
end

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

node_researcher -->|"runs"| node_legacy_runner
node_eeg -->|"provides recordings"| node_legacy_runner
node_legacy_runner -->|"renames channels"| node_rename
node_legacy_runner -->|"aligns recordings"| node_align
node_legacy_runner -->|"preprocesses"| node_individual
node_researcher -.->|"runs"| node_inputprep
node_eeg -->|"provides EDFs"| node_inputprep
node_inputprep -->|"stacks channels"| node_npy
node_npy -->|"trains on"| node_supervised
node_npy -->|"trains on"| node_unsupervised
node_researcher -.->|"runs"| node_uniform250
node_uniform250 -.->|"checks filtering"| node_filterqc
node_uniform250 -.->|"supports extraction"| node_aperiodic
node_researcher -.->|"runs"| node_aqdelta
node_researcher -.->|"runs"| node_individualaq
node_researcher -.->|"runs"| node_permutations
node_researcher -.->|"runs"| node_geometry
node_geometry -.->|"interprets clusters"| node_gmm
node_researcher -.->|"builds reports"| node_evaluation
node_researcher -.->|"runs"| node_bands
node_researcher -.->|"runs"| node_gender
node_researcher -.->|"runs"| node_valence
node_researcher -.->|"runs"| node_stateperm

click node_legacy_runner "https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/run_pipeline.py"
click node_rename "https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/preprocessing/rename_channels.py"
click node_align "https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/preprocessing/mutual_alignment.py"
click node_individual "https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/preprocessing/individual_preprocessing.py"
click node_uniform250 "https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/downsample_and_filter_edf.py"
click node_filterqc "https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/qc_filtered_edfs.py"
click node_aperiodic "https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/extract_aperiodic_fooof.py"
click node_inputprep "https://github.com/ml4sci/neurodyads/blob/main/CEBRAInputs/batch_stack_edfs_for_cebra.py"
click node_nonoscinput "https://github.com/ml4sci/neurodyads/blob/main/CEBRAInputs/build_nonosc_speakerfirst.py"
click node_supervised "https://github.com/ml4sci/neurodyads/blob/main/train_cebra_cut_supervised.py"
click node_unsupervised "https://github.com/ml4sci/neurodyads/blob/main/train_cebra_cut_unsupervised.py"
click node_aqdelta "https://github.com/ml4sci/neurodyads/blob/main/CEBRATraining/run_aq_delta6_pipeline.py"
click node_individualaq "https://github.com/ml4sci/neurodyads/blob/main/CEBRATraining/run_individual_aq_role_mapping.py"
click node_permutations "https://github.com/ml4sci/neurodyads/blob/main/PermutationControls/run_dyad_aq_permutation_control.py"
click node_geometry "https://github.com/ml4sci/neurodyads/blob/main/EmbeddingGeometry/analyze_cebra_longitude_latitude.py"
click node_gmm "https://github.com/ml4sci/neurodyads/blob/main/EmbeddingGeometry/analyze_gmm_component_identity.py"
click node_evaluation "https://github.com/ml4sci/neurodyads/blob/main/Evaluation/build_reports_and_export.py"
click node_bands "https://github.com/ml4sci/neurodyads/blob/main/CEBRATraining/run_band_cebra_analysis.py"
click node_gender "https://github.com/ml4sci/neurodyads/blob/main/GenderStateRuns/run_gender_participant_states.py"
click node_valence "https://github.com/ml4sci/neurodyads/blob/main/GenderStateRuns/run_female_valence_cebra.py"
click node_stateperm "https://github.com/ml4sci/neurodyads/blob/main/PermutationControls/run_state_permutation_control.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_legacy_runner,node_rename,node_align,node_individual,node_uniform250,node_filterqc,node_aperiodic toneBlue
class node_inputprep,node_nonoscinput,node_npy toneAmber
class node_supervised,node_unsupervised toneMint
class node_aqdelta,node_individualaq,node_permutations,node_geometry,node_gmm,node_evaluation toneRose
class node_bands,node_gender,node_valence,node_stateperm,node_researcher,node_eeg toneIndigo
```

## Components

### EEG preprocessing

- [Pair preprocessing](https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/run_pipeline.py): `PreprocessingPipeline/run_pipeline.py`
- [Channel renaming](https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/preprocessing/rename_channels.py): `PreprocessingPipeline/preprocessing/rename_channels.py`
- [Mutual alignment](https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/preprocessing/mutual_alignment.py): `PreprocessingPipeline/preprocessing/mutual_alignment.py`
- [Individual cleaning](https://github.com/ml4sci/neurodyads/blob/main/PreprocessingPipeline/preprocessing/individual_preprocessing.py): `PreprocessingPipeline/preprocessing/individual_preprocessing.py`
- [250 Hz processing](https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/downsample_and_filter_edf.py): `Preprocessing250Hz/downsample_and_filter_edf.py`
- [Filter QC](https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/qc_filtered_edfs.py): `Preprocessing250Hz/qc_filtered_edfs.py`
- [Aperiodic extraction](https://github.com/ml4sci/neurodyads/blob/main/Preprocessing250Hz/extract_aperiodic_fooof.py): `Preprocessing250Hz/extract_aperiodic_fooof.py`

### Input preparation

- [Dyad input building](https://github.com/ml4sci/neurodyads/blob/main/CEBRAInputs/batch_stack_edfs_for_cebra.py): `CEBRAInputs/batch_stack_edfs_for_cebra.py`
- [Nonoscillatory inputs](https://github.com/ml4sci/neurodyads/blob/main/CEBRAInputs/build_nonosc_speakerfirst.py): `CEBRAInputs/build_nonosc_speakerfirst.py`
- **Stacked EEG arrays**

### CEBRA training

- [Supervised training](https://github.com/ml4sci/neurodyads/blob/main/train_cebra_cut_supervised.py): `train_cebra_cut_supervised.py`
- [Time-only training](https://github.com/ml4sci/neurodyads/blob/main/train_cebra_cut_unsupervised.py): `train_cebra_cut_unsupervised.py`

### Decoding and geometry

- [AQ difference pipeline](https://github.com/ml4sci/neurodyads/blob/main/CEBRATraining/run_aq_delta6_pipeline.py): `CEBRATraining/run_aq_delta6_pipeline.py`
- [Participant AQ mapping](https://github.com/ml4sci/neurodyads/blob/main/CEBRATraining/run_individual_aq_role_mapping.py): `CEBRATraining/run_individual_aq_role_mapping.py`
- [Permutation controls](https://github.com/ml4sci/neurodyads/blob/main/PermutationControls/run_dyad_aq_permutation_control.py): `PermutationControls/run_dyad_aq_permutation_control.py`
- [Embedding geometry](https://github.com/ml4sci/neurodyads/blob/main/EmbeddingGeometry/analyze_cebra_longitude_latitude.py): `EmbeddingGeometry/analyze_cebra_longitude_latitude.py`
- [GMM identity analysis](https://github.com/ml4sci/neurodyads/blob/main/EmbeddingGeometry/analyze_gmm_component_identity.py): `EmbeddingGeometry/analyze_gmm_component_identity.py`
- [Results and figures](https://github.com/ml4sci/neurodyads/blob/main/Evaluation/build_reports_and_export.py): `Evaluation/build_reports_and_export.py`

### Analysis extensions

- [Band comparison](https://github.com/ml4sci/neurodyads/blob/main/CEBRATraining/run_band_cebra_analysis.py): `CEBRATraining/run_band_cebra_analysis.py`
- [Gender and states](https://github.com/ml4sci/neurodyads/blob/main/GenderStateRuns/run_gender_participant_states.py): `GenderStateRuns/run_gender_participant_states.py`
- [Female valence](https://github.com/ml4sci/neurodyads/blob/main/GenderStateRuns/run_female_valence_cebra.py): `GenderStateRuns/run_female_valence_cebra.py`
- [State permutation](https://github.com/ml4sci/neurodyads/blob/main/PermutationControls/run_state_permutation_control.py): `PermutationControls/run_state_permutation_control.py`

### Other components

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

## Connections

- Researcher → Pair preprocessing: runs (evidence: `PreprocessingPipeline/run_pipeline.py`)
- EEG recordings → Pair preprocessing: provides recordings (evidence: `PreprocessingPipeline/run_pipeline.py`)
- Pair preprocessing → Channel renaming: renames channels (evidence: `PreprocessingPipeline/run_pipeline.py`)
- Pair preprocessing → Mutual alignment: aligns recordings (evidence: `PreprocessingPipeline/run_pipeline.py`)
- Pair preprocessing → Individual cleaning: preprocesses (evidence: `PreprocessingPipeline/run_pipeline.py`)
- Researcher → Dyad input building: runs
- EEG recordings → Dyad input building: provides EDFs
- Dyad input building → Stacked EEG arrays: stacks channels
- Stacked EEG arrays → Supervised training: trains on
- Stacked EEG arrays → Time-only training: trains on
- Researcher → 250 Hz processing: runs
- 250 Hz processing → Filter QC: checks filtering
- 250 Hz processing → Aperiodic extraction: supports extraction
- Researcher → AQ difference pipeline: runs
- Researcher → Participant AQ mapping: runs
- Researcher → Permutation controls: runs
- Researcher → Embedding geometry: runs
- Embedding geometry → GMM identity analysis: interprets clusters
- Researcher → Results and figures: builds reports
- Researcher → Band comparison: runs
- Researcher → Gender and states: runs
- Researcher → Female valence: runs
- Researcher → State permutation: runs