[ENH] BEP 020 Eye Tracking

mkdocs.yml

@@ -17,6 +17,7 @@ nav:
         - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md
         - Microscopy: modality-specific-files/microscopy.md
         - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
+        - Eye Tracking: modality-specific-files/eye-tracking.md
         - Motion: modality-specific-files/motion.md
       - Derivatives:
         - BIDS Derivatives: derivatives/introduction.md
@@ -92,6 +93,7 @@ plugins:
             '04-modality-specific-files/09-positron-emission-tomography.md': 'modality-specific-files/positron-emission-tomography.md'
             '04-modality-specific-files/10-microscopy.md': 'modality-specific-files/microscopy.md'
             '04-modality-specific-files/11-near-infrared-spectroscopy.md': 'modality-specific-files/near-infrared-spectroscopy.md'
+            '04-modality-specific-files/12-eye-tracking.md': 'modality-specific-files/eye-tracking.md'
             '05-derivatives/01-introduction.md': 'derivatives/introduction.md'
             '05-derivatives/02-common-data-types.md': 'derivatives/common-data-types.md'
             '05-derivatives/03-imaging.md': 'derivatives/imaging.md'

src/modality-specific-files/electroencephalography.md

@@ -22,7 +22,7 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template(
    "raw",
    datatypes=["eeg"],
-   suffixes=["eeg", "events", "physio", "stim"])
+   suffixes=["eeg", "events", "physio", "stim", "eyetrack"])
 }}
 
 The EEG community uses a variety of formats for storing raw data, and there is

src/modality-specific-files/eye-tracking.md

@@ -0,0 +1,213 @@
+# Eye-tracking including gaze position and pupil size
+
+Support for eye-tracking dataset developed as a
+[BIDS Extension Proposal](../extensions.md#bids-extension-proposals).
+Please see [Citing BIDS](../introduction.md#citing-bids) on how to
+appropriately credit this extension when referring to it in the context
+of the academic literature.
+
+## Terminology and conventions
+
+Eyetracking-BIDS is fully consistent with the BIDS specification as a whole.
+However, BIDS was initially developed in the context of MRI,
+so some terminology may be unfamiliar to researchers from other fields.
+This section adds clarifications to
+[Common Principles - Definitions](../common-principles.md#definitions) for the
+eye-tracking context.
+
+-   **Eye-tracker** - refers to the apparatus allowing the records of gaze
+    position and/or pupil size.
+
+-   **Screen** - Video display used to present visual stimulation (for example
+    projector, monitor, tablet).
+
+## Eye-tracking data
+
+With EyeTracking-BIDS, we wish to promote the adoption of good practices in
+the management of scientific data.
+
+### Template
+
+<!--
+This block generates a filetree exanple.
+A guide for editing it can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md.
+-->
+{{ MACROS___make_filetree_example(
+
+   {
+   "sub-<label>": {
+      "<datatype>": {
+         "<matches>_eyetrack.json": "",
+         "<matches>_eyetrack.tsv[.gz]": "",
+         },
+      }
+   }
+
+) }}
+
+Eye-tracking data MUST be stored in the main data recording modality or
+ `<datatype>` directory (for example `func` when combined with fMRI, or
+ `beh` when combined with behavioral measures).
+
+In the template filenames, the `<matches>` part corresponds to task filename
+before the suffix. For example, when fMRI is considered the main modality with
+files such as `sub-01_ses-1_task-pRF_run-1_bold.nii.gz`, `<matches>` would
+then correspond to `sub-01_ses-1_task-pRF_run-1`.
+
+### Tabular file (`*_eyetrack.tsv[.gz]`)
+
+The eye-tracking data must be saved in `.tsv` or `.tsv.gz` format.
+The tabular files consist of one row per sample and a set of REQUIRED and
+OPTIONAL columns.
+
+<!--
+This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/rules/tabular_data/eyetrack.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_columns_table("eyetrack.EyeTracking") }}
+
+Throughout BIDS you can indicate missing values with `n/a` (for "not
+available").
+
+We encourage users to put the eye-tracking raw data within the
+`/sourcedata` directory (for example put eye-tracker proprietary files before
+conversion to `tsv.gz` format in the sourcedata directory).
+
+### Sidecar JSON document (`*_eyetrack.json`)
+
+#### Required fields
+
+The following specific eye-tracking fields MUST be present:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+ src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+ src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("eyetrack.EyeTrackingRequired") }}
+
+Note that the following fields from `*_events.json` files
+are REQUIRED as they are considered essential in eye-tracking data analysis:
+
+-   `StimulusPresentation.ScreenSize`,
+-   `StimulusPresentation.ScreenResolution`,
+-   `StimulusPresentation.ScreenDistance`.
+
+#### Recommended fields
+
+Although not REQUIRED for the validity of your dataset, the following fields
+are important and should be well documented. In particular, we highly
+RECOMMEND to carefully document the calibration metadata.
+
+<!-- This block generates a metadata table.
+These tables are defined in
+ src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+ src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("eyetrack.EyeTrackingRecommended") }}
+
+#### Hardware information
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table("eyetrack.EyeTrackingHardware") }}
+
+### Example sidecar JSON document
+
+Below is an example of the sidecar JSON files
+for a fMRI dataset with eye-tracking data.
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+   {
+   "sub-01": {
+      "func": {
+         "sub-01_task-visualSearch_bold.nii.gz": "",
+         "sub-01_task-visualSearch_bold.json": "",
+         "sub-01_task-visualSearch_events.tsv": "",
+         "sub-01_task-visualSearch_events.json": "",
+         "sub-01_task-visualSearch_eyetrack.tsv": "",
+         "sub-01_task-visualSearch_eyetrack.json": "",
+         },
+      }
+   }
+) }}
+
+Content of `sub-01_task-visualSearch_eyetrack.json`:
+
+```JSON
+{
+    "Manufacturer": "SR-Research",
+    "ManufacturersModelName": "EYELINK II CL v4.56 Aug 18 2010",
+    "DeviceSerialNumber": "17535483",
+    "SoftwareVersion": "SREB1.10.1630 WIN32 LID:F2AE011 Mod:2017.04.21 15:19 CEST",
+    "SamplingFrequency": 1000,
+    "SampleCoordinateUnits": "pixel",
+    "SampleCoordinateSystem": "gaze-on-screen",
+    "EnvironmentCoordinates": "top-left",
+    "RecordedEye": "Both",
+    "ScreenAOIDefinition": ["square",
+                            [100, 150, 300, 350]]
+}
+```
+
+Content of `sub-01_task-VisualSearch_events.json`:
+
+```JSON
+{
+   "TaskName": "Visual Search",
+   "InstitutionName": "Stanford University",
+   "InstitutionAddress": "450 Serra Mall, Stanford, CA 94305-2004, USA",
+   "StimulusPresentation": {
+       "ScreenDistance": 60,
+       "ScreenRefreshRate": 60,
+       "ScreenResolution": [1024, 768],
+       "ScreenSize": [0.386, 0.29]
+   }
+}
+```
+
+### Example Datasets
+<!--
+1. Datasets will be updated later to adapt to the agreed format.
+2. We aim at adding a last example converting published dataset from openeuro.
+-->
+
+-   Combined behavior and eye-tracking fixation and saccade data,
+    measured with an Eyelink (SR Research), from 8 particpants reading 320
+    embedded target words and invisible boundary (see
+    [Gagl, 2016](https://peerj.com/articles/2467/)).
+
+    [BIDS dataset](https://zenodo.org/record/1228659)
+
+-   Combined behavior and eye-tracking position and pupil data, measured with
+    an Eyelink (SR Research), from 26 participants performing a
+    binocular rivalry task (see
+    [Brascamp et.al, 2021](https://doi.org/10.7554/eLife.66161)).
+
+    [BIDS dataset](https://doi.org/10.5061/dryad.41ns1rncp)
+
+-   Combined resting-state fMRI and eye-tracking data, measured with an Eyelink
+    (SR research), from 20 participants keeping their gaze steady at the
+    screen center.
+
+    [BIDS dataset]([https://openneuro.org/datasets/ds004158/versions/2.0.1]

src/modality-specific-files/intracranial-electroencephalography.md

@@ -22,7 +22,7 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template(
    "raw",
    datatypes=["ieeg"],
-   suffixes=["ieeg", "events", "physio", "stim"])
+   suffixes=["ieeg", "events", "physio", "stim", "eyetrack"])
 }}
 
 The iEEG community uses a variety of formats for storing raw data, and there is

src/modality-specific-files/magnetoencephalography.md

@@ -26,7 +26,7 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template(
    "raw",
    datatypes=["meg"],
-   suffixes=["meg", "markers", "events", "physio", "stim"])
+   suffixes=["meg", "markers", "events", "physio", "stim", "eyetrack"])
 }}
 
 Unprocessed MEG data MUST be stored in the native file format of the MEG

src/modality-specific-files/near-infrared-spectroscopy.md

@@ -22,7 +22,7 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template(
    "raw",
    datatypes=["nirs"],
-   suffixes=["nirs", "events", "physio", "stim"])
+   suffixes=["nirs", "events", "channels", "optodes", "coordsystem", "physio", "stim", "eyetrack"])
 }}
 
 Only the *Shared Near Infrared Spectroscopy Format* ([SNIRF](https://github.com/fNIRS/snirf))

src/modality-specific-files/physiological-and-other-continuous-recordings.md

@@ -41,12 +41,10 @@ Note that when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
 
 The [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish between several recording files.
-For example `sub-01_task-bart_recording-eyetracking_physio.tsv.gz` to contain
-the eyetracking data in a certain sampling frequency, and
-`sub-01_task-bart_recording-breathing_physio.tsv.gz` to contain respiratory
+For example `sub-01_task-bart_recording-breathing_physio.tsv.gz` to contain respiratory
 measurements in a different sampling frequency.
 
-Physiological recordings (including eyetracking) SHOULD use the `_physio`
+Physiological recordings SHOULD use the `_physio`
 suffix, and signals related to the stimulus SHOULD use `_stim` suffix.
 
 The following table specifies metadata fields for the `*_<physio|stim>.json` file.

src/modality-specific-files/positron-emission-tomography.md

@@ -70,7 +70,7 @@ and a guide for using macros can be found at
 {{ MACROS___make_filename_template(
    "raw",
    datatypes=["pet"],
-   suffixes=["pet", "events", "physio", "stim"])
+   suffixes=["pet", "events", "physio", "stim", "eyetrack"])
 }}
 
 PET data MUST be stored in the `pet` directory.

src/schema/objects/columns.yaml

@@ -132,6 +132,55 @@ duration:
     - type: string
       enum:
         - n/a
+eye1_x_coordinate:
+  name: eye1_x_coordinate
+  display_name: Eye 1 x-coordinate
+  description: |
+    Gaze position x-coordinate of the first recorded eye.
+    If the two eyes are recorded, it MUST be the left eye x-coordinate.
+  type: integer
+eye1_y_coordinate:
+  name: eye1_y_coordinate
+  display_name: Eye 1 y-coordinate
+  description: |
+    Gaze position y-coordinate of the first recorded eye.
+    If the two eyes are recorded, it MUST be the left eye y-coordinate.
+  type: integer
+eye1_pupil_size:
+  name: eye1_pupil_size
+  display_name: Eye 1 pupil size
+  description: |
+    Pupil size of the first recorded eye.
+    If the two eyes are recorded, it MUST be the left eye pupil size.
+  type: integer
+eye2_x_coordinate:
+  name: eye2_x_coordinate
+  display_name: Eye 2 x-coordinate
+  description: |
+    Gaze position x-coordinate of the second recorded eye.
+    If the two eyes are recorded, it MUST be the right eye x-coordinate.
+  type: integer
+eye2_y_coordinate:
+  name: eye2_y_coordinate
+  display_name: Eye 2 y-coordinate
+  description: |
+    Gaze position y-coordinate of the second recorded eye.
+    If the two eyes are recorded, it MUST be the right eye y-coordinate.
+  type: integer
+eye2_pupil_size:
+  name: eye2_pupil_size
+  display_name: Eye 2 pupil size
+  description: |
+    Pupil size of the second recorded eye.
+    If the two eyes are recorded, it MUST be the right eye pupil size.
+  type: integer
+eye_timestamp:
+  name: eye_timestamp
+  display_name: Eye-tracking sample timestamp
+  description: |
+    Eye-tracker timestamp of the sampled recorded eye(s) gaze position
+    coordinates and/or pupil size.
+  type: integer
 filename:
   name: filename
   display_name: Filename

src/schema/objects/datatypes.yaml

@@ -20,6 +20,11 @@ eeg:
   value: eeg
   display_name: Electroencephalography
   description: Electroencephalography
+eyetrack:
+  value: eyetrack
+  display_name: Eye-tracking
+  description: |
+    Eye-tracking including gaze position and pupil size
 fmap:
   value: fmap
   display_name: Field maps