From c004c7adc17108188404b38815ddba86621a280b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 11:09:39 +0100
Subject: [PATCH] fix: move ``_stim.<ext>`` specification within the task
 events module

Depends-on: #1749.
---
 mkdocs.yml                                    |  4 +-
 src/common-principles.md                      |  5 +-
 ...ordings.md => physiological-recordings.md} | 21 ++---
 src/modality-specific-files/task-events.md    | 90 +++++++++++++++++++
 4 files changed, 101 insertions(+), 19 deletions(-)
 rename src/modality-specific-files/{physiological-and-other-continuous-recordings.md => physiological-recordings.md} (89%)

diff --git a/mkdocs.yml b/mkdocs.yml
index 051aa2aaa6..114e05c135 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -12,7 +12,7 @@ nav:
           - Electroencephalography: modality-specific-files/electroencephalography.md
           - Intracranial Electroencephalography: modality-specific-files/intracranial-electroencephalography.md
           - Task events: modality-specific-files/task-events.md
-          - Physiological and other continuous recordings: modality-specific-files/physiological-and-other-continuous-recordings.md
+          - Physiological recordings: modality-specific-files/physiological-recordings.md
           - Behavioral experiments (with no neural recordings): modality-specific-files/behavioral-experiments.md
           - Genetic Descriptor: modality-specific-files/genetic-descriptor.md
           - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md
@@ -122,7 +122,7 @@ plugins:
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"
         "04-modality-specific-files/04-intracranial-electroencephalography.md": "modality-specific-files/intracranial-electroencephalography.md"
         "04-modality-specific-files/05-task-events.md": "modality-specific-files/task-events.md"
-        "04-modality-specific-files/06-physiological-and-other-continuous-recordings.md": "modality-specific-files/physiological-and-other-continuous-recordings.md"
+        "04-modality-specific-files/06-physiological-and-other-continuous-recordings.md": "modality-specific-files/physiological-recordings.md"
         "04-modality-specific-files/07-behavioral-experiments.md": "modality-specific-files/behavioral-experiments.md"
         "04-modality-specific-files/08-genetic-descriptor.md": "modality-specific-files/genetic-descriptor.md"
         "04-modality-specific-files/09-positron-emission-tomography.md": "modality-specific-files/positron-emission-tomography.md"
diff --git a/src/common-principles.md b/src/common-principles.md
index df007b12d7..2c77af4375 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -434,8 +434,9 @@ Tabular data MUST be saved as tab delimited values (`.tsv`) files, that is, CSV
 files where commas are replaced by tabs. Tabs MUST be true tab characters and
 MUST NOT be a series of space characters. Each TSV file MUST start with a header
 line listing the names of all columns (with the exception of
-[physiological and other continuous recordings](modality-specific-files/physiological-and-other-continuous-recordings.md)
-as well as [motion recording data](modality-specific-files/motion.md)).
+[physiological](modality-specific-files/physiological-recordings.md),
+[stimuli-related](modality-specific-files/task-events.md#continuously-sampled-stimulus-related-signals),
+and [motion recording data](modality-specific-files/motion.md)).
 It is RECOMMENDED that the column names in the header of the TSV file are
 written in [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) with the
 first letter in lower case (for example, `variable_name`, not `Variable_name`).
diff --git a/src/modality-specific-files/physiological-and-other-continuous-recordings.md b/src/modality-specific-files/physiological-recordings.md
similarity index 89%
rename from src/modality-specific-files/physiological-and-other-continuous-recordings.md
rename to src/modality-specific-files/physiological-recordings.md
index f3bc4f27e2..ed2b992d6d 100644
--- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -1,7 +1,6 @@
-# Physiological and other continuous recordings
+# Physiological recordings
 
-Physiological recordings such as cardiac and respiratory signals and other
-continuous measures (such as parameters of a film or audio stimuli) MAY be
+Physiological recordings such as cardiac and respiratory signals MAY be
 specified using a [compressed tabular file](../common-principles.md#compressed-tabular-files)
 ([TSVGZ file](../glossary.md#tsvgz-extensions)) and a corresponding
 JSON file for storing metadata fields (see below).
@@ -22,8 +21,6 @@ sub-<label>/[ses-<label>/]
     <datatype>/
         <matches>[_recording-<label>]_physio.tsv.gz
         <matches>[_recording-<label>]_physio.json
-        <matches>[_recording-<label>]_stim.tsv.gz
-        <matches>[_recording-<label>]_stim.json
 ```
 
 For the template directory name, `<datatype>` can correspond to any data
@@ -37,8 +34,8 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 
 !!! warning "TSVGZ files SHOULD NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))"
 
-    As a result, when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
-    `*_<physio|stim>.json` MUST be supplied as well.
+    As a result, when supplying a `*_physio.tsv.gz` file, an accompanying
+    `*_physio.json` MUST be supplied as well.
 
 The [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish between several recording files.
@@ -47,10 +44,9 @@ 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 (including eyetracking) SHOULD use the `_physio`.
 
-The following table specifies metadata fields for the `*_<physio|stim>.json` file.
+The following table specifies metadata fields for the `*_physio.json` file.
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -158,11 +154,6 @@ stored in separate files
 (and the [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish these 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 MRI scanner side motion correction, the
 `_physio` suffix SHOULD be used.
 
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 0fb6ec2a52..d2375c3f4b 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -309,3 +309,93 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
     "VisionCorrection": "lenses"
 }
 ```
+
+### Continuously-sampled, stimulus-related signals
+
+!!! example "Example datasets"
+
+      At the time of writing, there are no
+      [example datasets](https://bids-standard.github.io/bids-examples/#dataset-index)
+      showcasing stimulus-related signals.
+      However, the following datasets shared on [OpenNeuro](https://openneuro.org)
+      include these type of signals and may be used (with caution, because they are not
+      "official" examples) as a reference when curating a new dataset:
+
+      -   [*Trial timing for multivariate pattern
+          analysis*](https://openneuro.org/datasets/ds000238/versions/00002)
+
+Signals related to stimuli (such as parameters of a film or audio stimuli) that are
+evenly recorded at a constant sampling frequency SHOULD be stored as follows.
+
+Template:
+
+```Text
+sub-<label>/[ses-<label>/]
+    <datatype>/
+        <matches>[_recording-<label>]_stim.tsv.gz
+        <matches>[_recording-<label>]_stim.json
+```
+
+For the template directory name, `<datatype>` can correspond to any data
+recording modality, for example `func`, `anat`, `dwi`, `meg`, `eeg`, `ieeg`,
+or `beh`.
+
+In the template filenames, the `<matches>` part corresponds to task filename
+before the suffix.
+For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
+`<matches>` would correspond to `sub-control01_task-nback_run-1`.
+
+!!! warning "TSVGZ files SHOULD NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))"
+
+    As a result, when supplying a `<matches>[_recording-<label>]_stim.tsv.gz` file,
+    an accompanying `<matches>[_recording-<label>]_stim.json` MUST be supplied as well.
+
+The [`recording-<label>`](../appendices/entities.md#recording)
+entity MAY be used to distinguish between several recording files,
+as prescribed by the specifications for
+[physiological recordings](physiological-recordings.md).
+
+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 placed in the
+root directory (for example, `<root>/task-movie_stim.<tsv.gz|json>`) MAY be used
+and will apply to all `<matches>_task-movie_<matches>_<suffix>.<ext>` files.
+In the following example, the two `task-nback_stim.<json|tsv.gz>` apply
+to all the `task-nback` runs across the two available subjects:
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example({
+  "sub-01": {
+    "func": {
+      "sub-01_task-nback_run-1_bold.nii.gz": "",
+      "sub-01_task-nback_run-2_bold.nii.gz": "",
+    },
+  },
+  "sub-02": {
+    "func": {
+      "sub-02_task-nback_run-1_bold.nii.gz": "",
+      "sub-02_task-nback_run-2_bold.nii.gz": "",
+    },
+  },
+  "task-nback_stim.json": "",
+  "task-nback_stim.tsv.gz": "",
+}) }}
+
+The following table specifies metadata fields for the
+`<matches>[_recording-<label>]_stim.json` file.
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table(["continuous.Continuous"]) }}
+
+Additional metadata may be included as in
+[any TSV file](../common-principles.md#tabular-files) to specify, for
+example, the units of the recorded time series for each column.