[ENH] BEP 020 Eye Tracking

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/modality-specific-files/task-events.md

@@ -263,6 +263,19 @@ and a guide for using macros can be found at
 -->
 {{ MACROS___make_subobject_table("metadata.StimulusPresentation") }}
 
+!!! warning "Important"
+
+    Some metadata of the `StimulusPresentation` object become REQUIRED with the presence of
+    [eye-tracking data](physiological-recordings.md#eye-tracking)
+
+    The following fields pertaining to `<matches>_events.json` of tasks that were acquired
+    with the simultaneous recording of eye-tracking escalate to REQUIRED as they are considered
+    essential in eye-tracking data analysis:
+
+    -   `ScreenSize`,
+    -   `ScreenResolution`,
+    -   `ScreenDistance`.
+
 The operating system description SHOULD include the following attributes:
 
 -   type (for example, Windows, macOS, Linux)

src/schema/objects/columns.yaml

@@ -165,6 +165,34 @@ duration:
     - type: string
       enum:
         - n/a
+x_coordinate:
+  name: x_coordinate
+  display_name: Gaze x-coordinate
+  description: |
+    Gaze position x-coordinate of the recorded eye, in the coordinate
+    units specified in the corresponding metadata sidecar.
+  type: number
+y_coordinate:
+  name: y_coordinate
+  display_name: Gaze y-coordinate
+  description: |
+    Gaze position y-coordinate of the recorded eye, in the coordinate
+    units specified in the corresponding metadata sidecar.
+  type: number
+pupil_size:
+  name: pupil_size
+  display_name: Pupil size
+  description: |
+    Pupil size or area of the recorded eye, in the
+    units specified in the corresponding metadata sidecar.
+  type: number
+et_timestamp:
+  name: timestamp
+  display_name: Eye-tracking recording timestamp
+  description: |
+    Timestamp issued by the eye-tracker indexing the continuous recordings corresponding to
+    the sampled eye.
+  type: number
 filename:
   name: filename
   display_name: Filename
@@ -282,6 +310,13 @@ mapping:
   description: |
     Corresponding integer label in the standard BIDS label lookup.
   type: integer
+message:
+  name: message
+  display_name: Message
+  description: |
+    Brief free-text description of a message (for example in a log generated
+    by a device), or other information of interest.
+  type: string
 material:
   name: material
   display_name: Electrode material

src/schema/objects/enums.yaml

@@ -1405,3 +1405,13 @@ microvascular:
   display_name: microvascular
   description: |
     The origin of a tissue: microvascular
+PhysioTypeGeneric:
+  value: generic
+  display_name: Generic Physiological Recording
+  description: |
+    Unspecified physiological recording.
+PhysioTypeEyetrack:
+  value: eyetrack
+  display_name: Eye-tracking recording
+  description: |
+    A specific physiological recording type: eye-tracking.