Physiological recordings

Example datasets

Example datasets with physiological data have been formatted using this specification and can be used for practical guidance when curating a new dataset:

• 7t_trt
• ds210

General specifications

Continuous (that is, regularly sampled over time at a fixed frequency) physiological recordings such as cardiac and respiratory signals, and asynchronous events corresponding to those signals MAY be specified using compressed tabular files (TSV.GZ file). TSV.GZ files MUST be accompanied by a JSON file with the same name as their corresponding tabular file but with a .json extension.

Template:

sub-<label>/
    [ses-<label>/]
        anat/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        beh/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        dwi/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        eeg/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        func/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        ieeg/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        meg/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        motion/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        nirs/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        perf/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz
        pet/
            <matches>[_recording-<label>]_physio.json
            <matches>[_recording-<label>]_physio.tsv.gz
            <matches>[_recording-<label>]_physioevents.json
            <matches>[_recording-<label>]_physioevents.tsv.gz

Legend:

• For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

• <matches> is a placeholder to denote an arbitrary (and valid) sequence of entities and labels at the beginning of the filename (only BIDS "raw").

• <source_entities> is a placeholder to denote an arbitrary sequence of entities and labels at the beginning of the filename matching a source file from which the file derives (only BIDS-Derivatives).

• Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

• Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

• _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

• .<extension> means that there are several (>6) valid extensions for this file type.

• [.gz] means that both the unzipped and gzipped versions of the extension are valid.

The recording-<label> entity is OPTIONAL, and is described below.

Caution

Columns of TSV.GZ files MUST be defined in the corresponding JSON sidecar and the tabular content MUST NOT include a header line.

As a consequence, when supplying a <matches>_<physio|physioevents>.tsv.gz file, an accompanying <matches>_<physio|physioevents>.json MUST be supplied as well.

For multi-echo data, a single _<physio>.<tsv.gz|json> file without the echo-<index> entity applies to all echos of a particular run. For example:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-nback_run-1_echo-1_bold.nii.gz 
      ├─ sub-01_task-nback_run-1_echo-2_bold.nii.gz 
      ├─ sub-01_task-nback_run-1_echo-3_bold.nii.gz 
      └─ sub-01_task-nback_run-1_physio.tsv.gz 

This specification section first describes the organization of continuous physiological recordings, and then events corresponding to the physiological recordings. Finally, the remainder of the document describes specific types of continuous recordings such as eye-tracking.

Continuous physiological recordings

Continuous physiological recordings, such as pulse monitoring, electrocardiogram, respiratory movement measured with a respiration belt, gas concentration, eye-tracking, or head-motion parameters estimated by the MRI scanner, MUST use _physio.<tsv.gz|json> pairs.

Storing different recordings. The recording-<label> entity MAY be used to distinguish between several recording files. Recordings with different metadata such as sampling frequencies or recording device MUST be stored in separate files with different recording-<label> entities. For example, given a multi-echo acquisition corresponding to a breath-holding task (task-bht) for which pulse and respiratory movement were sampled at different frequencies, recordings are separated as follows:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-bht_echo-1_bold.nii.gz 
      ├─ sub-01_task-bht_echo-2_bold.nii.gz 
      ├─ sub-01_task-bht_echo-3_bold.nii.gz 
      ├─ sub-01_task-bht_recording-cardiac_physio.json 
      ├─ sub-01_task-bht_recording-cardiac_physio.tsv.gz 
      ├─ sub-01_task-bht_recording-respiratory_physio.json 
      └─ sub-01_task-bht_recording-respiratory_physio.tsv.gz 

Metadata fields for <matches>_<physio>.json files. General metadata fields include SamplingFrequency, StartTime, Columns, and Manufacturer, in addition to individual column descriptions. Each individual column in the TSV file MAY be documented as its own field in the JSON file (identical to the practice in other TSV+JSON file pairs).

Caution

Recordings with different key metadata MUST be split into separate files.

When key metadata such as sampling frequencies, manufacturers varies between recordings, tabular data MUST be split into separate files. In such cases, the recording-<label> entity MUST be used to distinguish these files.

Metadata sidecar files (<matches>_physio.json) MAY define the field PhysioType to indicate a specific type of recording. The default value of PhysioType is "generic", and MUST be assumed if the PhysioType metadata is not defined. Specific recording types (that is, when PhysioType takes a valid value other than "generic") have separate prescriptions for columns in the TSV.GZ files and corresponding metadata specifications.

RECOMMENDED

Using specific recording types is RECOMMENDED when available in the specification.

The allowed physiological recording types encoded by PhysioType and their corresponding metadata specifications are described in subsection Specific physiological signal types below, and its subsections:

• eye-tracking (subsection Eye-tracking).

The following table specifies metadata fields for "generic" recordings:

Key name	Requirement Level	Data type	Description
SamplingFrequency	REQUIRED	number	Sampling frequency (in Hz) of all the data in the recording, regardless of their type (for example, 2400).
StartTime	REQUIRED	number	Start time in seconds in relation to the start of acquisition of the first data sample in the corresponding (neural) dataset (negative values are allowed). This data MAY be specified with sub-second precision using the syntax s[.000000], where s reflects whole seconds, and .000000 reflects OPTIONAL fractional seconds.
Columns	REQUIRED	array of strings	Names of columns in file.
PhysioType	RECOMMENDED	string	Defines the specific type of physiological recording. For backwards compatibility, the default value is "generic". Must be one of: "generic", "eyetrack".

Hardware information. Details about the hardware MAY be stored with the following metadata fields.

Key name	Requirement Level	Data type	Description
DeviceSerialNumber	RECOMMENDED	string	The serial number of the equipment that produced the measurements. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset.
Manufacturer	RECOMMENDED	string	Manufacturer of the equipment that produced the measurements.
ManufacturersModelName	RECOMMENDED	string	Manufacturer's model name of the equipment that produced the measurements.
SoftwareVersions	RECOMMENDED	string	Manufacturer's designation of software version of the equipment that produced the measurements.

Additional metadata may be included as in any TSV file to specify, for example, the units of the recorded time series.

Column naming recommendations for "generic" recordings. To store pulse or breathing measurements, or the scanner trigger signal, the following naming conventions SHOULD be used for the column names:

Column name	Requirement Level	Data type	Description
cardiac	OPTIONAL	number	continuous pulse measurement
respiratory	OPTIONAL	number	continuous breathing measurement
trigger	OPTIONAL	number	continuous measurement of the scanner trigger signal
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

Please note that the specification of columns such as cardiac, respiratory, and trigger above follow the general specifications for tabular files:

Key name	Requirement Level	Data type	Description
LongName	OPTIONAL	string	Long (unabbreviated) name of the column.
Description	RECOMMENDED	string	Free-form natural language description. The description of the column.
Levels	RECOMMENDED	object	For categorical variables: An object of possible values (keys) and their descriptions (values).
Units	RECOMMENDED	string	Measurement units for the associated variable. SI units in CMIXF formatting are RECOMMENDED (see Units).
Delimiter	OPTIONAL	string	If rows in a column may be interpreted as a lists of values, the character that separates one value from the next.
TermURL	RECOMMENDED	string	URL pointing to a formal definition of this type of data in an ontology available on the web. For example: https://www.ncbi.nlm.nih.gov/mesh/68008297 for "male".
HED	OPTIONAL	string or object of strings	Hierarchical Event Descriptor (HED) information, see the HED Appendix for details.

Examples. Let's encode cardiac and respiratory recordings, as well as a trigger signal, the three of them sampled at 100.0 Hz by the same device during a behavioral task:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-nback_physio.json 
      └─ sub-01_task-nback_physio.tsv.gz 

In this example, the contents of sub-01_task-nback_physio.tsv.gz after decompression are:

0	34	110	0
1	44	112	0
2	23	100	1

and the header-less TSV.GZ contents are described with the following metadata sub-01_task-nback_physio.json where the Columns field defines the names corresponding to the three columns above:

{
    "Columns": ["cardiac", "respiratory", "trigger"],
    "Manufacturer": "Brain Research Equipment ltd.",
    "PhysioType": "generic",
    "SamplingFrequency": 100.0,
    "StartTime": -22.345,
    "cardiac": {
      "Description": "continuous pulse measurement",
      "Units": "mV"
    },
    "respiratory": {
      "Description": "continuous measurements by respiration belt",
      "Units": "mV"
    },
    "trigger": {
      "Description": "continuous measurement of the scanner trigger signal",
      "Units": "V"
    }
}

The example shows the three REQUIRED metadata entries Columns, SamplingFrequency, and StartTime. Columns are further described following the specifications for tabular files, indicating Description and Units fields. Other fields, such as TermURL, LongName, MAY be included.

The PhysioType can be omitted as the recordings are "generic":

{
    "Columns": ["cardiac", "respiratory", "trigger"],
    "Manufacturer": "Brain Research Equipment ltd.",
    "SamplingFrequency": 100.0,
    "StartTime": -22.345,
    "cardiac": {
      "Description": "continuous pulse measurement",
      "Units": "mV"
    },
    "respiratory": {
      "Description": "continuous measurements by respiration belt",
      "Units": "mV"
    },
    "trigger": {
      "Description": "continuous measurement of the scanner trigger signal",
      "Units": "V"
    }
}

If the "cardiac" and "respiratory" signals above were acquired at different sampling frequencies, then the recordings MUST be separated into two files disambiguated by the recording-<label> entity:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-nback_recording-cardiac_physio.json 
      ├─ sub-01_task-nback_recording-cardiac_physio.tsv.gz 
      ├─ sub-01_task-nback_recording-respiratory_physio.json 
      └─ sub-01_task-nback_recording-respiratory_physio.tsv.gz 

Physiology "events"

Discontinuous data associated with continuous recordings stored in <matches>_physio.tsv.gz files MAY be specified following the summary template pattern above.

Physiology "events" files <matches>_recording-<label>_physioevents.tsv.gz MUST follow specific column specifications:

Column name	Requirement Level	Data type	Description
onset	REQUIRED	number	Onset of the event relative to the timeline defined by the corresponding physiological recording file. Typically, it will correspond to a timestamp issued by the recording device. This column must appear first in the file.
duration	RECOMMENDED	number	Duration of the event (measured from onset) in seconds. Must always be either zero or positive (or n/a if unavailable). A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse. This column may appear anywhere in the file. Must be a number greater than or equal to 0.
trial_type	OPTIONAL	string	Primary categorisation of each trial to identify them as instances of the experimental conditions. For example: for a response inhibition task, it could take on values go and no-go to refer to response initiation and response inhibition experimental conditions. This column may appear anywhere in the file.
message	OPTIONAL	string	Brief free-text description of a message (for example in a log generated by a device), or other information of interest. This column may appear anywhere in the file.
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

The following table specifies metadata fields for the <matches>[_recording-<label>]_physioevents.json file.

Key name	Requirement Level	Data type	Description
Columns	REQUIRED	array of strings	Names of columns in file.
Description	RECOMMENDED	string	Free-form natural language description.
ForeignIndexColumn	RECOMMENDED	string	An existing column name in an corresponding recoding data TSV file that indexes the "onset" column of the present TSV file. For example, "timestamp" column.

The ForeignIndexColumn metadata specifies whether <matches>[_recording-<label>]_physio.tsv.gz files are implicitly or explicitly indexed.

Implicit indexing of <matches>_physioevents.tsv.gz files. When ForeignIndexColumn is not provided, the "onset" column corresponds to the one-based row number of the associated <matches>_physio.tsv.gz file. The "onset" column accepts negative values to register events occurred before the recording(s) in the corresponding <matches>_physio.tsv.gz file started.

For example, considering the following structure:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-nback_physio.json 
      ├─ sub-01_task-nback_physio.tsv.gz 
      ├─ sub-01_task-nback_physioevents.json 
      └─ sub-01_task-nback_physioevents.tsv.gz 

where the decompressed contents of sub-01_task-nback_physio.tsv.gz are:

10.1
10.0
9.5
9.2
9.0
10.2
10.3
10.1

Please note that the above code block has the line numbers enabled, but those line numbers are not part of the contents of the file. Since there is no explicit column to index the recording, the ForeignIndexColumn SHOULD NOT be defined in the sub-01_task-nback_physioevents.json file:

{
    "Columns": ["onset", "message"],
    "Description": "Messages logged by the measurement device"
}

An example of the decompressed contents of the corresponding TSV file, sub-01_task-nback_physioevents.tsv.gz is:

-3	Ready
3	Synchronous recalibration triggered
6	External message received: new block

In this case, the first column lists the indexes (one-based row number) from the sub-01_task-nback_physio.tsv.gz. The first entry, with "onset" set to 3, maps to the third line of the sub-01_task-nback_physio.tsv.gz, indicating that the message Synchronous recalibration triggered was logged at the same time the sample with value 9.5 was registered. Likewise, the second message was logged when the recording later registered a value of 10.2 (row number 5 of sub-01_task-nback_physio.tsv.gz). As negative indexes are allowed, the first Ready message occurred four sampling cycles before the first recorded measurement (line number 1). For example, if SamplingFrequency in sub-01_task-nback_physio.json is set to 100 Hz and StartTime is -22.345 s, then the Ready message was recorded 0.04 s before the first sample, therefore at -22.305 s.

Explicit indexing of <matches>_physioevents.tsv.gz files (RECOMMENDED). When the ForeignIndexColumn defines a value such as "timestamp", that specific column name MUST be present the <matches>_physio.tsv.gz file. In that case, all values of the "onset" column of the <matches>_physioevents.tsv.gz are indexed by the index established by the ForeignIndexColumn of the corresponding <matches>_physio.tsv.gz file (that is, "timestamp" in this example). It is RECOMMENDED to specify metadata such as Units or Origin corresponding to the column defined by ForeignIndexColumn.

For example, let us consider the previous structure:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-nback_physio.json 
      ├─ sub-01_task-nback_physio.tsv.gz 
      ├─ sub-01_task-nback_physioevents.json 
      └─ sub-01_task-nback_physioevents.tsv.gz 

However, the sub-01_task-nback_physio.json will define now an extra column called "timestamp":

{
    "SamplingFrequency": 100.0,
    "StartTime": -22.345,
    "Columns": ["timestamp", "cardiac"],
    "cardiac": {
        "Description": "continuous pulse measurement",
        "Units": "mV"
    },
    "timestamp": {
        "Description": "a continuously increasing identifier of the sampling time registered by the device",
        "Units": "ms",
        "Origin": "System startup"
    }
}

The decompressed contents of sub-01_task-nback_physio.tsv.gz are now:

10.1	13894432329
10.0	13894432330
9.5	13894432331
9.2	13894432332
9.0	13894432333
10.2	13894432334
10.3	13894432335
10.1	13894432336

Then, the sub-01_task-nback_physioevents.json MAY define the ForeignIndexColumn for indexing:

{
    "Columns": ["onset", "message"],
    "Description": "Messages logged by the measurement device",
    "ForeignIndexColumn": "timestamp"
}

The decompressed contents of the corresponding TSV file, sub-01_task-nback_physioevents.tsv.gz could read now:

13894432325	Ready
13894432331	Synchronous recalibration triggered
13894432334	External message received: new block

Specific physiological signal types

Eye-tracking

Example datasets

Example datasets with eye-tracking data have been formatted using this specification and can be used for practical guidance when curating a new dataset:

• Combined fMRI and eye-tracking data in a resting-state task, measured with an Eyelink (SR research). Human participant kept their gaze steady at the screen center.

  BIDS dataset

• Combined behavioral and eye-tracking data, measured with and Eyelink (SR Research). Human participants freely viewed as set of natural images. Published paper: https://doi.org/10.1523/ENEURO.0287-23.2023

  BIDS dataset

Setting PhysioType to the keyword "eyetrack" specifies that the physiological recordings in the <matches>_physio.tsv.gz have been acquired with an eye-tracker. In the following, eye-tracker refers to the apparatus allowing the recording of gaze position, and, optionally, pupil size.

Eye-tracking data MUST be stored following the general specifications for "generic" physiological recordings. However, it is REQUIRED that recordings corresponding to each eye (and/or cyclopean or averaged signals for binocular eye-trackers providing a third recording) are split into files with different recording-<label>. Therefore, the use of recording-<label> is REQUIRED with eye-tracking data. The values "eye1", "eye2", and "eye3" are RECOMMENDED as the respective labels for the recording-<label> entity.

MANDATORY metadata

The correspondence of labels and the recorded eye MUST be encoded by the MANDATORY RecordedEye metadata.

The recording-<label> entity MAY take other values such as "left", "cyclopean", or "right" corresponding to the RecordedEye metadata. However, it is RECOMMENDED that metadata is not encoded in the file names to avert that filename and metadata enter into conflict. For example, if recording-<label> takes the value "left" but the corresponding sidecar JSON file contains a definition of RecordedEye being "right".

Eye-tracking files <matches>_recording-<label>_physio.tsv.gz MUST follow specific column prescriptions:

Column name	Requirement Level	Data type	Description
timestamp	RECOMMENDED	number	Timestamp issued by the eye-tracker indexing the continuous recordings corresponding to the sampled eye. This column must appear first in the file.
x_coordinate	REQUIRED	number	Gaze position x-coordinate of the recorded eye, in the coordinate units specified in the corresponding metadata sidecar. This column must appear second in the file.
y_coordinate	REQUIRED	number	Gaze position y-coordinate of the recorded eye, in the coordinate units specified in the corresponding metadata sidecar. This column must appear third in the file.
pupil_size	OPTIONAL	number	Pupil size or area of the recorded eye, in the units specified in the corresponding metadata sidecar. It is RECOMMENDED to indicate the particular type of pupil size that is being recorded in the Description field of this column. It is RECOMMENDED to specify the Units field corresponding to this column. This column may appear anywhere in the file.
Additional Columns	OPTIONAL	n/a	Additional columns are allowed.

Please note that the specification of columns such as timestamp, x_coordinate, y_coordinate, and pupil_size follow the general specifications for tabular files and MAY define metadata fields such as LongName, Description, Levels, or TermURL. However, in the case of eye-tracking, the metadata entry Units, becomes REQUIRED for the colums x_coordinate and y_coordinate:

Key name	Requirement Level	Data type	Description
Units	REQUIRED	string	Measurement units for the associated variable. SI units in CMIXF formatting are RECOMMENDED (see Units).

The following table specifies metadata fields for the <matches>_recording-<label>_physio.json file:

Key name	Requirement Level	Data type	Description
SamplingFrequency	REQUIRED	number	Sampling frequency (in Hz) of all the data in the recording, regardless of their type (for example, 2400).
StartTime	REQUIRED	number	Start time in seconds in relation to the start of acquisition of the first data sample in the corresponding (neural) dataset (negative values are allowed). This data MAY be specified with sub-second precision using the syntax s[.000000], where s reflects whole seconds, and .000000 reflects OPTIONAL fractional seconds.
Columns	REQUIRED	array of strings	Names of columns in file.
DeviceSerialNumber	RECOMMENDED	string	The serial number of the equipment that produced the measurements. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset.
Manufacturer	RECOMMENDED	string	Manufacturer of the equipment that produced the measurements.
ManufacturersModelName	RECOMMENDED	string	Manufacturer's model name of the equipment that produced the measurements.
SoftwareVersions	RECOMMENDED	string	Manufacturer's designation of software version of the equipment that produced the measurements.
PhysioType	REQUIRED	string	Defines the specific type of physiological recording. For backwards compatibility, the default value is "generic". Must be one of: "generic", "eyetrack".
RecordedEye	REQUIRED	string	Indicates the eye tracked, for example, "left" or "right". It SHOULD be set to "cyclopean" for recordings combining both eyes as potentially generated by binocular eye-trackers. Must be one of: "left", "right", "cyclopean".
SampleCoordinateSystem	REQUIRED	string	Coordinate system of the gaze position recordings. Generally eye-trackers are set to use "gaze-on-screen" coordinate system, but you may use "eye-in-head" or "gaze-in-world". If none of the three default options properly describe the coordinate system, the "custom" keyword MUST be employed and the coordinate system MUST be described using additional metadata entries. Must be one of: "gaze-on-screen", "eye-in-head", "gaze-in-world", "custom".
AverageCalibrationError	RECOMMENDED	number	Average calibration error in degrees of visual angle.
CalibrationCount	RECOMMENDED	integer	The number of calibrations corresponding to this run. Must be a number greater than or equal to 0.
CalibrationPosition	RECOMMENDED	array of arrays	A list of [x, y] coordinates in the CalibrationUnit. For example, using 5 positions calibration presented on an HD screen, it could be [[960,50],[960,540],[960,1030],[50,540],[1870,540]].
CalibrationType	RECOMMENDED	string	The type of the calibration procedure executed last. For example the "H3" for horizontal calibration with 3 positions or "HV9" for horizontal and vertical calibration with 9 positions, or one point calibration.
CalibrationUnit	RECOMMENDED	string	Unit of "CalibrationPosition". Must be one of: "pixel", "mm", "cm".
EyeCameraSettings	RECOMMENDED	object of objects	A field to store any settings that influence the resolution and quality of the eye imagery. Autowhitebalance? Changes in sharpness?
EyeTrackerDistance	RECOMMENDED	number or array of numbers	Distance (in meters) between the eye-tracker and the participant eye(s). Distance can either be expressed as a single numeric value indicating the shortest distance between the participant's eye and the eye-tracker's camera, or a three-coordinates array indicating the X, Y, Z distances between the participant's eye and the eye-tracker's camera.
EyeTrackingMethod	RECOMMENDED	string	Method used to track gaze or pupil position: "P–CR" for video based eye-tracking using pupil and corneal reflection; "DPI" for Dual-Purkinje Imaging system, "SSC" for scleral search coils; "EOG" for electro-oculogram; "Limbus" for trackers estimating limbus borders between the iris and sclera; or other.
FeatureDetectionSettings	RECOMMENDED	object of objects	Description of feature detection settings. For example, minimum/maximum pupil size.
GazeMappingSettings	RECOMMENDED	object of objects	Description of gaze-mapping settings. For example, threshold on pupil confidence REQUIRED for gaze mapping.
MaximalCalibrationError	RECOMMENDED	number	Maximal calibration error in degrees of visual angle.
PupilFitMethod	RECOMMENDED	string	The method employed for fitting the pupil, for example "centre-of-mass" or "ellipse". If "centre-of-mass" or "ellipse" method is used, it is RECOMMENDED to use these exact labels.
RawDataFilters	RECOMMENDED	string	Filter settings applied to eye-movement raw data.
ScreenAOIDefinition	RECOMMENDED	object of objects	A description of the shape of the Screen AOIs and what coordinates are used. ["square", ["x_start", "x_stop", "y_start", "y_stop"]] Other options: "custom"/"circle"/"triangle", [["x", "y"], ["x", "y"], ["x", "y"], and so on.]

Comprehensively documenting the calibration metadata is RECOMMENDED.

Eye-tracking files <matches>_recording-<label>_physio.tsv.gz MAY be annotated with a corresponding <matches>_recording-<label>_physioevents.tsv.gz file. The <matches>_recording-<label>_physioevents.tsv.gz file MAY be employed to record discontinuous model parameters generated by the eye-tracker, for example, those derived from the saccade and blinks model some eye-trackers produce.

Important

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:

• StimulusPresentation.ScreenDistance,
• StimulusPresentation.ScreenOrigin,
• StimulusPresentation.ScreenResolution,
• StimulusPresentation.ScreenSize.

Examples. The recordings produced by a monocular eye-tracker during a visual search task may display the following structure:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-visualSearch_bold.json 
      ├─ sub-01_task-visualSearch_bold.nii.gz 
      ├─ sub-01_task-visualSearch_events.json 
      ├─ sub-01_task-visualSearch_events.tsv 
      ├─ sub-01_task-visualSearch_recording-eye1_physio.json 
      ├─ sub-01_task-visualSearch_recording-eye1_physio.tsv.gz 
      ├─ sub-01_task-visualSearch_recording-eye1_physioevents.json 
      └─ sub-01_task-visualSearch_recording-eye1_physioevents.tsv.gz 

The above example is extended to a binocular eye-tracker producing three signals (left and right eyes, plus a cyclopean recording), as follows:

└─ sub-01/
   └─ func/
      ├─ sub-01_task-visualSearch_bold.json 
      ├─ sub-01_task-visualSearch_bold.nii.gz 
      ├─ sub-01_task-visualSearch_events.json 
      ├─ sub-01_task-visualSearch_events.tsv 
      ├─ sub-01_task-visualSearch_recording-eye1_physio.json 
      ├─ sub-01_task-visualSearch_recording-eye1_physio.tsv.gz 
      ├─ sub-01_task-visualSearch_recording-eye1_physioevents.json 
      ├─ sub-01_task-visualSearch_recording-eye1_physioevents.tsv.gz 
      ├─ sub-01_task-visualSearch_recording-eye2_physio.json 
      ├─ sub-01_task-visualSearch_recording-eye2_physio.tsv.gz 
      ├─ sub-01_task-visualSearch_recording-eye2_physioevents.json 
      ├─ sub-01_task-visualSearch_recording-eye2_physioevents.tsv.gz 
      ├─ sub-01_task-visualSearch_recording-eye3_physio.json 
      ├─ sub-01_task-visualSearch_recording-eye3_physio.tsv.gz 
      ├─ sub-01_task-visualSearch_recording-eye3_physioevents.json 
      └─ sub-01_task-visualSearch_recording-eye3_physioevents.tsv.gz 

Given the above example file structures, a corresponding sub-01_task-visualSearch_recording-eye1_physio.json sidecar could read:

{
    "DeviceSerialNumber": "17535483",
    "Columns": ["timestamp", "x_coordinate", "y_coordinate", "pupil_size"],
    "EnvironmentCoordinates": "top-left",
    "Manufacturer": "SR-Research",
    "ManufacturersModelName": "EYELINK II CL v4.56 Aug 18 2010",
    "PhysioType": "eyetrack",
    "RecordedEye": "right",
    "SampleCoordinateSystem": "gaze-on-screen",
    "SamplingFrequency": 1000,
    "SoftwareVersion": "SREB1.10.1630 WIN32 LID:F2AE011 Mod:2017.04.21 15:19 CEST",
    "ScreenAOIDefinition": [
        "square",
        [100, 150, 300, 350]
    ],
    "timestamp": {
        "Description": "a continuously increasing identifier of the sampling time registered by the device",
        "Units": "ms",
        "Origin": "System startup"
    },
    "x_coordinate": {
      "LongName": "Gaze position (x)",
      "Description": "Gaze position x-coordinate of the recorded eye, in the coordinate units specified in the corresponding metadata sidecar.",
      "Units": "pixel"
    },
    "y_coordinate": {
      "LongName": "Gaze position (y)",
      "Description": "Gaze position y-coordinate of the recorded eye, in the coordinate units specified in the corresponding metadata sidecar.",
      "Units": "pixel"
    },
    "pupil_size": {
        "Description": "Pupil area of the recorded eye as calculated by the eye-tracker in arbitrary units (see EyeLink's documentation for conversion).",
        "Units": "a.u."
    }
}

Content of sub-01_task-VisualSearch_events.json:

{
   "TaskName": "Visual Search",
   "InstitutionName": "Stanford University",
   "InstitutionAddress": "450 Serra Mall, Stanford, CA 94305-2004, USA",
   "StimulusPresentation": {
       "ScreenDistance": 0.6,
       "ScreenOrigin": ["top", "left"],
       "ScreenRefreshRate": 60,
       "ScreenResolution": [1024, 768],
       "ScreenSize": [0.386, 0.29]
   }
}

Example eye-tracking recording. Given the above sub-01_task-visualSearch_recording-eye1_physio.json metadata specification, the decompressed content of the sub-01_task-visualSearch_recording-eye1_physio.tsv.gz can be:

7186799    416.29    267.39    4612.0
7186800    416.29    268.10    4623.0
7186801    416.20    269.00    4623.0
7186802    415.89    269.60    4613.0
7186803    415.70    269.20    4603.0
7186804    415.60    266.79    4591.0
7186805    415.79    264.60    4589.0
7186806    416.10    263.89    4587.0
7186807    416.29    265.20    4587.0
7186808    416.39    266.50    4588.0
7186809    416.50    266.79    4594.0
7186810    416.50    267.20    4599.0
7186811    416.10    268.00    4609.0
7186812    415.70    268.29    4612.0
7186813    416.00    268.60    4605.0

Example sub-01_task-visualSearch_recording-eye1_physioevents.tsv.gz corresponding to the above eye-tracking recording, after decompressing:

7184392    n/a    n/a         n/a    "NO Reply is disabled for function eyelink_cal_result"
7184392    n/a    n/a         n/a    "RECCFG CR 1000 2 0 R"
7184392    n/a    n/a         n/a    "ELCLCFG TOWER"
7186771    n/a    n/a         n/a    "First task trigger"
7186806    72     fixation    0      n/a
7186879    231    saccade     1      n/a
7187111    6186   fixation    0      n/a
7193298    216    saccade     1      n/a
7193515    1286   fixation    0      n/a
7194802    24     saccade     0      n/a
7194827    2403   fixation    0      n/a
7197231    17     saccade     0      n/a
7197249    1640   fixation    0      n/a
7198890    6      saccade     0      n/a
7198897    1105   fixation    0      n/a
7200003    233    saccade     1      n/a
7200237    184    fixation    0      n/a
7200422    15     saccade     0      n/a
7200438    264    fixation    0      n/a

where the first three rows are logged by the eye-tracker and the fourth row shows a message asynchronously received by the eye-tracker. The remainder of the rows contain a subset of parameters registered by the device, derived from applying a model to identify saccades and blinks. The corresponding sub-01_task-visualSearch_recording-eye1_physioevents.json sidecar would read:

{
    "Columns": ["onset", "duration", "trial_type", "blink", "message"],
    "Description": "Messages logged by the measurement device",
    "ForeignIndexColumn": "timestamp",
    "blink": {
      "Description": "Gives status of the eye.",
      "Levels": {
          "0": "Indicates if the eye was open.",
          "1": "Indicates if the eye was closed.",
      },
    },
    "message": {
      "Description": "String messages logged by the eye-tracker."
    },
    "trial_type": {
      "Description": "Event type as identified by the eye-tracker's model.",
      "Levels": {
          "fixation": "Indicates a fixation.",
          "saccade": "Indicates a saccade.",
      },
    }
}