[ENH] BEP044 - Stim-BIDS

[neuromechanist]

This PR addresses #153 by introducing specifications for handling and standardizing stimulus files and their annotations within the BIDS specifications. The changes focus on improving the organization, referencing, and metadata of stimulus files to enhance consistency, reusability, and efficiency.

[!IMPORTANT] HTML render of the stimuli page : https://bids-specification--2022.org.readthedocs.build/en/2022/modality-specific-files/stimuli.html

[!NOTE] The issue: #153 Google Doc Example PR: https://github.com/bids-standard/bids-examples/pull/433

Known issues:

• The validator fails because extensions in /src/schema/rules/files/raw require datatype. Stimuli might be a special data type that can only be present at the root of the dataset. So, the datatype field is missing for now.
• There are some style errors by the remark validators

cc: @bids-standard/bep044 and @monique2208

[Remi-Gau]

will do a bit of clean up to get less red in CI and maybe see if we can get the HTML version of the BEP to render

[Remi-Gau]

HTML: stimuli page https://bids-specification--2022.org.readthedocs.build/en/2022/modality-specific-files/stimuli.html

[codecov[bot]]

Codecov Report

:x: Patch coverage is 84.00000% with 4 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 82.68%. Comparing base (73281ae) to head (bede400).

Files with missing lines	Patch %	Lines
...ools/schemacode/src/bidsschematools/render/text.py	66.66%	4 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2022      +/-   ##
==========================================
- Coverage   82.71%   82.68%   -0.03%     
==========================================
  Files          20       20              
  Lines        1608     1629      +21     
==========================================
+ Hits         1330     1347      +17     
- Misses        278      282       +4     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[neuromechanist]

Obserinvg #750 and the _stim.<extension> suffix, and a discussion pursued last month in #1771, we should clarify when to use the stimuli directory and when to use subject-based _stim.<extension> files. IMO, the difference is clear, stimulus files in the stim directory are used for >1 subject while the subject-based _stim.<extension> is exclusively for the the subject/session where the file is located.

[VisLab]

I think this extension will be a very valuable addition to BIDS. I have read through the HTML rendered version and have the following typo corrections:

1. In the Stimuli Description section the stimuli.tsv table has a lot of nan elements.
2. In the example for stimuli.tsv below this table, the present column isn't explained (or aligned). Maybe it is one of the nan values in 1.?
3. In the Annotation Description section, the annotations.tsv table also has nan entries.
4. In the Referencing Stimulus Identifiers section the ./stimuli directory should be in code font.

[neuromechanist]

I think this extension will be a very valuable addition to BIDS. I have read through the HTML rendered version and have the following typo corrections:

Thanks very much @VisLab. The nans were due to the columns not being defined in columns.yaml They should be ok now.

[neuromechanist]

@rwblair and I just discussed the possibilities and challenges to write schema rules for this PR 😍. Some rules can be enforced readily, but some other would require more development and reflection. We will try to come up with a list of the rules and their required implementation effort as a next step.

[neuromechanist]

Update prior to making PR out of Draft:

1. Moved Stimuli to Modality Agnostic section.
2. Added MACROS to render root-level file tree (should hopefully help with other use cases down the road)
3. Tests are passing for simple (no-annotation) example from https://github.com/bids-standard/bids-examples/pull/433
4. X Validator should probably be extended to handle event files under stimuli 🤔
5. Tests are passing