Merge branch 'master' of https://github.com/markmikkelsen/bids-specification

Author: markmikkelsen

.github/workflows/schemacode_ci.yml

@@ -33,7 +33,7 @@ jobs:
       - name: "Install build dependencies"
         run: pip install --upgrade build twine
       - name: "Install test dependencies on tag"
-        run: pip install --upgrade tools/schemacode[test]
+        run: pip install --upgrade tools/schemacode[tests]
         if: ${{ startsWith(github.ref, 'refs/tags/schema-') }}
       - name: "Build archive on tag"
         run: pytest tools/schemacode/bidsschematools -k make_archive

src/appendices/arterial-spin-labeling.md

@@ -79,7 +79,7 @@ For (P)CASL, specifying the `LabelingDuration` and the `PostLabelingDelay` is re
 The `LabelingDuration` is defined as the total duration of the labeling pulse train in seconds.
 `PostLabelingDelay` is the time in seconds after the end of the labeling until the middle of the excitation pulse applied
 to the imaging slab (for 3D acquisition) or first slice (for 2D acquisition).
-Additionally, the `BackgroundSuppressionPulseTime`'s is required in case `BackgroundSuppression` was applied.
+Additionally, the `BackgroundSuppressionPulseTime` is RECOMMENDED if `BackgroundSuppression` was applied.
 This an array of numbers containing the timing in seconds of the background suppression pulses
 with respect to the start of the labeling.
 In the case of `PCASL`, the recommended `PCASLType` field defines the type of the gradient pulses

src/appendices/contributors.md

@@ -55,6 +55,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Alexander Jones                                      | 💻🐛                                   |
 | Alexander L. Cohen                                   | 🐛💻📖💬                               |
 | Alexander von Lautz                                  | 📖                                     |
+| Alexandre D'Astous                                   | 📖                                     |
 | Alexandre Gramfort                                   | 📖💡                                   |
 | Alexandre Hutton                                     | 📖                                     |
 | Alexandre Routier                                    | 📖                                     |

src/metaschema.json

@@ -68,6 +68,7 @@
         "versions": {
           "type": "array",
           "items": {
+            "type": "string",
             "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
           }
         }
@@ -315,7 +316,7 @@
                       "$ref": "#/definitions/ruleTypes/expressionList"
                     }
                   },
-                  "required": ["checks", "selectors"],
+                  "required": ["checks", "selectors", "issue"],
                   "additionalProperties": false
                 }
               }
@@ -386,19 +387,25 @@
           "required": ["common", "deriv", "raw"],
           "additionalProperties": false
         },
+        "json": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/json"
+          }
+        },
         "sidecars": {
           "type": "object",
           "patternProperties": {
             "^derivatives$": {
               "type": "object",
               "properties": {
-                "common_derivatives": { "$ref": "#/definitions/sidecar" }
+                "common_derivatives": { "$ref": "#/definitions/json" }
               },
               "required": ["common_derivatives"],
               "additionalProperties": false
             },
             "^(?!derivatives$)[a-z_]+$": {
-              "$ref": "#/definitions/sidecar"
+              "$ref": "#/definitions/json"
             },
             "additionalProperties": false
           },
@@ -464,7 +471,7 @@
               "properties": {
                 "datatypes": {
                   "type": "array",
-                  "items": { "pattern": "^[a-z]+$" }
+                  "items": { "type": "string", "pattern": "^[a-z]+$" }
                 }
               },
               "required": ["datatypes"],
@@ -476,6 +483,7 @@
       "required": [
         "entities",
         "files",
+	"json",
         "sidecars",
         "tabular_data",
         "common_principles",
@@ -586,7 +594,7 @@
         }
       }
     },
-    "sidecar": {
+    "json": {
       "type": "object",
       "patternProperties": {
         "^[a-zA-Z0-9_]+$": {
@@ -654,7 +662,7 @@
         "level": { "enum": ["optional", "recommended", "required"] },
         "datatypes": {
           "type": "array",
-          "items": { "pattern": "^[a-z]+$" }
+          "items": { "type": "string", "pattern": "^[a-z]+$" }
         },
         "stem": { "type": "string" },
         "extensions": { "type": "array", "items": { "type": "string" } }
@@ -668,11 +676,11 @@
         "level": { "enum": ["optional", "recommended", "required"] },
         "datatypes": {
           "type": "array",
-          "items": { "pattern": "^[a-z]+$" }
+          "items": { "type": "string", "pattern": "^[a-z]+$" }
         },
         "suffixes": {
           "type": "array",
-          "items": { "pattern": "^[a-zA-Z0-9]+$" }
+          "items": { "type": "string", "pattern": "^[a-zA-Z0-9]+$" }
         },
         "extensions": { "type": "array", "items": { "type": "string" } },
         "entities": {

src/modality-specific-files/electroencephalography.md

@@ -390,7 +390,7 @@ 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("eeg.EEGCoordsystemGeneral") }}
+{{ MACROS___make_json_table("json.eeg.EEGCoordsystemGeneral") }}
 
 Fields relating to the EEG electrode positions:
 
@@ -402,7 +402,7 @@ 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("eeg.EEGCoordsystemPositions") }}
+{{ MACROS___make_json_table("json.eeg.EEGCoordsystemPositions") }}
 
 Fields relating to the position of fiducials measured during an EEG session/run:
 
@@ -414,7 +414,7 @@ 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("eeg.EEGCoordsystemFiducials") }}
+{{ MACROS___make_json_table("json.eeg.EEGCoordsystemFiducials") }}
 
 Fields relating to the position of anatomical landmark measured during an EEG session/run:
 
@@ -426,7 +426,7 @@ 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(["eeg.EEGCoordsystemLandmark", "eeg.EEGCoordsystemLandmarkDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.eeg.EEGCoordsystemLandmark", "json.eeg.EEGCoordsystemLandmarkDescriptionRec"]) }}
 
 If the position of anatomical landmarks is measured using the same system or
 device used to measure electrode positions, and if thereby the anatomical

src/modality-specific-files/intracranial-electroencephalography.md

@@ -389,7 +389,7 @@ 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("ieeg.iEEGCoordsystemGeneral") }}
+{{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemGeneral") }}
 
 Fields relating to the iEEG electrode positions:
 
@@ -401,7 +401,7 @@ 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("ieeg.iEEGCoordsystemPositions") }}
+{{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemPositions") }}
 
 ### Recommended 3D coordinate systems
 

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

@@ -721,37 +721,46 @@ 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/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
-the third row contains the *z* elements of a unit vector in the direction of the applied
-diffusion gradient, where the *i*-th elements in each row correspond together to
-the *i*-th volume, with `[0,0,0]` for *non-diffusion-weighted* (also called *b*=0 or *low-b*)
-volumes.
-Following the FSL format for the `[*_]dwi.bvec` specification, the coordinate system of
-the *b* vectors MUST be defined with respect to the coordinate system defined by
-the header of the corresponding `_dwi` NIfTI file and not the scanner's device
-coordinate system (see [Coordinate systems](../appendices/coordinate-systems.md)).
-The most relevant limitation imposed by this choice is that the gradient information cannot
-be directly stored in this format if the scanner generates *b*-vectors in *scanner coordinates*.
-
-Example of `[*_]dwi.bvec` file, with *N*=6, with two *b*=0 volumes in the beginning:
-
-```Text
-0 0 0.021828 -0.015425 -0.70918 -0.2465
-0 0 0.80242 0.22098 -0.00063106 0.1043
-0 0 -0.59636 0.97516 -0.70503 -0.96351
-```
-
-The `[*_]dwi.bval` file contains the *b*-values (in s/mm<sup>2</sup>) corresponding to the
-volumes in the relevant NIfTI file), with 0 designating *b*=0 volumes, space-delimited.
-
-Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` example:
-
-```Text
-0 0 2000 2000 1000 1000
-```
+[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.
+Across these three rows,
+each column encodes three elements of a 3-vector for the corresponding image volume;
+each vector MUST be either of unit norm,
+or optionally the vector `[0.0,0.0,0.0]`
+for *non-diffusion-weighted* (also called *b*=0 or *low-b*) volumes.
+These values are to be interpreted as cosine values with respect to the image axis orientations
+as defined by the corresponding NIfTI image header transformation;
+*unless* the image axes defined in the corresponding NIfTI image header
+form a right-handed coordinate system
+(that is, the 3x3 matrix of direction cosines has a positive determinant),
+in which case the sign of the first element of each 3-vector must be inverted
+for this interpretation to be valid.
+Note that this definition of orientations with respect to the NIfTI image axes
+is *not* equivalent to the DICOM convention,
+where orientations are instead defined with respect to the scanner device's coordinate system
+(see [Coordinate systems](../appendices/coordinate-systems.md)).
+
+The `[*_]dwi.bval` file contains the *b*-values (in s/mm<sup>2</sup>)
+corresponding to the volumes in the relevant NIfTI file,
+with 0 designating *b*=0 volumes; space-delimited.
+
+Examples of `[*_]dwi.bvec` and `[*_]dwi.bval` files,
+corresponding to a NIfTI image with 6 volumes
+with the first two volumes having no diffusion sensitization:
+
+-   `[*_]dwi.bvec`:
+    ```Text
+    0 0 0.021828 -0.015425 -0.70918 -0.2465
+    0 0 0.80242 0.22098 -0.00063106 0.1043
+    0 0 -0.59636 0.97516 -0.70503 -0.96351
+    ```
+
+-   `[_]dwi.bval`:
+    ```Text
+    0 0 2000 2000 1000 1000
+    ```
 
 ### Multipart (split) DWI schemes
 

src/modality-specific-files/magnetoencephalography.md

@@ -343,7 +343,7 @@ 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("meg.MEGCoordsystemWithEEG") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemWithEEG") }}
 
 Head localization coils:
 
@@ -355,7 +355,7 @@ 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("meg.MEGCoordsystemHeadLocalizationCoils") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemHeadLocalizationCoils") }}
 
 Digitized head points:
 
@@ -367,7 +367,7 @@ 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("meg.MEGCoordsystemDigitizedHeadPoints") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemDigitizedHeadPoints") }}
 
 Anatomical MRI:
 
@@ -379,7 +379,7 @@ 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("meg.MEGCoordsystemAnatomicalMRI") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemAnatomicalMRI") }}
 
 Anatomical landmarks:
 
@@ -391,7 +391,7 @@ 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("meg.MEGCoordsystemAnatomicalLandmarks") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemAnatomicalLandmarks") }}
 
 It is also RECOMMENDED that the MRI voxel coordinates of the actual anatomical
 landmarks for co-registration of MEG with structural MRI are stored in the
@@ -419,7 +419,7 @@ 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("meg.MEGCoordsystemFiducialsInformation") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemFiducialsInformation") }}
 
 For more information on the definition of anatomical landmarks, please visit:
     [How are the Left and Right Pre-Auricular (LPA and RPA) points defined? - FieldTrip Toolbox](https://www.fieldtriptoolbox.org/faq/how_are_the_lpa_and_rpa_points_defined/)

src/modality-specific-files/near-infrared-spectroscopy.md

@@ -386,7 +386,7 @@ 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("nirs.CoordsystemGeneral") }}
+{{ MACROS___make_json_table("json.nirs.CoordsystemGeneral") }}
 
 Fields relating to the NIRS optode positions:
 
@@ -399,7 +399,7 @@ 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(["nirs.CoordinateSystem", "nirs.CoordinateSystemDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.nirs.CoordinateSystem", "json.nirs.CoordinateSystemDescriptionRec"]) }}
 
 Fields relating to the position of fiducials measured during an NIRS session/run:
 
@@ -412,7 +412,7 @@ 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(["nirs.Fiducials", "nirs.FiducialsCoordinateSystemDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.nirs.Fiducials", "json.nirs.FiducialsCoordinateSystemDescriptionRec"]) }}
 
 Fields relating to the position of anatomical landmarks measured during an NIRS session/run:
 
@@ -425,7 +425,7 @@ 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(["nirs.AnatomicalLandmark", "nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.nirs.AnatomicalLandmark", "json.nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }}
 
 ### Example `*_coordsystem.json`