From 3f9b48571f6efd4333f8c68f7298a07d6801aab0 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Wed, 24 Jun 2020 14:17:58 +0200
Subject: [PATCH 1/4] [FIX] restructure and clarify *_physio/*_stim section

---
 ...logical-and-other-continuous-recordings.md | 110 ++++++++++--------
 1 file changed, 63 insertions(+), 47 deletions(-)

diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index a65172c0ec..155f057918 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -13,11 +13,20 @@ sub-<label>/[ses-<label>/]
 
 Optional: Yes
 
-Where `<matches>` corresponds to task file name without the `_bold.nii[.gz]`
-suffix. For example: `sub-control01_task-nback_run-1`. If the same continuous
-recording has been used for all subjects (for example in the case where they
-all watched the same movie) one file can be used and placed in the root
-directory. For example:`task-movie_stim.tsv.gz`
+In the template file names, the `<matches>` part corresponds to task file name
+without 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`.
+
+The `recording-<label>` entity can 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) SHOULD use the `_physio`
+suffix, and signals related to the stimulus SHOULD use `_stim` suffix.
 
 Physiological recordings such as cardiac and respiratory signals and other
 continuous measures (such as parameters of a film or audio stimuli) can be
@@ -33,45 +42,14 @@ line) and a JSON for storing the following metadata fields:
 Additional metadata may be included as in
 [any TSV file](../02-common-principles.md#tabular-files) to specify, for
 example, the units of the recorded time series.
-Please note that in contrast to other TSV files this one does not include a
-header line. Instead the name of columns are specified in the JSON file.
-This is to improve compatibility with existing software (FSL PNM) as
-well as make support for other file formats possible in the future.
-Recordings with different sampling frequencies and/or starting times should be
-stored in separate files.
-The following naming conventions should be used for column names:
-
-| Column name | Definition                                           |
-| ----------------- | ------------------------------------------------------- |
-| cardiac     | continuous pulse measurement                         |
-| respiratory | continuous breathing measurement                     |
-| trigger     | continuous measurement of the scanner trigger signal |
-
-Any combination of those three can be included as well as any other stimuli
-related continuous variables (such as low level image properties in a video
-watching paradigm).
+Please note that in contrast to other TSV files in BIDS, the TSV files specified
+for phsyiological and other continuous recordings *do not* include a header
+line.
+Instead the name of columns are specified in the JSON file.
+This is to improve compatibility with existing software (e.g., FSL, PNM) as well
+as to make support for other file formats possible in the future.
 
-Physiological recordings (including eye tracking) should use the `_physio`
-suffix, and signals related to the stimulus should use `_stim` suffix. For
-motion parameters acquired from scanner side motion correction please use
-`_physio` suffix.
-
-More than one continuous recording file can be included (with different sampling
-frequencies). In such case use different labels. For example:
-`_recording-contrast`, `_recording-saturation`. The full file name could then
-look like this: `sub-control01_task-nback_run-2_recording-movie_stim.tsv.gz`
-
-For multi-echo data, physio.tsv file is applicable to all echos of particular
-run. For eg:
-
-```Text
-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
-```
-
-Example:
+Example for `*.tsv.gz`:
 
 ```Text
 sub-control01/
@@ -82,11 +60,13 @@ sub-control01/
 (after decompression)
 
 ```Text
-34  110 0
-44  112 0
-23  100 1
+34 110 0
+44 112 0
+23 100 1
 ```
 
+Example for `*.json`:
+
 ```Text
 sub-control01/
     func/
@@ -97,9 +77,45 @@ sub-control01/
 {
    "SamplingFrequency": 100.0,
    "StartTime": -22.345,
-    "Columns": ["cardiac", "respiratory", "trigger"],
+   "Columns": ["cardiac", "respiratory", "trigger"],
    "cardiac": {
        "Units": "mV"
    }
 }
 ```
+
+## Additional rules
+
+To store pulse or breathing measurements, or the scanner trigger signal, the
+following naming conventions SHOULD be used for the column names:
+
+| Column name | Definition                                           |
+| ----------------- | ------------------------------------------------------- |
+| cardiac     | continuous pulse measurement                         |
+| respiratory | continuous breathing measurement                     |
+| trigger     | continuous measurement of the scanner trigger signal |
+
+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 and/or starting times should be
+stored in separate files.
+
+If the same continuous recording has been used for all subjects (for example in
+the case where they all watched the same movie), one file MAY be used and
+placed in the root directory.
+For example:`task-movie_stim.tsv.gz`
+
+For motion parameters acquired from scanner side motion correction, the
+`_physio` suffix SHOULD be used.
+
+For multi-echo data, a given `physio.tsv` file is applicable to all echos of
+a particular run.
+For example:
+
+```Text
+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
+```

From 84140e7aafb1227bb1e431faa3f407234c889716 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Sun, 28 Jun 2020 18:30:31 +0200
Subject: [PATCH 2/4] mixed formatting improvements

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 ...siological-and-other-continuous-recordings.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index 155f057918..b3dbbd5b91 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -14,7 +14,7 @@ sub-<label>/[ses-<label>/]
 Optional: Yes
 
 In the template file names, the `<matches>` part corresponds to task file name
-without the suffix.
+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`.
 
@@ -42,14 +42,14 @@ line) and a JSON for storing the following metadata fields:
 Additional metadata may be included as in
 [any TSV file](../02-common-principles.md#tabular-files) to specify, for
 example, the units of the recorded time series.
-Please note that in contrast to other TSV files in BIDS, the TSV files specified
+Please note that, in contrast to other TSV files in BIDS, the TSV files specified
 for phsyiological and other continuous recordings *do not* include a header
 line.
 Instead the name of columns are specified in the JSON file.
 This is to improve compatibility with existing software (e.g., FSL, PNM) as well
 as to make support for other file formats possible in the future.
 
-Example for `*.tsv.gz`:
+Example `*_physio.tsv.gz`:
 
 ```Text
 sub-control01/
@@ -60,12 +60,12 @@ sub-control01/
 (after decompression)
 
 ```Text
-34 110 0
-44 112 0
-23 100 1
+34    110    0
+44    112    0
+23    100    1
 ```
 
-Example for `*.json`:
+Example `*_physio.json`:
 
 ```Text
 sub-control01/
@@ -104,7 +104,7 @@ stored in separate files.
 If the same continuous recording has been used for all subjects (for example in
 the case where they all watched the same movie), one file MAY be used and
 placed in the root directory.
-For example:`task-movie_stim.tsv.gz`
+For example, `task-movie_stim.tsv.gz`
 
 For motion parameters acquired from scanner side motion correction, the
 `_physio` suffix SHOULD be used.

From 806e1741abb0490d5b174aba8a61797a72442289 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Mon, 29 Jun 2020 11:05:54 +0200
Subject: [PATCH 3/4] improve template and heading

---
 .../06-physiological-and-other-continuous-recordings.md   | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index b3dbbd5b91..0ce0858b14 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -4,7 +4,7 @@ Template:
 
 ```Text
 sub-<label>/[ses-<label>/]
-    func/
+    <datatype>/
         <matches>[_recording-<label>]_physio.tsv.gz
         <matches>[_recording-<label>]_physio.json
         <matches>[_recording-<label>]_stim.tsv.gz
@@ -13,6 +13,10 @@ sub-<label>/[ses-<label>/]
 
 Optional: Yes
 
+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 file names, the `<matches>` part corresponds to task file name
 before the suffix.
 For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
@@ -84,7 +88,7 @@ sub-control01/
 }
 ```
 
-## Additional rules
+## 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:

From 548cf30a3c84f84702b237b64a1c1f4de6f1eac4 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Tue, 30 Jun 2020 09:57:13 +0200
Subject: [PATCH 4/4] Update
 src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md

---
 .../06-physiological-and-other-continuous-recordings.md         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
index 0ce0858b14..feca36787e 100644
--- a/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
+++ b/src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md
@@ -110,7 +110,7 @@ the case where they all watched the same movie), one file MAY be used and
 placed in the root directory.
 For example, `task-movie_stim.tsv.gz`
 
-For motion parameters acquired from scanner side motion correction, the
+For motion parameters acquired from MRI scanner side motion correction, the
 `_physio` suffix SHOULD be used.
 
 For multi-echo data, a given `physio.tsv` file is applicable to all echos of