# ihgumilar/hyperscanning2-redesign architecture

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

- Interactive diagram: https://gitdiagram.com/ihgumilar/hyperscanning2-redesign
- Repository: https://github.com/ihgumilar/hyperscanning2-redesign

## Overview

- EEG data pre-processing and analysis
- Eye Tracker data pre-processing (with ongoing analysis development)
- Questionnaire data processing and subsequent statistical analysis (such as ANCOVA)

##### Main components
- Data Sources & Ingestion:
– Raw EEG data for both baseline and experimental sessions (coming in separate folders).
– Raw Eye Tracker files (to be processed to separate baseline and experimental data).
– Questionnaire responses.
- Pre-processing Modules:
– For EEG:
- Module to separate baseline/experimental data.
- Module to combine pre and post data for each eye condition.
- Cleaning module with functions for epoching and removing artifacts.
– For Eye Tracker:
- Extraction, combining, and cleaning modules (note: one extraction script is deprecated).
– For Questionnaire:
- Data parsing and score calculation for SPGQ, Co-Presence, and other sub-scales.
- Analysis & Statistical Processing:
– EEG: Analysis modules that identify significant connections, apply permutation statistical tests, and calculate average scores.
– Eye Tracker: (Still under construction, but would eventually include analysis modules).
– Questionnaire: ANCOVA tests on questionnaire scores.
- Data Storage & HPC Integration:
– Specific folders leading to HPC storage paths for raw, pre-processed, and analyzed data.
- (Additional) VR/Unity Component:
– Mentioned in the README for questionnaire integration which represents further input integration via improvement in UNITY.

##### Relationships and data flow
- Raw data (from EEG, Eye Tracker, Questionnaire) flows into individual pre-processing modules.
- Pre-processed data then feeds into analysis modules where, for example, EEG data is partitioned in baseline versus experimental conditions, and subsequently processed for statistical significance.
- The outputs from these analysis pipelines then lead to further computations (e.g., ANCOVA) or final aggregated results.
- Notice that within EEG there are separate branches for each eye condition (averted, direct, natural) and for different phases (pre and post). These should be depicted as sub-components or branches within the EEG module.

##### Architectural patterns and design principles
- Modular Design: Each experimental dataset (EEG, Eye Tracker, Questionnaire) is handled by its own set of processing modules.
- Pipeline/Workflow Structure: The sequence of pre-processing steps and analyses is clearly defined (data separation, combination, cleaning, statistical analysis).
- Emphasis on reproducibility and traceability (noting commit IDs in the README suggests version control integration and code traceability).
- Scalability: The modules are designed to work with large raw datasets stored on HPC systems.

##### Relevant technologies and aspects
- Python (as the main programming language, indicated by .py files).
- Sphinx documentation (as seen in the docs directory within the “phd_codes” folder).
- HPC storage integration (shown by the mentioned storage paths).
- Specific functions like add_leading_zero, total_significant_connections, and others that symbolize utility modules.
- UNITY integration improvements for questionnaire inside VR (this might be represented as an external or interfaced module).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    ds1["EEG Raw Data"]:::dataSources
    ds2["Eye Tracker Raw Data"]:::dataSources
    ds3["Questionnaire Responses"]:::dataSources

    %% Data Ingestion
    subgraph "Data Ingestion"
        ds1
        ds2
        ds3
    end

    %% Pre-processing Pipeline
    subgraph "Pre-processing Pipeline"
        %% EEG Processing Branch
        subgraph "EEG Processing"
            EEG_Pre["EEG Pre-processing & Analysis"]:::eeg
            EEG_Sep["Separation (Baseline/Experimental)"]:::eeg
            EEG_Comb["Combination (Pre & Post)"]:::eeg
            EEG_Clean["Cleaning (Epoching & Artifact Removal)"]:::eeg
        end

        %% Eye Tracker Processing Branch
        subgraph "Eye Tracker Processing"
            ET_Pre["Eye Tracker Pre-processing & Analysis"]:::eye
            ET_Extract["Extraction"]:::eye
            ET_Combine["Combining"]:::eye
            ET_Clean["Cleaning"]:::eye
        end

        %% Questionnaire Processing Branch
        subgraph "Questionnaire Processing"
            Q_Pre["Questionnaire Data Processing"]:::questionnaire
            Q_Parse["Data Parsing & Scoring"]:::questionnaire
            Q_ANCOVA["Statistical Analysis (ANCOVA)"]:::questionnaire
            VR_Unity["VR/Unity Integration for Questionnaire"]:::questionnaire
        end
    end

    %% Analysis and Data Storage
    subgraph "Analysis & Data Storage"
        Final_Analysis["Final Statistical Analysis & Aggregation"]:::analysis
        HPC["HPC Data Storage"]:::storage
        Docs["Pipeline Documentation"]:::docs
    end

    %% Data Flow Connections
    ds1 -->|"feeds"| EEG_Pre
    ds2 -->|"feeds"| ET_Pre
    ds3 -->|"feeds"| Q_Pre

    EEG_Pre -->|"executes"| EEG_Sep
    EEG_Sep -->|"then"| EEG_Comb
    EEG_Comb -->|"then"| EEG_Clean
    EEG_Clean -->|"results to"| Final_Analysis

    ET_Pre -->|"triggers"| ET_Extract
    ET_Extract -->|"then"| ET_Combine
    ET_Combine -->|"then"| ET_Clean
    ET_Clean -->|"results to"| Final_Analysis

    Q_Pre -->|"initiates"| Q_Parse
    Q_Parse -->|"then"| VR_Unity
    VR_Unity -->|"feeds into"| Q_ANCOVA
    Q_ANCOVA -->|"results to"| Final_Analysis

    Final_Analysis -->|"stores output"| HPC
    Final_Analysis -->|"documented in"| Docs

    %% Click Events for Component Mapping
    click EEG_Pre "https://github.com/ihgumilar/hyperscanning2-redesign/tree/main/phd_codes/EEG"
    click ET_Pre "https://github.com/ihgumilar/hyperscanning2-redesign/tree/main/phd_codes/eye_tracker"
    click Q_Pre "https://github.com/ihgumilar/hyperscanning2-redesign/blob/main/phd_codes/questionnaire/questionnaire.py"
    click Docs "https://github.com/ihgumilar/hyperscanning2-redesign/tree/main/phd_codes/docs"
    click EEG_Sep "https://github.com/ihgumilar/hyperscanning2-redesign/blob/main/phd_codes/EEG/preprocesses.py"
    click EEG_Comb "https://github.com/ihgumilar/hyperscanning2-redesign/blob/main/phd_codes/EEG/template.py"
    click EEG_Clean "https://github.com/ihgumilar/hyperscanning2-redesign/blob/main/phd_codes/EEG/stats.py"
    click ET_Extract "https://github.com/ihgumilar/hyperscanning2-redesign/blob/main/phd_codes/eye_tracker/preprocesses.py"
    click ET_Clean "https://github.com/ihgumilar/hyperscanning2-redesign/blob/main/phd_codes/eye_tracker/analysis.py"

    %% Styles
    classDef eeg fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef eye fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef questionnaire fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef storage fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef dataSources fill:#ffff99,stroke:#b15928,stroke-width:2px;
    classDef docs fill:#e31a1c,stroke:#fb9a99,stroke-width:2px;
    classDef analysis fill:#f1e2cc,stroke:#d17b00,stroke-width:2px;

    class ds1,ds2,ds3 dataSources;
    class EEG_Pre,EEG_Sep,EEG_Comb,EEG_Clean eeg;
    class ET_Pre,ET_Extract,ET_Combine,ET_Clean eye;
    class Q_Pre,Q_Parse,Q_ANCOVA,VR_Unity questionnaire;
    class HPC storage;
    class Docs docs;
    class Final_Analysis analysis;
```
