[ENH] BEP044 - Stim-BIDS

.gitignore

@@ -163,3 +163,8 @@ dmypy.json
 cython_debug/
 
 .*.swp
+
+# Claude specific files
+CLAUDE.md
+.rules/
+.context/

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
           - Phenotypic and assessment data: modality-agnostic-files/phenotypic-and-assessment-data.md
           - Code: modality-agnostic-files/code.md
           - Events: modality-agnostic-files/events.md
+          - Stimuli: modality-agnostic-files/stimuli.md
       - Modality specific files:
           - Magnetic Resonance Imaging: modality-specific-files/magnetic-resonance-imaging-data.md
           - Magnetoencephalography: modality-specific-files/magnetoencephalography.md

src/metaschema.json

@@ -393,7 +393,12 @@
                 "^[a-z]+$": {
                   "type": "object",
                   "patternProperties": {
-                    "^[a-zA-Z0-9_]+$": { "$ref": "#/definitions/suffixRule" }
+                    "^[a-zA-Z0-9_]+$": {
+                      "anyOf": [
+                        { "$ref": "#/definitions/suffixRule" },
+                        { "$ref": "#/definitions/stemRule" }
+                      ]
+                    }
                   },
                   "additionalProperties": false
                 }
@@ -689,7 +694,30 @@
           "items": { "type": "string", "pattern": "^[a-z]+$" }
         },
         "stem": { "type": "string" },
-        "extensions": { "type": "array", "items": { "type": "string" } }
+        "path": { "type": "string" },
+        "extensions": { "type": "array", "items": { "type": "string" } },
+        "entities": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-z]+$": {
+              "anyOf": [
+                { "enum": ["optional", "required"] },
+                {
+                  "type": "object",
+                  "properties": {
+                    "level": { "enum": ["optional", "required"] },
+                    "enum": {
+                      "type": "array",
+                      "items": { "type": "string" }
+                    }
+                  },
+                  "required": ["level", "enum"]
+                }
+              ]
+            }
+          },
+          "additionalProperties": false
+        }
       },
       "required": ["level", "stem", "extensions"],
       "additionalProperties": false
@@ -707,6 +735,7 @@
           "type": "array",
           "items": { "type": "string", "pattern": "^[a-zA-Z0-9]+$" }
         },
+        "path": { "type": "string" },
         "extensions": { "type": "array", "items": { "type": "string" } },
         "entities": {
           "type": "object",

src/modality-agnostic-files/events.md

@@ -397,3 +397,35 @@ 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.
+
+## Stimulus Organization
+
+For standardized organization and reuse of stimulus files, events may reference stimuli using two approaches:
+
+### Using `stim_file`
+
+Reference stimulus files directly using the `stim_file` column, where values represent the relative path to the stimulus file within the `/stimuli` directory:
+
+```JSON
+{
+    "stim_file": {
+        "LongName": "Stimulus file",
+        "Description": "Location of stimulus file presented at the given onset time, relative to /stimuli directory."
+    }
+}
+```
+
+### Using `stim_id`
+
+Reference stimulus identifiers using the `stim_id` column to link events to comprehensive stimulus metadata and annotations:
+
+```JSON
+{
+    "stim_id": {
+        "LongName": "Stimulus identifier",
+        "Description": "Unique identifier linking to stimulus files and annotations in /stimuli directory."
+    }
+}
+```
+
+For detailed information on stimulus file organization, metadata, and annotations, see the [Stimuli](./stimuli.md) specification.

src/modality-agnostic-files/stimuli.md

@@ -0,0 +1,160 @@
+# Stimuli
+
+## Stimulus Files Organization
+
+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 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:
+
+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 the `/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 filename templates for root-level directories.
+The inputs for this macro can be found in the directory
+  src/schema/rules/files/raw
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_root_filename_template(
+   "raw",
+   path="stimuli")
+}}
+
+Note: The presence of the `stimuli.tsv` file indicates that the content of the `/stimuli` directory follows this BIDS specification for stimulus organization.
+
+### Stimulus File Formats
+
+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`, `.webp` | 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 following fields are defined to describe the stimulus 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") }}
+
+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.
+
+### Example `stim-<label>_<suffix>.json`
+
+```JSON
+{
+    "License": "CC-BY-4.0",
+    "Copyright": "2023 Lab Name lab@university.edu",
+    "URL": "https://example.com/stimuli/",
+    "Description": "Collection of face images, tones, and movie clips used in the experiment"
+}
+```
+
+The `License` field SHOULD provide the known identifiers, such as `PDL`, `CC0`, `CC-BY` from the [BIDS Licensees Appendix](https://bids-specification.readthedocs.io/en/stable/appendices/licenses.html), or common license lists such as [SPDX](https://spdx.org/licenses/) or [Creative Commons](https://creativecommons.org/licenses/).
+The `Copyright` filed SHOULD provide the year, copyright holder's name, and if available, the email address of the copyright holder.
+If the stimulus file is not shared, the `URL` field SHOULD provide a link to the stimulus file.
+
+## Stimuli Description (`stimuli.tsv`)
+
+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 `stimuli.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:
+
+<!-- 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") }}
+
+### Example `stimuli.tsv`
+
+```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
+```
+
+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 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  |
+
+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`)
+
+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
+  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.Annotations") }}
+
+### Example `*_annotations.tsv`
+
+```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
+```
+
+## 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 expand 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."
+    }
+}
+```

src/modality-specific-files/behavioral-experiments.md

@@ -25,6 +25,8 @@ metadata (`_events.json`),
 physiological (`_physio.tsv.gz`, `_physio.json`)
 and other continuous recordings (`_stim.tsv.gz`, `_stim.json`)
 as for tasks performed during MRI, electrophysiological or other neural recordings.
+
+Note that `*_stim.tsv.gz` files contain subject-specific, continuously-sampled stimulus-related signals (such as audio waveforms, video parameters, electrical, mechanical, or optical stimuli), which is distinct from subject-invariant stimulus files stored in the [`/stimuli` directory](../modality-agnostic-files/stimuli.md).
 Additionally, events files
 that do not include the mandatory `onset` and `duration` columns
 MAY be included,

src/schema/objects/columns.yaml

@@ -589,6 +589,15 @@ 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. 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
   display_name: Strain
@@ -852,3 +861,69 @@ template_z:
   description: |
     Assumed or ideal position along the z axis.
   type: number
+stimulus_id:
+  name: stimulus_id
+  display_name: Stimulus Identifier
+  description: |
+    Unique identifier for a specific stimulus.
+  type: string
+annot_id:
+  name: annot_id
+  display_name: Annotation Identifier
+  description: |
+    Unique identifier for a specific annotation set applying to a stimulus or group of stimuli. Links to annotation
+    files (for example, `*_annot-<label>_events.tsv`).
+  type: string
+copyright:
+  name: copyright
+  display_name: Stimulus Copyright
+  description: |
+    Copyright information for the stimulus file, typically including year and holder.
+  type: string
+license:
+  name: license
+  display_name: Stimulus License
+  description: |
+    License under which the stimulus file is distributed.
+    SHOULD use identifiers from recognized lists like SPDX or Creative Commons.
+  type: string
+partDescription__stimuli:
+  name: partDescription
+  display_name: Stimulus Part Description
+  description: |
+    Free-form text description of a specific part of a stimulus, relevant when the stimulus is split into multiple
+    files using the `part` entity.
+  type: string
+present:
+  name: present
+  display_name: Stimulus File Present
+  description: |
+    Indicates whether the stimulus file corresponding to the `stimulus_id` is physically present in the dataset.
+  type: boolean
+URL:
+  name: URL
+  display_name: Stimulus URL
+  description: |
+    Uniform Resource Locator pointing to the stimulus file, particularly useful
+    if the stimulus file is not distributed with the dataset.
+  type: string
+  format: uri
+description__stimuli:
+  name: description
+  display_name: Stimulus Description
+  description: |
+    Free-form text description of the stimulus identified by `stimulus_id`.
+  type: string
+description__annot:
+  name: description
+  display_name: Annotation Description
+  description: |
+    Free-form text description of the annotation identified by `annot_id`.
+  type: string
+type__stimuli:
+  name: type
+  display_name: Stimulus type
+  description: |
+    Type of stimulus (for example, image, audio, video).
+    Refers to the suffix of the stimulus file if present.
+  type: string

src/schema/objects/datatypes.yaml

@@ -72,3 +72,8 @@ nirs:
   value: nirs
   display_name: Near-Infrared Spectroscopy
   description: Near-Infrared Spectroscopy data organized around the SNIRF format
+stimuli:
+  value: stimuli
+  display_name: Stimuli
+  description: |
+    Stimulus data, including audio, video, images, and annotations.