Eyetracking (eye)
=================

Following the guidelines from 
`BEP020 <https://github.com/bids-standard/bids-specification/pull/1128>`_, 
we propose the following **additional requirements** for eyetracking data.

Modality specific data SHOULD be split into modality specific files carrying the modality-label. Modality label for eyetracking data is ``eye<#>`` as shown in the example below 

.. code-block:: text

    physio/
    ├─ sub-01_ses-1_task-TaskName_recording-eye1_physio.json 
    ├─ sub-01_ses-1_task-TaskName_recording-eye2_physio.json 
    ├─ sub-01_ses-1_task-TaskName_recording-eye1_physio.tsv 
    ├─ sub-01_ses-1_task-TaskName_recording-eye2_physio.tsv 

**For facilitating automated data processing, we REQUIRE "eye1" to correspond to the "left" eye, and "eye2" to correspond to the "right" eye.**


Eyetracking Physiological Data
------------------------------

**TSV file:** ``<matches>_recording-eye1_physio.tsv``  

.. code-block:: text

    pupil_size  x-coordinate    y-coordinate
    4.43498	    515.3	257.1
    4.43851	    587.5	247.2
    4.43910	    586.2	247.9
    4.43851	    584.5	248.9
    4.44028	    583.5	248.9
    4.44264	    583.3	249.2
    4.44499	    583.7	248.9
    4.44558	    584.2	248.5


*In case of compressed tabular files (like `.tsv.gz`) column names MUST NOT be included.*

**JSON sidecar:** ``<matches>_recording-eye1_physio.json``  
- Must include metadata as specified in BEP020.  

Example of JSON sidecar: 

.. code-block:: text
    
    {
    "Columns": [
        "pupil_size",
        "x_coordinate",
        "y_coordinate"
    ],
    "Manufacturer": "SR-Research",
    "ManufacturersModelName": "EYELINK II CL v4.56 Aug 18 2010",
    "RecordedEye": "left",
    "StartTime": 0,
    "SampleCoordinateSystem": "gaze-on-screen",
    "SamplingFrequency": 500,
    "pupil_size": {
        "Description": "Pupil diameter",
        "Units": "mm"
    },
    "x_coordinate": {
        "LongName": "Gaze position (x)",
        "Description": "Gaze position x-coordinate of the recorded eye",
        "Units": "pixel"
    },
    "y_coordinate": {
        "LongName": "Gaze position (y)",
        "Description": "Gaze position y-coordinate of the recorded eye",
        "Units": "pixel"
    },
    "BestEye": "l",
    "PupilFitMethod": "ellipse",
    "GazeRange": {
        "xmin": 0,
        "ymin": 0,
        "xmax": 1023,
        "ymax": 767
    },
    "RecordingDuration": 597.102
    }


Eyetracking Events
------------------

The eyetracking “physioevents” file contains information about physiological events detected by the eyetracker during the session.  

**Files:**  
- ``<matches>_physioevents.tsv``  
- ``<matches>_physioevents.json``