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-\\[\_part-\\]\_\.\\] - -└── \[stim-\\[\_part-\\]\_\.json\] - -Currently supported suffixes (see 2.1): - -- audio -- audiovideo -- image -- video - -If annotations are added: - -└── stimuli - -├── \[\[stim-\\_\]annotations.tsv\] - -├── \[\[stim-\\_\]annotations.json\] - -├── stim-\\[\_part-\\]\_annot-\\_events.tsv - -└── \[stim-\\[\_part-\\]\_annot-\\_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-