You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
with physiological data have been formatted using this specification
12
-
and can be used for practical guidance when curating a new dataset:
7
+
The file and dataset naming conventions for physiological data follow the common principles of BIDS. When present, physiological recordings **SHOULD** be stored as compressed tabular files (`.tsv.gz` format) along with corresponding JSON files for storing metadata fields (see below).
As a result, when supplying a `<matches>_physio.tsv.gz` file, an accompanying
30
-
`<matches>_physio.json` MUST be present to indicate the column names.
36
+
When recording physiological data, we **RECOMMEND** to always record and save the data with the least amount of processing possible applied to it following this specification. If derivatives are computed in real time, we **RECOMMEND** to save them following the derivatives BEP, and to also store raw data following this concBEP.
31
37
32
-
The [`recording-<label>`](../appendices/entities.md#recording)
33
-
entity MAY be used to distinguish between several recording files.
34
-
For example `sub-01_task-bart_recording-eyetracking_physio.tsv.gz` to contain
35
-
the eyetracking data in a certain sampling frequency, and
36
-
`sub-01_task-bart_recording-breathing_physio.tsv.gz` to contain respiratory
37
-
measurements in a different sampling frequency.
38
+
#### 1.2 Splitting concurrently acquired data into multiple files
38
39
39
-
Physiological recordings (including eyetracking) MUST use the `_physio` suffix.
40
+
Recorded physio data **MUST** be split into separate data files in case of difference in top-level metadata like `SamplingFrequency`, `Software`, and `Manufacturer` of the main recording device (i.e., data source). These top-level metadata are discussed in the following section.
40
41
41
-
The following tables specify metadata fields for the `*_physio.json`file.
42
+
Data with common top-level metadata **MAY** be kept aggregated in one file otherwise, or split based on channel type, if preferred. The sole exception is eye tracking data, that **MUST** be split in its own file, following BEP020 specifications.
42
43
43
-
<!-- This block generates a metadata table.
44
-
These tables are defined in
45
-
src/schema/rules/sidecars
46
-
The definitions of the fields specified in these tables may be found in
We generally recommend keeping different files from different recording devices separate, but the option to keep data together acknowledges not only current standards in data collection, but also the fact that often physiological data is inspected and analysed together to get a clearer picture of what the fluctuations describe (e.g., looking at ventilation and respiration together, or PPG and ECG for motion artifacts).
52
45
53
-
## Hardware information
46
+
Moreover, the set of metadata we are proposing managed to consider most, if not all, possible channel types - with the exception of eye tracking. Thus, the choice to aggregate physiological data with common key metadata in a single file is left to user preference.
54
47
55
-
<!-- This block generates a metadata table.
56
-
These tables are defined in
57
-
src/schema/rules/sidecars
58
-
The definitions of the fields specified in these tables may be found in
We **RECOMMEND** to store trigger signals recorded alongside physiological channels in the same file when concurrent modalities are collected (e.g. functional MRI or EEG).
64
49
65
-
Additional metadata may be included as in
66
-
[any TSV file](../common-principles.md#tabular-files) to specify, for
67
-
example, the units of the recorded time series.
50
+
**For example:**
68
51
69
-
Example `*_physio.tsv.gz`:
52
+
**Splitting recorded data into separate physio data files**
It is possible that the `recording-<label>` entity uses terms that could be confused with metadata field values, such as `MeasurementType` or `SamplingFrequency`. In that case, the lowest metadata level available should always be interpreted as the most reliable information. For instance, if the file name contains `recording-1000hz` but the `SamplingFrequency` metadata indicates a sampling frequency of 100Hz, data **MUST** be interpreted as being sampled at 100 Hz. Similarly, if the entity `recording-ecg` is used, but the `MeasurementType` metadata of the contained columns indicate “ppg” and “Ventilation”, the data **MUST** be interpreted as PPG and Ventilation, and not ECG.
107
+
108
+
---
108
109
109
-
```JSON
110
+
### 2. JSON Data files
111
+
112
+
Metadata sidecar files (`<matches>_physio.json`) **SHOULD** define the field `PhysioType`. This field indicates a specific type of formatting, rather than a physiological modality. The `PhysioType``"generic"` value, being the default, **MUST** be assumed if the `PhysioType` metadata is not defined.
113
+
114
+
All metadata we are proposing are either **OPTIONAL** or **RECOMMENDED**, and they are meant to enrich the current `"generic"``PhysioType`. However, we are also suggesting the introduction of a `"specified"``PhysioType`, that will differ from `"generic"` because one proposed metadata, `MeasureType`, will be **REQUIRED** rather than **RECOMMENDED**. Equally, the `Units` metadata will be **REQUIRED** instead of **RECOMMENDED** in this case.
115
+
116
+
Compared to the current BIDS specification (1.10.0), at the file level we are adding one metadata, the **OPTIONAL**`SubjectPosition`, indicating the position of the subject during the data collection (see section 2.1).
117
+
118
+
When specifying column names, columns **MUST** have unique names. All such data columns **MUST** be appropriately defined in the JSON metadata.
119
+
120
+
**Example:**
121
+
122
+
```json
110
123
{
111
-
"SamplingFrequency": 100.0,
112
-
"StartTime": -22.345,
113
-
"Columns": ["cardiac", "respiratory", "trigger"],
114
-
"Manufacturer": "Brain Research Equipment ltd.",
115
-
"cardiac": {
116
-
"Description": "continuous pulse measurement",
117
-
"Units": "mV"
118
-
},
119
-
"respiratory": {
120
-
"Description": "continuous measurements by respiration belt",
121
-
"Units": "mV"
122
-
},
123
-
"trigger": {
124
-
"Description": "continuous measurement of the scanner trigger signal"
125
-
}
124
+
"Columns": ["screda1", "screda2", "ecg", "ppg"],
125
+
"SamplingFrequency": 1000,
126
+
"SubjectPosition": "sitting",
127
+
"PhysioType": "specified",
128
+
...
129
+
"screda1": {
130
+
"MeasureType": "EDA-phasic",
131
+
"Units": "mS",
132
+
"Placement": "Thenar",
133
+
...
134
+
},
135
+
"screda2": {
136
+
"MeasureType": "EDA-tonic",
137
+
"Units": "mS",
138
+
"Placement": "Hypothenar",
139
+
...
140
+
},
141
+
"ecg": {
142
+
"MeasureType": "ECG",
143
+
"Units": "mV",
144
+
"Placement": "II",
145
+
...
146
+
},
147
+
"ppg": {
148
+
"MeasureType": "PPG",
149
+
"Units": "au",
150
+
"Placement": "Right earlobe",
151
+
...
152
+
},
153
+
...
126
154
}
127
155
```
128
156
129
-
Note how apart from the general metadata fields like `SamplingFrequency`, `StartTime`, `Columns`,
130
-
and `Manufacturer`,
131
-
each individual column in the TSV file may be documented as its own field in the JSON file
132
-
(identical to the practice in other TSV+JSON file pairs).
133
-
Here, only the `Description` and `Units` fields are shown, but you may use any other of the
134
-
[defined fields](../common-principles.md#tabular-files) such as `TermURL`, `LongName`, and so on.
135
-
In this example, the `"cardiac"` and `"respiratory"` time series are produced by devices from
136
-
the same manufacturer and follow the same sampling frequency.
137
-
To specify different sampling frequencies or manufacturers, the time series would have to be split
138
-
into separate files like `*_recording-cardiac_physio.<tsv.gz|json>` and `*_recording-respiratory_physio.<tsv.gz|json>`.
139
-
140
-
## Recommendations for specific use cases
141
-
142
-
To store pulse or breathing measurements, or the scanner trigger signal, the
143
-
following naming conventions SHOULD be used for the column names:
As described in the following table (Section 2.2), this BEP is adding a few metadata to describe columns.
152
158
153
-
For any other data to be specified in columns, the column names can be chosen
154
-
as deemed appropriate by the researcher.
159
+
- The most important one is `MeasureType`, a **RECOMMENDED** metadata that indicates the actual nature of the data in the column.
160
+
- This metadata value is a string that **MUST** come from a set of keywords (see table 2.2).
161
+
- This set of keywords can be expanded in the future to include more physiological modalities.
162
+
- When the file-level metadata `PhysioType` is `"specified"`, `MeasureType` becomes a **REQUIRED** field for each column.
155
163
156
-
Recordings with different sampling frequencies or starting times should be
157
-
stored in separate files
158
-
(and the [`recording-<label>`](../appendices/entities.md#recording)
159
-
entity MAY be used to distinguish these files).
164
+
This metadata is meant to be the most reliable indicator of the type of data contained in the described column. Having a reliable and standardized indication of what type of data is being handled allows automated modality specific data processing and prevents data misuse.
160
165
161
-
For motion parameters acquired from MRI scanner side motion correction, the
162
-
`_physio` suffix MUST be used.
166
+
Furthermore, we are proposing that `Units` becomes a **REQUIRED** metadata when `PhysioType` is `"Specified"`. Not only this helps to better reflect the possible quantitative nature of physiological data, but since similarly labelled data (e.g. Ventilation) can be expressed in different units, indicating different underlying processes, sensors, or levels of real-time preprocessing and data manipulation (e.g. transformation from Volts to millimeters of Mercury), making this field more explicit in the section regarding physiological data will help improve data interpretation. Specification of units **SHOULD** follow the International System of Units (see BIDS specification).
163
167
164
-
For multi-echo data, a given `physio.tsv` file is applicable to all echos of
165
-
a particular run.
166
-
For example:
168
+
We are also introducing a `Placement`**RECOMMENDED** metadata, that describes the position of the sensor during data collection. For instance, a file could have three columns of ventilation data, one collected at the navel, one at the diaphragm, and one at the armpit level, in which case `Placement` values would be “Navel”, “Diaphragm”, and “Armpit” respectively. In case the data describes gas concentration, such as CO2 or O2, `Placement`**SHOULD** be used to indicate if a “Nose” cannula versus a “Mouth” mouthpiece or a “Mask” was used.
These metadata are meant to describe the nature of the equipment used to record data. Different components from different manufacturers could be used at the same time in a “patchwork” approach in which a sensor or amplifier from manufacturer A is connected to the recording device of manufacturer B, and even the same manufacturer could provide two or more options to measure the same type of data. Many setups that differ in this way introduce a potential difference in data processing (e.g. digital vs analogical lags, delays and sharpness of the recording, quantification, …).
177
+
178
+
Thus, we **RECOMMEND** to increase the granularity of the setup description for each column, and we **RECOMMEND** to report names and manufacturers (when different from the main unit) of sensors, connective elements (e.g. cannulae or cables), and amplifiers. Serial numbers **MAY** be reported as well.
179
+
180
+
In this framework, it is crucial to distinguish between the different fields available for specifying recording equipment in the meta-data: at the top-level, the main recording device and software are characterized in meta-data fields such as `SoftwareModels` and `DeviceSerialNumber`, while at the column-level, information about channel-specific hardware is characterized in meta-data fields such as `ChannelDeviceSerialNumber`.
181
+
182
+
We provide the example shown above to assist in determining the main recording device in common physiological acquisition set-ups. In the example shown above, three different recording systems are being used to concurrently acquire physiological data. The first system acquires two channels of physiological data with software A and main recording device ‘a’, which both would be specified using the top-level fields in the accompanying meta-data. Upstream, hardware such as amplifiers, filters, cables, and sensors would be specified using column-level fields specific to each channel in the accompanying meta-data. In the second system, one channel of physiological data is being acquired by main recording device ‘b’ and wirelessly transmitted to software B. In this case, the sensor attached to device ‘b’ can still be specified using column-level meta-data fields if it is an independent product. In the third system, data is acquired by a physiological monitoring unit which is integrated with an MRI scanner (device ‘c’), which itself acts as the main recording device. In case of using networked middleware systems such as the lab streaming layer, where the data may be centrally recorded, the central recording computer itself **MAY** be considered the main recording device.
183
+
184
+
Finally, the `AmplifierSettings` is a dictionary meant to be filled with potential amplifier settings that can manipulate the data collection at the source, e.g. low-pass filters or DC/AC currents. Because each amplifier and each manufacturer have different settings, we cannot define further the content of this dictionary, but we suggest using manufacturer specific pairs of keys and values. In this dictionary, we also **SUGGEST** reporting eventual data transformations (e.g. the exact formula used to transform gas pressure from measured Voltage to millimetres of Mercury).
185
+
186
+
More information about the metadata entities contained in the JSON files can be found in the tables below.
187
+
188
+
---
189
+
190
+
### 2.1 Metadata fields used in top level metadata
191
+
192
+
We highlight in *italics* the changes from the current specification.
0 commit comments