From 93c628344b1d5d081733c9b869aa510e33327066 Mon Sep 17 00:00:00 2001
From: m-miedema <39968233+m-miedema@users.noreply.github.com>
Date: Thu, 17 Jul 2025 09:19:44 -0400
Subject: [PATCH 01/20] Update datatypes.yaml

I'm not sure if a corresponding change should be made to modalities.yaml, I'm having trouble finding where the latter table is used by the compiler macros.
---
 src/schema/objects/datatypes.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/schema/objects/datatypes.yaml b/src/schema/objects/datatypes.yaml
index b3fdc455e3..115e143a96 100644
--- a/src/schema/objects/datatypes.yaml
+++ b/src/schema/objects/datatypes.yaml
@@ -72,6 +72,11 @@ phenotype:
     Participant level measurement data
     (for example, responses from multiple questionnaires)
     split into individual files separate from `participants.tsv`.
+physio:
+  value: physio
+  display_name: Physiological Data
+  description: |
+    Continuous peripheral physiological recordings such as respiratory, cardiac, pulse, gastric fluctuations, skin conductance, or blood pressure changes.
 nirs:
   value: nirs
   display_name: Near-Infrared Spectroscopy

From e731d9f4aace6888f5e8837fbc14b6afb1c22041 Mon Sep 17 00:00:00 2001
From: m-miedema <39968233+m-miedema@users.noreply.github.com>
Date: Wed, 13 Aug 2025 14:58:09 -0400
Subject: [PATCH 02/20] Migrate new/updated metadata fields relevant for raw
 data

Some checks on formatting (particularly for how I entered the allowable values) might be necessary here, I also added some comments on the BEP document to flag potential issues or changes we could make going forward.
---
 src/schema/objects/metadata.yaml | 119 +++++++++++++++++++++++++++++--
 1 file changed, 115 insertions(+), 4 deletions(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index f7bdc4defa..7e8845fa49 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -51,6 +51,13 @@ AcquisitionMode:
   description: |
     Type of acquisition of the PET data (for example, `"list mode"`).
   type: string
+AcquisitionObservations:
+  name: AcquisitionObservations
+  display_name: Acquisition Observations
+  description: |
+    General observations during the acquisition that might alter physiological fluctuations, 
+    their recording, or their QC/QA (e.g. subject moves hands often, or does not comply with instructions).
+  type: string
 AcquisitionVoxelSize:
   name: AcquisitionVoxelSize
   display_name: Acquisition Voxel Size
@@ -68,6 +75,13 @@ AcquisitionVoxelSize:
     type: number
     exclusiveMinimum: 0
     unit: mm
+AmplifierSettings:
+  name: AmplifierSettings
+  display_name: AmplifierSettings
+  description: |
+    Amplifier settings during data acquisition (e.g. gain, sampling filters, bandwidth, etc.)
+    Strings MAY be represented in the format Setting:Value  (e.g. Gain:10)
+  type: array of strings
 Anaesthesia:
   name: Anaesthesia
   display_name: Anaesthesia
@@ -499,6 +513,36 @@ CellType:
     Values SHOULD come from the
     [cell ontology](https://obofoundry.org/ontology/cl.html).
   type: string
+ChannelDeviceSerialNumber:
+  name: ChannelDeviceSerialNumber
+  display_name: Channel Device Serial Number
+  description: |
+    The serial number(s) of each piece of hardware equipment that 
+    produced the measurements, including the sensor, connecting cables, 
+    and amplifiers. Equipment should be listed in order of attachment, 
+    from participant to recording device. A pseudonym can also be used to 
+    prevent the equipment from being identifiable, so long as each 
+    pseudonym is unique within the dataset.
+  type: string or array of strings
+ChannelManufacturer:
+  name: ChannelManufacturer
+  display_name: Channel Manufacturer
+  description: |
+    Manufacturer(s) of each piece of the equipment that 
+    produced the measurements upstream of the recording device, including 
+    the sensor, connecting cables, and amplifiers. If more than one manufacturer 
+    applies, list the manufacturer for each piece of hardware, in order 
+    of attachment from participant to recording device.
+  type: string or array of strings
+ChannelManufacturersModelName:
+  name: ChannelManufacturersModelName
+  display_name: Channel Manufacturers Model Name
+  description: |
+    Manufacturer's model name(s) of each piece of hardware equipment that 
+    produced the measurements upstream of the recording device, including 
+    the sensor, connecting cables, and amplifiers. Equipment should be listed 
+    in order of attachment, from participant to recording device.
+  type: string or array of strings
 ChemicalShiftOffset:
   name: ChemicalShiftOffset
   display_name: Chemical Shift Offset
@@ -642,6 +686,14 @@ Columns:
   type: array
   items:
     type: string
+ConcurrenceGroup:
+  name: ConcurrenceGroup
+  display_name: ConcurrenceGroup
+  description: |
+    An identifier shared by files recorded concurrently.
+    Each "ConcurrenceGroup" MUST be a unique string within one participant's tree,
+    shared only by the continuously recorded data which was measured simultaneously.
+  type: string
 Container:
   name: Container
   display_name: Container
@@ -927,7 +979,8 @@ DeviceSerialNumber:
   name: DeviceSerialNumber
   display_name: Device Serial Number
   description: |
-    The serial number of the equipment that produced the measurements.
+    The serial number of the equipment that recorded the measurements:
+    that is, the main recording device.
     A pseudonym can also be used to prevent the equipment from being
     identifiable, so long as each pseudonym is unique within the dataset.
   type: string
@@ -2498,13 +2551,13 @@ Manufacturer:
   name: Manufacturer
   display_name: Manufacturer
   description: |
-    Manufacturer of the equipment that produced the measurements.
+    Manufacturer of the main equipment that recorded the measurements.
   type: string
 ManufacturersModelName:
   name: ManufacturersModelName
   display_name: Manufacturers Model Name
   description: |
-    Manufacturer's model name of the equipment that produced the measurements.
+    Manufacturer's model name of the main equipment that recorded the measurements.
   type: string
 MatrixCoilMode:
   name: MatrixCoilMode
@@ -2564,6 +2617,26 @@ MeasurementToolMetadata:
       $ref: objects.metadata.TermURL
     Description:
       $ref: objects.metadata.Description
+MeasureType:
+  name: MeasureType
+  display_name: Measure Type
+  description: |
+    Describes the category of physiological data which was recorded.
+  type: string
+  enum:
+  - Trigger,
+  - PPG
+  - ECG
+  - Ventilation
+  - CO2
+  - O2
+  - PetCO2
+  - PetO2
+  - EDA-tonic
+  - EDA-phasic
+  - EDA-total
+  - BP
+  - Other
 MetaboliteAvail:
   name: MetaboliteAvail
   display_name: Metabolite Available
@@ -3037,6 +3110,7 @@ PhysioType:
   type: string
   enum:
     - $ref: objects.enums.PhysioTypeGeneric.value
+    - $ref: objects.enums.PhysioTypeSpecified.value
     - $ref: objects.enums.PhysioTypeEyetrack.value
 PixelSize:
   name: PixelSize
@@ -3067,6 +3141,13 @@ PixelSizeUnits:
     - mm
     - um
     - nm
+Placement:
+  name: Placement
+  display_name: Placement
+  description: |
+    Placement of sensor on the measurement subject. 
+    Non-physiological and trigger columns must have “n/a”.
+  type: string
 PlasmaAvail:
   name: PlasmaAvail
   display_name: Plasma Avail
@@ -3936,6 +4017,12 @@ SoftwareFilters:
     - type: string
       enum:
         - n/a
+SoftwareModels:
+  name: SoftwareModels
+  display_name: Software Models
+  description: |
+    Name of the software which recorded the measurements.
+  type: string
 SoftwareName:
   name: SoftwareName
   display_name: Software Name
@@ -4165,9 +4252,12 @@ StartTime:
   display_name: Start Time
   description: |
     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).
+    data sample in a reference file sharing the same "ConcurrenceGroup" identifier 
+    (negative values are allowed). Within each set of “ConcurrenceGroup” files, 
+    a reference file MUST be designated with a “StartTime” equaling 0.
     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.
+    If no ConcurrenceGroup identifier is defined, the StartTime should be set to 0.
   type: number
   unit: s
 StationName:
@@ -4225,6 +4315,27 @@ SubjectArtefactDescription:
     If this field is set to `"n/a"`, it will be interpreted as absence of major
     source of artifacts except cardiac and blinks.
   type: string
+SubjectArtefactDescription:
+  name: SubjectArtefactDescription
+  display_name: Subject Artifact Description
+  description: |
+    Freeform description of the observed subject artifact and its possible cause
+    (for example, `"Vagus Nerve Stimulator"`, `"non-removable implant"`).
+    If this field is set to `"n/a"`, it will be interpreted as absence of major
+    source of artifacts except cardiac and blinks.
+  type: string
+SubjectPosition:
+  name: SubjectPosition
+  display_name: Subject Position
+  description: |
+    Position of the subject during data acquisition.
+  type: string
+  enum:
+  - prone
+  - supine
+  - standing
+  - sitting
+  - reclined
 TablePosition:
   name: TablePosition
   display_name: Table Position

From 75c921b9f9fd3f25a9bf6fdaf5de8f7aa5276e6a Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Fri, 18 Jul 2025 15:35:28 -0400
Subject: [PATCH 03/20] Incorporate physio BEP section 4

---
 .../physiological-recordings.md               | 170 ++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 6d6adc41c6..4ccc7c1e85 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -732,3 +732,173 @@ would read:
     }
 }
 ```
+) }}
+
+## Raw Physiological Data
+
+### 1. File formats and directory structure
+
+#### 1.1 General principles
+
+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).
+
+An example of the physio directory structure is shown below:
+
+```
+dataset/
+[...]
+sub-<label>/[ses-<label>/]
+physio/
+sub-<label>[_ses-<label>]_task-<label>_[recording-<label>]_physio.json
+sub-<label>[_ses-<label>]_task-<label>_[recording-<label>]_physio.tsv.gz
+
+dataset/
+[...]
+sub-<label>/[ses-<label>/]
+func/
+   [...]
+<matches>_[recording-<label>]_physio.json
+<matches>_[recording-<label>]_physio.tsv.gz
+```
+
+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.
+
+#### 1.2 Splitting concurrently acquired data into multiple files
+
+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.
+
+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.
+
+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).
+
+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.
+
+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).
+
+**For example:**
+
+**Splitting recorded data into separate physio data files**
+```
+dataset/
+[...]
+sub-<label>/[ses-<label>/]
+physio/
+sub-001_ses-01_recording-scr_physio.json
+sub-001_ses-01_recording-scr_physio.tsv.gz
+sub-001_ses-01_recording-ecg_physio.json
+sub-001_ses-01_recording-ecg_physio.tsv.gz
+sub-001_ses-01_recording-resp_physio.json
+sub-001_ses-01_recording-resp_physio.tsv.gz
+```
+
+**Combining recorded data into one pair of physio data files**
+```
+dataset/
+[...]
+sub-<label>/[ses-<label>/]
+physio/
+sub-001_ses-01_physio.json
+sub-001_ses-01_physio.tsv.gz
+```
+
+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.
+
+---
+
+### 2. JSON Data files
+
+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.
+
+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.
+
+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).
+
+When specifying column names, columns **MUST** have unique names. All such data columns **MUST** be appropriately defined in the JSON metadata.
+
+**Example:**
+
+```json
+{
+  "Columns": ["screda1", "screda2", "ecg", "ppg"],
+  "SamplingFrequency": 1000,
+  "SubjectPosition": "sitting",
+  "PhysioType": "specified",
+  ...
+  "screda1": {
+    "MeasureType": "EDA-phasic",
+    "Units": "mS",
+    "Placement": "Thenar",
+    ...
+  },
+  "screda2": {
+    "MeasureType": "EDA-tonic",
+    "Units": "mS",
+    "Placement": "Hypothenar",
+    ...
+  },
+  "ecg": {
+    "MeasureType": "ECG",
+    "Units": "mV",
+    "Placement": "II",
+    ...
+  },
+  "ppg": {
+    "MeasureType": "PPG",
+    "Units": "au",
+    "Placement": "Right earlobe",
+    ...
+  },
+  ...
+}
+```
+
+As described in the following table (Section 2.2), this BEP is adding a few metadata to describe columns.
+
+- The most important one is `MeasureType`, a **RECOMMENDED** metadata that indicates the actual nature of the data in the column. 
+    - This metadata value is a string that **MUST** come from a set of keywords (see table 2.2).
+    - This set of keywords can be expanded in the future to include more physiological modalities. 
+    - When the file-level metadata `PhysioType` is `"specified"`, `MeasureType` becomes a **REQUIRED** field for each column.
+
+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.
+
+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).
+
+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.
+
+The three metadata at this level describing hardware are:
+
+- `ChannelManufacturersModelName` (**RECOMMENDED**)
+- `ChannelManufacturers` (**RECOMMENDED**)
+- `ChannelDeviceSerialNumber` (**OPTIONAL**)
+
+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, …).
+
+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.
+
+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`.
+
+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.
+
+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).
+
+More information about the metadata entities contained in the JSON files can be found in the tables below.
+
+---
+
+### 2.1 Metadata fields used in top level metadata 
+
+We highlight in *italics* the changes from the current specification.
+| Key name | Requirement level | Data type | Description |
+|----------|----------|----------|----------|
+| Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
+| Row 2-A  | Row 2-B  | Row 2-C  | Row 2-D  |
+| Row 3-A  | Row 3-B  | Row 3-C  | Row 3-D  |
+
+### 2.2 Metadata fields for column description
+| Key name | Requirement level | Data type | Description |
+|----------|----------|----------|----------|
+| Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
+| Row 2-A  | Row 2-B  | Row 2-C  | Row 2-D  |
+| Row 3-A  | Row 3-B  | Row 3-C  | Row 3-D  |
+
+---

From 45051d60d117ec5466a4483e2c1e7afffb8411bf Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Fri, 18 Jul 2025 17:07:58 -0400
Subject: [PATCH 04/20] Update macros

---
 .../physiological-recordings.md                        | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 4ccc7c1e85..95443f02c3 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -743,7 +743,7 @@ would read:
 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).
 
 An example of the physio directory structure is shown below:
-
+{{ MACROS___make_filename_template()}}
 ```
 dataset/
 [...]
@@ -778,6 +778,7 @@ We **RECOMMEND** to store trigger signals recorded alongside physiological chann
 **For example:**
 
 **Splitting recorded data into separate physio data files**
+{{ MACROS___make_filetree_example() }}
 ```
 dataset/
 [...]
@@ -792,6 +793,7 @@ sub-001_ses-01_recording-resp_physio.tsv.gz
 ```
 
 **Combining recorded data into one pair of physio data files**
+{{ MACROS___make_filetree_example() }}
 ```
 dataset/
 [...]
@@ -888,17 +890,15 @@ More information about the metadata entities contained in the JSON files can be
 ### 2.1 Metadata fields used in top level metadata 
 
 We highlight in *italics* the changes from the current specification.
+{{ MACROS___make_sidecar_table(["continuous.Continuous"]) }}
 | Key name | Requirement level | Data type | Description |
 |----------|----------|----------|----------|
 | Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
-| Row 2-A  | Row 2-B  | Row 2-C  | Row 2-D  |
-| Row 3-A  | Row 3-B  | Row 3-C  | Row 3-D  |
 
 ### 2.2 Metadata fields for column description
+{{ MACROS___make_columns_table("physio.PhysioColumns") }}
 | Key name | Requirement level | Data type | Description |
 |----------|----------|----------|----------|
 | Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
-| Row 2-A  | Row 2-B  | Row 2-C  | Row 2-D  |
-| Row 3-A  | Row 3-B  | Row 3-C  | Row 3-D  |
 
 ---

From b5453d9e3b84d4f61fbfdb67fafde9d1bcfe052c Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Fri, 18 Jul 2025 17:08:38 -0400
Subject: [PATCH 05/20] Update physiological-recordings.md

---
 src/modality-specific-files/physiological-recordings.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 95443f02c3..091cd929c3 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -743,6 +743,7 @@ would read:
 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).
 
 An example of the physio directory structure is shown below:
+
 {{ MACROS___make_filename_template()}}
 ```
 dataset/

From fcdd6b03b5b53968de9b6419b0d24b52dd2e88a7 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Fri, 18 Jul 2025 17:09:34 -0400
Subject: [PATCH 06/20] Update physiological-recordings.md

---
 src/modality-specific-files/physiological-recordings.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 091cd929c3..fc067455f1 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -779,6 +779,7 @@ We **RECOMMEND** to store trigger signals recorded alongside physiological chann
 **For example:**
 
 **Splitting recorded data into separate physio data files**
+
 {{ MACROS___make_filetree_example() }}
 ```
 dataset/
@@ -794,6 +795,7 @@ sub-001_ses-01_recording-resp_physio.tsv.gz
 ```
 
 **Combining recorded data into one pair of physio data files**
+
 {{ MACROS___make_filetree_example() }}
 ```
 dataset/
@@ -891,12 +893,14 @@ More information about the metadata entities contained in the JSON files can be
 ### 2.1 Metadata fields used in top level metadata 
 
 We highlight in *italics* the changes from the current specification.
+
 {{ MACROS___make_sidecar_table(["continuous.Continuous"]) }}
 | Key name | Requirement level | Data type | Description |
 |----------|----------|----------|----------|
 | Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
 
 ### 2.2 Metadata fields for column description
+
 {{ MACROS___make_columns_table("physio.PhysioColumns") }}
 | Key name | Requirement level | Data type | Description |
 |----------|----------|----------|----------|

From 0b3dd0fb3c230f998d53deca15eac9040b7a7636 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Fri, 18 Jul 2025 17:29:18 -0400
Subject: [PATCH 07/20] Update physiological-recordings.md macros

---
 .../physiological-recordings.md               | 39 +++++++++++++++++--
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index fc067455f1..4b013798a2 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -744,7 +744,14 @@ The file and dataset naming conventions for physiological data follow the common
 
 An example of the physio directory structure is shown below:
 
-{{ MACROS___make_filename_template()}}
+{{ MACROS___make_filename_template(
+       "raw",
+       placeholders=True,
+       show_entities=["recording"],
+       suffixes=["physio"]
+   )
+}}
+
 ```
 dataset/
 [...]
@@ -780,7 +787,22 @@ We **RECOMMEND** to store trigger signals recorded alongside physiological chann
 
 **Splitting recorded data into separate physio data files**
 
-{{ MACROS___make_filetree_example() }}
+{{ MACROS___make_filetree_example(
+   {
+   "sub-001": {
+      "ses-01": {
+         "physio": {
+            "sub-001_ses-01_recording-scr_physio.json": "",
+            "sub-001_ses-01_recording-scr_physio.tsv.gz": "",
+            "sub-001_ses-01_recording-ecg_physio.json": "",
+            "sub-001_ses-01_recording-ecg_physio.tsv.gz": "",
+            "sub-001_ses-01_recording-resp_physio.json": "",
+            "sub-001_ses-01_recording-resp_physio.tsv.gz": ""
+            },
+         },
+      }
+   }
+) }}
 ```
 dataset/
 [...]
@@ -796,7 +818,18 @@ sub-001_ses-01_recording-resp_physio.tsv.gz
 
 **Combining recorded data into one pair of physio data files**
 
-{{ MACROS___make_filetree_example() }}
+{{ MACROS___make_filetree_example(
+   {
+   "sub-001": {
+      "ses-01": {
+         "physio": {
+            "sub-001_ses-01_physio.json": "",
+            "sub-001_ses-01_physio.tsv.gz": ""
+            },
+         },
+      }
+   }
+) }}
 ```
 dataset/
 [...]

From 48f9605542bf051ce1645ed7ce9c1728405ca155 Mon Sep 17 00:00:00 2001
From: m-miedema <39968233+m-miedema@users.noreply.github.com>
Date: Thu, 23 Oct 2025 09:05:18 -0400
Subject: [PATCH 08/20] Addresses #21: adds PhysioTypeEnriched

---
 src/schema/objects/enums.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/schema/objects/enums.yaml b/src/schema/objects/enums.yaml
index be12f2f624..05a976a6a6 100644
--- a/src/schema/objects/enums.yaml
+++ b/src/schema/objects/enums.yaml
@@ -1476,6 +1476,11 @@ PhysioTypeGeneric:
   display_name: Generic Physiological Recording
   description: |
     Unspecified physiological recording.
+PhysioTypeEnriched:
+  value: enriched
+  display_name: Enriched Physiological Recording
+  description: |
+    Physiological recording data accompanied by enriched metadata.
 PhysioTypeEyetrack:
   value: eyetrack
   display_name: Eye-tracking recording

From 71218eb374daf65a153c0d5dbd09426dbb8d8492 Mon Sep 17 00:00:00 2001
From: m-miedema <39968233+m-miedema@users.noreply.github.com>
Date: Thu, 23 Oct 2025 20:38:50 -0400
Subject: [PATCH 09/20] Added MeasureType entries to enums, updated metadata
 accordingly.

---
 src/schema/objects/enums.yaml    | 70 ++++++++++++++++++++++++++++++++
 src/schema/objects/metadata.yaml | 26 ++++++------
 2 files changed, 82 insertions(+), 14 deletions(-)

diff --git a/src/schema/objects/enums.yaml b/src/schema/objects/enums.yaml
index 05a976a6a6..58ab3bb008 100644
--- a/src/schema/objects/enums.yaml
+++ b/src/schema/objects/enums.yaml
@@ -1486,3 +1486,73 @@ PhysioTypeEyetrack:
   display_name: Eye-tracking recording
   description: |
     A specific physiological recording type: eye-tracking.
+PPG__physio:
+  value: PPG
+  display_name: Photoplethysmography (PPG)
+  tags:
+    - physio
+  description: |
+    Continuous optical measurements capturing cardiac pulsation.
+Trigger:
+  value: Trigger
+  display_name: Trigger
+  tags:
+    - physio
+  description: |
+    Continuous digital (binary TTL) or analog (TTL in Volt) values indicating scanner triggers.
+ECG__physio:
+  value: ECG
+  display_name: Electrocardiogram (ECG)
+  tags:
+    - physio
+  description: |
+    Continuous electrical measurements capturing cardiac activity.
+Ventilation:
+  value: Ventilation
+  display_name: Ventilation
+  tags:
+    - physio
+  description: |
+    Continuous breathing measurements, e.g. signal acquired using a respiratory belt.
+CO2:
+  value: CO2
+  display_name: Carbon dioxide (CO2)
+  tags:
+    - physio
+  description: |
+    Continuous measurements of the carbon dioxide concentration in expired air..
+O2:
+  value: O2
+  display_name: Oxygen (O2)
+  tags:
+    - physio
+  description: |
+    Continuous measurements of the oxygen concentration from respiratory gases.
+PETCO2:
+  value: PETCO2
+  display_name: End-tidal carbon dioxide (PETCO2)
+  tags:
+    - physio
+  description: |
+    Continuous measurements of the end-tidal pressure of carbon dioxide at the end of an exhalation.
+PETO2:
+  value: PETO2
+  display_name: End-tidal oxygen (PETO2)
+  tags:
+    - physio
+  description: |
+    Continuous measurements of the end-tidal pressure of oxygen at the end of an inhalation.
+EDA:
+  value: EDA
+  display_name: Electrodermal activity (EDA)
+  tags:
+    - physio
+  description: |
+    Continuous measurements of changes in the electrical properties of the skin.
+BP:
+  value: BP
+  display_name: Blood pressure (BP)
+  tags:
+    - physio
+  description: |
+    Continuous measurements of the blood pressure waveform representing changes in arterial pressure over time.
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 7e8845fa49..7e6d3977a7 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -2624,19 +2624,17 @@ MeasureType:
     Describes the category of physiological data which was recorded.
   type: string
   enum:
-  - Trigger,
-  - PPG
-  - ECG
-  - Ventilation
-  - CO2
-  - O2
-  - PetCO2
-  - PetO2
-  - EDA-tonic
-  - EDA-phasic
-  - EDA-total
-  - BP
-  - Other
+    - $ref: objects.enums.BP.value
+    - $ref: objects.enums.PPG__physio.value
+    - $ref: objects.enums.ECG__physio.value
+    - $ref: objects.enums.Ventilation.value
+    - $ref: objects.enums.EDA.value
+    - $ref: objects.enums.CO2.value
+    - $ref: objects.enums.O2.value
+    - $ref: objects.enums.PETCO2.value
+    - $ref: objects.enums.PETO2.value
+    - $ref: objects.enums.Trigger.value
+    - Other
 MetaboliteAvail:
   name: MetaboliteAvail
   display_name: Metabolite Available
@@ -3110,7 +3108,7 @@ PhysioType:
   type: string
   enum:
     - $ref: objects.enums.PhysioTypeGeneric.value
-    - $ref: objects.enums.PhysioTypeSpecified.value
+    - $ref: objects.enums.PhysioTypeEnhanced.value
     - $ref: objects.enums.PhysioTypeEyetrack.value
 PixelSize:
   name: PixelSize

From 437868fddc14c21d98952fad2e39962a46bcb9fa Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 18 Dec 2025 09:53:13 -0500
Subject: [PATCH 10/20] Update physiological recordings MACROS_filetree

---
 .../physiological-recordings.md               | 73 +++++++++++--------
 1 file changed, 44 insertions(+), 29 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 4b013798a2..7b599dd37f 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -753,20 +753,36 @@ An example of the physio directory structure is shown below:
 }}
 
 ```
-dataset/
-[...]
-sub-<label>/[ses-<label>/]
-physio/
-sub-<label>[_ses-<label>]_task-<label>_[recording-<label>]_physio.json
-sub-<label>[_ses-<label>]_task-<label>_[recording-<label>]_physio.tsv.gz
+{{ MACROS___make_filetree_example(
+{
+"dataset":{
+   "sub-<label>": {
+      "ses-<label>": {
+         "physio": {
+            "sub-<label>[_ses-<label>]_task-<label>_[recording-<label>]_physio.json": "",
+            "sub-<label>[_ses-<label>]_task-<label>_[recording-<label>]_physio.tsv.gz": "",
+            },
+         },
+      }
+   }
+}
+) }}
+
+{{ MACROS___make_filetree_example(
+{
+"dataset":{
+   "sub-<label>": {
+      "ses-<label>": {
+         "func": {
+            "<matches>_[recording-<label>]_physio.json": "",
+            "<matches>_[recording-<label>]_physio.tsv.gz": "",
+            },
+         },
+      }
+   }
+}
+) }}
 
-dataset/
-[...]
-sub-<label>/[ses-<label>/]
-func/
-   [...]
-<matches>_[recording-<label>]_physio.json
-<matches>_[recording-<label>]_physio.tsv.gz
 ```
 
 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.
@@ -831,12 +847,21 @@ sub-001_ses-01_recording-resp_physio.tsv.gz
    }
 ) }}
 ```
-dataset/
-[...]
-sub-<label>/[ses-<label>/]
-physio/
-sub-001_ses-01_physio.json
-sub-001_ses-01_physio.tsv.gz
+{{ MACROS___make_filetree_example(
+{
+"dataset":{
+   "sub-<label>": {
+      "ses-<label>": {
+         "physio": {
+            "sub-001_ses-01_physio.json": "",
+            "sub-001_ses-01_physio.tsv.gz": "",
+            },
+         },
+      }
+   }
+}
+) }}
+
 ```
 
 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.
@@ -925,18 +950,8 @@ More information about the metadata entities contained in the JSON files can be
 
 ### 2.1 Metadata fields used in top level metadata 
 
-We highlight in *italics* the changes from the current specification.
-
 {{ MACROS___make_sidecar_table(["continuous.Continuous"]) }}
-| Key name | Requirement level | Data type | Description |
-|----------|----------|----------|----------|
-| Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
 
 ### 2.2 Metadata fields for column description
 
-{{ MACROS___make_columns_table("physio.PhysioColumns") }}
-| Key name | Requirement level | Data type | Description |
-|----------|----------|----------|----------|
-| Row 1-A  | Row 1-B  | Row 1-C  | Row 1-D  |
-
 ---

From 44468ac09c5fdd8d0b5885207d7e420fe4dd82e3 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 18 Dec 2025 09:54:08 -0500
Subject: [PATCH 11/20] Remove repetitive examples

Removed example file structure for physiological recordings.
---
 .../physiological-recordings.md                      | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 7b599dd37f..0e9683fccc 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -819,18 +819,6 @@ We **RECOMMEND** to store trigger signals recorded alongside physiological chann
       }
    }
 ) }}
-```
-dataset/
-[...]
-sub-<label>/[ses-<label>/]
-physio/
-sub-001_ses-01_recording-scr_physio.json
-sub-001_ses-01_recording-scr_physio.tsv.gz
-sub-001_ses-01_recording-ecg_physio.json
-sub-001_ses-01_recording-ecg_physio.tsv.gz
-sub-001_ses-01_recording-resp_physio.json
-sub-001_ses-01_recording-resp_physio.tsv.gz
-```
 
 **Combining recorded data into one pair of physio data files**
 

From a15b4097dd3de08d8574459dc8b38c02d49eec2d Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 18 Dec 2025 09:55:47 -0500
Subject: [PATCH 12/20] Add columns table for physiological recordings metadata

---
 src/modality-specific-files/physiological-recordings.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 0e9683fccc..05dbda26f7 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -942,4 +942,6 @@ More information about the metadata entities contained in the JSON files can be
 
 ### 2.2 Metadata fields for column description
 
+{{ MACROS___make_columns_table("physio.PhysioColumns") }}
+
 ---

From 77c4bb97888a9714bc72db99fb847684e250f124 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 18 Dec 2025 11:11:33 -0500
Subject: [PATCH 13/20] Add MeasureType descriptions section

Add MeasureType descriptions section to documentation
---
 src/modality-specific-files/physiological-recordings.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 05dbda26f7..2135500148 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -944,4 +944,6 @@ More information about the metadata entities contained in the JSON files can be
 
 {{ MACROS___make_columns_table("physio.PhysioColumns") }}
 
+### 2.3 MeasureType descriptions
+
 ---

From abd5c1ec805796235e34b0e560474dd8a4ed3fa5 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 18 Dec 2025 11:25:15 -0500
Subject: [PATCH 14/20] Update physiological recordings documentation

Removed unnecessary code blocks and clarified recommendations for recording physiological data.
---
 src/modality-specific-files/physiological-recordings.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 2135500148..862b6ae42b 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -752,7 +752,6 @@ An example of the physio directory structure is shown below:
    )
 }}
 
-```
 {{ MACROS___make_filetree_example(
 {
 "dataset":{
@@ -783,8 +782,6 @@ An example of the physio directory structure is shown below:
 }
 ) }}
 
-```
-
 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.
 
 #### 1.2 Splitting concurrently acquired data into multiple files
@@ -834,7 +831,7 @@ We **RECOMMEND** to store trigger signals recorded alongside physiological chann
       }
    }
 ) }}
-```
+
 {{ MACROS___make_filetree_example(
 {
 "dataset":{
@@ -850,8 +847,6 @@ We **RECOMMEND** to store trigger signals recorded alongside physiological chann
 }
 ) }}
 
-```
-
 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.
 
 ---

From 5245c71b6755985ad3cff4ff9e9d4f7a2d5dd420 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 18 Dec 2025 11:32:10 -0500
Subject: [PATCH 15/20] Add MeasureType descriptions table

Added descriptions for various MeasureTypes related to physiological recordings.
---
 .../physiological-recordings.md                 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 862b6ae42b..a0cfeec170 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -941,4 +941,21 @@ More information about the metadata entities contained in the JSON files can be
 
 ### 2.3 MeasureType descriptions
 
+| **MeasureType** | **Name** | **Description** |
+|-----------------|----------|-----------------|
+| Trigger | Trigger | Digital (binary TTL) or analog (TTL in Volt) values indicating scanner triggers. |
+| PPG | Photoplethysmography | Continuous optical signal capturing the cardiac pulsation. |
+| ECG | Electrocardiography | Continuous electrical signal capturing the cardiac activity. |
+| Ventilation | Ventilation | Continuous breathing measurement. |
+| CO2 | Carbon dioxide | Continuous measurement of the carbon dioxide concentration in expired air. |
+| O2 | Oxygen | Continuous measurement of the oxygen concentration from respiratory gases. |
+| PetCO2 | End-tidal carbon dioxide | Continuous measurement of the end-tidal pressure of carbon dioxide at the end of an exhalation. |
+| PetO2 | End-tidal oxygen | Continuous measurement of the end-tidal pressure of oxygen at the end of an inhalation. |
+| EDA-tonic | Electrodermal activity, tonic component | Continuous measurement of low-frequency changes in electrodermal activity, also known as skin conductance level. |
+| EDA-phasic | Electrodermal activity, phasic component | Continuous measurement of high-frequency changes in electrodermal activity, also known as skin conductance response. |
+| EDA-total | Electrodermal activity | Continuous measurement of the changes in electrical properties of the skin. |
+| BP | Blood pressure | Continuous measurement of the blood pressure waveform representing the changes in arterial pressure over time. |
+| Other | Other | Any other type of channel. |
+
+
 ---

From 522d56d54a4bd6a2cd6889969e3dc7cbe1b2be57 Mon Sep 17 00:00:00 2001
From: m-miedema <39968233+m-miedema@users.noreply.github.com>
Date: Wed, 13 Aug 2025 14:58:09 -0400
Subject: [PATCH 16/20] Migrate new/updated metadata fields relevant for raw
 data

Some checks on formatting (particularly for how I entered the allowable values) might be necessary here, I also added some comments on the BEP document to flag potential issues or changes we could make going forward.
---
 src/schema/objects/metadata.yaml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 7e6d3977a7..937ead100e 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -732,6 +732,14 @@ ContainerURI:
     URI for software container image used to produce the dataset
   type: string
   format: uri
+ConcurrenceGroup:
+  name: ConcurrenceGroup
+  display_name: ConcurrenceGroup
+  description: |
+    An identifier shared by files recorded concurrently.
+    Each "ConcurrenceGroup" MUST be a unique string within one participant's tree,
+    shared only by the continuously recorded data which was measured simultaneously.
+  type: string
 ContinuousHeadLocalization:
   name: ContinuousHeadLocalization
   display_name: Continuous Head Localization
@@ -3108,8 +3116,8 @@ PhysioType:
   type: string
   enum:
     - $ref: objects.enums.PhysioTypeGeneric.value
-    - $ref: objects.enums.PhysioTypeEnhanced.value
     - $ref: objects.enums.PhysioTypeEyetrack.value
+    - $ref: objects.enums.PhysioTypeEnriched.value
 PixelSize:
   name: PixelSize
   display_name: Pixel Size

From 7e504f1dc252d5b9af12bdf12aba33cf202c63e6 Mon Sep 17 00:00:00 2001
From: m-miedema <39968233+m-miedema@users.noreply.github.com>
Date: Thu, 23 Oct 2025 09:05:18 -0400
Subject: [PATCH 17/20] Addresses #21: adds PhysioTypeEnriched

---
 src/schema/objects/enums.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/schema/objects/enums.yaml b/src/schema/objects/enums.yaml
index 58ab3bb008..2ef05cfef6 100644
--- a/src/schema/objects/enums.yaml
+++ b/src/schema/objects/enums.yaml
@@ -1476,16 +1476,16 @@ PhysioTypeGeneric:
   display_name: Generic Physiological Recording
   description: |
     Unspecified physiological recording.
-PhysioTypeEnriched:
-  value: enriched
-  display_name: Enriched Physiological Recording
-  description: |
-    Physiological recording data accompanied by enriched metadata.
 PhysioTypeEyetrack:
   value: eyetrack
   display_name: Eye-tracking recording
   description: |
     A specific physiological recording type: eye-tracking.
+PhysioTypeEnriched:
+  value: enriched
+  display_name: Enriched Physiological Recording
+  description: |
+    Physiological recording data accompanied by enriched metadata.
 PPG__physio:
   value: PPG
   display_name: Photoplethysmography (PPG)

From 1d669ad3320bf1a8b75b01f3abf2a60d987dce7b Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia.research@gmail.com>
Date: Thu, 26 Feb 2026 11:55:41 -0500
Subject: [PATCH 18/20] Update recommendations for physiological recordings

Clarified recommendations for file separation based on recording devices and metadata. Emphasized the importance of interpreting metadata correctly.
---
 .../physiological-recordings.md               | 76 +++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index a0cfeec170..36190b3213 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -72,11 +72,87 @@ electrocardiogram, respiratory movement measured with a respiration belt,
 gas concentration, or eye-tracking, MUST use `_physio.<tsv.gz|json>` pairs.
 
 ### Storing different recordings
+
+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.
+
+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 [its specification](#eye-tracking).
+
+We **RECOMMEND** keeping different files from different recording
+devices separate, but for easier inspection and analysis they can kept 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).
+
+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).
+
 The [`recording-<label>`](../appendices/entities.md#recording)
 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>`](../appendices/entities.md#recording) entities.
+
+<!-- #!# There is a mention of `MeasurementType` that may be wrong --> 
+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.
+
+
+<!-- #!# Conflict here -->
+**For example:**
+
+**Splitting recorded data into separate physio data files**
+
+{{ MACROS___make_filetree_example(
+   {
+   "sub-001": {
+      "ses-01": {
+         "physio": {
+            "sub-001_ses-01_recording-scr_physio.json": "",
+            "sub-001_ses-01_recording-scr_physio.tsv.gz": "",
+            "sub-001_ses-01_recording-ecg_physio.json": "",
+            "sub-001_ses-01_recording-ecg_physio.tsv.gz": "",
+            "sub-001_ses-01_recording-resp_physio.json": "",
+            "sub-001_ses-01_recording-resp_physio.tsv.gz": ""
+            },
+         },
+      }
+   }
+) }}
+
+**Combining recorded data into one pair of physio data files**
+
+{{ MACROS___make_filetree_example(
+   {
+   "sub-001": {
+      "ses-01": {
+         "physio": {
+            "sub-001_ses-01_physio.json": "",
+            "sub-001_ses-01_physio.tsv.gz": ""
+            },
+         },
+      }
+   }
+) }}
+
+{{ MACROS___make_filetree_example(
+{
+"dataset":{
+   "sub-<label>": {
+      "ses-<label>": {
+         "physio": {
+            "sub-001_ses-01_physio.json": "",
+            "sub-001_ses-01_physio.tsv.gz": "",
+            },
+         },
+      }
+   }
+}
+) }}
+
+
 For example, given a BOLD acquisition of a breath-holding task (`task-bht`)
 for which pulse and respiratory movement were sampled at different frequencies,
 recordings are separated as follows:

From 8388f011050c39fb2f35e80782ea3acb91b8a0a8 Mon Sep 17 00:00:00 2001
From: Marie-Eve Picard <marie-eve.picard.2@umontreal.ca>
Date: Wed, 25 Mar 2026 13:53:36 -0400
Subject: [PATCH 19/20] Change specified to enriched

---
 .../physiological-recordings.md               | 115 ++++++++++++++++++
 1 file changed, 115 insertions(+)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 36190b3213..167bca9209 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -505,6 +505,121 @@ the `OnsetSource` is set to `"n/a"` in `sub-01_task-nback_physioevents.json`:
 
 ## Specific physiological signal types
 
+### Enriched physiological metadata
+
+
+<!-- #!# This needs to be fixed -->
+
+### 2. JSON Data files
+
+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.
+
+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 `"enriched"` `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.
+
+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).
+
+When specifying column names, columns **MUST** have unique names. All such data columns **MUST** be appropriately defined in the JSON metadata.
+
+**Example:**
+
+```json
+{
+  "Columns": ["screda1", "screda2", "ecg", "ppg"],
+  "SamplingFrequency": 1000,
+  "SubjectPosition": "sitting",
+  "PhysioType": "enriched",
+  ...
+  "screda1": {
+    "MeasureType": "EDA-phasic",
+    "Units": "mS",
+    "Placement": "Thenar",
+    ...
+  },
+  "screda2": {
+    "MeasureType": "EDA-tonic",
+    "Units": "mS",
+    "Placement": "Hypothenar",
+    ...
+  },
+  "ecg": {
+    "MeasureType": "ECG",
+    "Units": "mV",
+    "Placement": "II",
+    ...
+  },
+  "ppg": {
+    "MeasureType": "PPG",
+    "Units": "au",
+    "Placement": "Right earlobe",
+    ...
+  },
+  ...
+}
+```
+
+As described in the following table (Section 2.2), this BEP is adding a few metadata to describe columns.
+
+- The most important one is `MeasureType`, a **RECOMMENDED** metadata that indicates the actual nature of the data in the column. 
+    - This metadata value is a string that **MUST** come from a set of keywords (see table 2.2).
+    - This set of keywords can be expanded in the future to include more physiological modalities. 
+    - When the file-level metadata `PhysioType` is `"enriched"`, `MeasureType` becomes a **REQUIRED** field for each column.
+
+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.
+
+Furthermore, we are proposing that `Units` becomes a **REQUIRED** metadata when `PhysioType` is `"enriched"`. 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).
+
+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.
+
+The three metadata at this level describing hardware are:
+
+- `ChannelManufacturersModelName` (**RECOMMENDED**)
+- `ChannelManufacturers` (**RECOMMENDED**)
+- `ChannelDeviceSerialNumber` (**OPTIONAL**)
+
+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, …).
+
+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.
+
+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`.
+
+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.
+
+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).
+
+More information about the metadata entities contained in the JSON files can be found in the tables below.
+
+---
+
+### 2.1 Metadata fields used in top level metadata 
+
+{{ MACROS___make_sidecar_table(["continuous.Continuous"]) }}
+
+### 2.2 Metadata fields for column description
+
+{{ MACROS___make_columns_table("physio.PhysioColumns") }}
+
+### 2.3 MeasureType descriptions
+
+| **MeasureType** | **Name** | **Description** |
+|-----------------|----------|-----------------|
+| Trigger | Trigger | Digital (binary TTL) or analog (TTL in Volt) values indicating scanner triggers. |
+| PPG | Photoplethysmography | Continuous optical signal capturing the cardiac pulsation. |
+| ECG | Electrocardiography | Continuous electrical signal capturing the cardiac activity. |
+| Ventilation | Ventilation | Continuous breathing measurement. |
+| CO2 | Carbon dioxide | Continuous measurement of the carbon dioxide concentration in expired air. |
+| O2 | Oxygen | Continuous measurement of the oxygen concentration from respiratory gases. |
+| PetCO2 | End-tidal carbon dioxide | Continuous measurement of the end-tidal pressure of carbon dioxide at the end of an exhalation. |
+| PetO2 | End-tidal oxygen | Continuous measurement of the end-tidal pressure of oxygen at the end of an inhalation. |
+| EDA-tonic | Electrodermal activity, tonic component | Continuous measurement of low-frequency changes in electrodermal activity, also known as skin conductance level. |
+| EDA-phasic | Electrodermal activity, phasic component | Continuous measurement of high-frequency changes in electrodermal activity, also known as skin conductance response. |
+| EDA-total | Electrodermal activity | Continuous measurement of the changes in electrical properties of the skin. |
+| BP | Blood pressure | Continuous measurement of the blood pressure waveform representing the changes in arterial pressure over time. |
+| Other | Other | Any other type of channel. |
+
+
+
+
+
 ### Eye-tracking
 
 <!--

From fc186dd76b2b2de1408e15124b3dad7b57bb4688 Mon Sep 17 00:00:00 2001
From: ShiyuBelleWang <120072352+ShiyuBelleWang@users.noreply.github.com>
Date: Thu, 26 Mar 2026 02:40:43 -0500
Subject: [PATCH 20/20] Reformat & remove redundancy

Updated headings and removed redundant description of "generic" Physiotype
---
 .../physiological-recordings.md               | 28 ++++++-------------
 1 file changed, 9 insertions(+), 19 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 167bca9209..5b1a25e8c8 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -371,7 +371,7 @@ A guide for using macros can be found at
   },
 }) }}
 
-## Physiology "events"
+### Physiology "events"
 
 Discontinuous data associated with continuous recordings
 stored in `<matches>_physio.tsv.gz` files MAY be specified
@@ -510,13 +510,9 @@ the `OnsetSource` is set to `"n/a"` in `sub-01_task-nback_physioevents.json`:
 
 <!-- #!# This needs to be fixed -->
 
-### 2. JSON Data files
-
-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.
+**JSON Data files**. 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 `"enriched"` `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.
 
-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 `"enriched"` `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.
-
-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).
+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 below "Metadata fields used in top level metadata").
 
 When specifying column names, columns **MUST** have unique names. All such data columns **MUST** be appropriately defined in the JSON metadata.
 
@@ -528,39 +524,33 @@ When specifying column names, columns **MUST** have unique names. All such data
   "SamplingFrequency": 1000,
   "SubjectPosition": "sitting",
   "PhysioType": "enriched",
-  ...
   "screda1": {
     "MeasureType": "EDA-phasic",
     "Units": "mS",
     "Placement": "Thenar",
-    ...
   },
   "screda2": {
     "MeasureType": "EDA-tonic",
     "Units": "mS",
     "Placement": "Hypothenar",
-    ...
   },
   "ecg": {
     "MeasureType": "ECG",
     "Units": "mV",
     "Placement": "II",
-    ...
   },
   "ppg": {
     "MeasureType": "PPG",
     "Units": "au",
     "Placement": "Right earlobe",
-    ...
-  },
-  ...
+  }
 }
 ```
 
-As described in the following table (Section 2.2), this BEP is adding a few metadata to describe columns.
+As described in the table below ("Metadata fields for column description."), this BEP is adding a few metadata to describe columns.
 
 - The most important one is `MeasureType`, a **RECOMMENDED** metadata that indicates the actual nature of the data in the column. 
-    - This metadata value is a string that **MUST** come from a set of keywords (see table 2.2).
+    - This metadata value is a string that **MUST** come from a set of keywords.
     - This set of keywords can be expanded in the future to include more physiological modalities. 
     - When the file-level metadata `PhysioType` is `"enriched"`, `MeasureType` becomes a **REQUIRED** field for each column.
 
@@ -590,15 +580,15 @@ More information about the metadata entities contained in the JSON files can be
 
 ---
 
-### 2.1 Metadata fields used in top level metadata 
+**Metadata fields used in top level metadata.** 
 
 {{ MACROS___make_sidecar_table(["continuous.Continuous"]) }}
 
-### 2.2 Metadata fields for column description
+**Metadata fields for column description.**
 
 {{ MACROS___make_columns_table("physio.PhysioColumns") }}
 
-### 2.3 MeasureType descriptions
+**MeasureType descriptions.**
 
 | **MeasureType** | **Name** | **Description** |
 |-----------------|----------|-----------------|