How ml4sci/neurodyads works
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: run_pipeline.py Pair preprocessing · downsample_and_filter_edf.py 250 Hz processing · batch_stack_edfs_for_cebra.py Dyad input building · analyze_cebra_longitude_latitude.py Embedding geometry
Components 24
EEG preprocessing
- Pair preprocessing
PreprocessingPipeline/run_pipeline.py - Channel renaming
PreprocessingPipeline/preprocessing/rename_channels.py - Mutual alignment
PreprocessingPipeline/preprocessing/mutual_alignment.py - Individual cleaning
PreprocessingPipeline/preprocessing/individual_preprocessing.py - 250 Hz processing
Preprocessing250Hz/downsample_and_filter_edf.py - Filter QC
Preprocessing250Hz/qc_filtered_edfs.py - Aperiodic extraction
Preprocessing250Hz/extract_aperiodic_fooof.py
Input preparation
- Dyad input building
CEBRAInputs/batch_stack_edfs_for_cebra.py - Nonoscillatory inputs
CEBRAInputs/build_nonosc_speakerfirst.py - Stacked EEG arrays
CEBRA training
- Supervised training
train_cebra_cut_supervised.py - Time-only training
train_cebra_cut_unsupervised.py
Decoding and geometry
- AQ difference pipeline
CEBRATraining/run_aq_delta6_pipeline.py - Participant AQ mapping
CEBRATraining/run_individual_aq_role_mapping.py - Permutation controls
PermutationControls/run_dyad_aq_permutation_control.py - Embedding geometry
EmbeddingGeometry/analyze_cebra_longitude_latitude.py - GMM identity analysis
EmbeddingGeometry/analyze_gmm_component_identity.py - Results and figures
Evaluation/build_reports_and_export.py
Analysis extensions
- Band comparison
CEBRATraining/run_band_cebra_analysis.py - Gender and states
GenderStateRuns/run_gender_participant_states.py - Female valence
GenderStateRuns/run_female_valence_cebra.py - State permutation
PermutationControls/run_state_permutation_control.py
Other components
- Researcher
- EEG recordings
Connections 23
- Researcher → Pair preprocessing: runs
PreprocessingPipeline/run_pipeline.py - EEG recordings → Pair preprocessing: provides recordings
PreprocessingPipeline/run_pipeline.py - Pair preprocessing → Channel renaming: renames channels
PreprocessingPipeline/run_pipeline.py - Pair preprocessing → Mutual alignment: aligns recordings
PreprocessingPipeline/run_pipeline.py - Pair preprocessing → Individual cleaning: preprocesses
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