{ "cells": [ { "cell_type": "markdown", "id": "2e2a79a2", "metadata": {}, "source": [ "# Understanding Eye-Tracking Data\n", "\n", "Before preprocessing, event detection, or statistical analysis, it is important to understand\n", "what eye-tracking data look like at their most basic level and how they are structured. This\n", "section introduces the core components of eye-tracking recordings and the representations\n", "commonly used in analysis.\n", "\n", "## What are Eye-Tracking Data?\n", "\n", "Eye-tracking data consist of measurements of eye position over time, typically recorded at a fixed\n", "sampling frequency. Depending on the experimental setup, these measurements can be collected while participants are:\n", "\n", "- reading texts,\n", "- viewing static images,\n", "- watching videos,\n", "- or interacting with dynamic or real-world **stimuli**, i.e., the content presented to\n", " participants during the experiment.\n", "\n", "A device called an **eye tracker** estimates the point of **gaze**, that is, where on a stimulus or\n", "display a participant is inferred to be looking, by measuring the relative position of the pupil\n", "and corneal reflections. During calibration, participants fixate known reference points, allowing\n", "the system to learn a mapping from eye position signals to **gaze coordinates** on the stimulus. In\n", "screen-based experiments, gaze coordinates are commonly expressed in pixel units, corresponding to\n", "positions on the display surface.\n", "\n", "These initial eye tracker files contain mixed content. They typically include time-stamped eye position coordinates (**raw samples**); information about the gaze quickly moving or, on the contrary, slowing down at certain positions (**occumotoric events**); various additional eye tracker markings, including experiment metadata and vendor-provided labels (**messages**). These files are often referred to as \"raw eye-tracking data\". However, this term is used inconsistently in the literature and sometimes is confused with \"raw gaze data\" or \"raw samples\". Thus, these terms can indicate:\n", "\n", "In `pymovements`, \"raw samples\" refer specifically to the lowest-level gaze time series available after import, before any other processing. Events, whether vendor-provided or detected through processing, are stored separateley. In fact, `pymovements` aggregates these and other data \n", "components into one comprehensible {py:class}`~pymovements.Gaze` object, presented below." ] }, { "cell_type": "markdown", "id": "537251da", "metadata": {}, "source": [ "## The `Gaze` Object\n", "\n", "All loading functions in `pymovements` return a {py:class}`~pymovements.Gaze` object. \n", "This is the central data structure used throughout the library and serves as a self-contained object for eye-tracking data and its metadata. A {py:class}`~pymovements.Gaze` object bundles together multiple components of a recording, including samples, events, experiment data and more." ] }, { "cell_type": "code", "execution_count": null, "id": "782e1f2b", "metadata": { "tags": [ "hide-input" ] }, "outputs": [], "source": [ "from pymovements import Experiment\n", "from pymovements.gaze.io import from_csv\n", "\n", "experiment = Experiment(\n", " screen_width_px=1280,\n", " screen_height_px=1024,\n", " screen_width_cm=38,\n", " screen_height_cm=30.2,\n", " distance_cm=68,\n", " origin='upper left',\n", " sampling_rate=250.0,\n", ")\n", "\n", "gaze = from_csv(\n", " '../../examples/gaze-toy-example.csv',\n", " experiment=experiment,\n", " time_column='time',\n", " pixel_columns=['x', 'y'],\n", ")\n", "\n", "gaze" ] }, { "cell_type": "markdown", "id": "244836cd", "metadata": {}, "source": [ "### Samples: The Core Time Series\n", "\n", "The most important part of the {py:class}`~pymovements.Gaze` object is the `samples` table. Each row corresponds to one recorded time point, and each column \n", "represents a signal channel, such as gaze position, pupil size, velocity, or other measurements. Internally, gaze signals can be stored \n", "in nested component columns. For example, column `pixel` contains the `x` and `y` pixel coordinates. Read more in {doc}`Defining Gaze Components <../loading-gaze-data/csv>`.\n", "\n", "### Events\n", "\n", "If available, detected or imported eye-movement events are stored separately\n", "in `gaze.events`. These are not raw samples but fixations, saccades, or blinks pre-calcualted by the eye-tracker or added later through processing. Read more about events in {doc}`Detecting Occumotoric Events <../event-detection>`.\n", "\n", "### Experiment\n", "\n", "Each {py:class}`~pymovements.Gaze` object can contain an associated {py:class}`~pymovements.Experiment`, which defines screen geometry and sampling rate. \n", "This link is essential for interpreting the samples in physical or visual-angle units and for computing time-based measures like velocity. \n", "Read more about this in the next chapter {doc}`Experiment Configuration <../experiment>`.\n", "\n", "### Other\n", "\n", "Additionally, the {py:class}`~pymovements.Gaze` object can contain various metadata provided during import and optional time-stamped messages from the experiment software. " ] }, { "cell_type": "markdown", "id": "560f55ac", "metadata": {}, "source": [ "***\n", "\n", "## Good To Know\n", "\n", "**Coordinate systems**\n", "\n", "Depending on the experimental setup and research question, gaze data can be expressed in different coordinate systems. \n", "For instance, **allocentric coordinates** describe where gaze falls on the stimulus or display surface, \n", "typically in pixels or degrees of visual angle. **Egocentric coordinates** describe eye orientation relative to the head, \n", "often in degrees of rotation. These coordinates are more common in head-mounted or mobile eye tracking.\n", "\n", "``pymovements`` primarily works with stimulus-referenced coordinates but allows explicit transformations when the necessary \n", "experimental information is available.\n", "\n", "**The Optimal Pipeline**\n", "\n", "However, there is no single preprocessing pipeline or set of eye-tracking measures that is optimal\n", "for all research questions. Instead, appropriate choices depend on the experimental design, the\n", "properties of the recording device, and the quality of the data\n", "(see {doc}`Inspecting Data Quality <../data-quality>`). Making these transformations explicit and\n", "transparent is therefore essential for valid, interpretable, and reproducible analysis.\n", "\n", "**What Do Eye-tracking Data Tell Us** \n", "\n", "Crucially, eye-tracking data are signals rather than direct measurements of perception or\n", "cognition. Constructs such as attention, comprehension, or cognitive processes are inferred through\n", "preprocessing, event detection, and analysis choices." ] } ], "metadata": {}, "nbformat": 4, "nbformat_minor": 5 }