From 95ebf752d601e4bbe9921b58b0a8d8ffc974163d Mon Sep 17 00:00:00 2001
From: "Seyed (Yahya) Shirazi" <shirazi@ieee.org>
Date: Sat, 14 Dec 2024 14:15:20 -0800
Subject: [PATCH 01/21] Add stimuli specifications to BIDS

Implement the standardization of stimulus files and their annotations within the BIDS specifications.

* **Add new file `src/modality-specific-files/stimuli.md`**
  - Describe the specifications for the stimuli directory.
  - Include guidelines for storing stimulus files and their annotations.
  - Define what goes into `stimuli.tsv/json`, `annotations.tsv/json`, and `stim-<label>.json`.
  - Use the same style as other modality-specific docs to design the tables, variables, and examples.

* **Modify `src/modality-specific-files/task-events.md`**
  - Add a section detailing the standardization of stimulus files and their annotations within the BIDS specifications.
  - Include examples of how to use the `stim_file` and `stim_id` columns in `events.tsv` files.
  - Provide guidelines for storing stimulus files in the `/stimuli` directory.
  - Expand the definition of the `stim_file` column to include `stim_id`.

* **Modify `src/schema/objects/columns.yaml`**
  - Update the definition of the `stim_file` column to ensure consistency in stimulus file references.
  - Add the `stim_id` column definition for `events.tsv` files.

* **Modify `src/schema/rules/checks/events.yaml`**
  - Add a check for missing stimulus files declared in `events.tsv`.
  - Add a check for missing `stim_id` references in `events.tsv`.

* **Modify `src/schema/rules/sidecars/events.yaml`**
  - Specify the `StimulusPresentation` metadata field for `events.tsv` files.
  - Include the `stim_id` column in the metadata field specifications.

* **Modify `src/schema/objects/entities.yaml`**
  - Add entities described in the document with proper requirement levels and descriptions.

* **Modify `src/schema/objects/suffixes.yaml`**
  - Add suffixes for `{audio, image, video, audiovideo}`.
  - Include the file extensions and descriptions for each suffix.

* **Add new file `src/schema/rules/sidecars/stimulus.yaml`**
  - Define sidecar tables for `stimuli.tsv/json`, `annotations.tsv/json`, and `stim-<label>.json`.
  - Use the same style as other modality-specific docs to design the tables.

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/neuromechanist/bids-specification?shareId=XXXX-XXXX-XXXX-XXXX).
---
 src/modality-specific-files/stimuli.md     | 167 +++++++++++++++++++++
 src/modality-specific-files/task-events.md |  86 +++++++++++
 src/schema/objects/columns.yaml            |   6 +
 src/schema/objects/entities.yaml           |  12 ++
 src/schema/objects/suffixes.yaml           |  47 ++++++
 src/schema/rules/checks/events.yaml        |  12 ++
 src/schema/rules/sidecars/events.yaml      |   2 +
 src/schema/rules/sidecars/stimulus.yaml    |  32 ++++
 8 files changed, 364 insertions(+)
 create mode 100644 src/modality-specific-files/stimuli.md
 create mode 100644 src/schema/rules/sidecars/stimulus.yaml

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
new file mode 100644
index 0000000000..5074672e96
--- /dev/null
+++ b/src/modality-specific-files/stimuli.md
@@ -0,0 +1,167 @@
+# Stimuli
+
+The purpose of this file is to describe the specifications for the stimuli directory within the BIDS specifications.
+
+## Storing Stimulus Files
+
+Stimulus files should be stored in the `/stimuli` directory under the root directory of the dataset. The `/stimuli` directory can contain subdirectories to organize the stimulus files. There are no restrictions on the file formats of the stimulus files.
+
+Example directory structure:
+
+<!-- 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({
+  "stimuli": {
+    "images": {
+      "cat01.jpg": "",
+      "cat02.jpg": "",
+    },
+    "videos": {
+      "movie01.mp4": "",
+      "movie02.mp4": "",
+    },
+  },
+}) }}
+
+## Referencing Stimulus Files in `events.tsv`
+
+To reference stimulus files in the `events.tsv` file, use the `stim_file` column. The values in the `stim_file` column should represent the relative path to the stimulus file within the `/stimuli` directory.
+
+Example `events.tsv` file:
+
+```Text
+onset	duration	trial_type	response_time	stim_file
+1.23	0.65	start	1.435	images/cat01.jpg
+5.65	0.65	stop	1.739	images/cat02.jpg
+12.1	2.35	n/a	n/a	videos/movie01.mp4
+```
+
+In the accompanying JSON sidecar, the `stim_file` column might be described as follows:
+
+```JSON
+{
+    "stim_file": {
+        "LongName": "Stimulus file",
+        "Description": "Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. The values correspond to a path relative to the /stimuli directory."
+    }
+}
+```
+
+## Referencing Stimulus Identifiers in `events.tsv`
+
+To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli.
+
+Example `events.tsv` file:
+
+```Text
+onset	duration	trial_type	response_time	stim_file	stim_id
+1.23	0.65	start	1.435	images/cat01.jpg	stim001
+5.65	0.65	stop	1.739	images/cat02.jpg	stim002
+12.1	2.35	n/a	n/a	videos/movie01.mp4	stim003
+```
+
+In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
+
+```JSON
+{
+    "stim_id": {
+        "LongName": "Stimulus identifier",
+        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
+    }
+}
+```
+
+## Standardization of Stimulus Files and Annotations
+
+To ensure consistency and facilitate reuse, the BIDS specifications provide guidelines for standardizing stimulus files and their annotations. This section outlines the recommended practices for storing and referencing stimulus files within a BIDS dataset.
+
+### Advantages of Standardization
+
+Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
+
+1. **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
+2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
+3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
+4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
+
+By following these guidelines, researchers can enhance the interoperability and reproducibility of their studies, making it easier to share and reuse data within the scientific community.
+
+## Stimuli.tsv and Stimuli.json
+
+The `stimuli.tsv` and `stimuli.json` files are used to provide additional information about the stimuli used in the experiment. These files should be placed in the `/stimuli` directory.
+
+### Stimuli.tsv
+
+The `stimuli.tsv` file contains information about each stimulus, including its onset time, duration, and other relevant details. The following table describes the required, recommended, and optional columns for the `stimuli.tsv` file:
+
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/rules/tabular_data/*.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_columns_table("stimuli.Stimuli") }}
+
+### Stimuli.json
+
+The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. The following table describes the required, recommended, and optional fields for the `stimuli.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("stimuli.Stimuli") }}
+
+## Annotations.tsv and Annotations.json
+
+The `annotations.tsv` and `annotations.json` files are used to provide additional information about the annotations associated with the stimuli. These files should be placed in the `/stimuli` directory.
+
+### Annotations.tsv
+
+The `annotations.tsv` file contains information about each annotation, including its onset time, duration, and other relevant details. The following table describes the required, recommended, and optional columns for the `annotations.tsv` file:
+
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/rules/tabular_data/*.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_columns_table("annotations.Annotations") }}
+
+### Annotations.json
+
+The `annotations.json` file provides detailed descriptions of the columns in the `annotations.tsv` file. The following table describes the required, recommended, and optional fields for the `annotations.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("annotations.Annotations") }}
+
+## Stim-<label>.json
+
+The `stim-<label>.json` file provides detailed information about a specific stimulus. This file should be placed in the `/stimuli` directory and named according to the unique identifier of the stimulus.
+
+### Stim-<label>.json
+
+The following table describes the required, recommended, and optional fields for the `stim-<label>.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("stimulus.Stimulus") }}
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 7dd53428a6..d3507493fd 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -400,3 +400,89 @@ 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.
+
+## Standardization of Stimulus Files and Annotations
+
+To ensure consistency and facilitate reuse, the BIDS specifications provide guidelines for standardizing stimulus files and their annotations. This section outlines the recommended practices for storing and referencing stimulus files within a BIDS dataset.
+
+### Storing Stimulus Files
+
+Stimulus files should be stored in the `/stimuli` directory under the root directory of the dataset. The `/stimuli` directory can contain subdirectories to organize the stimulus files. There are no restrictions on the file formats of the stimulus files.
+
+Example directory structure:
+
+<!-- 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({
+  "stimuli": {
+    "images": {
+      "cat01.jpg": "",
+      "cat02.jpg": "",
+    },
+    "videos": {
+      "movie01.mp4": "",
+      "movie02.mp4": "",
+    },
+  },
+}) }}
+
+### Referencing Stimulus Files in `events.tsv`
+
+To reference stimulus files in the `events.tsv` file, use the `stim_file` column. The values in the `stim_file` column should represent the relative path to the stimulus file within the `/stimuli` directory.
+
+Example `events.tsv` file:
+
+```Text
+onset	duration	trial_type	response_time	stim_file
+1.23	0.65	start	1.435	images/cat01.jpg
+5.65	0.65	stop	1.739	images/cat02.jpg
+12.1	2.35	n/a	n/a	videos/movie01.mp4
+```
+
+In the accompanying JSON sidecar, the `stim_file` column might be described as follows:
+
+```JSON
+{
+    "stim_file": {
+        "LongName": "Stimulus file",
+        "Description": "Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. The values correspond to a path relative to the /stimuli directory."
+    }
+}
+```
+
+### Referencing Stimulus Identifiers in `events.tsv`
+
+To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli.
+
+Example `events.tsv` file:
+
+```Text
+onset	duration	trial_type	response_time	stim_file	stim_id
+1.23	0.65	start	1.435	images/cat01.jpg	stim001
+5.65	0.65	stop	1.739	images/cat02.jpg	stim002
+12.1	2.35	n/a	n/a	videos/movie01.mp4	stim003
+```
+
+In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
+
+```JSON
+{
+    "stim_id": {
+        "LongName": "Stimulus identifier",
+        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
+    }
+}
+```
+
+### Advantages of Standardization
+
+Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
+
+1. **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
+2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
+3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
+4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
+
+By following these guidelines, researchers can enhance the interoperability and reproducibility of their studies, making it easier to share and reuse data within the scientific community.
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index edfa1de1ea..bde641ea3b 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -585,6 +585,12 @@ stim_file:
     For example `images/cat03.jpg` will be translated to `/stimuli/images/cat03.jpg`.
   type: string
   format: stimuli_relative
+stim_id:
+  name: stim_id
+  display_name: Stimulus identifier
+  description: |
+    Represents a unique identifier for the stimulus presented at the given onset time.
+  type: string
 strain:
   name: strain
   display_name: Strain
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index b60a12a87b..0f3b9cfb19 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -373,6 +373,18 @@ stain:
     and/or `"SampleSecondaryAntibodies"` metadata fields, as appropriate.
   type: string
   format: label
+stimulus:
+  name: stim
+  display_name: Stimulus
+  description: |
+    The `stim-<label>` entity can be used to distinguish different stimulus files or annotations.
+    The label is a unique identifier for the stimulus or annotation.
+
+    This entity represents the `"Stimulus"` metadata field.
+    Therefore, if the `stim-<label>` entity is present in a filename,
+    `"Stimulus"` MUST be defined in the associated metadata.
+  type: string
+  format: label
 subject:
   name: sub
   display_name: Subject
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 1e2825ced2..ad035d7162 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -877,3 +877,50 @@ unloc:
   description: |
     MRS acquisitions run without localization.
     This includes signals detected using coil sensitivity only.
+audio:
+  value: audio
+  display_name: Audio stimulus file
+  description: |
+    Any data file used as an audio stimulus. Media files usually have an audio file type (such as wav, mp3, aac, ogg).
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+  extensions:
+    - .wav
+    - .mp3
+    - .aac
+    - .ogg
+image:
+  value: image
+  display_name: Image stimulus file
+  description: |
+    Any data file used as an image stimulus. Media files usually have an image file type (such as jpg, png, svg).
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+  extensions:
+    - .jpg
+    - .png
+    - .svg
+video:
+  value: video
+  display_name: Video stimulus file
+  description: |
+    Any data file used as a video stimulus. Media files usually have a video file type (such as mp4, avi, mkv, webm).
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+  extensions:
+    - .mp4
+    - .avi
+    - .mkv
+    - .webm
+audiovideo:
+  value: audiovideo
+  display_name: Audiovideo stimulus file
+  description: |
+    Any data file used as an audiovideo stimulus. Media files usually have an audiovideo file type (such as mp4, avi, mkv, webm).
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+  extensions:
+    - .mp4
+    - .avi
+    - .mkv
+    - .webm
diff --git a/src/schema/rules/checks/events.yaml b/src/schema/rules/checks/events.yaml
index 536423aec7..6ec2e51514 100644
--- a/src/schema/rules/checks/events.yaml
+++ b/src/schema/rules/checks/events.yaml
@@ -31,6 +31,18 @@ StimulusFileMissing:
   checks:
     - exists(columns.stim_file, "stimuli") == length(columns.stim_file) - count(columns.stim_file, "n/a")
 
+StimulusIDMissing:
+  issue:
+    code: STIMULUS_ID_MISSING
+    message: |
+      A stimulus identifier was declared but not found in the dataset.
+    level: error
+  selectors:
+    - intersects([suffix], ["events", "beh"])
+    - columns.stim_id != null
+  checks:
+    - exists(columns.stim_id, "stimuli") == length(columns.stim_id) - count(columns.stim_id, "n/a")
+
 SortedOnsets:
   issue:
     code: EVENT_ONSET_ORDER
diff --git a/src/schema/rules/sidecars/events.yaml b/src/schema/rules/sidecars/events.yaml
index abd58db73e..9d35da4b9f 100644
--- a/src/schema/rules/sidecars/events.yaml
+++ b/src/schema/rules/sidecars/events.yaml
@@ -12,3 +12,5 @@ StimulusPresentation:
   fields:
     StimulusPresentation: recommended
     VisionCorrection: optional
+    stim_file: recommended
+    stim_id: recommended
diff --git a/src/schema/rules/sidecars/stimulus.yaml b/src/schema/rules/sidecars/stimulus.yaml
new file mode 100644
index 0000000000..3029c4641e
--- /dev/null
+++ b/src/schema/rules/sidecars/stimulus.yaml
@@ -0,0 +1,32 @@
+# Sidecar tables for stimuli.tsv/json, annotations.tsv/json, and stim-<label>.json
+
+Stimuli:
+  selectors:
+    - suffix == "stimuli"
+  fields:
+    onset: required
+    duration: required
+    trial_type: recommended
+    response_time: optional
+    stim_file: required
+    stim_id: required
+
+Annotations:
+  selectors:
+    - suffix == "annotations"
+  fields:
+    onset: required
+    duration: required
+    annotation_id: required
+    description: recommended
+    stim_file: optional
+    stim_id: optional
+
+Stimulus:
+  selectors:
+    - suffix == "stim"
+  fields:
+    License: recommended
+    Copyright: recommended
+    URL: optional
+    Description: optional

From 91df78b8a3fce421a10d169991f1230966d18b35 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sun, 15 Dec 2024 11:42:59 -0800
Subject: [PATCH 02/21] edit stimuli description

---
 src/modality-specific-files/stimuli.md | 167 +++++++++++--------------
 1 file changed, 70 insertions(+), 97 deletions(-)

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index 5074672e96..a78792ac8b 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -1,66 +1,48 @@
 # Stimuli
 
-The purpose of this file is to describe the specifications for the stimuli directory within the BIDS specifications.
+Stimulus files should be stored in the `/stimuli` directory under the root directory of the dataset. The `/stimuli` directory can contain subdirectories to organize the stimulus files. Stimulus files SHOULD follow the BIDS naming conventions and SHOULD be referenced in the `events.tsv` file using the `stim_id` column. The `stim_id` column represents unique identifiers for the stimuli. Additional information about the stimuli and their annotations can be provided in the `stimuli.tsv`, `stimuli.json`, `annotations.tsv`, `annotations.json`, and `stim-<label>.json` files.
 
-## Storing Stimulus Files
+Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
 
-Stimulus files should be stored in the `/stimuli` directory under the root directory of the dataset. The `/stimuli` directory can contain subdirectories to organize the stimulus files. There are no restrictions on the file formats of the stimulus files.
+1. **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
+2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
+3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
+4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
 
-Example directory structure:
+To preserve backward compatibility with existing datasets (see the Legacy section below), the use of these specifications for `/stimuli` directory and the `stim_id` column in the `events.tsv` files is RECOMMENDED but not required. Researchers are encouraged to follow these guidelines to enhance the interoperability and reproducibility of their studies.
+
+Following these guidelines will help ensure that stimulus files and their annotations are stored and referenced in a consistent manner across different datasets, facilitating data sharing, reuse, and reproducibility.
 
 <!-- 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({
-  "stimuli": {
-    "images": {
-      "cat01.jpg": "",
-      "cat02.jpg": "",
-    },
-    "videos": {
-      "movie01.mp4": "",
-      "movie02.mp4": "",
-    },
-  },
-}) }}
-
-## Referencing Stimulus Files in `events.tsv`
-
-To reference stimulus files in the `events.tsv` file, use the `stim_file` column. The values in the `stim_file` column should represent the relative path to the stimulus file within the `/stimuli` directory.
-
-Example `events.tsv` file:
-
-```Text
-onset	duration	trial_type	response_time	stim_file
-1.23	0.65	start	1.435	images/cat01.jpg
-5.65	0.65	stop	1.739	images/cat02.jpg
-12.1	2.35	n/a	n/a	videos/movie01.mp4
-```
-
-In the accompanying JSON sidecar, the `stim_file` column might be described as follows:
-
-```JSON
-{
-    "stim_file": {
-        "LongName": "Stimulus file",
-        "Description": "Represents the location of the stimulus file (such as an image, video, or audio file) presented at the given onset time. The values correspond to a path relative to the /stimuli directory."
+   "stimuli": {
+    "stimuli.tsv": "",
+    "stimuli.json": "",
+    "[stim-<label>[_part-<label>]_<suffix>.<extension>]": "",
+    "[stim-<label>[_part-<label>]_<suffix>.json]": "",
+    "[[stim-<label>_]annotations.tsv]": "",
+    "[[stim-<label>_]annotations.json]": "",
+    "[stim-<label>[_part-<label>]_annot-<label>_events.tsv]": "",
+    "[stim-<label>[_part-<label>]_annot-<label>_events.json]": ""
     }
-}
-```
+  }) }}
+
+Note: The presence of `stimuli.tsv` file indicates that the content of the `/stimuli` folder follows this BIDS specification for stimulus organization. This structure is planned to become mandatory in BIDS 2.0.
 
 ## Referencing Stimulus Identifiers in `events.tsv`
 
-To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli.
+To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli. Stimulus ID (`stim_id`) should correspond to the unique identifier of the stimulus file in the /stimuli directory and expands to all files (both stimulus and annotation files) that share the same stimulus ID.
 
 Example `events.tsv` file:
 
-```Text
-onset	duration	trial_type	response_time	stim_file	stim_id
-1.23	0.65	start	1.435	images/cat01.jpg	stim001
-5.65	0.65	stop	1.739	images/cat02.jpg	stim002
-12.1	2.35	n/a	n/a	videos/movie01.mp4	stim003
-```
+| onset | duration | trial_type | response_time | stim_id |
+|-------|----------|------------|---------------|----------|
+| 1.23 | 0.65 | start | 1.435 | stim-\<label\> |
+| 5.65 | 0.65 | stop | 1.739 | stim-\<label\> |
+| 12.1 | 2.35 | n/a | n/a | stim-\<label\> |
 
 In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
 
@@ -68,33 +50,51 @@ In the accompanying JSON sidecar, the `stim_id` column might be described as fol
 {
     "stim_id": {
         "LongName": "Stimulus identifier",
-        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
+        "Description": "Represents a unique identifier for the stimulus presented at the given onset time.",
     }
 }
 ```
 
-## Standardization of Stimulus Files and Annotations
+## The stimulus file and JSON sidecar
 
-To ensure consistency and facilitate reuse, the BIDS specifications provide guidelines for standardizing stimulus files and their annotations. This section outlines the recommended practices for storing and referencing stimulus files within a BIDS dataset.
+Stimulus files can be of various types including audio, image, video, and combined audiovideo formats. Each stimulus file SHOULD have an accompanying JSON sidecar file containing metadata about the stimulus. The structure of the stimulus file name and the JSON sidecar file name SHOULD follow the BIDS naming conventions as below:
 
-### Advantages of Standardization
+- Stimulus file: `stim-<label>[_part-<label>]_<suffix>.<extension>`
+- JSON sidecar file: `stim-<label>[_part-<label>]_<suffix>.json`
 
-Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
+Then stimulus file names MUST start with `stim-` followed by a unique label, and an optional part label if the stimulus is divided into parts. `stim-` is the standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. The suffix SHOULD describe the type of stimulus (e.g., audio, image, video, audiovideo) and the extension MUST indicate the file format. The JSON sidecar file MUST have the same name as the stimulus file but with a `.json` extension. Here are the allowed suffixes and extensions for the stimulus files:
 
-1. **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
-2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
-3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
-4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
+| Modality | Extensions | Description |
+|----------|------------|-------------|
+| `audio` | .wav, .mp3, .aac, .ogg | Audio-only stimulus files |
+| `image` | .jpg, .png, .svg | Static visual stimulus files |
+| `video` | .mp4, .avi, .mkv, .webm | Video-only stimulus files |
+| `audioVideo` | .mp4, .avi, .mkv, .webm | Combined audio-visual stimulus files |
+<!-- | Tactile | .ros | Robot Operating System program files for tactile stimulation | -->
 
-By following these guidelines, researchers can enhance the interoperability and reproducibility of their studies, making it easier to share and reuse data within the scientific community.
+If distribution restrictions prevent including the actual stimulus file, the JSON sidecar SHOULD still be present with appropriate metadata describing the stimulus.
+For the stimuli that can be descibed in a table format (such as image datasets), the `stimuli.tsv` and `stimuli.json` files can be used to provide information about the stimuli based on their `stim_id`, and the presence of the stimulus file and JSON sidecar is OPTIONAL.
+
+
+The following table describes the REQURIED, RECOMMENDED, and OPTIONAL fields for the `stim-<label>.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("stimulus.Stimulus") }}
 
 ## Stimuli.tsv and Stimuli.json
 
-The `stimuli.tsv` and `stimuli.json` files are used to provide additional information about the stimuli used in the experiment. These files should be placed in the `/stimuli` directory.
+The `stimuli.tsv` and `stimuli.json` files are used to provide information about the stimuli based on their `stim_id`. This file is similar in usage as `participants.tsv`, `scans.tsv` and `sessions.tsv`, which list descriptions about subjects, scans and sessions, respectively. The `stimluli.tsv/json` files should be placed in the `/stimuli` directory.
 
 ### Stimuli.tsv
 
-The `stimuli.tsv` file contains information about each stimulus, including its onset time, duration, and other relevant details. The following table describes the required, recommended, and optional columns for the `stimuli.tsv` file:
+The `stimuli.tsv` file contains information about each stimulus, including stimulus ID, type, URL, and other relevant details. The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL columns for the `stimuli.tsv` file:
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in
@@ -104,19 +104,18 @@ and a guide for using macros can be found at
 -->
 {{ MACROS___make_columns_table("stimuli.Stimuli") }}
 
-### Stimuli.json
+This is an example of the `stimuli.tsv` file describing three images from the natural scence dataset (NSD):
 
-The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. The following table describes the required, recommended, and optional fields for the `stimuli.json` file:
+| stimulus_id | type | description | HED | NSD_id | COCO_id |
+|------------|------|-------------|-----|---------|----------|
+| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
+| stim-nsd02991 | image | a couple of people are cooking in a room | (Foreground-view, ((Item-count/1, (Human, Body, Agent-trait/Adult)), (Item-count/1, (Human, Body, (Face, Away-from), Male, Agent-trait/Adult)), ((Item-count, High), Furnishing))), (Background-view, (Ingestible-object, Furnishing, Room, Indoors, Man-made-object, Assistive-device)) | 2991 | 262239 |
+| stim-nsd03050 | image | a person standing on a surfboard riding a wave | (Foreground-view, ((Item-count/1, ((Human, Human-agent), Body, Male, Agent-trait/Adolescent)), (Play, (Item-count/1, Man-made-object)))), (Background-view, (Outdoors, Natural-feature/Ocean)) | 3050 | 262414 |
 
-<!-- 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("stimuli.Stimuli") }}
+
+### Stimuli.json
+
+The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. There can be extra entries in the `stimuli.json` in addition to the columns in the `stimuli.tsv` to provide more details about the stimulus.
 
 ## Annotations.tsv and Annotations.json
 
@@ -124,7 +123,7 @@ The `annotations.tsv` and `annotations.json` files are used to provide additiona
 
 ### Annotations.tsv
 
-The `annotations.tsv` file contains information about each annotation, including its onset time, duration, and other relevant details. The following table describes the required, recommended, and optional columns for the `annotations.tsv` file:
+The `annotations.tsv` file contains information about each annotation, including the annotation ID and description. The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL columns for the `annotations.tsv` file:
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in
@@ -136,32 +135,6 @@ and a guide for using macros can be found at
 
 ### Annotations.json
 
-The `annotations.json` file provides detailed descriptions of the columns in the `annotations.tsv` file. The following table describes the required, recommended, and optional fields for the `annotations.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("annotations.Annotations") }}
-
-## Stim-<label>.json
+The `annotations.json` file provides detailed descriptions of the columns in the `annotations.tsv` file.
 
-The `stim-<label>.json` file provides detailed information about a specific stimulus. This file should be placed in the `/stimuli` directory and named according to the unique identifier of the stimulus.
-
-### Stim-<label>.json
-
-The following table describes the required, recommended, and optional fields for the `stim-<label>.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("stimulus.Stimulus") }}
+There could be only one `annotations.tsv` in the `/stimuli` directory. Alternatively, each stimulus (with a unique stimulus ID) can have a separate `stim-<label>_annotations.tsv` to describe the annotations for a specific stimulus.

From 0167a4160bad9269b3c502bd78be519335105287 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Thu, 19 Dec 2024 12:25:35 -0800
Subject: [PATCH 03/21] Update task events to include stim-bids spec

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

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index d3507493fd..0a999b0ee3 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -454,15 +454,15 @@ In the accompanying JSON sidecar, the `stim_file` column might be described as f
 
 ### Referencing Stimulus Identifiers in `events.tsv`
 
-To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli.
+To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The `stim_id` corresponds to the unique identifier of the stimulus files and their annotations stored under the `/stimuli` directory. This allows linking each event to multiple related files associated with that stimulus.
 
 Example `events.tsv` file:
 
 ```Text
-onset	duration	trial_type	response_time	stim_file	stim_id
-1.23	0.65	start	1.435	images/cat01.jpg	stim001
-5.65	0.65	stop	1.739	images/cat02.jpg	stim002
-12.1	2.35	n/a	n/a	videos/movie01.mp4	stim003
+onset	duration	trial_type	response_time	stim_id
+1.23	0.65	start	1.435	stim-face01
+5.65	0.65	stop	1.739	stim-face02
+12.1	2.35	n/a	n/a	stim-video01
 ```
 
 In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
@@ -471,11 +471,28 @@ In the accompanying JSON sidecar, the `stim_id` column might be described as fol
 {
     "stim_id": {
         "LongName": "Stimulus identifier",
-        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
+        "Description": "Represents a unique identifier for the stimulus presented at the given onset time. Links to files and annotations in the /stimuli directory."
     }
 }
 ```
 
+The `stim_id` in the events file links to corresponding files:
+
+```Text
+stimuli/
+├── stim-face01_image.jpg
+├── stim-face01_image.json
+├── stim-face01_annotations.tsv
+├── stim-face02_image.jpg
+├── stim-face02_image.json
+├── stim-face02_annotations.tsv
+├── stim-face02_annotations.tsv
+├── stimuli.tsv
+└── stimuli.json
+```
+
+By using `stim_id`, multiple annotations and stimulus files associated with the same identifier can be efficiently linked to events in the `events.tsv` file. The `stim_id` is a unique identifier for the stimulus that can be used to reference the stimulus files, annotations, and metadata stored in `stimuli.tsv` and `stimuli.json`. For more information on the structure of stimulus files and annotations, refer to the [Stimuli](./stimuli.md) BIDS specifications.
+
 ### Advantages of Standardization
 
 Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:

From 3c2357b8477dfe5cf7b6158ef4e42fa9be4fac1e Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 09:31:38 -0800
Subject: [PATCH 04/21] Add missing entities

---
 src/schema/objects/columns.yaml  |  2 +-
 src/schema/objects/entities.yaml | 41 +++++++++++++++++---------------
 2 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index bde641ea3b..283b0fa59d 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -589,7 +589,7 @@ stim_id:
   name: stim_id
   display_name: Stimulus identifier
   description: |
-    Represents a unique identifier for the stimulus presented at the given onset time.
+    Represents a unique identifier for the stimulus presented at the given onset time. The `stim_id` is inclusive of the stimulus file(s), annotations related to the stimulus, and the information about the stimulus present in the `stimuli.tsv` file.
   type: string
 strain:
   name: strain
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 0f3b9cfb19..cbf0cd1e51 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -194,20 +194,12 @@ part:
   name: part
   display_name: Part
   description: |
-    This entity is used to indicate which component of the complex
-    representation of the MRI signal is represented in voxel data.
-    The `part-<label>` entity is associated with the DICOM Tag
-    `0008, 9208`.
-    Allowed label values for this entity are `phase`, `mag`, `real` and `imag`,
-    which are typically used in `part-mag`/`part-phase` or
-    `part-real`/`part-imag` pairs of files.
-
-    Phase images MAY be in radians or in arbitrary units.
-    The sidecar JSON file MUST include the `"Units"` of the `phase` image.
-    The possible options are `"rad"` or `"arbitrary"`.
-
-    When there is only a magnitude image of a given type, the `part` entity MAY be
-    omitted.
+    This entity is used to indicate which component of a complex 
+    representation is being stored. For MRI data, it indicates which component 
+    of the complex signal is represented in voxel data. For stimulus files, it can 
+    be used to distinguish different parts of a single stimulus, such as chapters 
+    in an audiobook or segments of a long movie (for example, `part-1`, `part-2`, 
+    `part-epilog`, `part-chapter1`).
   type: string
   format: label
   enum:
@@ -377,12 +369,13 @@ stimulus:
   name: stim
   display_name: Stimulus
   description: |
-    The `stim-<label>` entity can be used to distinguish different stimulus files or annotations.
-    The label is a unique identifier for the stimulus or annotation.
+    The `stim-<label>` entity can be used to distinguish different stimulus files 
+    or annotations. The label is a unique identifier for the stimulus or annotation.
 
-    This entity represents the `"Stimulus"` metadata field.
-    Therefore, if the `stim-<label>` entity is present in a filename,
-    `"Stimulus"` MUST be defined in the associated metadata.
+    This entity represents the `"Stimulus"` metadata field and requires corresponding 
+    entries in the `stimuli.tsv` file. Therefore, if the `stim-<label>` entity is 
+    present in a filename, `"Stimulus"` MUST be defined in the associated metadata, 
+    and a matching entry MUST exist in the `stimuli.tsv` file.
   type: string
   format: label
 subject:
@@ -455,3 +448,13 @@ tracksys:
     may be longer and more human readable.
   type: string
   format: label
+annotation:
+  name: annot
+  display_name: Annotation
+  description: |
+    The `annot-<label>` entity accommodates multiple annotations for a single 
+    (usually, but not necessarily, time-varying) stimulus id. Similar to `stimuli.tsv`, 
+    there can be one or multiple `annotations.tsv` files with `annotation_id`, providing 
+    a list of the annotations in the directory, or for a specific stimulus respectively.
+  type: string
+  format: label

From b7b19dfd295c5814feb26807d9f0ea72b014835d Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 13:59:22 -0800
Subject: [PATCH 05/21] handling GH Action errors

---
 src/modality-specific-files/stimuli.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index a78792ac8b..fe9120a586 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -4,14 +4,14 @@ Stimulus files should be stored in the `/stimuli` directory under the root direc
 
 Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
 
-1. **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
+1. **Consistency**: Ensures that stimulus files are stored and referenced consistently across different datasets.
 2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
 3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
 4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
 
 To preserve backward compatibility with existing datasets (see the Legacy section below), the use of these specifications for `/stimuli` directory and the `stim_id` column in the `events.tsv` files is RECOMMENDED but not required. Researchers are encouraged to follow these guidelines to enhance the interoperability and reproducibility of their studies.
 
-Following these guidelines will help ensure that stimulus files and their annotations are stored and referenced in a consistent manner across different datasets, facilitating data sharing, reuse, and reproducibility.
+Following these guidelines will help ensure that stimulus files and their annotations are stored and referenced consistently across different datasets, facilitating data sharing, reuse, and reproducibility.
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -62,7 +62,7 @@ Stimulus files can be of various types including audio, image, video, and combin
 - Stimulus file: `stim-<label>[_part-<label>]_<suffix>.<extension>`
 - JSON sidecar file: `stim-<label>[_part-<label>]_<suffix>.json`
 
-Then stimulus file names MUST start with `stim-` followed by a unique label, and an optional part label if the stimulus is divided into parts. `stim-` is the standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. The suffix SHOULD describe the type of stimulus (e.g., audio, image, video, audiovideo) and the extension MUST indicate the file format. The JSON sidecar file MUST have the same name as the stimulus file but with a `.json` extension. Here are the allowed suffixes and extensions for the stimulus files:
+Then stimulus file names MUST start with `stim-` followed by a unique label, and an optional part label if the stimulus is divided into parts. `stim-` is the standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. The suffix SHOULD describe the type of stimulus (such as audio, image, video, audiovideo) and the extension MUST indicate the file format. The JSON sidecar file MUST have the same name as the stimulus file but with a `.json` extension. Here are the allowed suffixes and extensions for the stimulus files:
 
 | Modality | Extensions | Description |
 |----------|------------|-------------|
@@ -73,10 +73,10 @@ Then stimulus file names MUST start with `stim-` followed by a unique label, and
 <!-- | Tactile | .ros | Robot Operating System program files for tactile stimulation | -->
 
 If distribution restrictions prevent including the actual stimulus file, the JSON sidecar SHOULD still be present with appropriate metadata describing the stimulus.
-For the stimuli that can be descibed in a table format (such as image datasets), the `stimuli.tsv` and `stimuli.json` files can be used to provide information about the stimuli based on their `stim_id`, and the presence of the stimulus file and JSON sidecar is OPTIONAL.
+For the stimuli that can be described in a table format (such as image datasets), the `stimuli.tsv` and `stimuli.json` files can be used to provide information about the stimuli based on their `stim_id`, and the presence of the stimulus file and JSON sidecar is OPTIONAL.
 
 
-The following table describes the REQURIED, RECOMMENDED, and OPTIONAL fields for the `stim-<label>.json` file:
+The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL fields for the `stim-<label>.json` file:
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -104,7 +104,7 @@ and a guide for using macros can be found at
 -->
 {{ MACROS___make_columns_table("stimuli.Stimuli") }}
 
-This is an example of the `stimuli.tsv` file describing three images from the natural scence dataset (NSD):
+This is an example of the `stimuli.tsv` file describing three images from the natural scene dataset (NSD):
 
 | stimulus_id | type | description | HED | NSD_id | COCO_id |
 |------------|------|-------------|-----|---------|----------|

From aa570ac16b548db27631b4e651e56df2de1c0ce8 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 14:22:43 -0800
Subject: [PATCH 06/21] yaml-link issues

---
 src/schema/objects/columns.yaml  |  5 ++++-
 src/schema/objects/entities.yaml | 24 ++++++++++++------------
 src/schema/objects/suffixes.yaml | 27 ++++++++++++++++++---------
 3 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index 283b0fa59d..d03a03cd92 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -589,7 +589,10 @@ stim_id:
   name: stim_id
   display_name: Stimulus identifier
   description: |
-    Represents a unique identifier for the stimulus presented at the given onset time. The `stim_id` is inclusive of the stimulus file(s), annotations related to the stimulus, and the information about the stimulus present in the `stimuli.tsv` file.
+    Represents a unique identifier for the stimulus presented at the given onset
+    time. The `stim_id` is inclusive of the stimulus file(s), annotations
+    related to the stimulus, and the information about the stimulus present in
+    the `stimuli.tsv` file.
   type: string
 strain:
   name: strain
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index cbf0cd1e51..4f75778160 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -194,11 +194,11 @@ part:
   name: part
   display_name: Part
   description: |
-    This entity is used to indicate which component of a complex 
-    representation is being stored. For MRI data, it indicates which component 
-    of the complex signal is represented in voxel data. For stimulus files, it can 
-    be used to distinguish different parts of a single stimulus, such as chapters 
-    in an audiobook or segments of a long movie (for example, `part-1`, `part-2`, 
+    This entity is used to indicate which component of a complex
+    representation is being stored. For MRI data, it indicates which component
+    of the complex signal is represented in voxel data. For stimulus files, it can
+    be used to distinguish different parts of a single stimulus, such as chapters
+    in an audiobook or segments of a long movie (for example, `part-1`, `part-2`,
     `part-epilog`, `part-chapter1`).
   type: string
   format: label
@@ -369,12 +369,12 @@ stimulus:
   name: stim
   display_name: Stimulus
   description: |
-    The `stim-<label>` entity can be used to distinguish different stimulus files 
+    The `stim-<label>` entity can be used to distinguish different stimulus files
     or annotations. The label is a unique identifier for the stimulus or annotation.
 
-    This entity represents the `"Stimulus"` metadata field and requires corresponding 
-    entries in the `stimuli.tsv` file. Therefore, if the `stim-<label>` entity is 
-    present in a filename, `"Stimulus"` MUST be defined in the associated metadata, 
+    This entity represents the `"Stimulus"` metadata field and requires corresponding
+    entries in the `stimuli.tsv` file. Therefore, if the `stim-<label>` entity is
+    present in a filename, `"Stimulus"` MUST be defined in the associated metadata,
     and a matching entry MUST exist in the `stimuli.tsv` file.
   type: string
   format: label
@@ -452,9 +452,9 @@ annotation:
   name: annot
   display_name: Annotation
   description: |
-    The `annot-<label>` entity accommodates multiple annotations for a single 
-    (usually, but not necessarily, time-varying) stimulus id. Similar to `stimuli.tsv`, 
-    there can be one or multiple `annotations.tsv` files with `annotation_id`, providing 
+    The `annot-<label>` entity accommodates multiple annotations for a single
+    (usually, but not necessarily, time-varying) stimulus id. Similar to `stimuli.tsv`,
+    there can be one or multiple `annotations.tsv` files with `annotation_id`, providing
     a list of the annotations in the directory, or for a specific stimulus respectively.
   type: string
   format: label
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index ad035d7162..4d10371f93 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -882,8 +882,10 @@ audio:
   display_name: Audio stimulus file
   description: |
     Any data file used as an audio stimulus. Media files usually have an audio file type (such as wav, mp3, aac, ogg).
-    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
-    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright
+    (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
+    present with only JSON sidecar file containing the aforementioned pertinent metadata.
   extensions:
     - .wav
     - .mp3
@@ -894,8 +896,10 @@ image:
   display_name: Image stimulus file
   description: |
     Any data file used as an image stimulus. Media files usually have an image file type (such as jpg, png, svg).
-    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
-    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright
+    (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
+    present with only JSON sidecar file containing the aforementioned pertinent metadata.
   extensions:
     - .jpg
     - .png
@@ -905,8 +909,10 @@ video:
   display_name: Video stimulus file
   description: |
     Any data file used as a video stimulus. Media files usually have a video file type (such as mp4, avi, mkv, webm).
-    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
-    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright
+    (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
+    present with only JSON sidecar file containing the aforementioned pertinent metadata.
   extensions:
     - .mp4
     - .avi
@@ -916,9 +922,12 @@ audiovideo:
   value: audiovideo
   display_name: Audiovideo stimulus file
   description: |
-    Any data file used as an audiovideo stimulus. Media files usually have an audiovideo file type (such as mp4, avi, mkv, webm).
-    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
-    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.
+    Any data file used as an audiovideo stimulus. Media files usually have an audiovideo file type (such as mp4, avi,
+    mkv, webm).
+    The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright
+    (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
+    However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
+    present with only JSON sidecar file containing the aforementioned pertinent metadata.
   extensions:
     - .mp4
     - .avi

From 162cd1c911f9b70bc5622036661dac97445eb443 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 15:32:40 -0800
Subject: [PATCH 07/21] remark validation

---
 src/modality-specific-files/stimuli.md     | 36 ++++++++++------------
 src/modality-specific-files/task-events.md | 12 ++++----
 2 files changed, 23 insertions(+), 25 deletions(-)

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index fe9120a586..da0b1d5940 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -4,10 +4,10 @@ Stimulus files should be stored in the `/stimuli` directory under the root direc
 
 Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
 
-1. **Consistency**: Ensures that stimulus files are stored and referenced consistently across different datasets.
-2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
-3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
-4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
+1.  **Consistency**: Ensures that stimulus files are stored and referenced consistently across different datasets.
+2.  **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
+3.  **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
+4.  **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
 
 To preserve backward compatibility with existing datasets (see the Legacy section below), the use of these specifications for `/stimuli` directory and the `stim_id` column in the `events.tsv` files is RECOMMENDED but not required. Researchers are encouraged to follow these guidelines to enhance the interoperability and reproducibility of their studies.
 
@@ -39,10 +39,10 @@ To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` co
 Example `events.tsv` file:
 
 | onset | duration | trial_type | response_time | stim_id |
-|-------|----------|------------|---------------|----------|
-| 1.23 | 0.65 | start | 1.435 | stim-\<label\> |
-| 5.65 | 0.65 | stop | 1.739 | stim-\<label\> |
-| 12.1 | 2.35 | n/a | n/a | stim-\<label\> |
+|-------|----------|------------|---------------|---------|
+| 1.23  | 0.65     | start      | 1.435         | stim-\<label\> |
+| 5.65  | 0.65     | stop       | 1.739         | stim-\<label\> |
+| 12.1  | 2.35     | n/a        | n/a           | stim-\<label\> |
 
 In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
 
@@ -50,7 +50,7 @@ In the accompanying JSON sidecar, the `stim_id` column might be described as fol
 {
     "stim_id": {
         "LongName": "Stimulus identifier",
-        "Description": "Represents a unique identifier for the stimulus presented at the given onset time.",
+        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
     }
 }
 ```
@@ -64,18 +64,17 @@ Stimulus files can be of various types including audio, image, video, and combin
 
 Then stimulus file names MUST start with `stim-` followed by a unique label, and an optional part label if the stimulus is divided into parts. `stim-` is the standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. The suffix SHOULD describe the type of stimulus (such as audio, image, video, audiovideo) and the extension MUST indicate the file format. The JSON sidecar file MUST have the same name as the stimulus file but with a `.json` extension. Here are the allowed suffixes and extensions for the stimulus files:
 
-| Modality | Extensions | Description |
-|----------|------------|-------------|
-| `audio` | .wav, .mp3, .aac, .ogg | Audio-only stimulus files |
-| `image` | .jpg, .png, .svg | Static visual stimulus files |
-| `video` | .mp4, .avi, .mkv, .webm | Video-only stimulus files |
-| `audioVideo` | .mp4, .avi, .mkv, .webm | Combined audio-visual stimulus files |
+| Modality     | Extensions                | Description                        |
+|--------------|---------------------------|------------------------------------|
+| `audio`      | .wav, .mp3, .aac, .ogg    | Audio-only stimulus files          |
+| `image`      | .jpg, .png, .svg          | Static visual stimulus files       |
+| `video`      | .mp4, .avi, .mkv, .webm   | Video-only stimulus files          |
+| `audioVideo` | .mp4, .avi, .mkv, .webm   | Combined audio-visual stimulus files |
 <!-- | Tactile | .ros | Robot Operating System program files for tactile stimulation | -->
 
 If distribution restrictions prevent including the actual stimulus file, the JSON sidecar SHOULD still be present with appropriate metadata describing the stimulus.
 For the stimuli that can be described in a table format (such as image datasets), the `stimuli.tsv` and `stimuli.json` files can be used to provide information about the stimuli based on their `stim_id`, and the presence of the stimulus file and JSON sidecar is OPTIONAL.
 
-
 The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL fields for the `stim-<label>.json` file:
 
 <!-- This block generates a metadata table.
@@ -106,13 +105,12 @@ and a guide for using macros can be found at
 
 This is an example of the `stimuli.tsv` file describing three images from the natural scene dataset (NSD):
 
-| stimulus_id | type | description | HED | NSD_id | COCO_id |
-|------------|------|-------------|-----|---------|----------|
+| stimulus_id  | type  | description | HED | NSD_id | COCO_id |
+|--------------|-------|-------------|-----|--------|---------|
 | stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
 | stim-nsd02991 | image | a couple of people are cooking in a room | (Foreground-view, ((Item-count/1, (Human, Body, Agent-trait/Adult)), (Item-count/1, (Human, Body, (Face, Away-from), Male, Agent-trait/Adult)), ((Item-count, High), Furnishing))), (Background-view, (Ingestible-object, Furnishing, Room, Indoors, Man-made-object, Assistive-device)) | 2991 | 262239 |
 | stim-nsd03050 | image | a person standing on a surfboard riding a wave | (Foreground-view, ((Item-count/1, ((Human, Human-agent), Body, Male, Agent-trait/Adolescent)), (Play, (Item-count/1, Man-made-object)))), (Background-view, (Outdoors, Natural-feature/Ocean)) | 3050 | 262414 |
 
-
 ### Stimuli.json
 
 The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. There can be extra entries in the `stimuli.json` in addition to the columns in the `stimuli.tsv` to provide more details about the stimulus.
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 0a999b0ee3..66164b665d 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -269,15 +269,15 @@ and a guide for using macros can be found at
 
 The operating system description SHOULD include the following attributes:
 
--   type (for example, Windows, macOS, Linux)
--   distribution (if applicable, for example, Ubuntu, Debian, CentOS)
--   the version number (for example, 18.04.5)
+- type (for example, Windows, macOS, Linux)
+- distribution (if applicable, for example, Ubuntu, Debian, CentOS)
+- the version number (for example, 18.04.5)
 
 Examples:
 
--   Windows 10, Version 2004
--   macOS 10.15.6
--   Linux Ubuntu 18.04.5
+- Windows 10, Version 2004
+- macOS 10.15.6
+- Linux Ubuntu 18.04.5
 
 The amount of information supplied for the `OperatingSystem` SHOULD be sufficient
 to re-run the code under maximally similar conditions.

From 1ef76bc2848a1d155426e7d5681935501d212ce5 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 15:54:25 -0800
Subject: [PATCH 08/21] Move extensions to their own place.

---
 src/schema/objects/suffixes.yaml           | 19 -------------------
 src/schema/rules/files/raw/audio.yaml      | 16 ++++++++++++++++
 src/schema/rules/files/raw/audiovideo.yaml | 12 ++++++++++++
 src/schema/rules/files/raw/image.yaml      | 14 ++++++++++++++
 src/schema/rules/files/raw/video.yaml      | 12 ++++++++++++
 5 files changed, 54 insertions(+), 19 deletions(-)
 create mode 100644 src/schema/rules/files/raw/audio.yaml
 create mode 100644 src/schema/rules/files/raw/audiovideo.yaml
 create mode 100644 src/schema/rules/files/raw/image.yaml
 create mode 100644 src/schema/rules/files/raw/video.yaml

diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 4d10371f93..69b9104286 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -886,11 +886,6 @@ audio:
     (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
     However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
     present with only JSON sidecar file containing the aforementioned pertinent metadata.
-  extensions:
-    - .wav
-    - .mp3
-    - .aac
-    - .ogg
 image:
   value: image
   display_name: Image stimulus file
@@ -900,10 +895,6 @@ image:
     (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
     However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
     present with only JSON sidecar file containing the aforementioned pertinent metadata.
-  extensions:
-    - .jpg
-    - .png
-    - .svg
 video:
   value: video
   display_name: Video stimulus file
@@ -913,11 +904,6 @@ video:
     (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
     However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
     present with only JSON sidecar file containing the aforementioned pertinent metadata.
-  extensions:
-    - .mp4
-    - .avi
-    - .mkv
-    - .webm
 audiovideo:
   value: audiovideo
   display_name: Audiovideo stimulus file
@@ -928,8 +914,3 @@ audiovideo:
     (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media.
     However, in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be
     present with only JSON sidecar file containing the aforementioned pertinent metadata.
-  extensions:
-    - .mp4
-    - .avi
-    - .mkv
-    - .webm
diff --git a/src/schema/rules/files/raw/audio.yaml b/src/schema/rules/files/raw/audio.yaml
new file mode 100644
index 0000000000..e19401dd55
--- /dev/null
+++ b/src/schema/rules/files/raw/audio.yaml
@@ -0,0 +1,16 @@
+---
+suffixes:
+  audio:
+    extensions:
+      - .wav
+      - .WAV
+      - .mp3
+      - .MP3
+      - .ogg
+      - .OGG
+      - .m4a
+      - .M4A
+      - .flac
+      - .FLAC
+      - .acc
+      - .ACC
diff --git a/src/schema/rules/files/raw/audiovideo.yaml b/src/schema/rules/files/raw/audiovideo.yaml
new file mode 100644
index 0000000000..2cc3161a8e
--- /dev/null
+++ b/src/schema/rules/files/raw/audiovideo.yaml
@@ -0,0 +1,12 @@
+---
+suffixes:
+  audiovideo:
+    extensions:
+      - .avi
+      - .AVI
+      - .mp4
+      - .MP4
+      - .mov
+      - .MOV
+      - .mkv
+      - .MKV
diff --git a/src/schema/rules/files/raw/image.yaml b/src/schema/rules/files/raw/image.yaml
new file mode 100644
index 0000000000..81942f3d94
--- /dev/null
+++ b/src/schema/rules/files/raw/image.yaml
@@ -0,0 +1,14 @@
+---
+suffixes:
+  image:
+    extensions:
+      - .jpg
+      - .JPG
+      - .jpeg
+      - .JPEG
+      - .png
+      - .PNG
+      - .gif
+      - .GIF
+      - .webp
+      - .WEBP
diff --git a/src/schema/rules/files/raw/video.yaml b/src/schema/rules/files/raw/video.yaml
new file mode 100644
index 0000000000..f6dca13bf4
--- /dev/null
+++ b/src/schema/rules/files/raw/video.yaml
@@ -0,0 +1,12 @@
+---
+suffixes:
+  video:
+    extensions:
+      - .avi
+      - .AVI
+      - .mp4
+      - .MP4
+      - .mov
+      - .MOV
+      - .mkv
+      - .MKV

From e84cac433e57a200658057dafc48db130cd13075 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 16:06:07 -0800
Subject: [PATCH 09/21] Revise the extensions

---
 src/schema/rules/files/raw/audio.yaml      | 36 +++++++++++++---------
 src/schema/rules/files/raw/audiovideo.yaml | 11 +++++--
 src/schema/rules/files/raw/image.yaml      | 31 +++++++++++--------
 src/schema/rules/files/raw/video.yaml      | 11 +++++--
 4 files changed, 55 insertions(+), 34 deletions(-)

diff --git a/src/schema/rules/files/raw/audio.yaml b/src/schema/rules/files/raw/audio.yaml
index e19401dd55..7f15957e22 100644
--- a/src/schema/rules/files/raw/audio.yaml
+++ b/src/schema/rules/files/raw/audio.yaml
@@ -1,16 +1,22 @@
 ---
-suffixes:
-  audio:
-    extensions:
-      - .wav
-      - .WAV
-      - .mp3
-      - .MP3
-      - .ogg
-      - .OGG
-      - .m4a
-      - .M4A
-      - .flac
-      - .FLAC
-      - .acc
-      - .ACC
+audio:
+  suffixes:
+    - audio
+  extensions:
+    - .wav
+    - .WAV
+    - .mp3
+    - .MP3
+    - .ogg
+    - .OGG
+    - .m4a
+    - .M4A
+    - .flac
+    - .FLAC
+    - .acc
+    - .ACC
+  entities:
+    stimulus: required
+    part: optional
+    annotation: optional
+
diff --git a/src/schema/rules/files/raw/audiovideo.yaml b/src/schema/rules/files/raw/audiovideo.yaml
index 2cc3161a8e..13d371244f 100644
--- a/src/schema/rules/files/raw/audiovideo.yaml
+++ b/src/schema/rules/files/raw/audiovideo.yaml
@@ -1,7 +1,8 @@
 ---
-suffixes:
-  audiovideo:
-    extensions:
+audiovideo:
+  suffixes:
+    - audiovideo
+  extensions:
       - .avi
       - .AVI
       - .mp4
@@ -10,3 +11,7 @@ suffixes:
       - .MOV
       - .mkv
       - .MKV
+  entities:
+    stimulus: required
+    part: optional
+    annotation: optional
diff --git a/src/schema/rules/files/raw/image.yaml b/src/schema/rules/files/raw/image.yaml
index 81942f3d94..d3d3d15920 100644
--- a/src/schema/rules/files/raw/image.yaml
+++ b/src/schema/rules/files/raw/image.yaml
@@ -1,14 +1,19 @@
 ---
-suffixes:
-  image:
-    extensions:
-      - .jpg
-      - .JPG
-      - .jpeg
-      - .JPEG
-      - .png
-      - .PNG
-      - .gif
-      - .GIF
-      - .webp
-      - .WEBP
+image:
+  suffixes:
+    - image
+  extensions:
+    - .jpg
+    - .JPG
+    - .jpeg
+    - .JPEG
+    - .png
+    - .PNG
+    - .gif
+    - .GIF
+    - .webp
+    - .WEBP
+  entities:
+    stimulus: required
+    part: optional
+    annotation: optional
diff --git a/src/schema/rules/files/raw/video.yaml b/src/schema/rules/files/raw/video.yaml
index f6dca13bf4..1f8da1a6ba 100644
--- a/src/schema/rules/files/raw/video.yaml
+++ b/src/schema/rules/files/raw/video.yaml
@@ -1,7 +1,8 @@
 ---
-suffixes:
-  video:
-    extensions:
+video:
+  suffixes:
+    - video
+  extensions:
       - .avi
       - .AVI
       - .mp4
@@ -10,3 +11,7 @@ suffixes:
       - .MOV
       - .mkv
       - .MKV
+  entities:
+    stimulus: required
+    part: optional
+    annotation: optional

From 1dd9083502c348bd3d5e537f910b647c89b4edbd Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Sat, 21 Dec 2024 16:08:32 -0800
Subject: [PATCH 10/21] YAML lint

---
 src/schema/rules/files/raw/audio.yaml      |  1 -
 src/schema/rules/files/raw/audiovideo.yaml | 16 ++++++++--------
 src/schema/rules/files/raw/video.yaml      | 16 ++++++++--------
 3 files changed, 16 insertions(+), 17 deletions(-)

diff --git a/src/schema/rules/files/raw/audio.yaml b/src/schema/rules/files/raw/audio.yaml
index 7f15957e22..c3650379de 100644
--- a/src/schema/rules/files/raw/audio.yaml
+++ b/src/schema/rules/files/raw/audio.yaml
@@ -19,4 +19,3 @@ audio:
     stimulus: required
     part: optional
     annotation: optional
-
diff --git a/src/schema/rules/files/raw/audiovideo.yaml b/src/schema/rules/files/raw/audiovideo.yaml
index 13d371244f..75fbe77288 100644
--- a/src/schema/rules/files/raw/audiovideo.yaml
+++ b/src/schema/rules/files/raw/audiovideo.yaml
@@ -3,14 +3,14 @@ audiovideo:
   suffixes:
     - audiovideo
   extensions:
-      - .avi
-      - .AVI
-      - .mp4
-      - .MP4
-      - .mov
-      - .MOV
-      - .mkv
-      - .MKV
+    - .avi
+    - .AVI
+    - .mp4
+    - .MP4
+    - .mov
+    - .MOV
+    - .mkv
+    - .MKV
   entities:
     stimulus: required
     part: optional
diff --git a/src/schema/rules/files/raw/video.yaml b/src/schema/rules/files/raw/video.yaml
index 1f8da1a6ba..8d2e5f9832 100644
--- a/src/schema/rules/files/raw/video.yaml
+++ b/src/schema/rules/files/raw/video.yaml
@@ -3,14 +3,14 @@ video:
   suffixes:
     - video
   extensions:
-      - .avi
-      - .AVI
-      - .mp4
-      - .MP4
-      - .mov
-      - .MOV
-      - .mkv
-      - .MKV
+    - .avi
+    - .AVI
+    - .mp4
+    - .MP4
+    - .mov
+    - .MOV
+    - .mkv
+    - .MKV
   entities:
     stimulus: required
     part: optional

From 49785525fd76310a43e334c6a684acb6f26a4def Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Mon, 30 Dec 2024 16:02:43 -0800
Subject: [PATCH 11/21] Sidecar description is only needed of rhte individual
 stimulus files.

---
 src/schema/rules/sidecars/stimuli.yaml  | 22 +++++++++++++++++
 src/schema/rules/sidecars/stimulus.yaml | 32 -------------------------
 2 files changed, 22 insertions(+), 32 deletions(-)
 create mode 100644 src/schema/rules/sidecars/stimuli.yaml
 delete mode 100644 src/schema/rules/sidecars/stimulus.yaml

diff --git a/src/schema/rules/sidecars/stimuli.yaml b/src/schema/rules/sidecars/stimuli.yaml
new file mode 100644
index 0000000000..067ad4bcb0
--- /dev/null
+++ b/src/schema/rules/sidecars/stimuli.yaml
@@ -0,0 +1,22 @@
+# Sidecar tables for stim-<label>_suffix.json, the stimuli.json and annotations.json do not need additional fields
+# as the fields have been already defined in the tabular data 
+
+Stimulus:
+  selectors:
+    - suffix == "audio"
+    - suffix == "video"
+    - suffix == "audiovideo"
+    - suffix == "image"
+  fields:
+    License:
+      recommended: true
+      description: License under which this stimulus is shared
+    Copyright:
+      recommended: true
+      description: Copyright information for this stimulus
+    URL:
+      optional: true
+      description: Location (origin) for the stimulus file
+    Description:
+      optional: true
+      description: Free-form description of the stimulus
diff --git a/src/schema/rules/sidecars/stimulus.yaml b/src/schema/rules/sidecars/stimulus.yaml
deleted file mode 100644
index 3029c4641e..0000000000
--- a/src/schema/rules/sidecars/stimulus.yaml
+++ /dev/null
@@ -1,32 +0,0 @@
-# Sidecar tables for stimuli.tsv/json, annotations.tsv/json, and stim-<label>.json
-
-Stimuli:
-  selectors:
-    - suffix == "stimuli"
-  fields:
-    onset: required
-    duration: required
-    trial_type: recommended
-    response_time: optional
-    stim_file: required
-    stim_id: required
-
-Annotations:
-  selectors:
-    - suffix == "annotations"
-  fields:
-    onset: required
-    duration: required
-    annotation_id: required
-    description: recommended
-    stim_file: optional
-    stim_id: optional
-
-Stimulus:
-  selectors:
-    - suffix == "stim"
-  fields:
-    License: recommended
-    Copyright: recommended
-    URL: optional
-    Description: optional

From 80d3077cdb890254a927b7e793bc6be258659f87 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 31 Dec 2024 00:03:33 +0000
Subject: [PATCH 12/21] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 src/schema/rules/sidecars/stimuli.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/schema/rules/sidecars/stimuli.yaml b/src/schema/rules/sidecars/stimuli.yaml
index 067ad4bcb0..389f7ea185 100644
--- a/src/schema/rules/sidecars/stimuli.yaml
+++ b/src/schema/rules/sidecars/stimuli.yaml
@@ -1,5 +1,5 @@
 # Sidecar tables for stim-<label>_suffix.json, the stimuli.json and annotations.json do not need additional fields
-# as the fields have been already defined in the tabular data 
+# as the fields have been already defined in the tabular data
 
 Stimulus:
   selectors:

From a335ebfaa3f71d8045efc1c378ee85b693d95e36 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Mon, 30 Dec 2024 16:05:00 -0800
Subject: [PATCH 13/21] tabular information matching the spec.

---
 src/schema/rules/tabular_data/stimuli.yaml | 30 ++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 src/schema/rules/tabular_data/stimuli.yaml

diff --git a/src/schema/rules/tabular_data/stimuli.yaml b/src/schema/rules/tabular_data/stimuli.yaml
new file mode 100644
index 0000000000..0bf84b9416
--- /dev/null
+++ b/src/schema/rules/tabular_data/stimuli.yaml
@@ -0,0 +1,30 @@
+---
+Stimuli:
+  selectors:
+    - suffix == "stimuli"
+  initial_columns:
+    - stimulus_id
+    - type
+  columns:
+    stimulus_id: required
+    type: required
+    URL: optional
+    license: recommended
+    copyright: optional
+    description: optional
+    HED: optional
+    filename: optional
+    present: optional
+    partDescription: optional
+  additional_columns: allowed_if_defined
+
+Annotations:
+  selectors:
+    - suffix == "annotations"
+  initial_columns:
+    - annot_id
+    - description
+  columns:
+    annot_id: required
+    description: required
+  additional_columns: allowed_if_defined

From f370c951b5ebc9628b5fb41076d31e6b0e736c7e Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Mon, 30 Dec 2024 21:39:20 -0800
Subject: [PATCH 14/21] Edit stimuli.md to reflect the spec more completely

---
 src/modality-specific-files/stimuli.md | 157 ++++++++++++++-----------
 1 file changed, 89 insertions(+), 68 deletions(-)

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index da0b1d5940..b47701503f 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -1,18 +1,25 @@
 # Stimuli
 
-Stimulus files should be stored in the `/stimuli` directory under the root directory of the dataset. The `/stimuli` directory can contain subdirectories to organize the stimulus files. Stimulus files SHOULD follow the BIDS naming conventions and SHOULD be referenced in the `events.tsv` file using the `stim_id` column. The `stim_id` column represents unique identifiers for the stimuli. Additional information about the stimuli and their annotations can be provided in the `stimuli.tsv`, `stimuli.json`, `annotations.tsv`, `annotations.json`, and `stim-<label>.json` files.
+## Stimulus Files Organization
 
-Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
+Stimulus files MUST be stored in the `/stimuli` directory under the root directory of the dataset.
+The `/stimuli` directory can contain subdirectories to organize the stimulus files.
+Stimulus files MUST follow the BIDS naming conventions and SHOULD be referenced in the `events.tsv`
+file using the `stim_id` column.
 
-1.  **Consistency**: Ensures that stimulus files are stored and referenced consistently across different datasets.
-2.  **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
-3.  **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
-4.  **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
+The standardization of stimulus files and their annotations within BIDS offers several key benefits:
+
+1. **Consistency**: Ensures uniform storage and referencing across datasets
+2. **Reusability**: Enables stimulus reuse across studies through standardized structure
+3. **Efficiency**: Minimizes redundancy by centralizing annotations
+4. **Flexibility**: Facilitates dataset reuse with alternative annotations
 
 To preserve backward compatibility with existing datasets (see the Legacy section below), the use of these specifications for `/stimuli` directory and the `stim_id` column in the `events.tsv` files is RECOMMENDED but not required. Researchers are encouraged to follow these guidelines to enhance the interoperability and reproducibility of their studies.
 
 Following these guidelines will help ensure that stimulus files and their annotations are stored and referenced consistently across different datasets, facilitating data sharing, reuse, and reproducibility.
 
+## File Organization
+
 <!-- 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
@@ -21,8 +28,8 @@ A guide for using macros can be found at
    "stimuli": {
     "stimuli.tsv": "",
     "stimuli.json": "",
-    "[stim-<label>[_part-<label>]_<suffix>.<extension>]": "",
-    "[stim-<label>[_part-<label>]_<suffix>.json]": "",
+    "[stim-<label>[_part-<label>]<suffix>.<extension>]": "",
+    "[stim-<label>[_part-<label>]<suffix>.json]": "",
     "[[stim-<label>_]annotations.tsv]": "",
     "[[stim-<label>_]annotations.json]": "",
     "[stim-<label>[_part-<label>]_annot-<label>_events.tsv]": "",
@@ -32,50 +39,20 @@ A guide for using macros can be found at
 
 Note: The presence of `stimuli.tsv` file indicates that the content of the `/stimuli` folder follows this BIDS specification for stimulus organization. This structure is planned to become mandatory in BIDS 2.0.
 
-## Referencing Stimulus Identifiers in `events.tsv`
-
-To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli. Stimulus ID (`stim_id`) should correspond to the unique identifier of the stimulus file in the /stimuli directory and expands to all files (both stimulus and annotation files) that share the same stimulus ID.
-
-Example `events.tsv` file:
-
-| onset | duration | trial_type | response_time | stim_id |
-|-------|----------|------------|---------------|---------|
-| 1.23  | 0.65     | start      | 1.435         | stim-\<label\> |
-| 5.65  | 0.65     | stop       | 1.739         | stim-\<label\> |
-| 12.1  | 2.35     | n/a        | n/a           | stim-\<label\> |
-
-In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
-
-```JSON
-{
-    "stim_id": {
-        "LongName": "Stimulus identifier",
-        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
-    }
-}
-```
-
-## The stimulus file and JSON sidecar
-
-Stimulus files can be of various types including audio, image, video, and combined audiovideo formats. Each stimulus file SHOULD have an accompanying JSON sidecar file containing metadata about the stimulus. The structure of the stimulus file name and the JSON sidecar file name SHOULD follow the BIDS naming conventions as below:
+### Stimulus File Formats
 
-- Stimulus file: `stim-<label>[_part-<label>]_<suffix>.<extension>`
-- JSON sidecar file: `stim-<label>[_part-<label>]_<suffix>.json`
+The following table lists the supported stimulus file formats and their corresponding suffixes. The suffixes are used to identify the type of stimulus file and are appended to the `stim-<label>` prefix in the file name.
 
-Then stimulus file names MUST start with `stim-` followed by a unique label, and an optional part label if the stimulus is divided into parts. `stim-` is the standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. The suffix SHOULD describe the type of stimulus (such as audio, image, video, audiovideo) and the extension MUST indicate the file format. The JSON sidecar file MUST have the same name as the stimulus file but with a `.json` extension. Here are the allowed suffixes and extensions for the stimulus files:
+| **suffix**  | **extensions**          | **description**                   |
+|-------------|-------------------------|-----------------------------------|
+| audio       | `.wav`, `.mp3`, `.aac`, `.ogg` | Audio-only stimulus files        |
+| image       | `.jpg`, `.png`, `.svg`  | Static visual stimulus files      |
+| video       | `.mp4`, `.avi`, `.mkv`, `.webm` | Video-only stimulus files        |
+| audiovideo  | `.mp4`, `.avi`, `.mkv`, `.webm` | Combined audio-visual files      |
 
-| Modality     | Extensions                | Description                        |
-|--------------|---------------------------|------------------------------------|
-| `audio`      | .wav, .mp3, .aac, .ogg    | Audio-only stimulus files          |
-| `image`      | .jpg, .png, .svg          | Static visual stimulus files       |
-| `video`      | .mp4, .avi, .mkv, .webm   | Video-only stimulus files          |
-| `audioVideo` | .mp4, .avi, .mkv, .webm   | Combined audio-visual stimulus files |
-<!-- | Tactile | .ros | Robot Operating System program files for tactile stimulation | -->
-
-If distribution restrictions prevent including the actual stimulus file, the JSON sidecar SHOULD still be present with appropriate metadata describing the stimulus.
-For the stimuli that can be described in a table format (such as image datasets), the `stimuli.tsv` and `stimuli.json` files can be used to provide information about the stimuli based on their `stim_id`, and the presence of the stimulus file and JSON sidecar is OPTIONAL.
-
-The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL fields for the `stim-<label>.json` file:
+## Stimulus description (`stim-<label>_<suffix>.json`)
+The `stim-<label>_<suffix>.json` file provides metadata about the *singular* stimulus file.
+The following fields are defined to describe the stimulus file:
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -87,11 +64,22 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("stimulus.Stimulus") }}
 
-## Stimuli.tsv and Stimuli.json
+In some cases, such as observing the copyright of a stimulus file, the actual stimulus file may not be shared. In such cases, the `stim-<label>_<suffix>.json` file SHOULD be used to provide metadata about the stimulus file, including the license, copyright, URL, and description.
 
-The `stimuli.tsv` and `stimuli.json` files are used to provide information about the stimuli based on their `stim_id`. This file is similar in usage as `participants.tsv`, `scans.tsv` and `sessions.tsv`, which list descriptions about subjects, scans and sessions, respectively. The `stimluli.tsv/json` files should be placed in the `/stimuli` directory.
+### Example `stim-<label>_<suffix>.json`
+
+```JSON
+{
+    "License": "CC-BY-4.0",
+    "Copyright": "Lab 2023",
+    "URL": "https://example.com/stimuli/",
+    "Description": "Collection of face images, tones, and movie clips used in the experiment"
+}
+```
 
-### Stimuli.tsv
+## Stimuli Description (`stimuli.tsv`)
+
+The `stimuli.tsv/json` files are used to provide information about the stimuli based on their `stim_id`. This file is similar in usage as `participants.tsv`, `scans.tsv` and `sessions.tsv`, which list descriptions about subjects, scans and sessions, respectively. The `stimluli.tsv/json` files MUST be placed in the `/stimuli` directory.
 
 The `stimuli.tsv` file contains information about each stimulus, including stimulus ID, type, URL, and other relevant details. The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL columns for the `stimuli.tsv` file:
 
@@ -103,25 +91,32 @@ and a guide for using macros can be found at
 -->
 {{ MACROS___make_columns_table("stimuli.Stimuli") }}
 
-This is an example of the `stimuli.tsv` file describing three images from the natural scene dataset (NSD):
+### Example `stimuli.tsv`
 
-| stimulus_id  | type  | description | HED | NSD_id | COCO_id |
-|--------------|-------|-------------|-----|--------|---------|
-| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
-| stim-nsd02991 | image | a couple of people are cooking in a room | (Foreground-view, ((Item-count/1, (Human, Body, Agent-trait/Adult)), (Item-count/1, (Human, Body, (Face, Away-from), Male, Agent-trait/Adult)), ((Item-count, High), Furnishing))), (Background-view, (Ingestible-object, Furnishing, Room, Indoors, Man-made-object, Assistive-device)) | 2991 | 262239 |
-| stim-nsd03050 | image | a person standing on a surfboard riding a wave | (Foreground-view, ((Item-count/1, ((Human, Human-agent), Body, Male, Agent-trait/Adolescent)), (Play, (Item-count/1, Man-made-object)))), (Background-view, (Outdoors, Natural-feature/Ocean)) | 3050 | 262414 |
+```Text
+stimulus_id    type     URL                                     license      copyright    description                                  present
+stim-face01   image    https://example.com/faces/face01.jpg    CC-BY-4.0   Lab 2023    A female face with neutral expression       true
+stim-tone01   audio    https://example.com/tones/tone01.wav    CC-BY-4.0   Lab 2023    A 440Hz pure tone                          true
+stim-movie01  video    https://example.com/movies/movie01.mp4  n/a         Studio XYZ  A clip from copyrighted movie              false
+```
 
-### Stimuli.json
+The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. There MAY be extra entries in the `stimuli.json` in addition to the columns in the `stimuli.tsv` to provide more details about the stimulus.
 
-The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. There can be extra entries in the `stimuli.json` in addition to the columns in the `stimuli.tsv` to provide more details about the stimulus.
+In cases where the stimulus is not shared, the `stimuli.tsv` file can be used to provide metadata about the stimuli, including the license, copyright, URL, and description. This is simialr to the use of `stim-<label>_<suffix>.json` files for individual stimuli files. In the case of conflict between the metadata in the `stimuli.tsv` and `stim-<label>_<suffix>.json` files, the metadata in the `stim-<label>_<suffix>.json` file takes precedence.
 
-## Annotations.tsv and Annotations.json
+## Stimulus Annotations
+Annotations of the still images or general description of the stimuli (such as frequency and duration of a beep sound) can be stored in the `stimuli.tsv` as an additional column or `stim-<label>_<suffix>.json` as described above. Here is an example of how annotations can be stored in the `stimuli.tsv` file for an image from the Natural Scene Dataset (NSD):
 
-The `annotations.tsv` and `annotations.json` files are used to provide additional information about the annotations associated with the stimuli. These files should be placed in the `/stimuli` directory.
+| stimulus_id  | type  | description | HED | NSD_id | COCO_id |
+|--------------|-------|-------------|-----|--------|---------|
+| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
 
-### Annotations.tsv
+However, for time-varying stimuli, such as audio or video, it is RECOMMENDED to use specific annotations files in the form of `stim-<label>_annot-<label>_events.tsv/json` to store the annotations. These files have the same structure as the `events.tsv/json` files and are used to store annotations for the stimuli. There can be multiple annotation files for a single stimulus file, each with a unique annotation label. The annotation files MUST be stored in the `/stimuli` directory.
 
-The `annotations.tsv` file contains information about each annotation, including the annotation ID and description. The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL columns for the `annotations.tsv` file:
+## Annotation Description (`annotations.tsv`)
+
+The `annotations.tsv` file contains additional metadata about stimulus annotations. There MAY be a single `annotations.tsv` file for all the stimuli or separate `stim-<label>_annotations.tsv` files for each stimulus.
+The following columns are defined for the `annotations.tsv` file:
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in
@@ -129,10 +124,36 @@ The definitions of these fields can be found in
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_columns_table("annotations.Annotations") }}
+{{ MACROS___make_columns_table("stimuli.Annotations") }}
+
+### Example `*_annotations.tsv`
 
-### Annotations.json
+```Text
+annot_id     description
+face01_emo   Emotion annotation for face01 stimulus
+face01_gen   Gender annotation for face01 stimulus
+face01_age   Age group annotation for face01 stimulus
+```
 
-The `annotations.json` file provides detailed descriptions of the columns in the `annotations.tsv` file.
+## Referencing Stimulus Identifiers in `events.tsv`
 
-There could be only one `annotations.tsv` in the `/stimuli` directory. Alternatively, each stimulus (with a unique stimulus ID) can have a separate `stim-<label>_annotations.tsv` to describe the annotations for a specific stimulus.
+To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` column. The values in the `stim_id` column should represent unique identifiers for the stimuli. Stimulus ID (`stim_id`) should correspond to the unique identifier of the stimulus file in the /stimuli directory and expands to all files (both stimulus and annotation files) that share the same stimulus ID.
+
+Example `events.tsv` file:
+
+| onset | duration | trial_type | response_time | stim_id |
+|-------|----------|------------|---------------|---------|
+| 1.23  | 0.65     | start      | 1.435         | `stim-<label>` |
+| 5.65  | 0.65     | stop       | 1.739         | `stim-<label>` |
+| 12.1  | 2.35     | n/a        | n/a           | `stim-<label>` |
+
+In the accompanying JSON sidecar, the `stim_id` column might be described as follows:
+
+```JSON
+{
+    "stim_id": {
+        "LongName": "Stimulus identifier",
+        "Description": "Represents a unique identifier for the stimulus presented at the given onset time."
+    }
+}
+```

From 330b69f8883724bdb1e56374cb53812617ded690 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Tue, 31 Dec 2024 12:24:59 -0800
Subject: [PATCH 15/21] Implement Kay's comments for clarity

---
 ... stimulus files and annotations in BIDS.md | 371 ++++++++++++++++++
 1 file changed, 371 insertions(+)
 create mode 100644 BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md

diff --git a/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md b/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md
new file mode 100644
index 0000000000..7bcdd87773
--- /dev/null
+++ b/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md	
@@ -0,0 +1,371 @@
+**THERE is a PR for this BEP: [BIDS-Spec \#2022](https://github.com/bids-standard/bids-specification/pull/2022). Please do not make changes here.**
+
+**Provide your edits and comments on the PR or directly email the moderators.**
+
+**Main BIDS issue [\#153](https://github.com/bids-standard/bids-specification/issues/153),**
+
+**Example PR [\#433](https://github.com/bids-standard/bids-examples/pull/433)**
+
+with references and insights from issues [\#751](https://github.com/bids-standard/bids-specification/issues/751), [\#750](https://github.com/bids-standard/bids-specification/issues/750),  and [BIDS2-devel/\#54](https://github.com/bids-standard/bids-2-devel/issues/54) (regarding alternative hierarchies). Another related issue is [\#1170](https://github.com/bids-standard/bids-specification/issues/1770) to include media files within the data folders.
+
+# BIDS Extension Proposal 44 (BEP044):
+
+# Stimuli
+
+## version 0.0.1
+
+## Available under the CC-BY 4.0 International license.
+
+Extension moderators/leads: [Seyed Yahya Shirazi](mailto:shirazi@ieee.org)  
+Contributors: Dora Hermes, Yaroslav O. Halchenko, Kay Robbins, Scott Makeig, Monique Denissen
+
+| This document contains a draft for BEP0X44. It is a community effort to define standards in data / metadata storage for Stimuli. This is a working document in draft stage and any comments are welcome.  This specification is an extension of BIDS, and general principles are shared. The specification should work for many different settings and facilitate the integration with other imaging methods. To see the original BIDS specification, see [this link](https://bids-specification.readthedocs.io). This document inherits all components of the original specification (e.g. how to store imaging data, events, stimuli and behavioral data), and should be seen as an extension of it, not a replacement. |
+| :---- |
+
+**Meta-notes (to be deleted in actual BEPs)**
+
+This template provides a general outline that conforms to the patterns in some previously existing BEPs. However, no BEP fully follows this template, and this should not be interpreted as a list of requirements. Anything that does not apply to your BEP can be freely deleted, and anything else can be freely added. For more inspiration, see the [BEP Lead Guidelines](https://docs.google.com/document/d/1pWmEEY-1-WuwBPNy5tDAxVJYQ9Een4hZJM06tQZg8X4/edit?usp%3Dsharing&sa=D&ust=1537468908724000), and [other BEPs](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification).
+
+# **Table of contents**
+
+[**Introduction	2**](#introduction)
+
+[**Terminology	3**](#terminology)
+
+[**Stim-BIDS	3**](#stim-bids)
+
+[**Structure	3**](#3.1.-directory-structure)
+
+[**Entities and suffixes (modalities) introduced for this feature request:	3**](#heading=h.g82534ipxafy)
+
+[**Examples:	4**](#examples:)
+
+[Example 1: Image presentation (still, not time-varying)	4](#example-1:-image-presentation-\(still,-not-time-varying\))
+
+[Example 2: Face presentation (still, not time-varying)	7](#example-2:-face-presentation-\(still,-not-time-varying\))
+
+[Example 3: Movie example (time-varying)	8](#example-3:-movie-example-\(time-varying\))
+
+[Example of a stimulus file with a link to a movie and annotations	9](#example-4:-non-shareable-copyrighted-movie-example-\(time-varying\))
+
+[Other examples…	10](#other-examples-\(what-are-common-use-cases?\)…)
+
+[**Relation to  \`\*\_events.tsv\` and \`\*\_stim.tsv.gz\` files	10**](#relation-to-\`*_events.tsv\`-and-\`*_stim.tsv.gz\`-files)
+
+1. # **Introduction** {#introduction}
+
+Current BIDS specifications provide an option to include stimulus files (e.g., still images, movies, sounds, etc.) in the top \`/stimuli\` directory and to use the \`\*\_events.json\` and \`\*\_events.tsv\` files to define “which stimulus file was used for a given event.” This solution is a convenient method to avoid the need to repeat these stimulus files across subject or session directories, and to point to stimuli from public databases. However, **there is not currently a solution to list these stimuli and to hold the annotations related to the stimulus files.** Providing a structure and metadata for the stimulus files will make the experiments using specific stimuli more Findable, Accessible, Interoperable, and Reusable (FAIR). Also, possible annotations of the stimulus files do not need to be repeated in all `_events.tsv` files across subjects and sessions, and can be included and disseminated once in the `stimuli` directory.
+
+Following the BIDS convention of having a list of entities in the hierarchy (such as participants.tsv, scan.tsv, sessions.tsv, etc.), we propose having a similar `stimuli.tsv` that lists all the stimulus files in the `stimuli/` directory. For the annotation of the stimulus files, a straightforward solution is to include the annotations in the \`/stimuli\` folder with a distinction between annotations for **still (i.e., non-time-varying) stimulus files** (e.g., images, VR physical constructs, etc.) and annotations for **time-varying stimulus files** (i.e., movies, sounds, haptic feedback, etc.). A single-line annotation would be sufficient for the still stimulus files. However, a time-varying stimulus file could need separate annotations for every frame (i.e., the smallest temporal resolution of the stimulus file).
+
+Based on (1) the BIDS Common Principles for file names to “consist of a chain of entity instances and a suffix all separated by underscores,” (2) existing facilities to include Tabular files and Key-Value files with data files, (3) and an existing mechanism for summary tables (such as `participants.tsv` and `scans.tsv`), we propose a structure for the `stimuli/` directory to accommodate (i) stimulus files with multiple parts and tracks, (ii) annotation of both still and time-varying stimuli, and (ii) multiple annotations of the stimulus files. 
+
+2. # **Terminology** {#terminology}
+
+BIDS contains “required”, “recommended” and “optional” fields. These are indicated throughout the document:
+
+* REQUIRED: essential to be BIDS compliant (i.e. MUST as per RFC2199)  
+* RECOMMENDED: gives a warning if not present (i.e. SHOULD as per RFC2199)  
+* OPTIONAL: no warning if missing (i.e. MAY as per RFC2199)
+
+
+As in BIDS-Raw, the following apply:
+
+1) All specifications of paths need to use forward slashes.  
+2) The inheritance principle applies: any metadata file (.json, .tsv, etc.) may be defined at any directory level. The values from the top level are inherited by all lower levels unless they are overridden by a file at the lower level. For details see BIDS-Raw ([The Inheritance Principle](https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#the-inheritance-principle)).
+
+## **2.1 Entites and data types**
+
+We propose the following entities and data types to be added to BIDS to properly annotate the stimulus files.  
+**stim- (entity):** The standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. Subsequently, the `stimuli.tsv/json` (plural of stimulus) and `stimulus_id` will be generated for the stim-xxx stimulus files.
+
+**\_{audio, image, video, audiovideo} (suffix)**: Any data file (medium, plural: media) used as a stimulus. Media files usually have an audio-visual file type (such as png/jpg/mp4/mp3/mkv). The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media. However, **in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.**  
+Other types of stimuli to consider (10%?):   
+\- \_ros(tactile?).ros \- Robot Operating System program file … simulink is another file format for the same.
+
+| modality | extension | extension specification source | license |
+| :---- | :---- | :---- | :---- |
+| audio | .wav, .mp3, .aac, .ogg |  |  |
+| image | .jpg, .png, .svg |  |  |
+| video | .mp4, .avi, .mkv, .webm |  |  |
+| audiovideo | .mp4, .avi, .mkv, .webm |  |  |
+
+**annot- (entity):** Accommodates multiple annotations for a single (usually, but not necessarily, time-varying) stimulus id. Similar to `stimuli.tsv`, there can be one or multiple `annotations.tsv` files with `annotation_id`, providing a list of the annotations in the directory, or for a specific stimulus respectively (see 3.1).
+
+**part- (entity):** The `_part-` entity could be used to tell apart different, possibly overlapping, parts of a single stimulus, e.g. a long movie (e.g. `_part-1`, `_part-2`) or an audiobook (e.g. `_part-epilog`, `_part-chapter1`, …). Part is currently defined in BIDS specifications as “indicate which component of the complex representation of the MRI signal is represented in voxel data.” The definition should be expanded for all modalities, including stimuli. 
+
+**stim\_file (column in the *events.tsv):*** *Currently, it can only point to a stimulus file or a database.* The column name should be expanded to also  `stim_id`. The definition should be expanded to be either a specific file in the stimuli directory, a database, or a `stimulus_id`. In the latter case, all files sharing the `stimulus_id` will be in scope as well as the entry associated with the `stimulus_id` in `stimuli.tsv`.
+
+3. # **Stim-BIDS** {#stim-bids}
+
+## **3.1. Directory Structure** {#3.1.-directory-structure}
+
+└── stimuli/
+
+├── stimuli.tsv
+
+└── stimuli.json
+
+**Note:** presence of stimuli.tsv file would mandate the bids-validator to validate the content of stimuli/ folder to follow BEP044 specification.  
+**Proposal:** make BEP044 layout of stimuli/ to be mandatory for BIDS 2.0 ([bids-2-devel/issues/83](https://github.com/bids-standard/bids-2-devel/issues/83)).
+
+If stimuli.tsv is present the stimulus files in this directory MUST follow this naming structure: *(If non-audio, image, or video files are stored here, what will the extension become?)*
+
+ └── stimuli
+
+├── \[stim-\<label\>\[\_part-\<label\>\]\_\<suffix\>.\<extension\>\]
+
+└── \[stim-\<label\>\[\_part-\<label\>\]\_\<suffix\>.json\]
+
+Currently supported suffixes (see 2.1):
+
+- audio  
+- audiovideo  
+- image  
+- video
+
+If annotations are added:
+
+└── stimuli
+
+├── \[\[stim-\<label\>\_\]annotations.tsv\]
+
+├── \[\[stim-\<label\>\_\]annotations.json\]
+
+├── stim-\<label\>\[\_part-\<label\>\]\_annot-\<label\>\_events.tsv
+
+└── \[stim-\<label\>\[\_part-\<label\>\]\_annot-\<label\>\_events.json\]
+
+with annotations.tsv providing description similarly to [descriptions.tsv](https://bids-specification.readthedocs.io/en/stable/derivatives/common-data-types.html#descriptionstsv) providing descriptions to \_desc- entities with two REQUIRED columns `annotation_id` and `description`, followed by arbitrary number of OPTIONAL columns (e.g., rater\_age, annotation\_modality, etc). annotations.json would provide a description of columns in the annotations.tsv (similarly to `descriptions.json`, `participants.json` etc).
+
+If annotations and their features are generic to all stimuli, a single common `annotations.tsv` file can be used. If annotations are specific for a certain stimulus, the optional `[stim-<label>_]` prefix can be used. (This is analogous to the way in which `sessions.tsv` is used)
+
+For still images or body of words (that are not time-varying), multiple annotations could be included in the `stimuli.tsv/json` in separate columns. NOTE: Image-type stimuli SHOULD NOT use `_annot-events.tsv/json`. Additional annotations can be added to `stimuli.tsv/json` or the `stim-<label>.json` sidecar.
+
+Sidecar metadata and extensions most likely to align with 
+
+- [https://github.com/bids-standard/bids-specification/issues/1771](https://github.com/bids-standard/bids-specification/issues/1771) RFC: BEP for audio/video capture of behaving subjects 
+
+## 
+
+## **3.3. `stimuli.tsv/json`**
+
+The `stimuli.json` file describes the columns of the `stimuli.tsv` file, therefore snake\_case.
+
+If `stimuli.tsv` is present, it is RECOMMENDED that `stimuli.json` is also present.
+
+| Column name | Requirement Level | Data type | Description |
+| :---- | :---- | :---- | :---- |
+| stimulus\_id | REQUIRED | String | A stimulus ID in the form of stim-\<label\>, Represents a pointer stimulus file (such as an image, video, or audio file). There are no restrictions on the file formats of the stimuli files, but they should be stored in the /stimuli directory (under the root directory of the dataset; with OPTIONAL subdirectories). The values under the stim\_file column correspond to a path relative to /stimuli. For example for  stim-nsd02951\_image.png the stimulus\_id is stim-nsd0251.  This column MUST appear as the first column in the file. Alternative 1: stimulus\_id should be unique and only file of a single type could be associated with stimulus\_id.  In case of different stimulus types for the same stimulus concept, stimulus\_id should reflect composition of stimulus concept and type. |
+| type | REQUIRED | String | Freeform or ‘one of’ video, image, audio, audiovideo. If present, this column MUST appear as the second column in the file. Alternative 2: In case of files with different types for the same stimulus\_id, type MUST NOT be used. If it is desired to have per-type row/description \- stimulus\_id should reflect composition of stimulus concept and type. Aleternatively, the type can be sdescribed in the individual stimulus JSON sidecar. |
+| URL | OPTIONAL (REQUIRED, if the stimulus file or json is not available) | String | Location (origin) for the stimuli file. |
+| license  | RECOMMENDED | String | The license for the stimulus set. The use of license name abbreviations is OPTIONAL for specifying a license (see [Licenses](https://bids-specification.readthedocs.io/en/stable/appendices/licenses.html)). The corresponding full license text MAY be specified in an additional LICENSE file. |
+| copyright | OPTIONAL | String | Year(s) and Copyright owner for the particular stimuli media |
+| description | OPTIONAL | String | Freeform description of stimuli |
+| HED | OPTIONAL | String | Hierarchical Event Descriptor (HED) Tag. See the [HED Appendix](https://bids-specification.readthedocs.io/en/stable/appendices/hed.html) for details. This column may appear anywhere in the file. |
+| filename | OPTIONAL | String | For annotations corresponding to a single file (for example, when there is a multi-part stimulus), users may optionally include the filename of the stimulus being annotated.   Tools may then use this name to locate the stimulus file corresponding to this annotation. This column may appear anywhere in the file. |
+| present | OPTIONAL | Bool | Bool (true/false), Indicating whether the stimulus file is present in the directory (true). |
+| partDescription | OPTIONAL | String | Description of the multiple parts of a stimulus. |
+| Additional columns | OPTIONAL | String | Additional columns are allowed. |
+
+# **3.4. `annotations.tsv/json`**
+
+If `annotations.tsv` is present, it is RECOMMENDED that `annotations.json` is also present.
+
+| Column name | Requirement Level | Data type | Description |
+| :---- | :---- | :---- | :---- |
+| annot\_id | REQUIRED | [string](https://www.w3schools.com/js/js_json_datatypes.asp) | A desc-\<label\> entity present in the derivatives dataset. The desc\_id column contains the labels used with the [desc entity](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#desc), within the particular nesting that the descriptions.tsv file is placed. For example, if the descriptions.tsv file is placed at the root of the derivative dataset, its desc\_id column SHOULD contain all labels of the desc entity) used across the entire derivative dataset.  Values in desc\_id MUST be unique. This column must appear first in the file. |
+| [description](https://bids-specification.readthedocs.io/en/stable/glossary.html#objects.columns.description__entities) | REQUIRED | [string](https://www.w3schools.com/js/js_json_datatypes.asp) | Free-form text description of the entity's label (defined in \<entity\>\_id column). The corresponding label column is desc\_id. This column must appear second in the file. |
+| Additional Columns | OPTIONAL | n/a | Additional columns are allowed. |
+
+# **3.5. `stim-<label>.json`**
+
+Key values follow 3.3 stimuli.tsv/json. If a field is present in both `stim-<label>.json` and stimuli.tsv/json, the `stim-<label>.json` SHOULD override.
+
+# **Examples:** {#examples:}
+
+A draft pull request is created on the BIDS Examples to include the examples below in detail.
+
+## **Example 1: Image presentation (still, not time-varying)** {#example-1:-image-presentation-(still,-not-time-varying)}
+
+Below is an example of a \`/stimuli\` directory with three images from the NSD image database, as HED-annotated by Clair Holmes at Mayo Clinic (in the [NSD-HED-label](https://github.com/MultimodalNeuroimagingLab/nsd_hed_labels/blob/main/shared1000_HED.tsv) repository):
+
+The example */stimuli* directory:
+
+└── stimuli
+
+├── stimuli.tsv
+
+├── stimuli.json
+
+├── stim-nsd02951\_image.png
+
+├── \[stim-nsd02951\_image.json\]
+
+├── stim-nsd02991\_image.png
+
+├── \[stim-nsd02991\_image.json\]
+
+├── stim-nsd03050\_image.png
+
+└── \[stim-nsd03050\_image.json\]
+
+When optional columns in stimuli.tsv file are added as in the example below, these must be described in the stimuli.json 
+
+| NSD\_id | OPTIONAL. Image ID in the Natural Scenes Dataset  [https://naturalscenesdataset.org/](https://naturalscenesdataset.org/)  |
+| :---- | :---- |
+| COCO\_id | OPTIONAL. Image ID in the COCO database  [https://cocodataset.org/](https://cocodataset.org/)  |
+
+The example */stimuli/stimuli.tsv* file:
+
+| stimulus\_id | type | description | HED | NSD\_id | COCO\_id |
+| :---- | :---- | :---- | :---- | :---- | :---- |
+| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
+| stim-nsd02991 | image | a couple of people are cooking in a room | (Foreground-view, ((Item-count/1, (Human, Body, Agent-trait/Adult)), (Item-count/1, (Human, Body, (Face, Away-from), Male, Agent-trait/Adult)), ((Item-count, High), Furnishing))), (Background-view, (Ingestible-object, Furnishing, Room, Indoors, Man-made-object, Assistive-device)) | 2991 | 262239 |
+| stim-nsd03050 | image | a person standing on a surfboard riding a wave | (Foreground-view, ((Item-count/1, ((Human, Human-agent), Body, Male, Agent-trait/Adolescent)), (Play, (Item-count/1, Man-made-object)))), (Background-view, (Outdoors, Natural-feature/Ocean)) | 3050 | 262414 |
+
+Exemplary downstream \*\_events.tsv (bids\_dir/sub-\<label\>/sub-\<label\>*task-\<label\>\_*events.tsv)
+
+Imagine that, in a study, the three images listed above are shown to the subject, the following would be one row of the data-level \`\*\_events.tsv\` file:
+
+\[\*\_events.tsv file example, subject file\] (non-expanded version)
+
+| onset | duration | stim\_file |
+| :---- | :---- | :---- |
+| 25.033 | 1.02 | stim-nsd02951\_image.png |
+
+## **Example 2: Face presentation (still, not time-varying)**  {#example-2:-face-presentation-(still,-not-time-varying)}
+
+\[This is from the Wakeman-Hansen dataset (ds000117, ds003645), currently the most cited electrophysiology dataset on OpenNeuro\]. The example uses direct annotation of the stimulus images by HED in the stimuli.tsv file without the use of a stimuli.json file. 
+
+**Example:** stimuli.tsv using direct HED annotation with no stimuli.json
+
+| stimulus\_id | type | description | HED |
+| :---- | :---- | :---- | :---- |
+| stim-cross | image | A white fixation cross on a black background in the center of the screen. | (Foreground-view, (White, Cross), (Center-of, Computer-screen)), (Background-view, Black) |
+| stim-f001 | image | A female face that should be recognized by the participants. | (Foreground-view, (Image, (Face, Famous, Female), (Center-of, Computer-screen)), (Background-view, Black) |
+| stim-s005 | image | A scrambled face image generated by taking face 2D FFT. | (Foreground-view, (Image, (Face, Disordered), (Center-of, Computer-screen)), (Background-view, Black) |
+| stim-u112 | image | A male face that should not be recognized by the participants. | (Foreground-view, (Image, (Face, Male, Unfamiliar), (Center-of, Computer-screen)),(Background-view, Black) |
+
+The stimulus files themselves are named stim-cross\_image.bmp, stim-f001\_image.bmp, stim-s005\_image.bmp, and stim-u112\_image.bmp.
+
+An edited version of the main  sub\_002\_task-FacePerception\_run-1\_events.tsv file is:
+
+| onset | duration | event\_type | stim\_file |
+| :---- | :---- | :---- | :---- |
+| 26.731 | n/a | show\_cross | stim-cross |
+| 27.246 | n/a | show\_face | stim-u143 |
+| 27.893 | n/a | left\_press | n/a |
+| 29.796 | n/a | show\_cross | stim-cross |
+| 30.353 | n/a | show\_face | stim-f001 |
+| 32.884 | n/a | show\_cross | stim-cross |
+| 33.360 | n/a | show\_face | stim-s005 |
+
+| onset | duration | event\_type | stim\_file |
+| :---- | :---- | :---- | :---- |
+| 26.731 | n/a | show\_cross | cross.bmp |
+| 27.246 | n/a | show\_face | u143.bmp |
+| 27.893 | n/a | left\_press | n/a |
+| 29.796 | n/a | show\_cross | cross.bmp |
+| 30.353 | n/a | show\_face | f0001.bmp |
+| 32.884 | n/a | show\_cross | cross.bmp |
+| 33.360 | n/a | show\_face | s005.bmp |
+
+Since the stim\_file column entries do not have extensions, they are interpreted as stimulus\_id values, and their annotations are looked up using the stimulus\_id column of stimuli.tsv. If the values in the stim\_file column of the main \_events.tsv file have an extension, tools may search for corresponding annotations in the optional filename column of stimuli.tsv.  
+The above example annotated each of the images individually, resulting in duplication of annotations.  Users can also use the stimuli.json file and categorical columns with HED to reduce this redundancy. HED support of the stimuli.tsv/stimuli.json will be handled similarly to the annotation of the participants.tsv/participants.json.
+
+## 
+
+## **Example 3: Movie example (time-varying)** {#example-3:-movie-example-(time-varying)}
+
+Below is an example of a `/stimuli` directory with a movie (called [The Present](https://youtu.be/WjqiU5FgsYc)) used for the [Healthy Brain Network’s](https://healthybrainnetwork.org) EEG and fMRI studies:
+
+The example */stimuli* directory:
+
+└── stimuli
+
+├── stimuli.tsv
+
+├── stimuli.json 
+
+├── \[annotations.tsv\]
+
+├── \[annotations.json\]
+
+├── stim-thepresent\_audiovideo.mp4
+
+├── \[stim-thepresent\_audiovideo.json\]
+
+├── stim-thepresent\_annot-LogLumRatio\_events.tsv
+
+└── stim-thepresent\_annot-LogLumRatio\_events.json
+
+The example /stimuli/stimuli.tsv file:
+
+| stimulus\_id | type | HED |
+| :---- | :---- | :---- |
+| stim-thepresent | audiovideo | Visual-presentation, Movie |
+
+The example /stimuli/stim-thepresent\_annot-LogLumRatio\_events.tsv file:
+
+| onset | duration | shot\_number | LLR |
+| :---- | :---- | :---- | :---- |
+| 0 | n/a | video\_start | n/a |
+| 0 | 7.25 | 1 | n/a |
+| 7.25 | 3.542 | 2 | \-1.557820733 |
+| 10.792 | 5.208 | 3 | 0.3358234903 |
+
+\[sub-01\_task-thepresent\_events.tsv file example for a specific subject\](non-expanded version)
+
+| onset | duration | value | stim\_file |
+| :---- | :---- | :---- | :---- |
+| 1.0380 | 1.0 | video\_start | stim-thepresent\_annot-LogLumRatio\_events.tsv |
+| 204.10 | 1 | video\_stop | stim-thepresent\_annot-LogLumRatio\_events.tsv |
+
+## **Example 4: Non-shareable copyrighted movie example (time-varying)** {#example-4:-non-shareable-copyrighted-movie-example-(time-varying)}
+
+In some cases it may not be possible to share stimuli or movies shown to participants due to e.g. copyright or confidentiality issues. In this case, a link to a stimulus can be included or annotations for all stimuli can be shared. One such example would look as follows:
+
+Below is an example of a `/stimuli` directory with a movie:
+
+The example `/stimuli` directory:
+
+└── stimuli
+
+├── stimuli.tsv
+
+├── stimuli.json
+
+├── **stim-thepresent\_audiovideo.json**
+
+├── stim-thepresent\_annot-LogLumRatio\_events.tsv
+
+└── stim-thepresent\_annot-LogLumRatio\_events.json
+
+The example /stimuli/stimuli.tsv file:
+
+| stimulus\_id | type | HED |
+| :---- | :---- | :---- |
+| stim-thepresent | audiovideo | Visual-presentation, Movie |
+
+The example of stim-thepresent\_audiovideo.json would be:
+
+| stimSource | OPTIONAL. A link to the stimulus source file In this example:  [https://youtu.be/3XA0bB79oGc?si=Tnyd-7oFRzd0xCr9](https://youtu.be/3XA0bB79oGc?si=Tnyd-7oFRzd0xCr9)  |
+| :---- | :---- |
+
+## **Other examples (what are common use cases?)…** {#other-examples-(what-are-common-use-cases?)…}
+
+- Example 5: (long) Movie or audiobook split into parts.  
+  - Counter-example: since \_part in mri means something else, corresponding data file would **not** be 1-to-1 matching via \_task-forrest\_part-... and need to be ad-hoc like \_task-forrest1 or \_task-forrest\_run-1  
+  - This may be a good example: [https://github.com/psychoinformatics-de/studyforrest-data-annotations.git](https://github.com/psychoinformatics-de/studyforrest-data-annotations.git)   
+- Example 6: Parts of the story randomized for investigation of temporal structuring
+
+# **Relation to  \`\*\_events.tsv\` and \`\*\_stim.tsv.gz\` files** {#relation-to-`*_events.tsv`-and-`*_stim.tsv.gz`-files}
+
+\[*\`\*\_events.tsv\` is defined under [BIDS-specificaitons/modality-specifc files/task events](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/05-task-events.html). \`\*\_stim.tsv.gz\` files is defined in [BIDS-specificaitons/modality-specifc files/Physiological and other continuous recordings](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continuous-recordings.html)*.\]
+
+The annotations within the `stimuli.tsv` and `_annot-<label>_events.tsv` files can be expanded in the downstream `*_events.tsv` files when the file name is mentioned in the `stim_file` or `stim_id` column *(The use of `stim_id` is not defined under BIDS events specifications, and should be expanded in the pull request)*.
+
+While the contents of `stimuli.tsv` and `_annot-<label>_events.tsv` can also be included in the individual `*_events.tsv` files, such implementation unnecessarily replicates annotations across subjects, modalities, tasks, and runs. Also, using `stimuli.tsv` and `_annot-<label>_events.tsv` increases the possibility of both (1) reusing the same annotations in other studies and (2) reusing the dataset with alternative annotations – by merely changing one file. Using the current inefficient ‘within-\`\_events.tsv\`’ mechanism hinders reusing the annotations (for example, annotations of complex stimuli or standard stimulus sets) and complicates reusing the datasets using alternate annotations – as in the current specification, these annotations would have to be replaced in every data directory `*_events.tsv` and `*_events.json` file.
+
+Another advantage of top-level `stimuli.tsv` and `_annot-<label>_events.tsv` is avoiding the need to create and edit large `*_events.tsv/json` files for datasets that use complex stimuli, such as movies. By avoiding the need to include annotations in every data folder, the processing toolbox will retrieve these annotations housed in the single top-level `/stimuli` directory during the analysis. This will increase the readability of all the data level  `*_events.tsv` and `*_events.json` files and avoid using fixed, lengthy annotations to annotate every instance of a constant stimulus. For large, standard stimulus sets, such as the [Natural Scene Dataset](https://naturalscenesdataset.org) or the immense [COCO image dataset](https://cocodataset.org/), holding a list of images used across the BIDS dataset in the top-level `/stimuli` directory, with their complete annotations, would give a useful cross-reference for debugging and design of analyses.
\ No newline at end of file

From ad24800cedb23c6f00a95c9fb69e098d26b105d1 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 31 Dec 2024 20:25:27 +0000
Subject: [PATCH 16/21] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 ... stimulus files and annotations in BIDS.md | 50 +++++++++----------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md b/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md
index 7bcdd87773..9fc775f048 100644
--- a/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md	
+++ b/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md	
@@ -16,7 +16,7 @@ with references and insights from issues [\#751](https://github.com/bids-standar
 
 ## Available under the CC-BY 4.0 International license.
 
-Extension moderators/leads: [Seyed Yahya Shirazi](mailto:shirazi@ieee.org)  
+Extension moderators/leads: [Seyed Yahya Shirazi](mailto:shirazi@ieee.org)
 Contributors: Dora Hermes, Yaroslav O. Halchenko, Kay Robbins, Scott Makeig, Monique Denissen
 
 | This document contains a draft for BEP0X44. It is a community effort to define standards in data / metadata storage for Stimuli. This is a working document in draft stage and any comments are welcome.  This specification is an extension of BIDS, and general principles are shared. The specification should work for many different settings and facilitate the integration with other imaging methods. To see the original BIDS specification, see [this link](https://bids-specification.readthedocs.io). This document inherits all components of the original specification (e.g. how to store imaging data, events, stimuli and behavioral data), and should be seen as an extension of it, not a replacement. |
@@ -58,29 +58,29 @@ Current BIDS specifications provide an option to include stimulus files (e.g., s
 
 Following the BIDS convention of having a list of entities in the hierarchy (such as participants.tsv, scan.tsv, sessions.tsv, etc.), we propose having a similar `stimuli.tsv` that lists all the stimulus files in the `stimuli/` directory. For the annotation of the stimulus files, a straightforward solution is to include the annotations in the \`/stimuli\` folder with a distinction between annotations for **still (i.e., non-time-varying) stimulus files** (e.g., images, VR physical constructs, etc.) and annotations for **time-varying stimulus files** (i.e., movies, sounds, haptic feedback, etc.). A single-line annotation would be sufficient for the still stimulus files. However, a time-varying stimulus file could need separate annotations for every frame (i.e., the smallest temporal resolution of the stimulus file).
 
-Based on (1) the BIDS Common Principles for file names to “consist of a chain of entity instances and a suffix all separated by underscores,” (2) existing facilities to include Tabular files and Key-Value files with data files, (3) and an existing mechanism for summary tables (such as `participants.tsv` and `scans.tsv`), we propose a structure for the `stimuli/` directory to accommodate (i) stimulus files with multiple parts and tracks, (ii) annotation of both still and time-varying stimuli, and (ii) multiple annotations of the stimulus files. 
+Based on (1) the BIDS Common Principles for file names to “consist of a chain of entity instances and a suffix all separated by underscores,” (2) existing facilities to include Tabular files and Key-Value files with data files, (3) and an existing mechanism for summary tables (such as `participants.tsv` and `scans.tsv`), we propose a structure for the `stimuli/` directory to accommodate (i) stimulus files with multiple parts and tracks, (ii) annotation of both still and time-varying stimuli, and (ii) multiple annotations of the stimulus files.
 
 2. # **Terminology** {#terminology}
 
 BIDS contains “required”, “recommended” and “optional” fields. These are indicated throughout the document:
 
-* REQUIRED: essential to be BIDS compliant (i.e. MUST as per RFC2199)  
-* RECOMMENDED: gives a warning if not present (i.e. SHOULD as per RFC2199)  
+* REQUIRED: essential to be BIDS compliant (i.e. MUST as per RFC2199)
+* RECOMMENDED: gives a warning if not present (i.e. SHOULD as per RFC2199)
 * OPTIONAL: no warning if missing (i.e. MAY as per RFC2199)
 
 
 As in BIDS-Raw, the following apply:
 
-1) All specifications of paths need to use forward slashes.  
+1) All specifications of paths need to use forward slashes.
 2) The inheritance principle applies: any metadata file (.json, .tsv, etc.) may be defined at any directory level. The values from the top level are inherited by all lower levels unless they are overridden by a file at the lower level. For details see BIDS-Raw ([The Inheritance Principle](https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#the-inheritance-principle)).
 
 ## **2.1 Entites and data types**
 
-We propose the following entities and data types to be added to BIDS to properly annotate the stimulus files.  
+We propose the following entities and data types to be added to BIDS to properly annotate the stimulus files.
 **stim- (entity):** The standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. Subsequently, the `stimuli.tsv/json` (plural of stimulus) and `stimulus_id` will be generated for the stim-xxx stimulus files.
 
-**\_{audio, image, video, audiovideo} (suffix)**: Any data file (medium, plural: media) used as a stimulus. Media files usually have an audio-visual file type (such as png/jpg/mp4/mp3/mkv). The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media. However, **in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.**  
-Other types of stimuli to consider (10%?):   
+**\_{audio, image, video, audiovideo} (suffix)**: Any data file (medium, plural: media) used as a stimulus. Media files usually have an audio-visual file type (such as png/jpg/mp4/mp3/mkv). The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media. However, **in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.**
+Other types of stimuli to consider (10%?):
 \- \_ros(tactile?).ros \- Robot Operating System program file … simulink is another file format for the same.
 
 | modality | extension | extension specification source | license |
@@ -92,7 +92,7 @@ Other types of stimuli to consider (10%?):
 
 **annot- (entity):** Accommodates multiple annotations for a single (usually, but not necessarily, time-varying) stimulus id. Similar to `stimuli.tsv`, there can be one or multiple `annotations.tsv` files with `annotation_id`, providing a list of the annotations in the directory, or for a specific stimulus respectively (see 3.1).
 
-**part- (entity):** The `_part-` entity could be used to tell apart different, possibly overlapping, parts of a single stimulus, e.g. a long movie (e.g. `_part-1`, `_part-2`) or an audiobook (e.g. `_part-epilog`, `_part-chapter1`, …). Part is currently defined in BIDS specifications as “indicate which component of the complex representation of the MRI signal is represented in voxel data.” The definition should be expanded for all modalities, including stimuli. 
+**part- (entity):** The `_part-` entity could be used to tell apart different, possibly overlapping, parts of a single stimulus, e.g. a long movie (e.g. `_part-1`, `_part-2`) or an audiobook (e.g. `_part-epilog`, `_part-chapter1`, …). Part is currently defined in BIDS specifications as “indicate which component of the complex representation of the MRI signal is represented in voxel data.” The definition should be expanded for all modalities, including stimuli.
 
 **stim\_file (column in the *events.tsv):*** *Currently, it can only point to a stimulus file or a database.* The column name should be expanded to also  `stim_id`. The definition should be expanded to be either a specific file in the stimuli directory, a database, or a `stimulus_id`. In the latter case, all files sharing the `stimulus_id` will be in scope as well as the entry associated with the `stimulus_id` in `stimuli.tsv`.
 
@@ -106,7 +106,7 @@ Other types of stimuli to consider (10%?):
 
 └── stimuli.json
 
-**Note:** presence of stimuli.tsv file would mandate the bids-validator to validate the content of stimuli/ folder to follow BEP044 specification.  
+**Note:** presence of stimuli.tsv file would mandate the bids-validator to validate the content of stimuli/ folder to follow BEP044 specification.
 **Proposal:** make BEP044 layout of stimuli/ to be mandatory for BIDS 2.0 ([bids-2-devel/issues/83](https://github.com/bids-standard/bids-2-devel/issues/83)).
 
 If stimuli.tsv is present the stimulus files in this directory MUST follow this naming structure: *(If non-audio, image, or video files are stored here, what will the extension become?)*
@@ -119,9 +119,9 @@ If stimuli.tsv is present the stimulus files in this directory MUST follow this
 
 Currently supported suffixes (see 2.1):
 
-- audio  
-- audiovideo  
-- image  
+- audio
+- audiovideo
+- image
 - video
 
 If annotations are added:
@@ -142,11 +142,11 @@ If annotations and their features are generic to all stimuli, a single common `a
 
 For still images or body of words (that are not time-varying), multiple annotations could be included in the `stimuli.tsv/json` in separate columns. NOTE: Image-type stimuli SHOULD NOT use `_annot-events.tsv/json`. Additional annotations can be added to `stimuli.tsv/json` or the `stim-<label>.json` sidecar.
 
-Sidecar metadata and extensions most likely to align with 
+Sidecar metadata and extensions most likely to align with
 
-- [https://github.com/bids-standard/bids-specification/issues/1771](https://github.com/bids-standard/bids-specification/issues/1771) RFC: BEP for audio/video capture of behaving subjects 
+- [https://github.com/bids-standard/bids-specification/issues/1771](https://github.com/bids-standard/bids-specification/issues/1771) RFC: BEP for audio/video capture of behaving subjects
 
-## 
+##
 
 ## **3.3. `stimuli.tsv/json`**
 
@@ -210,7 +210,7 @@ The example */stimuli* directory:
 
 └── \[stim-nsd03050\_image.json\]
 
-When optional columns in stimuli.tsv file are added as in the example below, these must be described in the stimuli.json 
+When optional columns in stimuli.tsv file are added as in the example below, these must be described in the stimuli.json
 
 | NSD\_id | OPTIONAL. Image ID in the Natural Scenes Dataset  [https://naturalscenesdataset.org/](https://naturalscenesdataset.org/)  |
 | :---- | :---- |
@@ -236,7 +236,7 @@ Imagine that, in a study, the three images listed above are shown to the subject
 
 ## **Example 2: Face presentation (still, not time-varying)**  {#example-2:-face-presentation-(still,-not-time-varying)}
 
-\[This is from the Wakeman-Hansen dataset (ds000117, ds003645), currently the most cited electrophysiology dataset on OpenNeuro\]. The example uses direct annotation of the stimulus images by HED in the stimuli.tsv file without the use of a stimuli.json file. 
+\[This is from the Wakeman-Hansen dataset (ds000117, ds003645), currently the most cited electrophysiology dataset on OpenNeuro\]. The example uses direct annotation of the stimulus images by HED in the stimuli.tsv file without the use of a stimuli.json file.
 
 **Example:** stimuli.tsv using direct HED annotation with no stimuli.json
 
@@ -271,10 +271,10 @@ An edited version of the main  sub\_002\_task-FacePerception\_run-1\_events.tsv
 | 32.884 | n/a | show\_cross | cross.bmp |
 | 33.360 | n/a | show\_face | s005.bmp |
 
-Since the stim\_file column entries do not have extensions, they are interpreted as stimulus\_id values, and their annotations are looked up using the stimulus\_id column of stimuli.tsv. If the values in the stim\_file column of the main \_events.tsv file have an extension, tools may search for corresponding annotations in the optional filename column of stimuli.tsv.  
+Since the stim\_file column entries do not have extensions, they are interpreted as stimulus\_id values, and their annotations are looked up using the stimulus\_id column of stimuli.tsv. If the values in the stim\_file column of the main \_events.tsv file have an extension, tools may search for corresponding annotations in the optional filename column of stimuli.tsv.
 The above example annotated each of the images individually, resulting in duplication of annotations.  Users can also use the stimuli.json file and categorical columns with HED to reduce this redundancy. HED support of the stimuli.tsv/stimuli.json will be handled similarly to the annotation of the participants.tsv/participants.json.
 
-## 
+##
 
 ## **Example 3: Movie example (time-varying)** {#example-3:-movie-example-(time-varying)}
 
@@ -286,7 +286,7 @@ The example */stimuli* directory:
 
 ├── stimuli.tsv
 
-├── stimuli.json 
+├── stimuli.json
 
 ├── \[annotations.tsv\]
 
@@ -355,9 +355,9 @@ The example of stim-thepresent\_audiovideo.json would be:
 
 ## **Other examples (what are common use cases?)…** {#other-examples-(what-are-common-use-cases?)…}
 
-- Example 5: (long) Movie or audiobook split into parts.  
-  - Counter-example: since \_part in mri means something else, corresponding data file would **not** be 1-to-1 matching via \_task-forrest\_part-... and need to be ad-hoc like \_task-forrest1 or \_task-forrest\_run-1  
-  - This may be a good example: [https://github.com/psychoinformatics-de/studyforrest-data-annotations.git](https://github.com/psychoinformatics-de/studyforrest-data-annotations.git)   
+- Example 5: (long) Movie or audiobook split into parts.
+  - Counter-example: since \_part in mri means something else, corresponding data file would **not** be 1-to-1 matching via \_task-forrest\_part-... and need to be ad-hoc like \_task-forrest1 or \_task-forrest\_run-1
+  - This may be a good example: [https://github.com/psychoinformatics-de/studyforrest-data-annotations.git](https://github.com/psychoinformatics-de/studyforrest-data-annotations.git)
 - Example 6: Parts of the story randomized for investigation of temporal structuring
 
 # **Relation to  \`\*\_events.tsv\` and \`\*\_stim.tsv.gz\` files** {#relation-to-`*_events.tsv`-and-`*_stim.tsv.gz`-files}
@@ -368,4 +368,4 @@ The annotations within the `stimuli.tsv` and `_annot-<label>_events.tsv` files c
 
 While the contents of `stimuli.tsv` and `_annot-<label>_events.tsv` can also be included in the individual `*_events.tsv` files, such implementation unnecessarily replicates annotations across subjects, modalities, tasks, and runs. Also, using `stimuli.tsv` and `_annot-<label>_events.tsv` increases the possibility of both (1) reusing the same annotations in other studies and (2) reusing the dataset with alternative annotations – by merely changing one file. Using the current inefficient ‘within-\`\_events.tsv\`’ mechanism hinders reusing the annotations (for example, annotations of complex stimuli or standard stimulus sets) and complicates reusing the datasets using alternate annotations – as in the current specification, these annotations would have to be replaced in every data directory `*_events.tsv` and `*_events.json` file.
 
-Another advantage of top-level `stimuli.tsv` and `_annot-<label>_events.tsv` is avoiding the need to create and edit large `*_events.tsv/json` files for datasets that use complex stimuli, such as movies. By avoiding the need to include annotations in every data folder, the processing toolbox will retrieve these annotations housed in the single top-level `/stimuli` directory during the analysis. This will increase the readability of all the data level  `*_events.tsv` and `*_events.json` files and avoid using fixed, lengthy annotations to annotate every instance of a constant stimulus. For large, standard stimulus sets, such as the [Natural Scene Dataset](https://naturalscenesdataset.org) or the immense [COCO image dataset](https://cocodataset.org/), holding a list of images used across the BIDS dataset in the top-level `/stimuli` directory, with their complete annotations, would give a useful cross-reference for debugging and design of analyses.
\ No newline at end of file
+Another advantage of top-level `stimuli.tsv` and `_annot-<label>_events.tsv` is avoiding the need to create and edit large `*_events.tsv/json` files for datasets that use complex stimuli, such as movies. By avoiding the need to include annotations in every data folder, the processing toolbox will retrieve these annotations housed in the single top-level `/stimuli` directory during the analysis. This will increase the readability of all the data level  `*_events.tsv` and `*_events.json` files and avoid using fixed, lengthy annotations to annotate every instance of a constant stimulus. For large, standard stimulus sets, such as the [Natural Scene Dataset](https://naturalscenesdataset.org) or the immense [COCO image dataset](https://cocodataset.org/), holding a list of images used across the BIDS dataset in the top-level `/stimuli` directory, with their complete annotations, would give a useful cross-reference for debugging and design of analyses.

From a5acd547804cc368635edf6d73d9708b7917a11b Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Tue, 31 Dec 2024 12:30:49 -0800
Subject: [PATCH 17/21] Revert adding BEP044 doc, implementing Kay's
 suggestions.

---
 ... stimulus files and annotations in BIDS.md | 371 ------------------
 src/modality-specific-files/stimuli.md        |  12 +-
 2 files changed, 6 insertions(+), 377 deletions(-)
 delete mode 100644 BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md

diff --git a/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md b/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md
deleted file mode 100644
index 9fc775f048..0000000000
--- a/BEP044_ Stimuli, organizing stimulus files and annotations in BIDS.md	
+++ /dev/null
@@ -1,371 +0,0 @@
-**THERE is a PR for this BEP: [BIDS-Spec \#2022](https://github.com/bids-standard/bids-specification/pull/2022). Please do not make changes here.**
-
-**Provide your edits and comments on the PR or directly email the moderators.**
-
-**Main BIDS issue [\#153](https://github.com/bids-standard/bids-specification/issues/153),**
-
-**Example PR [\#433](https://github.com/bids-standard/bids-examples/pull/433)**
-
-with references and insights from issues [\#751](https://github.com/bids-standard/bids-specification/issues/751), [\#750](https://github.com/bids-standard/bids-specification/issues/750),  and [BIDS2-devel/\#54](https://github.com/bids-standard/bids-2-devel/issues/54) (regarding alternative hierarchies). Another related issue is [\#1170](https://github.com/bids-standard/bids-specification/issues/1770) to include media files within the data folders.
-
-# BIDS Extension Proposal 44 (BEP044):
-
-# Stimuli
-
-## version 0.0.1
-
-## Available under the CC-BY 4.0 International license.
-
-Extension moderators/leads: [Seyed Yahya Shirazi](mailto:shirazi@ieee.org)
-Contributors: Dora Hermes, Yaroslav O. Halchenko, Kay Robbins, Scott Makeig, Monique Denissen
-
-| This document contains a draft for BEP0X44. It is a community effort to define standards in data / metadata storage for Stimuli. This is a working document in draft stage and any comments are welcome.  This specification is an extension of BIDS, and general principles are shared. The specification should work for many different settings and facilitate the integration with other imaging methods. To see the original BIDS specification, see [this link](https://bids-specification.readthedocs.io). This document inherits all components of the original specification (e.g. how to store imaging data, events, stimuli and behavioral data), and should be seen as an extension of it, not a replacement. |
-| :---- |
-
-**Meta-notes (to be deleted in actual BEPs)**
-
-This template provides a general outline that conforms to the patterns in some previously existing BEPs. However, no BEP fully follows this template, and this should not be interpreted as a list of requirements. Anything that does not apply to your BEP can be freely deleted, and anything else can be freely added. For more inspiration, see the [BEP Lead Guidelines](https://docs.google.com/document/d/1pWmEEY-1-WuwBPNy5tDAxVJYQ9Een4hZJM06tQZg8X4/edit?usp%3Dsharing&sa=D&ust=1537468908724000), and [other BEPs](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification).
-
-# **Table of contents**
-
-[**Introduction	2**](#introduction)
-
-[**Terminology	3**](#terminology)
-
-[**Stim-BIDS	3**](#stim-bids)
-
-[**Structure	3**](#3.1.-directory-structure)
-
-[**Entities and suffixes (modalities) introduced for this feature request:	3**](#heading=h.g82534ipxafy)
-
-[**Examples:	4**](#examples:)
-
-[Example 1: Image presentation (still, not time-varying)	4](#example-1:-image-presentation-\(still,-not-time-varying\))
-
-[Example 2: Face presentation (still, not time-varying)	7](#example-2:-face-presentation-\(still,-not-time-varying\))
-
-[Example 3: Movie example (time-varying)	8](#example-3:-movie-example-\(time-varying\))
-
-[Example of a stimulus file with a link to a movie and annotations	9](#example-4:-non-shareable-copyrighted-movie-example-\(time-varying\))
-
-[Other examples…	10](#other-examples-\(what-are-common-use-cases?\)…)
-
-[**Relation to  \`\*\_events.tsv\` and \`\*\_stim.tsv.gz\` files	10**](#relation-to-\`*_events.tsv\`-and-\`*_stim.tsv.gz\`-files)
-
-1. # **Introduction** {#introduction}
-
-Current BIDS specifications provide an option to include stimulus files (e.g., still images, movies, sounds, etc.) in the top \`/stimuli\` directory and to use the \`\*\_events.json\` and \`\*\_events.tsv\` files to define “which stimulus file was used for a given event.” This solution is a convenient method to avoid the need to repeat these stimulus files across subject or session directories, and to point to stimuli from public databases. However, **there is not currently a solution to list these stimuli and to hold the annotations related to the stimulus files.** Providing a structure and metadata for the stimulus files will make the experiments using specific stimuli more Findable, Accessible, Interoperable, and Reusable (FAIR). Also, possible annotations of the stimulus files do not need to be repeated in all `_events.tsv` files across subjects and sessions, and can be included and disseminated once in the `stimuli` directory.
-
-Following the BIDS convention of having a list of entities in the hierarchy (such as participants.tsv, scan.tsv, sessions.tsv, etc.), we propose having a similar `stimuli.tsv` that lists all the stimulus files in the `stimuli/` directory. For the annotation of the stimulus files, a straightforward solution is to include the annotations in the \`/stimuli\` folder with a distinction between annotations for **still (i.e., non-time-varying) stimulus files** (e.g., images, VR physical constructs, etc.) and annotations for **time-varying stimulus files** (i.e., movies, sounds, haptic feedback, etc.). A single-line annotation would be sufficient for the still stimulus files. However, a time-varying stimulus file could need separate annotations for every frame (i.e., the smallest temporal resolution of the stimulus file).
-
-Based on (1) the BIDS Common Principles for file names to “consist of a chain of entity instances and a suffix all separated by underscores,” (2) existing facilities to include Tabular files and Key-Value files with data files, (3) and an existing mechanism for summary tables (such as `participants.tsv` and `scans.tsv`), we propose a structure for the `stimuli/` directory to accommodate (i) stimulus files with multiple parts and tracks, (ii) annotation of both still and time-varying stimuli, and (ii) multiple annotations of the stimulus files.
-
-2. # **Terminology** {#terminology}
-
-BIDS contains “required”, “recommended” and “optional” fields. These are indicated throughout the document:
-
-* REQUIRED: essential to be BIDS compliant (i.e. MUST as per RFC2199)
-* RECOMMENDED: gives a warning if not present (i.e. SHOULD as per RFC2199)
-* OPTIONAL: no warning if missing (i.e. MAY as per RFC2199)
-
-
-As in BIDS-Raw, the following apply:
-
-1) All specifications of paths need to use forward slashes.
-2) The inheritance principle applies: any metadata file (.json, .tsv, etc.) may be defined at any directory level. The values from the top level are inherited by all lower levels unless they are overridden by a file at the lower level. For details see BIDS-Raw ([The Inheritance Principle](https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#the-inheritance-principle)).
-
-## **2.1 Entites and data types**
-
-We propose the following entities and data types to be added to BIDS to properly annotate the stimulus files.
-**stim- (entity):** The standard entity for the stimulus files, indicating that the files do not belong to a specific subject or participant but rather are likely to be used across subjects throughout the experiment. Subsequently, the `stimuli.tsv/json` (plural of stimulus) and `stimulus_id` will be generated for the stim-xxx stimulus files.
-
-**\_{audio, image, video, audiovideo} (suffix)**: Any data file (medium, plural: media) used as a stimulus. Media files usually have an audio-visual file type (such as png/jpg/mp4/mp3/mkv). The JSON file associated with each media file should contain information such as License (RECOMMENDED), Copyright (RECOMMENDED), URL (OPTIONAL), and Description (OPTIONAL) to describe the origin and the nature of the media. However, **in the case of the imposed distribution restrictions of the stimulus, the media stimulus file may not be present with only JSON sidecar file containing the aforementioned pertinent metadata.**
-Other types of stimuli to consider (10%?):
-\- \_ros(tactile?).ros \- Robot Operating System program file … simulink is another file format for the same.
-
-| modality | extension | extension specification source | license |
-| :---- | :---- | :---- | :---- |
-| audio | .wav, .mp3, .aac, .ogg |  |  |
-| image | .jpg, .png, .svg |  |  |
-| video | .mp4, .avi, .mkv, .webm |  |  |
-| audiovideo | .mp4, .avi, .mkv, .webm |  |  |
-
-**annot- (entity):** Accommodates multiple annotations for a single (usually, but not necessarily, time-varying) stimulus id. Similar to `stimuli.tsv`, there can be one or multiple `annotations.tsv` files with `annotation_id`, providing a list of the annotations in the directory, or for a specific stimulus respectively (see 3.1).
-
-**part- (entity):** The `_part-` entity could be used to tell apart different, possibly overlapping, parts of a single stimulus, e.g. a long movie (e.g. `_part-1`, `_part-2`) or an audiobook (e.g. `_part-epilog`, `_part-chapter1`, …). Part is currently defined in BIDS specifications as “indicate which component of the complex representation of the MRI signal is represented in voxel data.” The definition should be expanded for all modalities, including stimuli.
-
-**stim\_file (column in the *events.tsv):*** *Currently, it can only point to a stimulus file or a database.* The column name should be expanded to also  `stim_id`. The definition should be expanded to be either a specific file in the stimuli directory, a database, or a `stimulus_id`. In the latter case, all files sharing the `stimulus_id` will be in scope as well as the entry associated with the `stimulus_id` in `stimuli.tsv`.
-
-3. # **Stim-BIDS** {#stim-bids}
-
-## **3.1. Directory Structure** {#3.1.-directory-structure}
-
-└── stimuli/
-
-├── stimuli.tsv
-
-└── stimuli.json
-
-**Note:** presence of stimuli.tsv file would mandate the bids-validator to validate the content of stimuli/ folder to follow BEP044 specification.
-**Proposal:** make BEP044 layout of stimuli/ to be mandatory for BIDS 2.0 ([bids-2-devel/issues/83](https://github.com/bids-standard/bids-2-devel/issues/83)).
-
-If stimuli.tsv is present the stimulus files in this directory MUST follow this naming structure: *(If non-audio, image, or video files are stored here, what will the extension become?)*
-
- └── stimuli
-
-├── \[stim-\<label\>\[\_part-\<label\>\]\_\<suffix\>.\<extension\>\]
-
-└── \[stim-\<label\>\[\_part-\<label\>\]\_\<suffix\>.json\]
-
-Currently supported suffixes (see 2.1):
-
-- audio
-- audiovideo
-- image
-- video
-
-If annotations are added:
-
-└── stimuli
-
-├── \[\[stim-\<label\>\_\]annotations.tsv\]
-
-├── \[\[stim-\<label\>\_\]annotations.json\]
-
-├── stim-\<label\>\[\_part-\<label\>\]\_annot-\<label\>\_events.tsv
-
-└── \[stim-\<label\>\[\_part-\<label\>\]\_annot-\<label\>\_events.json\]
-
-with annotations.tsv providing description similarly to [descriptions.tsv](https://bids-specification.readthedocs.io/en/stable/derivatives/common-data-types.html#descriptionstsv) providing descriptions to \_desc- entities with two REQUIRED columns `annotation_id` and `description`, followed by arbitrary number of OPTIONAL columns (e.g., rater\_age, annotation\_modality, etc). annotations.json would provide a description of columns in the annotations.tsv (similarly to `descriptions.json`, `participants.json` etc).
-
-If annotations and their features are generic to all stimuli, a single common `annotations.tsv` file can be used. If annotations are specific for a certain stimulus, the optional `[stim-<label>_]` prefix can be used. (This is analogous to the way in which `sessions.tsv` is used)
-
-For still images or body of words (that are not time-varying), multiple annotations could be included in the `stimuli.tsv/json` in separate columns. NOTE: Image-type stimuli SHOULD NOT use `_annot-events.tsv/json`. Additional annotations can be added to `stimuli.tsv/json` or the `stim-<label>.json` sidecar.
-
-Sidecar metadata and extensions most likely to align with
-
-- [https://github.com/bids-standard/bids-specification/issues/1771](https://github.com/bids-standard/bids-specification/issues/1771) RFC: BEP for audio/video capture of behaving subjects
-
-##
-
-## **3.3. `stimuli.tsv/json`**
-
-The `stimuli.json` file describes the columns of the `stimuli.tsv` file, therefore snake\_case.
-
-If `stimuli.tsv` is present, it is RECOMMENDED that `stimuli.json` is also present.
-
-| Column name | Requirement Level | Data type | Description |
-| :---- | :---- | :---- | :---- |
-| stimulus\_id | REQUIRED | String | A stimulus ID in the form of stim-\<label\>, Represents a pointer stimulus file (such as an image, video, or audio file). There are no restrictions on the file formats of the stimuli files, but they should be stored in the /stimuli directory (under the root directory of the dataset; with OPTIONAL subdirectories). The values under the stim\_file column correspond to a path relative to /stimuli. For example for  stim-nsd02951\_image.png the stimulus\_id is stim-nsd0251.  This column MUST appear as the first column in the file. Alternative 1: stimulus\_id should be unique and only file of a single type could be associated with stimulus\_id.  In case of different stimulus types for the same stimulus concept, stimulus\_id should reflect composition of stimulus concept and type. |
-| type | REQUIRED | String | Freeform or ‘one of’ video, image, audio, audiovideo. If present, this column MUST appear as the second column in the file. Alternative 2: In case of files with different types for the same stimulus\_id, type MUST NOT be used. If it is desired to have per-type row/description \- stimulus\_id should reflect composition of stimulus concept and type. Aleternatively, the type can be sdescribed in the individual stimulus JSON sidecar. |
-| URL | OPTIONAL (REQUIRED, if the stimulus file or json is not available) | String | Location (origin) for the stimuli file. |
-| license  | RECOMMENDED | String | The license for the stimulus set. The use of license name abbreviations is OPTIONAL for specifying a license (see [Licenses](https://bids-specification.readthedocs.io/en/stable/appendices/licenses.html)). The corresponding full license text MAY be specified in an additional LICENSE file. |
-| copyright | OPTIONAL | String | Year(s) and Copyright owner for the particular stimuli media |
-| description | OPTIONAL | String | Freeform description of stimuli |
-| HED | OPTIONAL | String | Hierarchical Event Descriptor (HED) Tag. See the [HED Appendix](https://bids-specification.readthedocs.io/en/stable/appendices/hed.html) for details. This column may appear anywhere in the file. |
-| filename | OPTIONAL | String | For annotations corresponding to a single file (for example, when there is a multi-part stimulus), users may optionally include the filename of the stimulus being annotated.   Tools may then use this name to locate the stimulus file corresponding to this annotation. This column may appear anywhere in the file. |
-| present | OPTIONAL | Bool | Bool (true/false), Indicating whether the stimulus file is present in the directory (true). |
-| partDescription | OPTIONAL | String | Description of the multiple parts of a stimulus. |
-| Additional columns | OPTIONAL | String | Additional columns are allowed. |
-
-# **3.4. `annotations.tsv/json`**
-
-If `annotations.tsv` is present, it is RECOMMENDED that `annotations.json` is also present.
-
-| Column name | Requirement Level | Data type | Description |
-| :---- | :---- | :---- | :---- |
-| annot\_id | REQUIRED | [string](https://www.w3schools.com/js/js_json_datatypes.asp) | A desc-\<label\> entity present in the derivatives dataset. The desc\_id column contains the labels used with the [desc entity](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html#desc), within the particular nesting that the descriptions.tsv file is placed. For example, if the descriptions.tsv file is placed at the root of the derivative dataset, its desc\_id column SHOULD contain all labels of the desc entity) used across the entire derivative dataset.  Values in desc\_id MUST be unique. This column must appear first in the file. |
-| [description](https://bids-specification.readthedocs.io/en/stable/glossary.html#objects.columns.description__entities) | REQUIRED | [string](https://www.w3schools.com/js/js_json_datatypes.asp) | Free-form text description of the entity's label (defined in \<entity\>\_id column). The corresponding label column is desc\_id. This column must appear second in the file. |
-| Additional Columns | OPTIONAL | n/a | Additional columns are allowed. |
-
-# **3.5. `stim-<label>.json`**
-
-Key values follow 3.3 stimuli.tsv/json. If a field is present in both `stim-<label>.json` and stimuli.tsv/json, the `stim-<label>.json` SHOULD override.
-
-# **Examples:** {#examples:}
-
-A draft pull request is created on the BIDS Examples to include the examples below in detail.
-
-## **Example 1: Image presentation (still, not time-varying)** {#example-1:-image-presentation-(still,-not-time-varying)}
-
-Below is an example of a \`/stimuli\` directory with three images from the NSD image database, as HED-annotated by Clair Holmes at Mayo Clinic (in the [NSD-HED-label](https://github.com/MultimodalNeuroimagingLab/nsd_hed_labels/blob/main/shared1000_HED.tsv) repository):
-
-The example */stimuli* directory:
-
-└── stimuli
-
-├── stimuli.tsv
-
-├── stimuli.json
-
-├── stim-nsd02951\_image.png
-
-├── \[stim-nsd02951\_image.json\]
-
-├── stim-nsd02991\_image.png
-
-├── \[stim-nsd02991\_image.json\]
-
-├── stim-nsd03050\_image.png
-
-└── \[stim-nsd03050\_image.json\]
-
-When optional columns in stimuli.tsv file are added as in the example below, these must be described in the stimuli.json
-
-| NSD\_id | OPTIONAL. Image ID in the Natural Scenes Dataset  [https://naturalscenesdataset.org/](https://naturalscenesdataset.org/)  |
-| :---- | :---- |
-| COCO\_id | OPTIONAL. Image ID in the COCO database  [https://cocodataset.org/](https://cocodataset.org/)  |
-
-The example */stimuli/stimuli.tsv* file:
-
-| stimulus\_id | type | description | HED | NSD\_id | COCO\_id |
-| :---- | :---- | :---- | :---- | :---- | :---- |
-| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
-| stim-nsd02991 | image | a couple of people are cooking in a room | (Foreground-view, ((Item-count/1, (Human, Body, Agent-trait/Adult)), (Item-count/1, (Human, Body, (Face, Away-from), Male, Agent-trait/Adult)), ((Item-count, High), Furnishing))), (Background-view, (Ingestible-object, Furnishing, Room, Indoors, Man-made-object, Assistive-device)) | 2991 | 262239 |
-| stim-nsd03050 | image | a person standing on a surfboard riding a wave | (Foreground-view, ((Item-count/1, ((Human, Human-agent), Body, Male, Agent-trait/Adolescent)), (Play, (Item-count/1, Man-made-object)))), (Background-view, (Outdoors, Natural-feature/Ocean)) | 3050 | 262414 |
-
-Exemplary downstream \*\_events.tsv (bids\_dir/sub-\<label\>/sub-\<label\>*task-\<label\>\_*events.tsv)
-
-Imagine that, in a study, the three images listed above are shown to the subject, the following would be one row of the data-level \`\*\_events.tsv\` file:
-
-\[\*\_events.tsv file example, subject file\] (non-expanded version)
-
-| onset | duration | stim\_file |
-| :---- | :---- | :---- |
-| 25.033 | 1.02 | stim-nsd02951\_image.png |
-
-## **Example 2: Face presentation (still, not time-varying)**  {#example-2:-face-presentation-(still,-not-time-varying)}
-
-\[This is from the Wakeman-Hansen dataset (ds000117, ds003645), currently the most cited electrophysiology dataset on OpenNeuro\]. The example uses direct annotation of the stimulus images by HED in the stimuli.tsv file without the use of a stimuli.json file.
-
-**Example:** stimuli.tsv using direct HED annotation with no stimuli.json
-
-| stimulus\_id | type | description | HED |
-| :---- | :---- | :---- | :---- |
-| stim-cross | image | A white fixation cross on a black background in the center of the screen. | (Foreground-view, (White, Cross), (Center-of, Computer-screen)), (Background-view, Black) |
-| stim-f001 | image | A female face that should be recognized by the participants. | (Foreground-view, (Image, (Face, Famous, Female), (Center-of, Computer-screen)), (Background-view, Black) |
-| stim-s005 | image | A scrambled face image generated by taking face 2D FFT. | (Foreground-view, (Image, (Face, Disordered), (Center-of, Computer-screen)), (Background-view, Black) |
-| stim-u112 | image | A male face that should not be recognized by the participants. | (Foreground-view, (Image, (Face, Male, Unfamiliar), (Center-of, Computer-screen)),(Background-view, Black) |
-
-The stimulus files themselves are named stim-cross\_image.bmp, stim-f001\_image.bmp, stim-s005\_image.bmp, and stim-u112\_image.bmp.
-
-An edited version of the main  sub\_002\_task-FacePerception\_run-1\_events.tsv file is:
-
-| onset | duration | event\_type | stim\_file |
-| :---- | :---- | :---- | :---- |
-| 26.731 | n/a | show\_cross | stim-cross |
-| 27.246 | n/a | show\_face | stim-u143 |
-| 27.893 | n/a | left\_press | n/a |
-| 29.796 | n/a | show\_cross | stim-cross |
-| 30.353 | n/a | show\_face | stim-f001 |
-| 32.884 | n/a | show\_cross | stim-cross |
-| 33.360 | n/a | show\_face | stim-s005 |
-
-| onset | duration | event\_type | stim\_file |
-| :---- | :---- | :---- | :---- |
-| 26.731 | n/a | show\_cross | cross.bmp |
-| 27.246 | n/a | show\_face | u143.bmp |
-| 27.893 | n/a | left\_press | n/a |
-| 29.796 | n/a | show\_cross | cross.bmp |
-| 30.353 | n/a | show\_face | f0001.bmp |
-| 32.884 | n/a | show\_cross | cross.bmp |
-| 33.360 | n/a | show\_face | s005.bmp |
-
-Since the stim\_file column entries do not have extensions, they are interpreted as stimulus\_id values, and their annotations are looked up using the stimulus\_id column of stimuli.tsv. If the values in the stim\_file column of the main \_events.tsv file have an extension, tools may search for corresponding annotations in the optional filename column of stimuli.tsv.
-The above example annotated each of the images individually, resulting in duplication of annotations.  Users can also use the stimuli.json file and categorical columns with HED to reduce this redundancy. HED support of the stimuli.tsv/stimuli.json will be handled similarly to the annotation of the participants.tsv/participants.json.
-
-##
-
-## **Example 3: Movie example (time-varying)** {#example-3:-movie-example-(time-varying)}
-
-Below is an example of a `/stimuli` directory with a movie (called [The Present](https://youtu.be/WjqiU5FgsYc)) used for the [Healthy Brain Network’s](https://healthybrainnetwork.org) EEG and fMRI studies:
-
-The example */stimuli* directory:
-
-└── stimuli
-
-├── stimuli.tsv
-
-├── stimuli.json
-
-├── \[annotations.tsv\]
-
-├── \[annotations.json\]
-
-├── stim-thepresent\_audiovideo.mp4
-
-├── \[stim-thepresent\_audiovideo.json\]
-
-├── stim-thepresent\_annot-LogLumRatio\_events.tsv
-
-└── stim-thepresent\_annot-LogLumRatio\_events.json
-
-The example /stimuli/stimuli.tsv file:
-
-| stimulus\_id | type | HED |
-| :---- | :---- | :---- |
-| stim-thepresent | audiovideo | Visual-presentation, Movie |
-
-The example /stimuli/stim-thepresent\_annot-LogLumRatio\_events.tsv file:
-
-| onset | duration | shot\_number | LLR |
-| :---- | :---- | :---- | :---- |
-| 0 | n/a | video\_start | n/a |
-| 0 | 7.25 | 1 | n/a |
-| 7.25 | 3.542 | 2 | \-1.557820733 |
-| 10.792 | 5.208 | 3 | 0.3358234903 |
-
-\[sub-01\_task-thepresent\_events.tsv file example for a specific subject\](non-expanded version)
-
-| onset | duration | value | stim\_file |
-| :---- | :---- | :---- | :---- |
-| 1.0380 | 1.0 | video\_start | stim-thepresent\_annot-LogLumRatio\_events.tsv |
-| 204.10 | 1 | video\_stop | stim-thepresent\_annot-LogLumRatio\_events.tsv |
-
-## **Example 4: Non-shareable copyrighted movie example (time-varying)** {#example-4:-non-shareable-copyrighted-movie-example-(time-varying)}
-
-In some cases it may not be possible to share stimuli or movies shown to participants due to e.g. copyright or confidentiality issues. In this case, a link to a stimulus can be included or annotations for all stimuli can be shared. One such example would look as follows:
-
-Below is an example of a `/stimuli` directory with a movie:
-
-The example `/stimuli` directory:
-
-└── stimuli
-
-├── stimuli.tsv
-
-├── stimuli.json
-
-├── **stim-thepresent\_audiovideo.json**
-
-├── stim-thepresent\_annot-LogLumRatio\_events.tsv
-
-└── stim-thepresent\_annot-LogLumRatio\_events.json
-
-The example /stimuli/stimuli.tsv file:
-
-| stimulus\_id | type | HED |
-| :---- | :---- | :---- |
-| stim-thepresent | audiovideo | Visual-presentation, Movie |
-
-The example of stim-thepresent\_audiovideo.json would be:
-
-| stimSource | OPTIONAL. A link to the stimulus source file In this example:  [https://youtu.be/3XA0bB79oGc?si=Tnyd-7oFRzd0xCr9](https://youtu.be/3XA0bB79oGc?si=Tnyd-7oFRzd0xCr9)  |
-| :---- | :---- |
-
-## **Other examples (what are common use cases?)…** {#other-examples-(what-are-common-use-cases?)…}
-
-- Example 5: (long) Movie or audiobook split into parts.
-  - Counter-example: since \_part in mri means something else, corresponding data file would **not** be 1-to-1 matching via \_task-forrest\_part-... and need to be ad-hoc like \_task-forrest1 or \_task-forrest\_run-1
-  - This may be a good example: [https://github.com/psychoinformatics-de/studyforrest-data-annotations.git](https://github.com/psychoinformatics-de/studyforrest-data-annotations.git)
-- Example 6: Parts of the story randomized for investigation of temporal structuring
-
-# **Relation to  \`\*\_events.tsv\` and \`\*\_stim.tsv.gz\` files** {#relation-to-`*_events.tsv`-and-`*_stim.tsv.gz`-files}
-
-\[*\`\*\_events.tsv\` is defined under [BIDS-specificaitons/modality-specifc files/task events](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/05-task-events.html). \`\*\_stim.tsv.gz\` files is defined in [BIDS-specificaitons/modality-specifc files/Physiological and other continuous recordings](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continuous-recordings.html)*.\]
-
-The annotations within the `stimuli.tsv` and `_annot-<label>_events.tsv` files can be expanded in the downstream `*_events.tsv` files when the file name is mentioned in the `stim_file` or `stim_id` column *(The use of `stim_id` is not defined under BIDS events specifications, and should be expanded in the pull request)*.
-
-While the contents of `stimuli.tsv` and `_annot-<label>_events.tsv` can also be included in the individual `*_events.tsv` files, such implementation unnecessarily replicates annotations across subjects, modalities, tasks, and runs. Also, using `stimuli.tsv` and `_annot-<label>_events.tsv` increases the possibility of both (1) reusing the same annotations in other studies and (2) reusing the dataset with alternative annotations – by merely changing one file. Using the current inefficient ‘within-\`\_events.tsv\`’ mechanism hinders reusing the annotations (for example, annotations of complex stimuli or standard stimulus sets) and complicates reusing the datasets using alternate annotations – as in the current specification, these annotations would have to be replaced in every data directory `*_events.tsv` and `*_events.json` file.
-
-Another advantage of top-level `stimuli.tsv` and `_annot-<label>_events.tsv` is avoiding the need to create and edit large `*_events.tsv/json` files for datasets that use complex stimuli, such as movies. By avoiding the need to include annotations in every data folder, the processing toolbox will retrieve these annotations housed in the single top-level `/stimuli` directory during the analysis. This will increase the readability of all the data level  `*_events.tsv` and `*_events.json` files and avoid using fixed, lengthy annotations to annotate every instance of a constant stimulus. For large, standard stimulus sets, such as the [Natural Scene Dataset](https://naturalscenesdataset.org) or the immense [COCO image dataset](https://cocodataset.org/), holding a list of images used across the BIDS dataset in the top-level `/stimuli` directory, with their complete annotations, would give a useful cross-reference for debugging and design of analyses.
diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index b47701503f..8added8af8 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -4,7 +4,7 @@
 
 Stimulus files MUST be stored in the `/stimuli` directory under the root directory of the dataset.
 The `/stimuli` directory can contain subdirectories to organize the stimulus files.
-Stimulus files MUST follow the BIDS naming conventions and SHOULD be referenced in the `events.tsv`
+Stimulus files MUST follow the BIDS naming conventions and are referenced in the `events.tsv`
 file using the `stim_id` column.
 
 The standardization of stimulus files and their annotations within BIDS offers several key benefits:
@@ -28,8 +28,8 @@ A guide for using macros can be found at
    "stimuli": {
     "stimuli.tsv": "",
     "stimuli.json": "",
-    "[stim-<label>[_part-<label>]<suffix>.<extension>]": "",
-    "[stim-<label>[_part-<label>]<suffix>.json]": "",
+    "[stim-<label>[_part-<label>]_<suffix>.<extension>]": "",
+    "[stim-<label>[_part-<label>]_<suffix>.json]": "",
     "[[stim-<label>_]annotations.tsv]": "",
     "[[stim-<label>_]annotations.json]": "",
     "[stim-<label>[_part-<label>]_annot-<label>_events.tsv]": "",
@@ -79,7 +79,7 @@ In some cases, such as observing the copyright of a stimulus file, the actual st
 
 ## Stimuli Description (`stimuli.tsv`)
 
-The `stimuli.tsv/json` files are used to provide information about the stimuli based on their `stim_id`. This file is similar in usage as `participants.tsv`, `scans.tsv` and `sessions.tsv`, which list descriptions about subjects, scans and sessions, respectively. The `stimluli.tsv/json` files MUST be placed in the `/stimuli` directory.
+The `stimuli.tsv` files are used to provide information about the stimuli based on their `stim_id`. This file is similar in usage as `participants.tsv`, `scans.tsv` and `sessions.tsv`, which list descriptions about subjects, scans and sessions, respectively. The `stimluli.tsv` files MUST be placed in the `/stimuli` directory.
 
 The `stimuli.tsv` file contains information about each stimulus, including stimulus ID, type, URL, and other relevant details. The following table describes the REQUIRED, RECOMMENDED, and OPTIONAL columns for the `stimuli.tsv` file:
 
@@ -102,7 +102,7 @@ stim-movie01  video    https://example.com/movies/movie01.mp4  n/a         Studi
 
 The `stimuli.json` file provides detailed descriptions of the columns in the `stimuli.tsv` file. There MAY be extra entries in the `stimuli.json` in addition to the columns in the `stimuli.tsv` to provide more details about the stimulus.
 
-In cases where the stimulus is not shared, the `stimuli.tsv` file can be used to provide metadata about the stimuli, including the license, copyright, URL, and description. This is simialr to the use of `stim-<label>_<suffix>.json` files for individual stimuli files. In the case of conflict between the metadata in the `stimuli.tsv` and `stim-<label>_<suffix>.json` files, the metadata in the `stim-<label>_<suffix>.json` file takes precedence.
+In cases where the stimulus is not shared, the `stimuli.tsv` file can be used to provide metadata about the stimuli, including the license, copyright, URL, and description. This is similar to the use of `stim-<label>_<suffix>.json` files for individual stimuli files. In the case of conflict between the metadata in the `stimuli.tsv` and `stim-<label>_<suffix>.json` files, the metadata in the `stim-<label>_<suffix>.json` file takes precedence.
 
 ## Stimulus Annotations
 Annotations of the still images or general description of the stimuli (such as frequency and duration of a beep sound) can be stored in the `stimuli.tsv` as an additional column or `stim-<label>_<suffix>.json` as described above. Here is an example of how annotations can be stored in the `stimuli.tsv` file for an image from the Natural Scene Dataset (NSD):
@@ -111,7 +111,7 @@ Annotations of the still images or general description of the stimuli (such as f
 |--------------|-------|-------------|-----|--------|---------|
 | stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
 
-However, for time-varying stimuli, such as audio or video, it is RECOMMENDED to use specific annotations files in the form of `stim-<label>_annot-<label>_events.tsv/json` to store the annotations. These files have the same structure as the `events.tsv/json` files and are used to store annotations for the stimuli. There can be multiple annotation files for a single stimulus file, each with a unique annotation label. The annotation files MUST be stored in the `/stimuli` directory.
+However, for time-varying stimuli, such as audio or video, it is RECOMMENDED to use specific annotations files in the form of `stim-<label>_annot-<label>_events.tsv` to store the annotations. These files have the same structure as the `events.tsv` files and are used to store annotations for the stimuli. There can be multiple annotation files for a single stimulus file, each with a unique annotation label. The annotation files MUST be stored in the `/stimuli` directory.
 
 ## Annotation Description (`annotations.tsv`)
 

From 074f5fb696bb2ef243890c165c4fceb7acf8e69d Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Thu, 9 Jan 2025 19:36:45 +0100
Subject: [PATCH 18/21] sty

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

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index 8added8af8..3a46451701 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -37,7 +37,7 @@ A guide for using macros can be found at
     }
   }) }}
 
-Note: The presence of `stimuli.tsv` file indicates that the content of the `/stimuli` folder follows this BIDS specification for stimulus organization. This structure is planned to become mandatory in BIDS 2.0.
+Note: The presence of `stimuli.tsv` file indicates that the content of the `/stimuli` directory follows this BIDS specification for stimulus organization. This structure is planned to become mandatory in BIDS 2.0.
 
 ### Stimulus File Formats
 

From f197bba7427cb9c05490737af30b3b091af252c7 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Thu, 9 Jan 2025 19:53:27 +0100
Subject: [PATCH 19/21] remark

---
 src/modality-specific-files/stimuli.md     | 34 ++++++++++++----------
 src/modality-specific-files/task-events.md | 20 ++++++-------
 2 files changed, 28 insertions(+), 26 deletions(-)

diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index 3a46451701..77a89aa41d 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -9,10 +9,10 @@ file using the `stim_id` column.
 
 The standardization of stimulus files and their annotations within BIDS offers several key benefits:
 
-1. **Consistency**: Ensures uniform storage and referencing across datasets
-2. **Reusability**: Enables stimulus reuse across studies through standardized structure
-3. **Efficiency**: Minimizes redundancy by centralizing annotations
-4. **Flexibility**: Facilitates dataset reuse with alternative annotations
+1.  **Consistency**: Ensures uniform storage and referencing across datasets
+1.  **Reusability**: Enables stimulus reuse across studies through standardized structure
+1.  **Efficiency**: Minimizes redundancy by centralizing annotations
+1.  **Flexibility**: Facilitates dataset reuse with alternative annotations
 
 To preserve backward compatibility with existing datasets (see the Legacy section below), the use of these specifications for `/stimuli` directory and the `stim_id` column in the `events.tsv` files is RECOMMENDED but not required. Researchers are encouraged to follow these guidelines to enhance the interoperability and reproducibility of their studies.
 
@@ -43,15 +43,16 @@ Note: The presence of `stimuli.tsv` file indicates that the content of the `/sti
 
 The following table lists the supported stimulus file formats and their corresponding suffixes. The suffixes are used to identify the type of stimulus file and are appended to the `stim-<label>` prefix in the file name.
 
-| **suffix**  | **extensions**          | **description**                   |
-|-------------|-------------------------|-----------------------------------|
-| audio       | `.wav`, `.mp3`, `.aac`, `.ogg` | Audio-only stimulus files        |
-| image       | `.jpg`, `.png`, `.svg`  | Static visual stimulus files      |
-| video       | `.mp4`, `.avi`, `.mkv`, `.webm` | Video-only stimulus files        |
-| audiovideo  | `.mp4`, `.avi`, `.mkv`, `.webm` | Combined audio-visual files      |
+| suffix      | extensions                      | description                  |
+| ----------- | ------------------------------- | ---------------------------- |
+| audio       | `.wav`, `.mp3`, `.aac`, `.ogg`  | Audio-only stimulus files    |
+| image       | `.jpg`, `.png`, `.svg`          | Static visual stimulus files |
+| video       | `.mp4`, `.avi`, `.mkv`, `.webm` | Video-only stimulus files    |
+| audiovideo  | `.mp4`, `.avi`, `.mkv`, `.webm` | Combined audio-visual files  |
 
 ## Stimulus description (`stim-<label>_<suffix>.json`)
-The `stim-<label>_<suffix>.json` file provides metadata about the *singular* stimulus file.
+
+The `stim-<label>_<suffix>.json` file provides metadata about the _singular_ stimulus file.
 The following fields are defined to describe the stimulus file:
 
 <!-- This block generates a metadata table.
@@ -105,11 +106,12 @@ The `stimuli.json` file provides detailed descriptions of the columns in the `st
 In cases where the stimulus is not shared, the `stimuli.tsv` file can be used to provide metadata about the stimuli, including the license, copyright, URL, and description. This is similar to the use of `stim-<label>_<suffix>.json` files for individual stimuli files. In the case of conflict between the metadata in the `stimuli.tsv` and `stim-<label>_<suffix>.json` files, the metadata in the `stim-<label>_<suffix>.json` file takes precedence.
 
 ## Stimulus Annotations
+
 Annotations of the still images or general description of the stimuli (such as frequency and duration of a beep sound) can be stored in the `stimuli.tsv` as an additional column or `stim-<label>_<suffix>.json` as described above. Here is an example of how annotations can be stored in the `stimuli.tsv` file for an image from the Natural Scene Dataset (NSD):
 
-| stimulus_id  | type  | description | HED | NSD_id | COCO_id |
-|--------------|-------|-------------|-----|--------|---------|
-| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951 | 262145 |
+| stimulus_id   | type  | description                                           | HED                                                                                                                                                               | NSD_id | COCO_id |
+| ------------- | ----- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- |
+| stim-nsd02951 | image | an open market full of people and piles of vegetables | ((Item-count, High), Ingestible-object), (Background-view, ((Human, Body, Agent-trait/Adult), Outdoors, Furnishing, Natural-feature/Sky, Urban, Man-made-object)) | 2951   | 262145  |
 
 However, for time-varying stimuli, such as audio or video, it is RECOMMENDED to use specific annotations files in the form of `stim-<label>_annot-<label>_events.tsv` to store the annotations. These files have the same structure as the `events.tsv` files and are used to store annotations for the stimuli. There can be multiple annotation files for a single stimulus file, each with a unique annotation label. The annotation files MUST be stored in the `/stimuli` directory.
 
@@ -141,8 +143,8 @@ To reference stimulus identifiers in the `events.tsv` file, use the `stim_id` co
 
 Example `events.tsv` file:
 
-| onset | duration | trial_type | response_time | stim_id |
-|-------|----------|------------|---------------|---------|
+| onset | duration | trial_type | response_time | stim_id        |
+| ----- | -------- | ---------- | ------------- | -------------- |
 | 1.23  | 0.65     | start      | 1.435         | `stim-<label>` |
 | 5.65  | 0.65     | stop       | 1.739         | `stim-<label>` |
 | 12.1  | 2.35     | n/a        | n/a           | `stim-<label>` |
diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
index 0c7e441654..653b493f53 100644
--- a/src/modality-specific-files/task-events.md
+++ b/src/modality-specific-files/task-events.md
@@ -269,15 +269,15 @@ and a guide for using macros can be found at
 
 The operating system description SHOULD include the following attributes:
 
-- type (for example, Windows, macOS, Linux)
-- distribution (if applicable, for example, Ubuntu, Debian, CentOS)
-- the version number (for example, 18.04.5)
+-   type (for example, Windows, macOS, Linux)
+-   distribution (if applicable, for example, Ubuntu, Debian, CentOS)
+-   the version number (for example, 18.04.5)
 
 Examples:
 
-- Windows 10, Version 2004
-- macOS 10.15.6
-- Linux Ubuntu 18.04.5
+-   Windows 10, Version 2004
+-   macOS 10.15.6
+-   Linux Ubuntu 18.04.5
 
 The amount of information supplied for the `OperatingSystem` SHOULD be sufficient
 to re-run the code under maximally similar conditions.
@@ -497,9 +497,9 @@ By using `stim_id`, multiple annotations and stimulus files associated with the
 
 Standardizing stimulus files and their annotations within the BIDS specifications offers several advantages:
 
-1. **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
-2. **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
-3. **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
-4. **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
+1.  **Consistency**: Ensures that stimulus files are stored and referenced in a consistent manner across different datasets.
+1.  **Reusability**: Facilitates the reuse of stimulus files and annotations in other studies by providing a standardized structure.
+1.  **Efficiency**: Reduces redundancy by avoiding the need to replicate annotations across subjects, modalities, tasks, and runs.
+1.  **Flexibility**: Allows for easy modification of annotations by updating a single file, enabling the reuse of datasets with alternative annotations.
 
 By following these guidelines, researchers can enhance the interoperability and reproducibility of their studies, making it easier to share and reuse data within the scientific community.

From 02c6f31dd27b9b267230037387192fb1411bb4ae Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Thu, 9 Jan 2025 20:24:46 +0100
Subject: [PATCH 20/21] fix

---
 src/schema/objects/datatypes.yaml                |  4 ++++
 src/schema/objects/metadata.yaml                 | 15 +++++++++++++++
 src/schema/rules/files/raw/audio.yaml            |  2 ++
 src/schema/rules/files/raw/audiovideo.yaml       |  2 ++
 src/schema/rules/files/raw/image.yaml            |  2 ++
 src/schema/rules/files/raw/video.yaml            |  2 ++
 src/schema/rules/sidecars/stimuli.yaml           | 16 ++++------------
 .../bidsschematools/tests/test_render_text.py    |  5 ++---
 8 files changed, 33 insertions(+), 15 deletions(-)

diff --git a/src/schema/objects/datatypes.yaml b/src/schema/objects/datatypes.yaml
index e84f1a6ba6..0240aff387 100644
--- a/src/schema/objects/datatypes.yaml
+++ b/src/schema/objects/datatypes.yaml
@@ -65,3 +65,7 @@ nirs:
   value: nirs
   display_name: Near-Infrared Spectroscopy
   description: Near-Infrared Spectroscopy data organized around the SNIRF format
+stimuli:
+  value: stimuli
+  display_name: Stimulus
+  description: Stimulus
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 5ed86c5dc6..8262738dcf 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -542,6 +542,11 @@ ContrastBolusIngredient:
     # TODO: Add definitions for these values. (perhaps don't specify)
     - UNKNOWN
     - NONE
+Copyright:
+  name: Copyright
+  display_name: Copyright
+  description: Copyright information
+  type: string
 DCOffsetCorrection:
   name: DCOffsetCorrection
   display_name: DC Offset Correction
@@ -1892,6 +1897,11 @@ License:
     The corresponding full license text MAY be specified in an additional
     `LICENSE` file.
   type: string
+StimulusLicense:
+  name: License
+  display_name: License
+  description: License under which this stimulus is shared.
+  type: string
 LongName:
   name: LongName
   display_name: Long Name
@@ -3653,6 +3663,11 @@ 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
+StimulusURL:
+  name: URL
+  display_name: URL
+  description: Location (origin) for the stimulus file.
+  type: string
 TablePosition:
   name: TablePosition
   display_name: Table Position
diff --git a/src/schema/rules/files/raw/audio.yaml b/src/schema/rules/files/raw/audio.yaml
index c3650379de..4ee4273fbc 100644
--- a/src/schema/rules/files/raw/audio.yaml
+++ b/src/schema/rules/files/raw/audio.yaml
@@ -1,5 +1,7 @@
 ---
 audio:
+  datatypes:
+    - stimuli
   suffixes:
     - audio
   extensions:
diff --git a/src/schema/rules/files/raw/audiovideo.yaml b/src/schema/rules/files/raw/audiovideo.yaml
index 75fbe77288..10c9679aff 100644
--- a/src/schema/rules/files/raw/audiovideo.yaml
+++ b/src/schema/rules/files/raw/audiovideo.yaml
@@ -1,5 +1,7 @@
 ---
 audiovideo:
+  datatypes:
+    - stimuli
   suffixes:
     - audiovideo
   extensions:
diff --git a/src/schema/rules/files/raw/image.yaml b/src/schema/rules/files/raw/image.yaml
index d3d3d15920..f1a0e1b7d7 100644
--- a/src/schema/rules/files/raw/image.yaml
+++ b/src/schema/rules/files/raw/image.yaml
@@ -1,5 +1,7 @@
 ---
 image:
+  datatypes:
+    - stimuli
   suffixes:
     - image
   extensions:
diff --git a/src/schema/rules/files/raw/video.yaml b/src/schema/rules/files/raw/video.yaml
index 8d2e5f9832..8ef0a4cd43 100644
--- a/src/schema/rules/files/raw/video.yaml
+++ b/src/schema/rules/files/raw/video.yaml
@@ -1,5 +1,7 @@
 ---
 video:
+  datatypes:
+    - stimuli
   suffixes:
     - video
   extensions:
diff --git a/src/schema/rules/sidecars/stimuli.yaml b/src/schema/rules/sidecars/stimuli.yaml
index 389f7ea185..3bd3f2194c 100644
--- a/src/schema/rules/sidecars/stimuli.yaml
+++ b/src/schema/rules/sidecars/stimuli.yaml
@@ -8,15 +8,7 @@ Stimulus:
     - suffix == "audiovideo"
     - suffix == "image"
   fields:
-    License:
-      recommended: true
-      description: License under which this stimulus is shared
-    Copyright:
-      recommended: true
-      description: Copyright information for this stimulus
-    URL:
-      optional: true
-      description: Location (origin) for the stimulus file
-    Description:
-      optional: true
-      description: Free-form description of the stimulus
+    StimulusLicense: recommended
+    Copyright: recommended
+    StimulusURL: optional
+    Description: optional
diff --git a/tools/schemacode/src/bidsschematools/tests/test_render_text.py b/tools/schemacode/src/bidsschematools/tests/test_render_text.py
index e6745c8780..b9ba809990 100644
--- a/tools/schemacode/src/bidsschematools/tests/test_render_text.py
+++ b/tools/schemacode/src/bidsschematools/tests/test_render_text.py
@@ -93,8 +93,7 @@ def test_make_filename_template(schema_obj, schema_dir):
         for datatype in rule.datatypes
     }
 
-    datatype_count = len(datatypes)
-    datatype_bases = [f"        {i}/" for i in datatypes]
+    datatype_bases = [f"        {i}/" for i in datatypes if i != "stimuli"]
     datatype_level = False
     datatype_file_start = "            sub-<label>"
     datatype_bases_found = 0
@@ -107,7 +106,7 @@ def test_make_filename_template(schema_obj, schema_dir):
             datatype_level = True
             datatype_bases_found += 1
     # Are all datatypes listed?
-    assert datatype_bases_found == datatype_count
+    assert datatype_bases_found == len(datatypes) - 1
 
 
 def test_define_common_principles(schema_obj):

From 3ae9fe1f490477b263b21b7f6cf08d16dbfd13cc Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Thu, 9 Jan 2025 20:33:40 +0100
Subject: [PATCH 21/21] fix

---
 mkdocs.yml                             | 1 +
 src/modality-specific-files/stimuli.md | 2 +-
 src/schema/rules/sidecars/stimuli.yaml | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index ef36d6eb5c..181e0d15f8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -20,6 +20,7 @@ nav:
           - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
           - Motion: modality-specific-files/motion.md
           - Magnetic Resonance Spectroscopy: modality-specific-files/magnetic-resonance-spectroscopy.md
+          - Stimuli: modality-specific-files/stimuli.md
       - Derivatives:
           - BIDS Derivatives: derivatives/introduction.md
           - Common data types and metadata: derivatives/common-data-types.md
diff --git a/src/modality-specific-files/stimuli.md b/src/modality-specific-files/stimuli.md
index 77a89aa41d..3c05a5bae5 100644
--- a/src/modality-specific-files/stimuli.md
+++ b/src/modality-specific-files/stimuli.md
@@ -63,7 +63,7 @@ The definitions of the fields specified in these tables may be found in
 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("stimulus.Stimulus") }}
+{{ MACROS___make_sidecar_table("stimuli.Stimuli") }}
 
 In some cases, such as observing the copyright of a stimulus file, the actual stimulus file may not be shared. In such cases, the `stim-<label>_<suffix>.json` file SHOULD be used to provide metadata about the stimulus file, including the license, copyright, URL, and description.
 
diff --git a/src/schema/rules/sidecars/stimuli.yaml b/src/schema/rules/sidecars/stimuli.yaml
index 3bd3f2194c..99cff658cd 100644
--- a/src/schema/rules/sidecars/stimuli.yaml
+++ b/src/schema/rules/sidecars/stimuli.yaml
@@ -1,7 +1,7 @@
 # Sidecar tables for stim-<label>_suffix.json, the stimuli.json and annotations.json do not need additional fields
 # as the fields have been already defined in the tabular data
 
-Stimulus:
+Stimuli:
   selectors:
     - suffix == "audio"
     - suffix == "video"