# Experiment Workflow and Dataset Organization

This document describes the complete workflow used to conduct the experiment and organize the resulting [dataset](https://github.com/dududsantos/L2_Reading_EyeTracking_Dataset/tree/main), developed as part of “*A Multi-Modal Eye-Tracking Dataset for L2 Idiomatic Processing.*”
The goal is to provide enough detail for future researchers to understand the experimental procedure, the data collection process, and the dataset structure, enabling reproducibility and extension of the project.

---

## 1. Stimulus Preparation

The experiment was built around sentences containing **Potentially Idiomatic Expressions (PIEs)**.
These expressions were selected primarily from the **MAGPIE corpus**, with additional examples adapted from **SemEval datasets**.

Each expression was embedded into a complete sentence designed to bias interpretation toward either a **literal** or **figurative** meaning.
This resulted in a dataset of **193 contextualized sentences**, each containing one target multi-word expression.

All stimulus metadata is stored in:

sentences/PIE_context_data.csv

This file serves as the central reference for the linguistic stimuli, and contains the following fields:

| Column | Description |
|-----------------|------------|
| mwe | Target multi-word expression (idiomatic candidate) |
| MWE_source | Source of the expression (e.g., corpus or invented) |
| block | Experimental block (e.g., practice or main task) |
| sense | Intended interpretation (literal or figurative) |
| sentence | Full sentence containing the expression |
| source | Origin of the sentence (e.g., Invented, corpus) |
| source_detail | Additional details about the source (if available) |
| start_index | Start position of the expression in the sentence (word index) |
| end_index | End position of the expression in the sentence (word index) |

---

## 2. Experiment Implementation

The experiment was implemented using the **PsychoPy** software, which controlled stimulus presentation and synchronized data collection with the eye-tracking hardware.

Each experimental session followed a fixed structure to ensure consistency across participants.

### Experimental Flow

1. Participant registration (before the experiment meeting)
2. Calibration
3. Practice phase
4. Main reading task
5. Comprehension questions

Each session lasted approximately **45–65 minutes**, excluding the calibration time.

---

### 2.1 Participant Registration

Participants were asked to self-report their English proficiency level according to the CEFR scale and were then assigned an anonymized identifier known only to the researchers.

This english level data is stored in:

experiment/proficiency_level.csv

| Column | Description |
|-----------------|------------|
| participant_id | Unique anonymized identifier assigned to each participant |
| english_level | Self-reported English proficiency level following the CEFR scale, including an additional descriptive label in Portuguese |

---

### 2.2 Calibration

Before the experiment began, participants completed a **9-point calibration procedure** using the [Tobii Eyetracking software](https://www.tobii.com/products/software/applications-and-developer-kits/tobii-pro-eye-tracker-manager).
This step maps gaze positions to screen coordinates and is essential for accurate eye-tracking measurements.


---
### 2.3 Launching the Application

The experiment is executed locally using PsychoPy.

Follow the steps below to correctly initialize the experiment.

#### Step 1 — Open PsychoPy

* Install and open [PsychoPy](https://www.psychopy.org/index.html)
* Load the experiment *.psyexp* file
##### PsychoPy interface:

#### Step 2 — Configure the EyeTracker

Click on the Engine button and verify that:

* The correct eye-tracking device is selected
* The sampling rate is properly configured


#### Step 3 — Run the Experiment

Set the execution mode to "Run", then click the green play button.

#### Step 4 — Participant Registration

A screen will appear prompting the researcher to enter the participant ID.

After submitting this information, the experiment will begin automatically.

---

### 2.4 Practice Phase

Participants completed a short practice session consisting of **six sentences**.
This phase allowed them to become familiar with the interface and timing of the experiment.

The corresponding data is stored in:

pre-experiment/

Although not used in the main analysis, this data is preserved for completeness and potential debugging.

---

### 2.5 Main Reading Task

Participants read all experimental sentences sequentially.
To mitigate fatigue, a short break was introduced at the midpoint of the experiment. During this interval, participants were allowed to drink water or leave the room if necessary. After the break, particular attention was given to restoring the participant’s position to ensure consistent eye-tracking conditions before resuming the task.

---

### 2.6 Comprehension Checks

To ensure engagement, participants answered a comprehension question after every **four sentences**.
Responses were recorded for possible later analysis.

---

## 3. Eye-Tracking Setup

Eye movements were recorded using a **Tobii Pro Spark eye tracker** with a sampling rate of **60 Hz**.

| Parameter | Value |
| ------------- | --------------- |
| Device | Tobii Pro Spark |
| Sampling Rate | 60 Hz |
| Distance | ~70 cm |
| Mounting | Below monitor |

Participants were instructed to minimize head movement, and environmental conditions (lighting, reflections) were controlled to ensure stable tracking.

---

## 4. Dataset Structure

The dataset is organized into three main directories:

dataset/
│
├── sentences/
├── pre-experiment/
└── experiment/

Each directory corresponds to a different stage of the experimental workflow.

---

### 4.1 Sentences

sentences/
└── PIE_context_data.csv

Contains all stimulus definitions and associated metadata.

---

### 4.2 Pre-Experiment Data

pre-experiment/

Stores gaze recordings from the practice phase.
These files are not used in the main analysis but are useful for debugging or exploratory analysis.

---

### 4.3 Main Experiment Data

experiment/
│
├── metrics/
└── participants/

This directory contains participant metadata, aggregated metrics, and detailed recordings.

---

## 5. Data Processing Pipeline

The dataset follows a structured transformation pipeline:

Raw gaze data (raw_data.csv)
        ↓
Cleaning & normalization
        ↓
processed_data.csv
        ↓
Feature extraction
        ↓
metrics.csv
        ↓
Aggregation
        ↓
group_metrics.csv

This pipeline ensures a clear progression from raw recordings to high-level behavioral metrics.

---

## 6. Participant-Level Data

Each participant has a dedicated directory:

experiment/participants/
└── participant_id/

This folder contains multiple files corresponding to different stages of processing.

---

### 6.1 Raw Data

raw_data.csv

This file contains the raw gaze recordings exported directly from the experiment.

| Column | Description |
|---------------------|------------|
| Participant_ID | Anonymized identifier of the participant (e.g., P01) |
| Trial_ID | Identifier of the trial within the session |
| Sentence_Number | Index of the sentence in the experiment sequence |
| Sentence | Full sentence presented to the participant |
| Left_Eye_Position | Gaze coordinates of the left eye (x, y), normalized between 0 and 1 |
| Right_Eye_Position | Gaze coordinates of the right eye (x, y), normalized between 0 and 1 |

**Note:** Eye position values are provided as normalized screen coordinates, where (0, 0) represents the top-left corner and (1, 1) represents the bottom-right corner of the screen.

Each row corresponds to a single recorded gaze sample.

---

### 6.2 Processed Data

processed_data.csv

A cleaned and reorganized version of the raw dataset.
| Column | Description |
|------------------|------------|
| time | Timestamp or sample index of the gaze recording |
| x | Horizontal gaze position in screen pixels |
| y | Vertical gaze position in screen pixels |
| Participant_ID | Anonymized identifier of the participant (e.g., P01) |
| Trial_ID | Identifier of the trial within the session |
| Sentence_Number | Index of the sentence in the experiment sequence |
| Sentence | Full sentence presented to the participant |
#### Processing Steps

* Timestamp standardization
* Coordinate normalization
* Left/right eye merging
* Column restructuring

This structure enables direct compatibility with [**PyGaze**](https://www.pygaze.org/), the toolbox/library chosen to support our analysis.

---

### 6.3 Sentence-Level Metrics

metrics.csv

Contains reading behavior metrics computed for each sentence.

| Metric | Description |
|----------------------|------------|
| n_fix | Total number of fixations in the sentence |
| mean_fix_dur | Mean fixation duration (in milliseconds) |
| n_regressions | Number of regressive (backward) eye movements |
| regression_rate | Proportion of fixations that are regressions |
| strongest_regression | Largest backward movement amplitude (in pixels) |
| Sentence_Number | Index of the sentence in the experiment sequence |

**Note:** The `strongest_regression` metric was included as an exploratory measure of backward movement amplitude. However, it was not used in the main analyses, as it did not yield consistent or interpretable patterns across participants and trials.

---

### 6.4 Aggregated Metrics

experiment/metrics/group_metrics.csv

Aggregates metrics across participants and sentences, providing a global view of reading behavior.

---

### 6.5 Comprehension Answers

compquest_answers.csv

Stores participant responses to comprehension questions.

---

## 7. Data Traceability

The dataset structure preserves the relationship between all stages of processing:

* Raw data → Processed data
* Processed data → Metrics
* Metrics → Participants
* Participants → Stimuli

This design allows researchers to:

* recompute metrics
* apply alternative processing pipelines
* validate experimental results

---

## 8. Future Extensions

Because both raw and processed data are preserved, the dataset can be extended in multiple ways:

* application of alternative fixation detection algorithms
* computation of additional gaze metrics
* integration with multimodal data sources
* use of different libraries

The structure was intentionally designed to support such extensions while maintaining clarity and reproducibility.

---

## 9. Summary

This dataset provides a complete pipeline from **stimulus definition → gaze recording → behavioral metrics**.

Its organization ensures:

* reproducibility
* extensibility
* transparency

making it suitable for both experimental replication and methodological research.