Merge branch 'master' into bep038

.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2.1
 jobs:
   build_docs:
     docker:
-      - image: cimg/python:3.8
+      - image: cimg/python:3.12-node
     steps:
       # checkout code to default ~/project
       - checkout
@@ -21,14 +21,15 @@ jobs:
       - persist_to_workspace:
           # the mkdocs build outputs are in ~/project/site
           root: ~/project
-          paths: site
+          paths:
+            - site
       - store_artifacts:
           path: ~/project/site/
           destination: dev_docs
 
   check_links:
     docker:
-      - image: cimg/python:3.8
+      - image: cimg/python:3.12
     steps:
       # checkout code to default ~/project
       - checkout
@@ -131,7 +132,8 @@ jobs:
       - persist_to_workspace:
           # raw generated changelog in ~/changelog_build/CHANGES.md
           root: ~/.
-          paths: changelog_build
+          paths:
+            - changelog_build
 
   # Lint and fix the auto generated changes.md file
   lint_generated_changelog:
@@ -164,7 +166,8 @@ jobs:
       - persist_to_workspace:
           # linted and fixed changelog in ~/changelog_build/CHANGES.md
           root: ~/.
-          paths: changelog_build
+          paths:
+            - changelog_build
 
   # Push built changelog to repo
   commit_generated_changelog:
@@ -178,7 +181,7 @@ jobs:
       - attach_workspace:
           # fixed+linted changelog in ~/changelog_build/CHANGES.md
           at: ~/.
-      - deploy:
+      - run:
           name: Changelog deployment
           # $CHANGE_TOKEN is generated via the GitHub web UI, and then securely stored within CircleCI web UI
           command: |
@@ -197,7 +200,6 @@ jobs:
             fi
 
 workflows:
-  version: 2
   search_build:
     jobs:
       - build_docs

.github/workflows/schemacode_ci.yml

@@ -164,7 +164,7 @@ jobs:
         uses: actions/download-artifact@v4
 
       - name: Upload to CodeCov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}  # not required but might help API rate limits
           fail_ci_if_error: true

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: check-added-large-files
       - id: check-case-conflict
   - repo: https://github.com/psf/black
-    rev: 23.12.1
+    rev: 24.2.0
     hooks:
       - id: black
         files: ^tools/(?!schemacode)

src/appendices/schema.md

@@ -9,7 +9,7 @@ to the BIDS standard.
 
 The BIDS schema is available in two machine readable formats:
 
--   as a set of [YAML](https://en.wikipedia.org/wiki/YAML) files in the [BIDS specification repository](https://github.com/bids-standard/bids-specification/src/schema)
+-   as a set of [YAML](https://en.wikipedia.org/wiki/YAML) files in the [BIDS specification repository](https://github.com/bids-standard/bids-specification/tree/master/src/schema)
 -   as a [single dereferenced json file](https://bids-specification.readthedocs.io/en/stable/schema.json)
 
 A didactic walkthrough of the schema can be found in the [BEP Guide](https://bids-extensions.readthedocs.io/en/latest/schema/),

src/common-principles.md

@@ -430,7 +430,8 @@ Tabular data MUST be saved as tab delimited values (`.tsv`) files, that is, CSV
 files where commas are replaced by tabs. Tabs MUST be true tab characters and
 MUST NOT be a series of space characters. Each TSV file MUST start with a header
 line listing the names of all columns (with the exception of
-[physiological and other continuous recordings](modality-specific-files/physiological-and-other-continuous-recordings.md)).
+[physiological and other continuous recordings](modality-specific-files/physiological-and-other-continuous-recordings.md)
+as well as [motion recording data](modality-specific-files/motion.md)).
 It is RECOMMENDED that the column names in the header of the TSV file are
 written in [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) with the
 first letter in lower case (for example, `variable_name`, not `Variable_name`).

src/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -162,6 +162,18 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table("mri.MRIEchoPlanarImagingAndB0Mapping") }}
 
+#### Tissue description
+
+<!-- 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("mri.MRISample") }}
+
 ## Anatomy imaging data
 
 Anatomy MRI sequences measure static, structural features of the brain.
@@ -298,6 +310,15 @@ and a guide for using macros can be found at
       ])
 }}
 
+Parametric images listed in the table below are typically generated by
+processing a [file collection](../common-principles.md#entity-linked-file-collections).
+Please visit the [file collections appendix](../appendices/file-collections.md) to see the
+list of suffixes available for quantitative MRI (qMRI) applications associated
+with these maps
+(for example, [MPM](../glossary.md#mpm-suffixes),
+[MP2RAGE](../glossary.md#mp2rage-suffixes),
+and [MTR](../glossary.md#mtransfer-entities)).
+
 Currently supported parametric maps include:
 
 <!--
@@ -330,11 +351,6 @@ and a guide for using macros can be found at
    )
 }}
 
-Parametric images listed in the table above are typically generated by
-processing a [file collection](../common-principles.md#entity-linked-file-collections).
-Please visit the [file collections appendix](../appendices/file-collections.md) to see the
-list of suffixes available for quantitative MRI (qMRI) applications associated
-with these maps.
 For any other details on the organization of parametric maps, their
 recommended metadata fields, and the application specific entity or
 metadata requirement levels of [file collections](../appendices/file-collections.md) that can generate

src/modality-specific-files/magnetoencephalography.md

@@ -504,25 +504,24 @@ has to be updated, then for MEG it could be considered to be a new session.
 
 Empty-room MEG recordings capture the environmental and recording system's noise.
 
-It is RECOMMENDED to explicitly specify which empty-room recording should be used with which experimental run(s) or session(s). This can be done via the [`AssociatedEmptyRoom`](../glossary.md#associatedemptyroom-metadata) field in the `*_meg.json` sidecar files.
+It is RECOMMENDED to explicitly specify which empty-room recording should be used with which experimental run(s) or session(s).
+This can be done via the [`AssociatedEmptyRoom`](../glossary.md#associatedemptyroom-metadata) field in the `*_meg.json` sidecar files.
 
 Empty-room recordings may be collected once per day, where a single empty-room recording may be shared between multiple subjects and/or sessions (see [Example 1](#example-1)).
-Empty-room recordings can also be collected for each individual experimental session (see [Example 2](#example-2)).
-
-In the case of empty-room recordings being associated with multiple subjects and/or sessions, it is RECOMMENDED to store the empty-room recording inside a subject directory named `sub-emptyroom`.
-If a [`session-<label>`](../appendices/entities.md#ses) entity is present, its label SHOULD be the date of the empty-room recording in the format `YYYYMMDD`, that is `ses-YYYYMMDD`.
-The `scans.tsv` file containing the date and time of the acquisition SHOULD also be included.
-The rationale is that this naming scheme will allow users to easily retrieve the empty-room recording that best matches a particular experimental session, based on date and time of the recording.
-It should be possible to query empty-room recordings just like usual subject recordings, hence all metadata sidecar files (such as the `channels.tsv`) file SHOULD be present as well.
-
-In the case of empty-room recordings being collected for the individual experimental session, it is recommended to store the empty-room recording along with that subject and session.
-
+Empty-room recordings may also be collected for each individual experimental session (see [Example 2](#example-2)).
 In either case, the label for the [`task-<label>`](../appendices/entities.md#task) entity in the empty-room recording SHOULD be set to `noise`.
 
 ### Example 1
 
 One empty-room recording per day, applying to all subjects for that day.
 
+In the case of empty-room recordings being associated with multiple subjects and/or sessions,
+it is RECOMMENDED to store the empty-room recording inside a subject directory named `sub-emptyroom`.
+If a [`session-<label>`](../appendices/entities.md#ses) entity is present, its label SHOULD be the date of the empty-room recording in the format `YYYYMMDD`, that is `ses-YYYYMMDD`.
+The `scans.tsv` file containing the date and time of the acquisition SHOULD also be included.
+The rationale is that this naming scheme will allow users to easily retrieve the empty-room recording that best matches a particular experimental session, based on date and time of the recording.
+It should be possible to query empty-room recordings just like usual subject recordings, hence all metadata sidecar files (such as the `channels.tsv`) file SHOULD be present as well.
+
 <!-- 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
@@ -546,7 +545,10 @@ A guide for using macros can be found at
 
 ### Example 2
 
-One recording per session, stored within the session directory.
+One empty-room recording per each participant's session, stored within the session directory.
+
+In the case of empty-room recordings being collected for the individual experimental session,
+it is RECOMMENDED to store the empty-room recording along with that subject and session.
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at

src/modality-specific-files/motion.md

@@ -42,7 +42,10 @@ each of which is accompanied by `*_tracksys-<label>_motion.json` and `*_tracksys
 Between `tracksys-<label>` entity and `*_motion.tsv`, `*_motion.json`, or `*_channels.tsv` suffixes, optional [`acq-<label>`](../appendices/entities.md#acq) or [`run-<index>`](../appendices/entities.md#run) entity MAY be inserted.
 
 One column in the `*_tracksys-<label>_motion.tsv` file represents one data channel.
-The ordering of columns MUST match the order of rows in the `*_channels.tsv` file for unambiguous assignment.
+Motion files MUST NOT have a header row;
+the ordering of columns is given by the order of rows in the associated `*_channels.tsv` file.
+The number of columns in `_motion.tsv` files MUST equal the number of rows
+in the associated `_channels.tsv` file.
 All relevant metadata about a tracking systems is stored in accompanying sidecar `*_tracksys-<label>_motion.json` file.
 
 The source data from each tracking system in their original format, if different from `.tsv`,

src/modality-specific-files/positron-emission-tomography.md

@@ -216,6 +216,18 @@ A guide for using macros can be found at
 
 {{ MACROS___make_sidecar_table("pet.PETInstitutionInformation") }}
 
+#### Tissue description
+
+<!-- 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("pet.PETSample") }}
+
 #### Task
 
 If the OPTIONAL [`task-<label>`](../appendices/entities.md#task) is used,

src/schema/objects/metadata.yaml

@@ -2661,10 +2661,10 @@ RepetitionTime:
     and the beginning of acquisition of the volume following it (TR).
     When used in the context of functional acquisitions this parameter best
     corresponds to
-    [DICOM Tag 0020, 0110](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0020,0110)):
+    [DICOM Tag 0020, 0110](http://dicomlookup.com/dicomtags/(0020,0110)):
     the "time delta between images in a
     dynamic of functional set of images" but may also be found in
-    [DICOM Tag 0018, 0080](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,0080)):
+    [DICOM Tag 0018, 0080](http://dicomlookup.com/dicomtags/(0018,0080)):
     "the period of time in msec between the beginning
     of a pulse sequence and the beginning of the succeeding
     (essentially identical) pulse sequence".
@@ -2681,7 +2681,7 @@ RepetitionTimeExcitation:
   display_name: Repetition Time Excitation
   description: |
     The interval, in seconds, between two successive excitations.
-    [DICOM Tag 0018, 0080](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,0080))
+    [DICOM Tag 0018, 0080](http://dicomlookup.com/dicomtags/(0018,0080))
     best refers to this parameter.
     This field may be used together with the `"RepetitionTimePreparation"` for
     certain use cases, such as

src/schema/rules/directories.yaml

@@ -0,0 +1,112 @@
+---
+# This file defines layouts of directories.
+#
+# A layout defines a collection of directory specifiers.
+# Each specifier has a naming convention, requirement level, opacity, and subdirectories.
+#
+# Naming conventions may take three forms:
+#   - name: The directory name has exactly this value.
+#   - entity: The directory name takes the form of {key}-{value} for the specified entity
+#   - value: The directory name takes the form of {value} for the specified term (like datatype)
+#
+# The requirement level indicates whether a directory MUST (required) or MAY (optional) exist.
+#
+# The opaque field indicates whether the contents of the directory are specified.
+#
+# The special "root" specifier describes the root of the dataset and only defines subdirectories.
+# No naming convention applies, and the requirement level and opacity would be superfluous.
+#
+raw:
+  root:
+    subdirs:
+      - code
+      - derivatives
+      - phenotype
+      - sourcedata
+      - stimuli
+      - subject
+  code:
+    name: code
+    level: optional
+    opaque: true
+  derivatives:
+    name: derivatives
+    level: optional
+    opaque: true
+  phenotype:
+    name: phenotype
+    level: optional
+    opaque: false
+  sourcedata:
+    name: sourcedata
+    level: optional
+    opaque: true
+  stimuli:
+    name: stimuli
+    level: optional
+    opaque: true
+  subject:
+    entity: subject
+    level: required
+    opaque: false
+    subdirs:
+      - oneOf:
+          - session
+          - datatype
+  session:
+    entity: session
+    level: optional
+    opaque: false
+    subdirs:
+      - datatype
+  datatype:
+    value: datatype
+    level: required
+    opaque: false
+
+derivative:
+  root:
+    subdirs:
+      - code
+      - derivatives
+      - phenotype
+      - sourcedata
+      - stimuli
+      - subject
+  code:
+    name: code
+    level: optional
+    opaque: true
+  derivatives:
+    name: derivatives
+    level: optional
+    opaque: true
+  phenotype:
+    name: phenotype
+    level: optional
+    opaque: false
+  sourcedata:
+    name: sourcedata
+    level: optional
+    opaque: true
+  stimuli:
+    name: stimuli
+    level: optional
+    opaque: true
+  subject:
+    entity: subject
+    level: optional
+    opaque: false
+    subdirs:
+      - session
+      - datatype
+  session:
+    entity: session
+    level: optional
+    opaque: false
+    subdirs:
+      - datatype
+  datatype:
+    value: datatype
+    level: optional
+    opaque: false

src/schema/rules/files/raw/fmap.yaml

@@ -38,6 +38,7 @@ pepolar:
     ceagent: optional
     direction: required
     run: optional
+    part: optional
     chunk: optional
 
 TB1DAM: