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

Depends-on: #1749.
---
 mkdocs.yml                                    |  4 +-
 ...ordings.md => physiological-recordings.md} | 23 ++---
 src/modality-specific-files/task-events.md    | 90 +++++++++++++++++++
 3 files changed, 98 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/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 8ecd00febe..96b53c2453 100644
--- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -1,9 +1,6 @@
-# Physiological and other continuous recordings
+# Physiological 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).
@@ -24,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
@@ -41,8 +36,8 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 
     TSVGZ files MUST 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 `<matches>_physio.tsv.gz` file, an accompanying
+    `<matches>_physio.json` MUST be supplied as well.
 
 The [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish between several recording files.
@@ -51,10 +46,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 tables specify 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
@@ -174,11 +168,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.

From c137ec302e4c3220b3111c916d83850ffe3099ea Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 26 Mar 2024 21:23:23 +0100
Subject: [PATCH 02/16] Apply suggestions from code review

Co-authored-by: Remi Gau <remi_gau@hotmail.com>
---
 src/modality-specific-files/task-events.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index d2375c3f4b..aecb71e389 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -337,8 +337,7 @@ sub-<label>/[ses-<label>/]
 ```
 
 For the template directory name, `<datatype>` can correspond to any data
-recording modality, for example `func`, `anat`, `dwi`, `meg`, `eeg`, `ieeg`,
-or `beh`.
+recording modality.
 
 In the template filenames, the `<matches>` part corresponds to task filename
 before the suffix.

From 1c34a57bbae178f0c52ddef63255a746b3eb7f0b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 27 Mar 2024 11:37:11 +0100
Subject: [PATCH 03/16] Update src/modality-specific-files/task-events.md

---
 src/modality-specific-files/task-events.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index aecb71e389..ef59013200 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -344,8 +344,10 @@ 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))"
+!!! warning "Caution"
 
+    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.
 

From c8bf8ad405f23a5bca276e4672b0439169281cf0 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 27 Mar 2024 11:38:21 +0100
Subject: [PATCH 04/16] Update
 src/modality-specific-files/physiological-recordings.md

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

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 96b53c2453..5034805180 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -32,10 +32,11 @@ 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`.
 
-!!! note "TSVGZ headers are specified in metadata files."
+!!! warning "Caution"
+
+    TSVGZ files MUST NOT include a header line, as established by the
+    [common-principles](../common-principles.md#compressed-tabular-files).
 
-    TSVGZ files MUST NOT include a header line,
-    as established by the [common-principles](../common-principles.md#compressed-tabular-files).
     As a result, when supplying a `<matches>_physio.tsv.gz` file, an accompanying
     `<matches>_physio.json` MUST be supplied as well.
 

From cc6146fd0eced985d37b9c9ff6f615b2188fad24 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 27 Mar 2024 10:38:24 +0000
Subject: [PATCH 05/16] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/modality-specific-files/task-events.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index ef59013200..5bf4c553c9 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -347,7 +347,7 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 !!! warning "Caution"
 
     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.
 

From d40a443e45362421dacb36b4943db27b695b0343 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 27 Mar 2024 14:14:57 +0100
Subject: [PATCH 06/16] enh: improve admonitions

---
 src/modality-specific-files/physiological-recordings.md | 5 ++---
 src/modality-specific-files/task-events.md              | 7 ++++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 5034805180..86412e3ab4 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -34,11 +34,10 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 
 !!! warning "Caution"
 
-    TSVGZ files MUST NOT include a header line, as established by the
+    `<matches>_physio.tsv.gz` files MUST NOT include a header line, as established by the
     [common-principles](../common-principles.md#compressed-tabular-files).
-
     As a result, when supplying a `<matches>_physio.tsv.gz` file, an accompanying
-    `<matches>_physio.json` MUST be supplied as well.
+    `<matches>_physio.json` MUST be present to indicate the column names.
 
 The [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish between several recording files.
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 5bf4c553c9..c152c8d09f 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -346,10 +346,11 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 
 !!! warning "Caution"
 
-    TSVGZ files SHOULD NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))
-
+    `<matches>[_recording-<label>]_stim.tsv.gz` files MUST 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.
+    an accompanying `<matches>[_recording-<label>]_stim.json` MUST be present to indicate
+    the column names.
 
 The [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish between several recording files,

From 82ca7bcdd2723e9183c5c548278a6a43668c0cf2 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 27 Mar 2024 16:26:30 +0100
Subject: [PATCH 07/16] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/modality-specific-files/physiological-recordings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 86412e3ab4..f29eb7ac66 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -46,7 +46,7 @@ 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`.
+Physiological recordings (including eyetracking) SHOULD use the `_physio` suffix.
 
 The following table specifies metadata fields for the `*_physio.json` file.
 

From eccef64a3a11c91d0c8438c903df974669dfe0ca Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 11:12:50 +0200
Subject: [PATCH 08/16] fix: markdown link with linebreak

---
 src/modality-specific-files/task-events.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index c152c8d09f..2406a786b2 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -314,15 +314,13 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
 
 !!! 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.
+      At the time of writing, there are no [example datasets][bids-examples] 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)
+      -   [*Trial timing for multivariate pattern analysis*][ds000238]
 
 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.
@@ -401,3 +399,7 @@ A guide for using macros can be found at
 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.
+
+<!-- Link Definitions -->
+[ds000238]: https://openneuro.org/datasets/ds000238/versions/00002
+[bids-examples]: https://bids-standard.github.io/bids-examples/#dataset-index

From bd5ea171218e5b3da9a558d1085cdfe0c9171070 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 11:13:42 +0200
Subject: [PATCH 09/16] fix: missing literal closing backtick

---
 src/modality-specific-files/task-events.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 2406a786b2..479ec38ebd 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -124,7 +124,7 @@ Note that in the example above:
 
 1.  The `channel` column contains a list of values that are separated
     by a delimiter (`|`), as is declared in the `Delimiter` metadata
-    field of the `events.json file.
+    field of the `events.json` file.
     Thus, the channels related to the event in the third row of the example
     are called `F,1`, `F,2`, and `Cz`.
 

From 8273f669ed245b20b37a228c60217b1dd8181a47 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 14:19:37 +0200
Subject: [PATCH 10/16] Apply suggestions from code review

Co-authored-by: Remi Gau <remi_gau@hotmail.com>
---
 src/modality-specific-files/physiological-recordings.md | 6 +++---
 src/modality-specific-files/task-events.md              | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index f29eb7ac66..cade0d262f 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -46,9 +46,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.
+Physiological recordings (including eyetracking) MUST use the `_physio` suffix.
 
-The following table specifies metadata fields for the `*_physio.json` file.
+The following tables specifiy metadata fields for the `*_physio.json` file.
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -169,7 +169,7 @@ stored in separate files
 entity MAY be used to distinguish these files).
 
 For motion parameters acquired from MRI scanner side motion correction, the
-`_physio` suffix SHOULD be used.
+`_physio` suffix MUST be used.
 
 For multi-echo data, a given `physio.tsv` file is applicable to all echos of
 a particular run.
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 479ec38ebd..a7ceba3ae3 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -323,7 +323,7 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
       -   [*Trial timing for multivariate pattern analysis*][ds000238]
 
 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.
+evenly recorded at a constant sampling frequency MUST be stored as follows.
 
 Template:
 

From a9b70f8415bbe770ec3b85b3312182c8d53ad3e5 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 14:28:13 +0200
Subject: [PATCH 11/16] fix: typo

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

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index cade0d262f..1bf540c17c 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -48,7 +48,7 @@ measurements in a different sampling frequency.
 
 Physiological recordings (including eyetracking) MUST use the `_physio` suffix.
 
-The following tables specifiy metadata fields for the `*_physio.json` file.
+The following tables specify metadata fields for the `*_physio.json` file.
 
 <!-- This block generates a metadata table.
 These tables are defined in

From 5a4f292aac5b876e99c8ef01e0eecdd0ece1b2a1 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 14:37:03 +0200
Subject: [PATCH 12/16] fix: consistency and ``[recording-<label>]`` soft
 removal

---
 .../physiological-recordings.md               |  2 +-
 src/modality-specific-files/task-events.md    | 23 ++++++++-----------
 2 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/src/modality-specific-files/physiological-recordings.md b/src/modality-specific-files/physiological-recordings.md
index 1bf540c17c..897deb3d1b 100644
--- a/src/modality-specific-files/physiological-recordings.md
+++ b/src/modality-specific-files/physiological-recordings.md
@@ -2,7 +2,7 @@
 
 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
+([TSV.GZ file](../glossary.md#tsvgz-extensions)) and a corresponding
 JSON file for storing metadata fields (see below).
 
 !!! example "Example datasets"
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index a7ceba3ae3..773f92956d 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -323,15 +323,18 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
       -   [*Trial timing for multivariate pattern analysis*][ds000238]
 
 Signals related to stimuli (such as parameters of a film or audio stimuli) that are
-evenly recorded at a constant sampling frequency MUST be stored as follows.
+evenly recorded at a constant sampling frequency MUST be specified using a
+[compressed tabular file](../common-principles.md#compressed-tabular-files)
+([TSV.GZ file](../glossary.md#tsvgz-extensions)) and a corresponding
+JSON file for storing metadata fields (see below).
 
 Template:
 
 ```Text
 sub-<label>/[ses-<label>/]
     <datatype>/
-        <matches>[_recording-<label>]_stim.tsv.gz
-        <matches>[_recording-<label>]_stim.json
+        <matches>_stim.tsv.gz
+        <matches>_stim.json
 ```
 
 For the template directory name, `<datatype>` can correspond to any data
@@ -344,16 +347,10 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 
 !!! warning "Caution"
 
-    `<matches>[_recording-<label>]_stim.tsv.gz` files MUST NOT include a header line,
+    `<matches>_stim.tsv.gz` files MUST 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 present to indicate
-    the column names.
-
-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).
+    As a result, when supplying a `<matches>_stim.tsv.gz` file, an accompanying
+    `<matches>_stim.json` MUST be present to indicate the column names.
 
 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
@@ -384,7 +381,7 @@ A guide for using macros can be found at
 }) }}
 
 The following table specifies metadata fields for the
-`<matches>[_recording-<label>]_stim.json` file.
+`<matches>_stim.json` file.
 
 <!-- This block generates a metadata table.
 These tables are defined in

From b30a6968037faa161f8364d9671eb14c2809e03b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 14:50:16 +0200
Subject: [PATCH 13/16] enh: add synthetic example

---
 src/modality-specific-files/task-events.md | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 773f92956d..3c7b7f0576 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -314,11 +314,13 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
 
 !!! example "Example datasets"
 
-      At the time of writing, there are no [example datasets][bids-examples] 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:
+      The following [BIDS-Examples][] showcase stimulus-related signals:
+
+      -   ["synthetic" example dataset][synthetic-example].
+
+      The following examples 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*][ds000238]
 
@@ -400,3 +402,4 @@ example, the units of the recorded time series for each column.
 <!-- Link Definitions -->
 [ds000238]: https://openneuro.org/datasets/ds000238/versions/00002
 [bids-examples]: https://bids-standard.github.io/bids-examples/#dataset-index
+[synthetic-example]: https://github.com/bids-standard/bids-examples/tree/master/synthetic

From cad7b48bfc83f55c5d38dee3a4d8bdd821a8049d Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 17:11:36 +0200
Subject: [PATCH 14/16] fix: defining links inside admonition

---
 src/modality-specific-files/task-events.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 3c7b7f0576..8cf3a656c8 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -324,6 +324,11 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
 
       -   [*Trial timing for multivariate pattern analysis*][ds000238]
 
+      <!-- Link Definitions -->
+      [ds000238]: https://openneuro.org/datasets/ds000238/versions/00002
+      [bids-examples]: https://bids-standard.github.io/bids-examples/#dataset-index
+      [synthetic-example]: https://github.com/bids-standard/bids-examples/tree/master/synthetic
+
 Signals related to stimuli (such as parameters of a film or audio stimuli) that are
 evenly recorded at a constant sampling frequency MUST be specified using a
 [compressed tabular file](../common-principles.md#compressed-tabular-files)
@@ -398,8 +403,3 @@ A guide for using macros can be found at
 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.
-
-<!-- Link Definitions -->
-[ds000238]: https://openneuro.org/datasets/ds000238/versions/00002
-[bids-examples]: https://bids-standard.github.io/bids-examples/#dataset-index
-[synthetic-example]: https://github.com/bids-standard/bids-examples/tree/master/synthetic

From 918a84aaca8bd7078fe8b66c9a8fcadf271fdff9 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 18:18:48 +0200
Subject: [PATCH 15/16] Apply suggestions from code review

---
 src/modality-specific-files/task-events.md | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 8cf3a656c8..1400eeb14f 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -314,20 +314,12 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
 
 !!! example "Example datasets"
 
-      The following [BIDS-Examples][] showcase stimulus-related signals:
+      The following [BIDS-Examples](https://bids-standard.github.io/bids-examples/#dataset-index)
+      showcase stimulus-related signals and may be used as a reference
+      when curating a new dataset:
 
-      -   ["synthetic" example dataset][synthetic-example].
+      -   ["synthetic" example dataset](https://github.com/bids-standard/bids-examples/tree/master/synthetic).
 
-      The following examples 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*][ds000238]
-
-      <!-- Link Definitions -->
-      [ds000238]: https://openneuro.org/datasets/ds000238/versions/00002
-      [bids-examples]: https://bids-standard.github.io/bids-examples/#dataset-index
-      [synthetic-example]: https://github.com/bids-standard/bids-examples/tree/master/synthetic
 
 Signals related to stimuli (such as parameters of a film or audio stimuli) that are
 evenly recorded at a constant sampling frequency MUST be specified using a

From 00114ccad85a15a16812b42ccf4b5ac1eae839f9 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 2 Apr 2024 18:19:20 +0200
Subject: [PATCH 16/16] Update src/modality-specific-files/task-events.md

---
 src/modality-specific-files/task-events.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 1400eeb14f..5a0e316b90 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -320,7 +320,6 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
 
       -   ["synthetic" example dataset](https://github.com/bids-standard/bids-examples/tree/master/synthetic).
 
-
 Signals related to stimuli (such as parameters of a film or audio stimuli) that are
 evenly recorded at a constant sampling frequency MUST be specified using a
 [compressed tabular file](../common-principles.md#compressed-tabular-files)