# nathanklineinstitute/natview_eegfmri architecture

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

- Interactive diagram: https://gitdiagram.com/nathanklineinstitute/natview_eegfmri
- Repository: https://github.com/nathanklineinstitute/natview_eegfmri

## Overview

##### Project Type & Purpose
- Open-source neuroimaging preprocessing toolkit.
- Automates gradient/pulse artifact removal in EEG, CCS-based fMRI preprocessing, eye-tracking conversion/QC, and stimulus presentation scripts for simultaneous EEG-fMRI experiments.

##### High-Level Architecture & Main Components
A. Data Store (BIDS Input)
- Raw data in BIDS format:
- /sub-*/eeg/*.bvef + .edf
- /sub-*/func/*.nii.gz (fMRI)
- /sub-*/eye/*.edf
- respiratory data
B. EEG Preprocessing Module
- natview_eeg_preprocess_pipeline.m
- BC-MR-64-X52.bvef (cap montage)
- Dependencies: EEGLAB + FMRIB plugin
- Output: cleaned EEG files (e.g., .set/.fdt) in BIDS derivatives
C. fMRI Preprocessing Module
- Bash scripts under fmri/preprocessing (ccs_bids_*.sh)
- Python helper (json2txt)
- Templates: MNI152 brain masks, config files
- Dependencies: CCS pipeline (FSL, FreeSurfer, AFNI)
- Output: preprocessed anatomical/functional images in BIDS derivatives
D. Eye-Tracking Preprocessing Module
- natview_eye_edf2bids.m (EDF→BIDS conversion)
- natview_eye_preprocess_blinks.m (blink detection/interpolation)
- natview_eye_data_qc.m (data-quality metrics)
- Dependencies: EEGLAB, EyeLink SDK
- Output: cleaned eye-tracking .tsv + QC reports
E. Stimulus Presentation Module
- natview_stimuli_checkerboard.m
- natview_stimuli_video.m
- Helpers.zip (custom functions)
- Dependencies: Psychtoolbox-3, EyeLink 1000 Plus drivers
- Output: stimulus timing logs for synchronization
F. Orchestration/Entry Point
- natview_cleaning_pipeline.m (master MATLAB script to launch modalities)

##### Relationships & Data Flow
- Eye Module: EDF→BIDS → blink detection → QC → output.
- Stimulus Module: initialization → display routines → log output.
- The Orchestration script invokes EEG, Eye, fMRI modules as appropriate.
- All modules write back to “BIDS Derivatives” folder.

##### Architectural Patterns & Design Principles
- Modularity by modality (EEG, fMRI, Eye, Stimulus).
- BIDS standard enforces consistent data organization.
- Shell/Python drivers wrap third-party pipelines (CCS, EEGLAB).
- MATLAB scripts isolate domain logic per modality.

##### Technology Stack Call-Outs
- MATLAB + EEGLAB/FMRIB plugin
- Bash + CCS pipeline (FSL, FreeSurfer, AFNI)
- Python (simple JSON→TXT converter)
- Psychtoolbox-3 + EyeLink SDK

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Stores
    RawBIDS("BIDS Raw Data"):::datastore
    Deriv("BIDS Derivatives"):::datastore

    %% Orchestration
    Orchestrator["natview_cleaning_pipeline.m"]:::orchestrator

    %% EEG Module
    subgraph "EEG Preprocessing Module"
        EEGScript["natview_eeg_preprocess_pipeline.m"]:::module
        CapFile["BC-MR-64-X52.bvef"]:::module
        EEGLAB["EEGLAB + FMRIB plugin"]:::external
        EEGScript -->|uses cap montage| CapFile
        EEGScript -->|depends on| EEGLAB
        EEGScript -->|"cleaned EEG (.set/.fdt)"| Deriv
    end

    %% fMRI Module
    subgraph "fMRI Preprocessing Module"
        Docker["ccs_preproc_bids_docker.sh"]:::module
        subgraph "CCS Scripts"
            sh1["ccs_bids_01_anatpreproc.sh"]:::module --> sh2["ccs_bids_01_anatsurfrecon.sh"]:::module
            sh2 --> sh3["ccs_bids_01_funcpreproc.sh"]:::module
            sh3 --> sh4["ccs_bids_02_anatregister.sh"]:::module
            sh4 --> sh5["ccs_bids_02_funcregister_func2anat.sh"]:::module
            sh5 --> sh6["ccs_bids_02_funcregister_func2std.sh"]:::module
            sh6 --> sh7["ccs_bids_03_funcsegment.sh"]:::module
            sh7 --> sh8["ccs_bids_04_funcnuisance.sh"]:::module
            sh8 --> sh9["ccs_bids_05_funcpreproc_vol.sh"]:::module
        end
        JSON2TXT["ccs_prep_bids_json2txt.py"]:::module
        Templates["Templates (MNI152, config)"]:::module
        CCSDeps["CCS pipeline (FSL, FreeSurfer, AFNI)"]:::external

        Docker -->|invokes| sh1
        Docker -->|uses converter| JSON2TXT
        Docker -->|loads templates| Templates
        Docker -->|requires| CCSDeps
        sh9 -->|"preprocessed fMRI images"| Deriv
    end

    %% Eye-Tracking Module
    subgraph "Eye-Tracking Preprocessing Module"
        EDF2BIDS["natview_edf2bids.m"]:::module
        Blink["natview_eye_preprocess_blinks.m"]:::module
        QC["natview_eye_data_qc.m"]:::module
        ELSDK["EyeLink SDK + EEGLAB"]:::external

        EDF2BIDS -->|EDF→BIDS| Blink
        Blink -->|blink detection| QC
        QC -->|"cleaned eye .tsv + QC reports"| Deriv
        EDF2BIDS -->|depends on| ELSDK
        Blink -->|depends on| ELSDK
        QC -->|depends on| ELSDK
    end

    %% Stimulus Module
    subgraph "Stimulus Presentation Module"
        Checker["natview_stimuli_checkerboard.m"]:::module
        Video["natview_stimuli_video.m"]:::module
        Helpers["helpers.zip"]:::module
        Psychtoolbox["Psychtoolbox-3 + EyeLink drivers"]:::external

        Checker -->|init/display/log| Deriv
        Video -->|init/display/log| Deriv
        Checker -->|uses| Helpers
        Video -->|uses| Helpers
        Checker -->|depends on| Psychtoolbox
        Video -->|depends on| Psychtoolbox
    end

    %% Orchestration links
    Orchestrator -->|launches| EEGScript
    Orchestrator -->|launches| Docker
    Orchestrator -->|launches| EDF2BIDS
    Orchestrator -->|launches| Checker

    %% Raw data ingestion
    RawBIDS -->|input| EEGScript
    RawBIDS -->|input| Docker
    RawBIDS -->|input| EDF2BIDS
    RawBIDS -->|input| Checker
    RawBIDS -->|input| Video

    %% Click Events
    click EEGScript "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/eeg/natview_eeg_preprocess_pipeline.m"
    click CapFile "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/eeg/BC-MR-64-X52.bvef"
    click Docker "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/ccs_preproc_bids_docker.sh"
    click sh1 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_01_anatpreproc.sh"
    click sh2 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_01_anatsurfrecon.sh"
    click sh3 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_01_funcpreproc.sh"
    click sh4 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_02_anatregister.sh"
    click sh5 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_02_funcregister_func2anat.sh"
    click sh6 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_02_funcregister_func2std.sh"
    click sh7 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_03_funcsegment.sh"
    click sh8 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_04_funcnuisance.sh"
    click sh9 "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_bids_05_funcpreproc_vol.sh"
    click JSON2TXT "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/fmri/preprocessing/ccs_prep_bids_json2txt.py"
    click Templates "https://github.com/nathanklineinstitute/natview_eegfmri/tree/main/fmri/templates"
    click EDF2BIDS "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/eye/natview_edf2bids.m"
    click Blink "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/eye/natview_eye_preprocess_blinks.m"
    click QC "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/eye/natview_eye_data_qc.m"
    click Checker "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/stimulus/natview_stimuli_checkerboard.m"
    click Video "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/stimulus/natview_stimuli_video.m"
    click Helpers "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/stimulus/helpers.zip"
    click Orchestrator "https://github.com/nathanklineinstitute/natview_eegfmri/blob/main/natview_cleaning_pipeline.m"

    %% Styles
    classDef datastore fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef module fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef orchestrator fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
