Merge branch 'master' into multi-site

src/appendices/contributors.md

@@ -37,6 +37,7 @@ ecosystem (in alphabetical order).
 If you contributed to the BIDS ecosystem and your name is not listed, please add it.
 
 <!-- THE SECTION BELOW IS AUTOMATICALLY GENERATED -->
+<!--lint ignore -->
 
 | name                                                 | contributions                          |
 | ---------------------------------------------------- | -------------------------------------- |
@@ -121,7 +122,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Dianne Patterson                                     | 📖                                     |
 | Dimitri Papadopoulos Orfanos                         | 📖💡🤔💬💻                             |
 | Dmitry Petrov                                        | 📖💻                                   |
-| Dora Hermes                                          | 📖💻✅🔍🤔                              |
+| Dora Hermes                                          | 📖💻✅🔍🤔                             |
 | Dorien Huijser                                       | 📖                                     |
 | Douglas N. Greve                                     | 📖                                     |
 | Duncan Macleod                                       | 📖🚇                                   |
@@ -194,7 +195,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Jeanette Mumford                                     | 📖                                     |
 | Jefferson Casimir                                    | 🔧                                     |
 | Jeffrey G. Ojemann                                   | 📖                                     |
-| Jeffrey S. Grethe                                    | 💬🐛✅📢💻                              |
+| Jeffrey S. Grethe                                    | 💬🐛✅📢💻                             |
 | JegouA                                               | 💻                                     |
 | Jelle Dalenberg                                      | 📖                                     |
 | Jeremy Moreau                                        | 📖💡                                   |
@@ -211,7 +212,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Jose Manuel Saborit                                  | 📖                                     |
 | Joseph Wexler                                        | 📖💡                                   |
 | Joseph Woods                                         | 📖                                     |
-| Julia Guiomar Niso Galán                             | 🤔🎨🔍👀📋📝🔧🐛💻🔣✅💬📖💡📢          |
+| Julia Guiomar Niso Galán                             | 🤔🎨🔍👀📋📝🔧🐛💻🔣✅💬📖💡📢         |
 | Julia Sprenger                                       | 📖                                     |
 | Julien Cohen-Adad                                    | 📖🔣🤔                                 |
 | Julius Welzel                                        | 📖💡🐛💻🔣🤔💬📓                       |
@@ -269,7 +270,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Michael Hanke                                        | 📖🤔🔧🐛📢                             |
 | Michael P. Harms                                     | 📖⚠️🔧                                 |
 | Michael P. Milham                                    | 💡🔍                                   |
-| Michael P. Notter                                    | 💬📝✅📢📖                              |
+| Michael P. Notter                                    | 💬📝✅📢📖                             |
 | Michael Schirner                                     | 📖                                     |
 | Mikaël Naveau                                        | 🐛                                     |
 | Nader Pouratian                                      | 📖                                     |
@@ -288,7 +289,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Patricia Clement                                     | 💬🐛💻📖🔣💡📋🤔📆⚠️📢                 |
 | Patrick Park                                         | 📖💡💬💻                               |
 | Paule-Joanne Toussaint                               | 📖                                     |
-| Peer Herholz                                         | 💬📖👀🔧✅📢                            |
+| Peer Herholz                                         | 💬📖👀🔧✅📢                           |
 | Petra Ritter                                         | 📖                                     |
 | Pierre Rioux                                         | 📖                                     |
 | Pieter Vandemaele                                    | 📖💻                                   |
@@ -318,7 +319,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
 | Shashank Bansal                                      | 📖                                     |
 | Sjoerd B. Vos                                        | 📖                                     |
 | Soichi Hayashi                                       | 📖🔧🐛                                 |
-| Stefan Appelhoff                                     | 📖💬🤔🐛💡💻👀⚠️📢✅🔧🔌📝🚧🔣          |
+| Stefan Appelhoff                                     | 📖💬🤔🐛💡💻👀⚠️📢✅🔧🔌📝🚧🔣         |
 | Stephan Bickel                                       | 📖                                     |
 | Steven Meisler                                       | 🐛💻💬🔧📓                             |
 | Suyash Bhogawar                                      | 📖💡⚠️🔧💬                             |

src/common-principles.md

@@ -97,6 +97,12 @@ and/or files (like `events.tsv`) are fully omitted *when they are unavailable or
 instead of specified with an `n/a` value, or included as an empty file
 (for example an empty `events.tsv` file with only the headers included).
 
+## Dataset naming
+
+BIDS does not prescribe a particular naming scheme for directories containing individual BIDS datasets.
+However, it is recommended to use a short descriptive name that reflects the content of the dataset, avoid spaces in the name, and use hyphens or underscores to separate words.
+BIDS datasets embedded within a larger BIDS dataset MAY follow some convention (see for example [Storage of derived datasets](#storage-of-derived-datasets)).
+
 ## Filesystem structure
 
 Data for each subject are placed in subdirectories named "`sub-<label>`",
@@ -252,9 +258,10 @@ recommending a particular naming scheme for including different types of
 source data (such as the raw event logs or parameter files, before conversion to BIDS).
 However, in the case that these data are to be included:
 
-1.  These data MUST be kept in separate `sourcedata` directory with a similar
-    directory structure as presented below for the BIDS-managed data. For example:
-    `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or
+1.  These data MUST be kept in separate `sourcedata` directory.
+    BIDS does not prescribe a particular naming scheme for source data,
+    but it is recommended for it to follow BIDS naming convention where possible.
+    For example: `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or
     `sourcedata/sub-01/ses-pre/func/MyEvent.sce`.
 
 1.  A README file SHOULD be found at the root of the `sourcedata` directory or the
@@ -271,41 +278,38 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_filetree_example(
     {
-    "my_dataset-1": {
-            "sourcedata": "",
-            "...": "",
-            "rawdata": {
-                "dataset_description.json": "",
-                "participants.tsv": "",
+    "my_project-1": {
+        "sourcedata": {
+            "dicoms": {},
+            "raw": {
                 "sub-01": {},
                 "sub-02": {},
                 "...": "",
+                "dataset_description.json": "",
+				"...": "",
             },
-            "derivatives": {
-                "pipeline_1": {},
-                "pipeline_2": {},
-                "...": "",
-            },
+            "..." : "",
+        },
+        "derivatives": {
+            "pipeline_1": {},
+            "pipeline_2": {},
+            "...": "",
         }
     }
+   }
 ) }}
 
-In this example, where `sourcedata` and `derivatives` are not nested inside
-`rawdata`, **only the `rawdata` subdirectory** needs to be a BIDS-compliant
-dataset.
+In this example, `sourcedata/dicoms` is not nested inside
+`sourcedata/raw`, **and only the `sourcedata/raw` subdirectory** is a BIDS-compliant dataset among `sourcedata/` subfolders.
 The subdirectories of `derivatives` MAY be BIDS-compliant derivatives datasets
 (see [Non-compliant derivatives](#non-compliant-derivatives) for further discussion).
-This specification does not prescribe anything about the contents of `sourcedata`
-directories in the above example - nor does it prescribe the `sourcedata`,
-`derivatives`, or `rawdata` directory names.
-The above example is just a convention that can be useful for organizing raw,
-source, and derived data while maintaining BIDS compliance of the raw data
-directory. When using this convention it is RECOMMENDED to set the `SourceDatasets`
+The above example is just a convention useful for organizing source, raw BIDS, and derived BIDS data while maintaining BIDS compliance of the raw data directory.
+When using this convention it is RECOMMENDED to set the `SourceDatasets`
 field in `dataset_description.json` of each subdirectory of `derivatives` to:
 
 ```JSON
 {
-  "SourceDatasets": [ {"URL": "../../rawdata/"} ]
+  "SourceDatasets": [ {"URL": "../../sourcedata/raw/"} ]
 }
 ```
 
@@ -406,6 +410,7 @@ Derivatives can be stored/distributed in two ways:
             "sub-01": {},
             "sub-02": {},
             "...": "",
+            "dataset_description.json": "",
             }
         }
     ) }}

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

@@ -1254,6 +1254,7 @@ EPI scans with different phase encoding directions to estimate the distortion
 map corresponding to the nonuniformities of the *B<sub>0</sub>* field.
 These `*_epi.nii[.gz]` - or `*_m0scan.nii[.gz]` for arterial spin labeling perfusion data - files can be 3D or 4D --
 in the latter case, all timepoints share the same scanning parameters.
+Some 4D scans intended for correcting DWIs may have accompanying `*_epi.bval` and `*_epi.bvec` files.
 Examples of software tools using these kinds of images are FSL TOPUP and
 AFNI `3dqwarp`.
 

src/schema/SCHEMA_VERSION

@@ -1 +1 @@
-0.8.1-dev
+0.8.2-dev

src/schema/meta/associations.yaml

@@ -59,15 +59,15 @@ magnitude1:
 
 bval:
   selectors:
-    - suffix == 'dwi'
+    - intersects([suffix], ['dwi', 'epi'])
     - match(extension, '\.nii(\.gz)?$')
   target:
     extension: .bval
   inherit: true
 
 bvec:
   selectors:
-    - suffix == 'dwi'
+    - intersects([suffix], ['dwi', 'epi'])
     - match(extension, '\.nii(\.gz)?$')
   target:
     extension: .bvec

src/schema/meta/context.yaml

@@ -183,6 +183,11 @@ context:
             n_rows:
               description: 'Number of rows in bval file'
               type: integer
+            values:
+              description: 'B-values contained in bval file'
+              type: array
+              items:
+                type: number
         bvec:
           description: 'B vector file'
           type: object

src/schema/objects/suffixes.yaml

@@ -687,6 +687,25 @@ nirs:
   value: nirs
   display_name: Near Infrared Spectroscopy
   description: Data associated with a Shared Near Infrared Spectroscopy Format file.
+noRF:
+  value: noRF
+  display_name: No Radio Frequency Excitation Scan
+  description: |
+    An MR noise scan often acquired alongside another MR scan.
+
+    These noise scans are acquired by disabling the radio frequency excitation,
+    while maintaining all other parameters from the associated scan.
+    These can be acquired using some other sequence with RF excitation removed
+    or as part of sequences that turns off RF at the beginning or end of a run.
+    For example a `bold` scan where a few volumes are acquired with RF off.
+    There is no consistent DICOM denotation for these scans.
+
+    If multiple sequences with different suffixes but otherwise the same entities have `noRF`
+    sequences, they SHOULD be disambiguated using the modality entity
+    (for example, `mod-bold_noRF.nii.gz` and `mod-cbv_noRF.nii`).
+
+    `noRF` are typically used to estimate properties of the scanner and
+    sequence that are independent from the object being imaged.
 optodes:
   value: optodes
   display_name: Optodes

src/schema/rules/checks/dwi.yaml

@@ -9,7 +9,7 @@ DWIVolumeCount:
       associated '.bvec' and '.bval' files.
     level: error
   selectors:
-    - suffix == "dwi"
+    - intersects([suffix], ["dwi", "epi"])
     - '"bval" in associations'
     - '"bvec" in associations'
     - type(nifti_header) != "null"
@@ -25,7 +25,7 @@ DWIBvalRows:
       '.bval' files should contain exactly one row of values.
     level: error
   selectors:
-    - suffix == "dwi"
+    - intersects([suffix], ["dwi", "epi"])
     - '"bval" in associations'
   checks:
     - associations.bval.n_rows == 1
@@ -38,7 +38,7 @@ DWIBvecRows:
       '.bvec' files should contain exactly three rows of values.
     level: error
   selectors:
-    - suffix == "dwi"
+    - intersects([suffix], ["dwi", "epi"])
     - '"bvec" in associations'
   checks:
     - associations.bvec.n_rows == 3

src/schema/rules/checks/fmap.yaml

@@ -49,3 +49,16 @@ MagnitudeFileWithTooManyDimensions:
     - nifti_header != null
   checks:
     - nifti_header.dim[0] == 3
+
+EPISmallBVals:
+  issue:
+    code: EPI_WITH_BVALS_NEEDS_SMALL_BVALS
+    message: |
+      EPI field maps with b-values should include small (b<100) values.
+    level: error
+  selectors:
+    - datatype == "fmap"
+    - suffix == "epi"
+    - '"bval" in associations'
+  checks:
+    - min(associations.bval.values) < 100

src/schema/rules/files/deriv/preprocessed_data.yaml

@@ -104,6 +104,13 @@ fmap_pepolar_common:
     space: optional
     description: optional
 
+fmap_pepolar_m0scan:
+  $ref: rules.files.raw.fmap.pepolar_m0scan
+  entities:
+    $ref: rules.files.raw.fmap.pepolar.entities
+    space: optional
+    description: optional
+
 fmap_TB1DAM_common:
   $ref: rules.files.raw.fmap.TB1DAM
   entities:

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

@@ -24,6 +24,26 @@ fieldmaps:
 pepolar:
   suffixes:
     - epi
+  extensions:
+    - .nii.gz
+    - .nii
+    - .json
+    - .bval
+    - .bvec
+  datatypes:
+    - fmap
+  entities:
+    subject: required
+    session: optional
+    acquisition: optional
+    ceagent: optional
+    direction: required
+    run: optional
+    part: optional
+    chunk: optional
+
+pepolar_m0scan:
+  suffixes:
     - m0scan
   extensions:
     - .nii.gz

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

@@ -23,6 +23,14 @@ func:
     part: optional
     chunk: optional
 
+norf:
+  $ref: rules.files.raw.func.func
+  suffixes:
+    - noRF
+  entities:
+    $ref: rules.files.raw.func.func.entities
+    modality: optional
+
 phase:
   suffixes:
     - phase # deprecated

tools/print_contributors.py

@@ -15,25 +15,23 @@
 
 
 def contributor_table_header(max_name_length, max_contrib_length):
-    return f"""| name{" " * (max_name_length-4)} | contributions{" " * (max_contrib_length-13)} |
-| {"-" * max_name_length} | {"-"*max_contrib_length} |
+    return f"""\
+| {"name":<{max_name_length}} | {"contributions":<{max_contrib_length}} |
+| {"":-<{max_name_length}} | {"":-<{max_contrib_length}} |
 """
 
 
 def create_line_contributor(
     contributor: dict[str, str], max_name_length: int, max_contrib_length: int
 ):
     name = contributor["name"]
+    emap = emoji_map()
+    contributions = "".join(
+        emoji.emojize(emap[cont]) for cont in contributor["contributions"]
+    )
 
-    line = f"| {name}{' '*(max_name_length-len(name))} | "
-
-    nb_contrib = len(contributor["contributions"]) * 2
-    for contrib in contributor["contributions"]:
-        line += emoji.emojize(emoji_map()[contrib])
-
-    line += f"{' '*(max_contrib_length-nb_contrib)} |\n"
-
-    return line
+    pad = max_contrib_length - len(contributor["contributions"]) * 2
+    return f"| {name:<{max_name_length}} | {contributions}{'':<{pad}} |\n"
 
 
 def main():

tools/schemacode/bidsschematools/tests/data/expected_bids_validator_xs_write.log

@@ -3,5 +3,5 @@ SUMMARY:
 0 out of 1 files were successfully validated, using the following regular expressions:
 	- `.*?/sub-(?P<subject>[0-9a-zA-Z]+)/(|ses-(?P<session>[0-9a-zA-Z]+)/)anat/sub-(?P=subject)(|_ses-(?P=session))(|_acq-(?P<acquisition>[0-9a-zA-Z]+))(|_ce-(?P<ceagent>[0-9a-zA-Z]+))(|_rec-(?P<reconstruction>[0-9a-zA-Z]+))(|_run-(?P<run>[0-9a-zA-Z]+))(|_part-(?P<part>(mag|phase|real|imag)))_(T1w|T2w|PDw|T2starw|FLAIR|inplaneT1|inplaneT2|PDT2|angio|T2star)\.(nii.gz|nii|json)$`
 The following files were not matched by any regex schema entry:
-	* `/home/chymera/.data2/datalad/000026/rawdata/sub-EXC022/anat/sub-EXC022_ses-MRI_flip-1_VFA.nii.gz
+	* `/home/chymera/.data2/datalad/000026/noncompliant/sub-EXC022/anat/sub-EXC022_ses-MRI_flip-1_VFA.nii.gz
 The following mandatory regex schema entries did not match any files:

tools/schemacode/bidsschematools/tests/test_validator.py

@@ -64,11 +64,11 @@ def test_write_report(tmp_path):
     ]
     validation_result["path_tracking"] = [
         "/home/chymera/.data2/datalad/000026/"
-        "rawdata/sub-EXC022/anat/sub-EXC022_ses-MRI_flip-1_VFA.nii.gz"
+        "noncompliant/sub-EXC022/anat/sub-EXC022_ses-MRI_flip-1_VFA.nii.gz"
     ]
     validation_result["path_listing"] = [
         "/home/chymera/.data2/datalad/000026/"
-        "rawdata/sub-EXC022/anat/sub-EXC022_ses-MRI_flip-1_VFA.nii.gz"
+        "noncompliant/sub-EXC022/anat/sub-EXC022_ses-MRI_flip-1_VFA.nii.gz"
     ]
 
     report_path = tmp_path / "output_bids_validator_xs_write.log"

tools/schemacode/bidsschematools/validator.py

@@ -599,7 +599,7 @@ def validate_bids(
     ::
 
         from bidsschematools import validator
-        bids_paths = '~/.data2/datalad/000026/rawdata'
+        bids_paths = '~/.data2/datalad/000026/noncompliant'
         validator.validate_bids(bids_paths)
 
     Notes