[ENH] BEP 020 Eye Tracking

mkdocs.yml

@@ -19,6 +19,7 @@ nav:
           - Microscopy: modality-specific-files/microscopy.md
           - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
           - Motion: modality-specific-files/motion.md
+          - Eye Tracking: modality-specific-files/eye-tracking.md
       - Derivatives:
           - BIDS Derivatives: derivatives/introduction.md
           - Common data types and metadata: derivatives/common-data-types.md

src/common-principles.md

@@ -85,7 +85,7 @@ saved under a particular filename specified in the standard. This standard
 aspires to describe a majority of datasets, but acknowledges that there will be
 cases that do not fit. In such cases one can include additional files and
 subdirectories to the existing directory structure following common sense. For example
-one may want to include eye tracking data in a vendor specific format that is
+one may want to include eye-tracking data in a vendor specific format that is
 not covered by this standard. The most sensible place to put it is next to the
 continuous recording file with the same naming scheme but different extensions.
 The solutions will change from case to case and publicly available datasets will

src/introduction.md

@@ -172,6 +172,10 @@ For example:
 
 -   (publication forthcoming)
 
+#### Eye-tracking
+
+-   (publication forthcoming)
+
 ### Research Resource Identifier (RRID)
 
 BIDS has also a

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

@@ -144,6 +144,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
+et_timestamp:
+  name: 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