Physiological recordings

Physiological recordings such as cardiac and respiratory signals MAY be specified using a compressed tabular file (TSV.GZ file) and a corresponding JSON file for storing metadata fields (see below).

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

Template:

sub-<label>/[ses-<label>/]
    <datatype>/
        <matches>[_recording-<label>]_physio.tsv.gz
        <matches>[_recording-<label>]_physio.json

For the template directory name, <datatype> can correspond to any data recording modality, for example func, anat, dwi, meg, eeg, ieeg, or beh.

In the template filenames, the <matches> part corresponds to task filename before the suffix. For example for the file sub-control01_task-nback_run-1_bold.nii.gz, <matches> would correspond to sub-control01_task-nback_run-1.

Caution

<matches>_physio.tsv.gz files MUST NOT include a header line, as established by the common-principles. As a result, when supplying a <matches>_physio.tsv.gz file, an accompanying <matches>_physio.json MUST be present to indicate the column names.

The recording-<label> 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 measurements in a different sampling frequency.

Physiological recordings (including eyetracking) MUST use the _physio suffix.

The following tables specify metadata fields for the *_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.

Hardware information

Key name	Requirement Level	Data type	Description
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.
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.

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

Example *_physio.tsv.gz:

└─ sub-control01/
   └─ func/
      └─ sub-control01_task-nback_physio.tsv.gz 

(after decompression)

34    110    0
44    112    0
23    100    1

Example *_physio.json:

└─ sub-control01/
   └─ func/
      └─ sub-control01_task-nback_physio.json 

{
    "SamplingFrequency": 100.0,
    "StartTime": -22.345,
    "Columns": ["cardiac", "respiratory", "trigger"],
    "Manufacturer": "Brain Research Equipment ltd.",
    "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"
        }
}

Note how apart from the general metadata fields like SamplingFrequency, StartTime, Columns, and Manufacturer, 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). Here, only the Description and Units fields are shown, but you may use any other of the defined fields such as TermURL, LongName, and so on. In this example, the "cardiac" and "respiratory" time series are produced by devices from the same manufacturer and follow the same sampling frequency. To specify different sampling frequencies or manufacturers, the time series would have to be split into separate files like *_recording-cardiac_physio.<tsv.gz|json> and *_recording-respiratory_physio.<tsv.gz|json>.

Recommendations for specific use cases

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.

For any other data to be specified in columns, the column names can be chosen as deemed appropriate by the researcher.

Recordings with different sampling frequencies or starting times should be stored in separate files (and the recording-<label> entity MAY be used to distinguish these files).

For motion parameters acquired from MRI scanner side motion correction, the _physio suffix MUST be used.

For multi-echo data, a given physio.tsv file is applicable to all echos of a particular run. For example:

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