# annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis architecture

> Architecture diagram of the GitHub repository annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis
- Repository: https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis

## Overview

#### Purpose and execution model
MATLAB analysis repository for a microsaccade-bias experiment. It processes behavioral and eye-tracking recordings produced by the separate Python experiment repository. There is no single application entry point; analysts run MATLAB scripts in a prescribed sequence and edit participant/data-location mapping as needed.

#### Subject and data-location boundary
`getSubjParam.m` is the central subject/session configuration boundary: it maps randomized participant/session identifiers to the repository owner’s data organization. Analysis scripts depend on this mapping rather than defining an independent data-ingestion layer.

Relevant paths:
- `getSubjParam.m`
- `setBehaviourParam.m`
- `getBehaviour.m`

#### Behavioral analysis pipeline
`getBehaviour.m` is the main behavioral-analysis entry point. It uses behavioral parameter setup and produces statistics/visualization through supporting scripts, separating behavioral results from the eye-tracking pipeline.

Relevant paths:
- `getBehaviour.m`
- `setBehaviourParam.m`
- `behaviour_stats.m`

#### Eye-data epoching stage
`epochEyeData.m` is the first required eye-tracking stage. It converts/segments raw eye-tracking data into analysis epochs that downstream gaze-position and saccade computations consume. This is the principal transition from acquired recordings to trial/epoch-level analysis data.

Relevant paths:
- `epochEyeData.m`
- `frevede_nanBlinks_1eye.m`
- `frevede_pixel2dva.m`

#### Participant-level gaze-position bias
`get_GazePositionBias.m` computes average gaze bias for each participant after epoching. Supporting transforms convert gaze position into one- or two-dimensional shift/bias representations and provide eye-data summaries.

Relevant paths:
- `get_GazePositionBias.m`
- `PBlab_gazepos2shift_1D.m`
- `PBlab_gazepos2shift_2D.m`

#### Participant-level saccade bias
`get_SaccadeBias.m` derives per-participant saccade bias from the epoched eye data. It is parallel to gaze-position analysis but represents a distinct metric and output stream.

Relevant paths:
- `get_SaccadeBias.m`
- `Eye_stats.m`
- `frevede_allbyall_correlations_new.m`

#### Group-level aggregation and inference
Grand-average scripts consume participant-level bias outputs. Their stated design weights every participant equally rather than weighting by completed trial count. Statistical support includes correlation and 1-D cluster-statistics utilities, with plotting helpers for group-result presentation.

Relevant paths:
- `GA_GazePositionBias.m`
- `GA_SaccadeBias.m`
- `frevede_ftclusterstat1D.m`

#### Runtime and external dependencies
The runtime is MATLAB. Several eye-tracking and statistical stages depend on the FieldTrip MATLAB toolbox, originally developed against FieldTrip version `2020.10.23`; FieldTrip likely provides core statistical/data-structure functionality for functions such as `frevede_ftclusterstat1D.m`. Input data and experimental semantics originate from the external Microsaccade-bias Python experiment repository.

Relevant paths:
- `frevede_ftclusterstat1D.m`
- `frevede_errorbarplot.m`
- `create_colour_map.m`

Main entry points: [`epochEyeData.m`](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/epochEyeData.m) (Eye-data epoching), [`getBehaviour.m`](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/getBehaviour.m) (Behavior analysis), [`getSubjParam.m`](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/getSubjParam.m) (Subject/session mapping), [`frevede_ftclusterstat1D.m`](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_ftclusterstat1D.m) (1-D cluster inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Inputs"]
  node_matlab{{"MATLAB<br/>runtime"}}
  node_experiment[("Python experiment repository<br/>external data source")]
  node_fieldtrip{{"FieldTrip toolbox<br/>MATLAB dependency"}}
  node_subjects["Subject/session mapping<br/>configuration boundary<br/>[getSubjParam.m]"]
end

subgraph group_behaviour["Behavioral Analysis"]
  node_behaviour_params["Behavior parameters<br/>parameter setup"]
  node_behaviour_entry["Behavior analysis<br/>pipeline entry<br/>[getBehaviour.m]"]
  node_behaviour_stats["Behavior statistics<br/>statistics and visualization<br/>[behaviour_stats.m]"]
end

subgraph group_eye["Eye-Tracking Pipeline"]
  node_epoching["Eye-data epoching<br/>pipeline stage<br/>[epochEyeData.m]"]
  node_blink_cleanup["Blink cleanup<br/>eye-data transform"]
  node_pixel_conversion["Pixel-to-DVA conversion<br/>eye-data transform"]
  node_gaze_bias["Participant gaze bias<br/>participant metric"]
  node_gaze_transforms["Gaze shift transforms<br/>bias representation"]
  node_saccade_bias["Participant saccade bias<br/>participant metric<br/>[get_SaccadeBias.m]"]
  node_eye_stats["Eye-data summaries<br/>eye statistics<br/>[Eye_stats.m]"]
end

subgraph group_group["Group Inference"]
  node_ga_gaze["Grand-average gaze bias<br/>group aggregation"]
  node_ga_saccade["Grand-average saccade bias<br/>group aggregation<br/>[GA_SaccadeBias.m]"]
  node_cluster_stats["1-D cluster inference<br/>statistical utility"]
  node_group_plots["Group result plots<br/>plotting utility"]
end

node_experiment -->|"recordings mapped by"| node_subjects
node_matlab -->|"runs"| node_behaviour_entry
node_matlab -->|"runs"| node_epoching
node_subjects -->|"data locations"| node_behaviour_entry
node_behaviour_params -->|"parameters"| node_behaviour_entry
node_behaviour_entry -->|"behavioral results"| node_behaviour_stats
node_subjects -->|"data locations"| node_epoching
node_experiment -->|"raw eye recordings"| node_epoching
node_blink_cleanup -->|"cleaning"| node_epoching
node_pixel_conversion -->|"coordinate conversion"| node_epoching
node_fieldtrip -.->|"eye-data support"| node_epoching
node_epoching -->|"analysis epochs"| node_gaze_bias
node_gaze_transforms -->|"shift representations"| node_gaze_bias
node_epoching -->|"analysis epochs"| node_saccade_bias
node_eye_stats -->|"summaries"| node_saccade_bias
node_gaze_bias -->|"participant outputs"| node_ga_gaze
node_saccade_bias -->|"participant outputs"| node_ga_saccade
node_cluster_stats -->|"inference"| node_ga_gaze
node_cluster_stats -->|"inference"| node_ga_saccade
node_fieldtrip -.->|"statistical support"| node_cluster_stats
node_ga_gaze -->|"group results"| node_group_plots
node_ga_saccade -->|"group results"| node_group_plots

click node_subjects "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/getSubjParam.m"
click node_behaviour_params "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/setBehaviourParam.m"
click node_behaviour_entry "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/getBehaviour.m"
click node_behaviour_stats "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/behaviour_stats.m"
click node_epoching "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/epochEyeData.m"
click node_blink_cleanup "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_nanBlinks_1eye.m"
click node_pixel_conversion "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_pixel2dva.m"
click node_gaze_bias "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/get_GazePositionBias.m"
click node_gaze_transforms "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/PBlab_gazepos2shift_1D.m"
click node_saccade_bias "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/get_SaccadeBias.m"
click node_eye_stats "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/Eye_stats.m"
click node_ga_gaze "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/GA_GazePositionBias.m"
click node_ga_saccade "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/GA_SaccadeBias.m"
click node_cluster_stats "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_ftclusterstat1D.m"
click node_group_plots "https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_errorbarplot.m"

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_matlab,node_experiment,node_fieldtrip,node_subjects toneBlue
class node_behaviour_params,node_behaviour_entry,node_behaviour_stats toneAmber
class node_epoching,node_blink_cleanup,node_pixel_conversion,node_gaze_bias,node_gaze_transforms,node_saccade_bias,node_eye_stats toneMint
class node_ga_gaze,node_ga_saccade,node_cluster_stats,node_group_plots toneRose
```

## Components

### Runtime & Inputs

- **MATLAB**: runtime · Analysts run scripts in sequence.
- **Python experiment repository**: external data source · Produces behavioral and eye-tracking recordings.
- **FieldTrip toolbox**: MATLAB dependency · Provides eye-data and statistical functionality.
- [Subject/session mapping](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/getSubjParam.m): configuration boundary · Maps randomized identifiers to local data organization. · `getSubjParam.m`

### Behavioral Analysis

- [Behavior parameters](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/setBehaviourParam.m): parameter setup · `setBehaviourParam.m`
- [Behavior analysis](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/getBehaviour.m): pipeline entry · `getBehaviour.m`
- [Behavior statistics](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/behaviour_stats.m): statistics and visualization · `behaviour_stats.m`

### Eye-Tracking Pipeline

- [Eye-data epoching](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/epochEyeData.m): pipeline stage · Converts recordings into trial-level analysis epochs. · `epochEyeData.m`
- [Blink cleanup](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_nanBlinks_1eye.m): eye-data transform · `frevede_nanBlinks_1eye.m`
- [Pixel-to-DVA conversion](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_pixel2dva.m): eye-data transform · `frevede_pixel2dva.m`
- [Participant gaze bias](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/get_GazePositionBias.m): participant metric · `get_GazePositionBias.m`
- [Gaze shift transforms](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/PBlab_gazepos2shift_1D.m): bias representation · Creates 1-D and 2-D gaze-shift representations. · `PBlab_gazepos2shift_1D.m`
- [Participant saccade bias](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/get_SaccadeBias.m): participant metric · `get_SaccadeBias.m`
- [Eye-data summaries](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/Eye_stats.m): eye statistics · `Eye_stats.m`

### Group Inference

- [Grand-average gaze bias](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/GA_GazePositionBias.m): group aggregation · Weights participants equally. · `GA_GazePositionBias.m`
- [Grand-average saccade bias](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/GA_SaccadeBias.m): group aggregation · Weights participants equally. · `GA_SaccadeBias.m`
- [1-D cluster inference](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_ftclusterstat1D.m): statistical utility · `frevede_ftclusterstat1D.m`
- [Group result plots](https://github.com/annavanharmelen/microsaccade-bias-shift-vs-maintain-analysis/blob/main/frevede_errorbarplot.m): plotting utility · `frevede_errorbarplot.m`

## Connections

- Python experiment repository → Subject/session mapping: recordings mapped by
- MATLAB → Behavior analysis: runs
- MATLAB → Eye-data epoching: runs
- Subject/session mapping → Behavior analysis: data locations
- Behavior parameters → Behavior analysis: parameters
- Behavior analysis → Behavior statistics: behavioral results
- Subject/session mapping → Eye-data epoching: data locations
- Python experiment repository → Eye-data epoching: raw eye recordings
- Blink cleanup → Eye-data epoching: cleaning
- Pixel-to-DVA conversion → Eye-data epoching: coordinate conversion
- FieldTrip toolbox → Eye-data epoching: eye-data support
- Eye-data epoching → Participant gaze bias: analysis epochs
- Gaze shift transforms → Participant gaze bias: shift representations
- Eye-data epoching → Participant saccade bias: analysis epochs
- Eye-data summaries → Participant saccade bias: summaries
- Participant gaze bias → Grand-average gaze bias: participant outputs
- Participant saccade bias → Grand-average saccade bias: participant outputs
- 1-D cluster inference → Grand-average gaze bias: inference
- 1-D cluster inference → Grand-average saccade bias: inference
- FieldTrip toolbox → 1-D cluster inference: statistical support
- Grand-average gaze bias → Group result plots: group results
- Grand-average saccade bias → Group result plots: group results