# carolfs/fmri_magic_carpet architecture

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

- Interactive diagram: https://gitdiagram.com/carolfs/fmri_magic_carpet
- Repository: https://github.com/carolfs/fmri_magic_carpet

## Overview

##### Main System Components
- Task Module: Represented by the “code/task” folder, this contains the experimental framework. It holds assets (instructions and quizzes), configuration files, and scripts (e.g., fmri_game.py, run.py) that drive the behavioral tasks. It essentially acts as the data acquisition front-end.
- Analysis Module: Shown under “code/analysis”, this part consists of many Python scripts (e.g., analyse_ratings.py, process_pupil_diameter.py) and Stan model files used for fMRI and behavioral data analysis. This module implements the data processing, statistical modeling (hybrid, logistic regression, etc.), and computes predictors from the collected data.
- Data Store: The “data” directory gathers all the raw inputs:
- Eye-tracking data (in compressed asc files)
- Questionnaire responses (plain text files)
- Task behavior data (CSV files)
- Additional ratings and other CSV files.
- External Dependencies & Configuration:
- The repository makes use of configuration files (for both task and analysis modules) and includes scripts relying on external libraries (e.g., Stan models, Bayesian analysis frameworks) and neuroimaging tools to process NIFTI files.

##### Out the Relationships and Data Flows
- Inside the Analysis Module, illustrate internal workflows – for example:
- fMRI analysis (using files like Nacc_3mm.nii.gz and mask_gm_conj_3mm.nii.gz)
- First-level and second-level data modeling (first_level_repl*.py, second_level_*.py)
- Bayesian and mixed effect modeling (seen in hybrid_*.stan, hybrid_bayesian.py, logreg.py).
- A component for configuration that is used by both the task and analysis submodules (referencing config.py files) to manage experiment settings and analysis parameters.

##### Incorporate Important Architectural Patterns and Technologies
- Modular separation between data collection (Task) and data analysis.
- Notice the lean “pipeline” nature typical of research code:
- Data acquisition (via task) → Data storage → Data processing & statistical modeling (via analysis).
- Use of probabilistic programming (Stan models) and standard Python scripting, typical in scientific computation workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Modules
    subgraph "Experimental Data Acquisition"
        T["Task Module"]:::module
    end

    subgraph "Data Repository"
        DS["Data Store"]:::data
    end

    subgraph "Data Analysis"
        A["Analysis Module"]:::module
        subgraph "Analysis Workflow"
            A1["fMRI Analysis"]:::workflow
            A2["Bayesian Modeling"]:::workflow
            A3["Behavioral Data Analysis"]:::workflow
        end
    end

    subgraph "Configuration & External Dependencies"
        CT["Task Config"]:::config
        CA["Analysis Config"]:::config
    end

    %% Data Flows
    T -->|"generates_data"| DS
    DS -->|"feeds_data"| A
    A -->|"initiates"| A1
    A1 -->|"progresses_to"| A2
    A2 -->|"progresses_to"| A3
    CT -->|"configures"| T
    CA -->|"configures"| A

    %% Click Events
    click T "https://github.com/carolfs/fmri_magic_carpet/tree/main/code/task"
    click DS "https://github.com/carolfs/fmri_magic_carpet/tree/main/data"
    click A "https://github.com/carolfs/fmri_magic_carpet/tree/main/code/analysis"
    click CT "https://github.com/carolfs/fmri_magic_carpet/blob/main/code/task/config.py"
    click CA "https://github.com/carolfs/fmri_magic_carpet/blob/main/code/analysis/config.py"

    %% Styles
    classDef module fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef workflow fill:#F5CBA7,stroke:#943126,stroke-width:2px;
```
