diff --git a/.gitignore b/.gitignore index 955a6f2c97..71dd08e68a 100644 --- a/.gitignore +++ b/.gitignore @@ -163,3 +163,8 @@ dmypy.json cython_debug/ .*.swp + +# Claude specific files +CLAUDE.md +.rules/ +.context/ diff --git a/mkdocs.yml b/mkdocs.yml index 28ba5d5b5a..dbcf0433cd 100644 --- a/mkdocs.yml +++ b/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 diff --git a/src/metaschema.json b/src/metaschema.json index e5d4c7b400..b663e9ac74 100644 --- a/src/metaschema.json +++ b/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", diff --git a/src/modality-agnostic-files/events.md b/src/modality-agnostic-files/events.md index 1c65a0196e..f456824a2a 100644 --- a/src/modality-agnostic-files/events.md +++ b/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. diff --git a/src/modality-agnostic-files/stimuli.md b/src/modality-agnostic-files/stimuli.md new file mode 100644 index 0000000000..04b0a6b7ca --- /dev/null +++ b/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 + + +{{ 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-