Merge branch 'master' into ad/table-position

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: check-added-large-files
       - id: check-case-conflict
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.29.0
+    rev: 0.29.1
     hooks:
       - id: check-dependabot
       - id: check-github-workflows
@@ -25,7 +25,7 @@ repos:
       - id: check-readthedocs
         files: readthedocs.yml
   - repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 24.8.0
     hooks:
       - id: black
         files: ^tools/(?!schemacode)
@@ -45,7 +45,7 @@ repos:
         files: tools/schemacode
         args: ["--settings-file", "tools/schemacode/pyproject.toml"]
   - repo: https://github.com/pyCQA/flake8
-    rev: 7.1.0
+    rev: 7.1.1
     hooks:
       - id: flake8
         args: [--config=tools/schemacode/setup.cfg]
@@ -67,7 +67,7 @@ repos:
       - id: codespell
         args: ["--config=.codespellrc", "--dictionary=-", "--dictionary=.codespell_dict"]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.0
+    rev: v1.11.1
     hooks:
       - id: mypy
         # Sync with project.optional-dependencies.typing

CONTRIBUTING.md

@@ -257,6 +257,9 @@ The keyword for the heading must be one of the following:
 - example
 - quote
 
+Do not put [macros](#using-macros) in admonitions,
+as this will likely not give the output you expect.
+
 ## Using macros
 
 We use [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)

src/metaschema.json

@@ -82,7 +82,18 @@
           "patternProperties": {
             "^[a-zA-Z0-9_]+$": {
               "allOf": [
-                { "$ref": "#/definitions/termTypes/JSONSchema" },
+                {
+                  "anyOf": [
+                    { "$ref": "#/definitions/termTypes/JSONSchema" },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "definition": { "type": "object" }
+                      },
+                      "required": ["definition"]
+                    }
+                  ]
+                },
                 { "$ref": "#/definitions/termTypes/general" },
                 { "$ref": "#/definitions/termTypes/nameValue" },
                 {
@@ -304,7 +315,7 @@
                       "$ref": "#/definitions/ruleTypes/expressionList"
                     }
                   },
-                  "required": ["checks", "selectors"],
+                  "required": ["checks", "selectors", "issue"],
                   "additionalProperties": false
                 }
               }

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

@@ -1,5 +1,11 @@
 # Behavioral experiments (with no neural recordings)
 
+!!! example "Example datasets"
+
+    Datasets containing behavioral data can be found
+    in the [BIDS examples repository](https://bids-standard.github.io/bids-examples/#behavioral)
+    and can be used as helpful guidance when curating new datasets.
+
 <!--
 This block generates a filename templates.
 The inputs for this macro can be found in the directory
@@ -9,17 +15,20 @@ and a guide for using macros can be found at
 -->
 {{ MACROS___make_filename_template("raw", datatypes=["beh"]) }}
 
-In addition to logs from behavioral experiments performed alongside imaging data
-acquisitions, one can also include data from experiments performed with no neural
-recordings.
-The results of those experiments can be stored in the `beh` directory using the same
-formats for event timing (`_events.tsv`), metadata (`_events.json`),
+In addition to logs from behavioral experiments
+performed alongside imaging data acquisitions,
+one MAY also include data from experiments
+performed with no neural recordings.
+The results of those experiments MAY be stored in the `beh` directory
+using the same formats for event timing (`_events.tsv`),
+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.
-Additionally, events files that do not include the mandatory `onset` and
-`duration` columns can still be included, but should be labeled `_beh.tsv`
-rather than `_events.tsv`.
+Additionally, events files
+that do not include the mandatory `onset` and `duration` columns
+MAY be included,
+but MUST be labeled `_beh.tsv` rather than `_events.tsv`.
 
 ## Sidecar JSON (`*_beh.json`)
 

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

@@ -160,7 +160,11 @@ The definitions of the fields specified in these tables may be found in
 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.MRIEchoPlanarImagingAndB0Mapping") }}
+{{ MACROS___make_sidecar_table([
+     "mri.MRIB0FieldIdentifier",
+     "mri.MRIEchoPlanarImagingAndB0FieldSource",
+   ])
+}}
 
 #### Tissue description
 
@@ -717,7 +721,7 @@ within the `[*_]dwi.bval` and `[*_]dwi.bvec` files) MAY change across DWI runs.
 
 **Gradient orientation file formats**.
 The `[*_]dwi.bval` and `[*_]dwi.bvec` files MUST follow the
-[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT):
+[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/index?id=diffusion-data-in-fsl):
 The `[*_]dwi.bvec` file contains 3 rows with *N* space-delimited floating-point numbers
 (corresponding to the *N* volumes in the corresponding NIfTI file.)
 The first row contains the *x* elements, the second row contains the *y* elements and

src/modality-specific-files/microscopy.md

@@ -55,7 +55,7 @@ Microscopy raw data MUST be stored in one of the following formats:
 
 -   [OME-TIFF](https://docs.openmicroscopy.org/ome-model/6.1.2/ome-tiff/specification.html#)
     (`.ome.tif` for standard TIFF files or `.ome.btf` for
-    [BigTIFF](https://www.awaresystems.be/imaging/tiff/bigtiff.html) files)
+    [BigTIFF](https://web.archive.org/web/20240706160214/https://www.awaresystems.be/imaging/tiff/bigtiff.html) files)
 
 -   [OME-ZARR/NGFF](https://ngff.openmicroscopy.org/latest/) (`.ome.zarr` directories)
 

src/modality-specific-files/task-events.md

@@ -27,9 +27,9 @@ Each task events file REQUIRES a corresponding task data file.
 It is also possible to have a single `events.tsv` file describing events
 for all participants and runs (see
 [Inheritance Principle](../common-principles.md#the-inheritance-principle)).
-As with all other tabular data, `events.tsv` files MAY be accompanied by a JSON
-file describing the columns in detail (see
-[Tabular Files](../common-principles.md#tabular-files)).
+As with all other tabular data, `events.tsv` files MAY be accompanied
+by a JSON file describing the columns in detail
+(see [Tabular Files](../common-principles.md#tabular-files)).
 
 The tabular files consists of one row per event and a set of REQUIRED
 and OPTIONAL columns:
@@ -44,26 +44,30 @@ and a guide for using macros can be found at
 
 The content of  `events.tsv` files SHOULD be sorted by values in the `onset` column.
 
-Note for MRI data:
-If any acquired scans have been discarded before forming the imaging data file,
-ensure that an `onset` of 0 corresponds to the time the first image was stored.
-For example in case there is an in scanner training phase that
-begins before the scanning sequence has started events from this sequence should
-have negative onset time counting down to the beginning of the acquisition of
-the first volume.
-
-Note regarding the precision of numeric metadata:
-It is RECOMMENDENDED that dataset curators specify numeric metadata like `onset` and
-`duration` with as much decimal precision as is reasonable in the context of the experiment.
-For example in an EEG experiment with devices operating at 1000 Hz sampling frequency,
-dataset curators SHOULD specify **at least** 3 figures after the decimal point.
-
-An arbitrary number of additional columns can be added. Those allow describing
-other properties of events that could be later referenced in modeling and
+An arbitrary number of additional columns can be added.
+Those allow describing other properties of events that could be later referenced in modeling and
 hypothesis extensions of BIDS.
 Note that the `trial_type` and any additional columns in a TSV file
 SHOULD be documented in an accompanying JSON sidecar file.
 
+!!! note "Regarding the precision of numeric metadata"
+
+    For the precision of numeric metadata,
+    it is RECOMMENDENDED that dataset curators specify numeric metadata like `onset` and
+    `duration` with as much decimal precision as is reasonable in the context of the experiment.
+    For example in an EEG experiment with devices operating at 1000 Hz sampling frequency,
+    dataset curators SHOULD specify **at least** 3 figures after the decimal point.
+
+!!! note "For fMRI data"
+
+    For fMRI data
+    if any acquired scans have been discarded before forming the imaging data file,
+    ensure that an `onset` of 0 corresponds to the time the first image was stored.
+    For example in case there is an in scanner training phase that
+    begins before the scanning sequence has started events from this sequence should
+    have negative onset time counting down to the beginning of the acquisition of
+    the first volume.
+
 Example:
 
 <!-- This block generates a file tree.
@@ -119,24 +123,26 @@ In the accompanying JSON sidecar, the `trial_type` column might look as follows:
 }
 ```
 
-Note that in the example above:
+!!! note
 
-1.  Only a subset of columns are described for the sake of brevity.
-    In a real dataset, all other columns SHOULD also be described.
+    In the example above:
 
-1.  The `channel` column contains a list of values that are separated
-    by a delimiter (`|`), as is declared in the `Delimiter` metadata
-    field of the `events.json` file.
-    Thus, the channels related to the event in the third row of the example
-    are called `F,1`, `F,2`, and `Cz`.
+    1.  Only a subset of columns are described for the sake of brevity.
+        In a real dataset, all other columns SHOULD also be described.
 
-1.  The example contains a column called `annots`.
-    This column is not defined in BIDS, and constitutes additional, arbitrary
-    (that is, unofficial) metadata.
-    In the present case, it is used to describe artifacts in the data,
-    in reference to the `channel` column.
-    The `annots` column is making
-    use of the powerful HED system for documenting events, see below.
+    1.  The `channel` column contains a list of values that are separated
+        by a delimiter (`|`), as is declared in the `Delimiter` metadata field
+        of the `events.json` file.
+        Thus, the channels related to the event in the third row of the example
+        are called `F,1`, `F,2`, and `Cz`.
+
+    1.  The example contains a column called `annots`.
+        This column is not defined in BIDS, and constitutes additional,
+        arbitrary (that is, unofficial) metadata.
+        In the present case, it is used to describe artifacts in the data,
+        in reference to the `channel` column.
+        The `annots` column is making use of the powerful HED system
+        for documenting events, see below.
 
 Events MAY also be documented in machine-actionable form
 using HED (Hierarchical Event Descriptor) tags.
@@ -145,8 +151,8 @@ in event-related analyses.
 See [Hierarchical Event Descriptors](../appendices/hed.md)
 for additional information and examples.
 
-For multi-echo files, the `events.tsv` file is applicable to all echos of
-a particular run:
+For multi-echo files, the `events.tsv` file is applicable
+to all echos of a particular run:
 
 <!-- This block generates a file tree.
 A guide for using macros can be found at
@@ -188,8 +194,6 @@ References to existing databases can also be encoded using additional columns.
 The following example includes references to the
 [Karolinska Directed Emotional Faces (KDEF) database](https://www.kdef.se/).
 
-Example:
-
 <!-- 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
@@ -235,8 +239,8 @@ in the accompanying JSON sidecar as follows:
 }
 ```
 
-Note that all other columns SHOULD also be described but are omitted for the
-sake of brevity.
+Note that all other columns SHOULD also be described but are omitted
+for the sake of brevity.
 
 ### Stimulus presentation details