Merge remote-tracking branch 'upstream/master' into bep031

.circleci/config.yml

@@ -11,13 +11,17 @@ jobs:
           command: |
             python -m pip install --upgrade pip
             pip install -r requirements.txt
+            pip install ~/project/tools/schemacode/
       - run:
           name: generate docs
           command: mkdocs build --clean --strict --verbose
       - persist_to_workspace:
           # the mkdocs build outputs are in ~/project/site
           root: ~/project
           paths: site
+      - store_artifacts:
+          path: ~/project/site/
+          destination: dev_docs
 
   linkchecker:
     docker:

.gitattributes

@@ -2,3 +2,4 @@
 *.png -text
 *.jpg -text
 *.webm -text
+tools/schemacode/schemacode/_version.py export-subst

.github/workflows/redirect_circleci_artifacts.yml

@@ -5,13 +5,9 @@ jobs:
     name: Run CircleCI artifacts redirector
     steps:
       - name: GitHub Action step
-        id: step1
         uses: larsoner/circleci-artifacts-redirector-action@master
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           artifact-path: 0/bids-spec.pdf
           circleci-jobs: build_docs_pdf
           job-title: Check the rendered PDF version here!
-      - name: Check the URL
-        run: |
-          curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA

.github/workflows/schemacode_ci.yml

@@ -0,0 +1,94 @@
+name: "schemacode_ci"
+
+on:
+  push:
+    branches:
+      - "master"
+    paths:
+      - "tools/schemacode/**"
+      - "src/schema/**"
+  pull_request:
+    branches:
+      - "*"
+    paths:
+      - "tools/schemacode/**"
+      - "src/schema/**"
+
+jobs:
+  check_skip:
+    runs-on: ubuntu-latest
+    outputs:
+      skip: ${{ steps.result_step.outputs.ci-skip }}
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - id: result_step
+        uses: mstachniuk/ci-skip@master
+        with:
+          commit-filter: "[skip ci];[ci skip];[skip github]"
+          commit-filter-separator: ";"
+
+  run_tests:
+    needs: check_skip
+    if: ${{ needs.check_skip.outputs.skip == 'false' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+        fail-fast: false
+        matrix:
+            os: ["ubuntu-latest"]
+            python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
+    name: ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v2
+        with:
+            python-version: ${{ matrix.python-version }}
+
+      - name: "Display Python version"
+        shell: bash {0}
+        run: python -c "import sys; print(sys.version)"
+
+      - name: "Install the schemacode package"
+        shell: bash {0}
+        run: |
+          python -m pip install --progress-bar off --upgrade pip setuptools wheel
+          python -m pip install -e ./tools/schemacode[tests]
+
+      - name: "Run tests"
+        shell: bash {0}
+        run: |
+          python -m pytest --pyargs schemacode --cov=schemacode ./tools/schemacode/
+
+      - name: "Upload coverage to CodeCov"
+        uses: codecov/codecov-action@v1
+        if: success()
+
+  flake8-lint:
+    runs-on: ubuntu-latest
+    name: Lint schemacode
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python environment
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.7"
+
+      - name: "Install the schemacode package"
+        shell: bash {0}
+        run: |
+          python -m pip install --progress-bar off --upgrade pip setuptools wheel
+          python -m pip install -e ./tools/schemacode[tests]
+
+      - name: "Run flake8"
+        working-directory: ./tools/schemacode/
+        shell: bash {0}
+        run: |
+          flake8 .

CODEOWNERS

@@ -18,3 +18,7 @@
 /src/05-derivatives/05-functional-derivatives.md @effigies
 /src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban @Lestropie
 /src/99-appendices/06-meg-file-formats.md @monkeyman192
+
+# The schema
+/src/schema/ @tsalo
+/tools/schemacode/ @tsalo

DECISION-MAKING.md

@@ -32,6 +32,7 @@ BIDS governance.
 | Taylor Salo ([@tsalo](https://github.com/tsalo))                               | 3h/week         | MRI                        |
 | Remi Gau ([@Remi-Gau](https://github.com/Remi-Gau))                            | 3h/week         | Community development, MRI |
 | Anthony Galassi  ([@bendhouseart](https://github.com/bendhouseart))            | 3h/week         | PET, Community development |
+| Eric Earl ([@ericearl](https://github.com/ericearl))                           | 2h/week         |                            |
 
 In addition to the [BIDS Governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group)
 classification of a maintainer, maintainers may declare a limited scope of responsibility.

mkdocs.yml

@@ -5,6 +5,8 @@ theme:
     custom_dir: theme_customizations/
     favicon: images/favicon.png
     logo: images/logo.png
+    features:
+      - navigation.sections
 extra_javascript:
     - js/jquery-3.6.0.min.js
 markdown_extensions:
@@ -58,8 +60,9 @@ nav:
         - Quantitative MRI: 99-appendices/11-qmri.md
         - Arterial Spin Labeling: 99-appendices/12-arterial-spin-labeling.md
         - Cross modality correspondence: 99-appendices/13-cross-modality-correspondence.md
+        - Glossary: 99-appendices/14-glossary.md
       - Changelog: CHANGES.md
     - The BIDS Starter Kit:
+      - Website: https://bids-standard.github.io/bids-starter-kit
+      - Tutorials: https://bids-standard.github.io/bids-starter-kit/tutorials/tutorials.html
       - GitHub repository: https://github.com/bids-standard/bids-starter-kit
-      - Tutorials: https://github.com/bids-standard/bids-starter-kit/wiki/Tutorials
-      - Wiki: https://github.com/bids-standard/bids-starter-kit/wiki

requirements.txt

@@ -4,6 +4,4 @@ pymdown-extensions>=7.0.0
 mkdocs-branchcustomization-plugin~=0.1.3
 mkdocs-macros-plugin
 numpy
-pandas
-PYYaml
-tabulate
+tools/schemacode/

src/02-common-principles.md

@@ -119,7 +119,7 @@ misunderstanding we clarify them here.
     the final `_`), right before the **File extension**, for example, it is `eeg` in
     `sub-05_task-matchingpennies_eeg.vhdr`.
 
-1.  **File extension** - a portion of the file name after the left-most
+1.  **File extension** - a portion of the filename after the left-most
     period (`.`) preceded by any other alphanumeric. For example, `.gitignore` does
     not have a file extension, but the file extension of `test.nii.gz` is `.nii.gz`.
     Note that the left-most period is included in the file extension.
@@ -134,10 +134,10 @@ misunderstanding we clarify them here.
 
 The following standard describes a way of arranging data and writing down
 metadata for a subset of neuroimaging experiments. Some aspects of the standard
-are compulsory. For example a particular file name format is required when
+are compulsory. For example a particular filename format is required when
 storing structural scans. Some aspects are regulated but optional. For example a
 T2 volume does not need to be included, but when it is available it should be
-saved under a particular file name specified in the standard. This standard
+saved under a particular filename specified in the standard. This standard
 aspires to describe a majority of datasets, but acknowledges that there will be
 cases that do not fit. In such cases one can include additional files and
 subfolders to the existing folder structure following common sense. For example
@@ -150,13 +150,13 @@ specification.
 
 ## File name structure
 
-A file name consists of a chain of *entities*, or key-value pairs, a *suffix* and an
+A filename consists of a chain of *entities*, or key-value pairs, a *suffix* and an
 *extension*.
 Two prominent examples of entities are `subject` and `session`.
 
 For a data file that was collected in a given `session` from a given
-`subject`, the file name MUST begin with the string `sub-<label>_ses-<label>`.
-If the `session` level is omitted in the folder structure, the file name MUST begin
+`subject`, the filename MUST begin with the string `sub-<label>_ses-<label>`.
+If the `session` level is omitted in the folder structure, the filename MUST begin
 with the string `sub-<label>`, without `ses-<label>`.
 
 Note that `sub-<label>` corresponds to the `subject` entity because it has
@@ -170,19 +170,19 @@ be added for all subjects if at least one subject in the dataset has more than
 one session.
 If a `/ses-<label>` subfolder is included as part of the directory hierarchy,
 then the same [`ses-<label>`](./99-appendices/09-entities.md#ses)
-key/value pair MUST also be included as part of the file names themselves.
+key/value pair MUST also be included as part of the filenames themselves.
 Acquisition time of session can
 be defined in the [sessions file](03-modality-agnostic-files.md#sessions-file).
 
 A chain of entities, followed by a suffix, connected by underscores (`_`)
-produces a human readable file name, such as `sub-01_task-rest_eeg.edf`.
-It is evident from the file name alone that the file contains resting state
+produces a human readable filename, such as `sub-01_task-rest_eeg.edf`.
+It is evident from the filename alone that the file contains resting state
 data from subject `01`.
 The suffix `eeg` and the extension `.edf` depend on the imaging modality and
 the data format and indicate further details of the file's contents.
 
-Entities within a file name MUST be unique.
-For example, the following file name is not valid because it uses the `acq`
+Entities within a filename MUST be unique.
+For example, the following filename is not valid because it uses the `acq`
 entity twice:
 `sub-01_acq-laser_acq-uneven_electrodes.tsv`
 
@@ -659,7 +659,7 @@ of `<index>`es.
 Please note that a given label or index is distinct from the "prefix"
 it refers to. For example `sub-01` refers to the `sub` entity (a
 subject) with the label `01`. The `sub-` prefix is not part of the subject
-label, but must be included in file names (similarly to other key names).
+label, but must be included in filenames (similarly to other key names).
 
 ## Uniform Resource Indicator
 
@@ -817,10 +817,10 @@ For example, an ASSET calibration scan might be named
 
 Non-standard files and directories should be named with care.
 Future BIDS efforts may standardize new entities and suffixes, changing the
-meaning of file names and setting requirements on their contents or metadata.
+meaning of filenames and setting requirements on their contents or metadata.
 Validation and parsing tools MAY treat the presence of non-standard files and
 directories as an error, so consult the details of these tools for mechanisms
-to suppress warnings or provide interpretations of your file names.
+to suppress warnings or provide interpretations of your filenames.
 
 <!-- Link Definitions -->
 

src/03-modality-agnostic-files.md

@@ -259,7 +259,7 @@ samples.json
 ```
 
 The purpose of this file is to describe properties of samples, indicated by the `sample` entity.
-This file is REQUIRED if `sample-<label>` is present in any file name within the dataset.
+This file is REQUIRED if `sample-<label>` is present in any filename within the dataset.
 Each sample MUST be described by one and only one row.
 
 {{ MACROS___make_columns_table(

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

@@ -150,7 +150,7 @@ Useful for multimodal co-registration with MEG, (S)EEG, TMS, and so on.
 
 {{ MACROS___make_metadata_table(
    {
-      "AnatomicalLandmarkCoordinates_mri": "RECOMMENDED",
+      "AnatomicalLandmarkCoordinates__mri": "RECOMMENDED",
    }
 ) }}
 
@@ -1072,7 +1072,7 @@ Required fields:
 
 {{ MACROS___make_metadata_table(
    {
-      "EchoTime_fmap": "REQUIRED",
+      "EchoTime__fmap": "REQUIRED",
    }
 ) }}
 

src/04-modality-specific-files/02-magnetoencephalography.md

@@ -457,7 +457,7 @@ Example:
    "sub-control01": {
       "ses-01":{
          "sub-control01_ses-01_acq-HEAD_headshape.pos": "",
-         "sub-control01_ses-01_acq-ECG_headshape.pos": "",
+         "sub-control01_ses-01_acq-EEG_headshape.pos": "",
          },
       }
    }

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

@@ -224,8 +224,9 @@ MUST be present **in this specific order**:
 
 {{ MACROS___make_columns_table(
    {
-      "name__channels": ("REQUIRED", "The label must correspond to `_electrodes.tsv` name "
-                         "and all ieeg type channels are required to have a position."),
+      "name__channels": ("REQUIRED", "When a corresponding electrode is specified in `_electrodes.tsv`, "
+                         "the name of that electrode MAY be specified here and the reference electrode "
+                         "name MAY be provided in the `reference` column."),
       "type__channels": "REQUIRED",
       "units": "REQUIRED",
       "low_cutoff": "REQUIRED",

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

@@ -20,7 +20,7 @@ sub-<label>/[ses-<label>]
         <matches>_events.json
 ```
 
-Where `<matches>` corresponds to task file name. For example:
+Where `<matches>` corresponds to task filename. For example:
 `sub-control01_task-nback`.
 
 Each task events file REQUIRES a corresponding task data file.

src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md

@@ -24,7 +24,7 @@ For the template directory name, `<datatype>` can correspond to any data
 recording modality, for example `func`, `anat`, `dwi`, `meg`, `eeg`, `ieeg`,
 or `beh`.
 
-In the template file names, the `<matches>` part corresponds to task file name
+In the template filenames, the `<matches>` part corresponds to task filename
 before the suffix.
 For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 `<matches>` would correspond to `sub-control01_task-nback_run-1`.

src/05-derivatives/01-introduction.md

@@ -57,7 +57,8 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     files.
 
 -   When necessary to distinguish two files that do not otherwise have a
-    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+    distinguishing entity, the [`_desc-<label>`](../99-appendices/09-entities.md#desc)
+    keyword-value SHOULD be used.
     This includes the cases of needing to distinguish both differing inputs and
     differing outputs (for example, `_desc-T1w` and `_desc-T2w` to distinguish
     brain mask files derived from T1w and T2w images;
@@ -67,7 +68,7 @@ in [Derived dataset and pipeline description][derived-dataset-description].
 -   When naming files that are not yet standardized, it is RECOMMENDED to use
     names consistent with BIDS conventions where those conventions apply.
     For example, if a summary statistic is derived from a given task, the file
-    name SHOULD contain `_task-<label>`.
+    name SHOULD contain [`_task-<label>`](../99-appendices/09-entities.md#task).
 
 <!-- Link Definitions -->
 

src/05-derivatives/02-common-data-types.md

@@ -24,8 +24,9 @@ share the following (non-required) ones:
 ### Examples
 
 Preprocessed `bold` NIfTI file in the original coordinate space of the original run.
-The location of the file in the original datasets is encoded in the `RawSources`
-metadata, and `desc-<label>` is used to prevent clashing with the original file name.
+The location of the file in the original datasets is encoded in the `RawSources` metadata,
+and [`_desc-<label>`](../99-appendices/09-entities.md#desc)
+is used to prevent clashing with the original filename.
 
 {{ MACROS___make_filetree_example(
    {
@@ -75,12 +76,13 @@ occurs in the derivatives, `Sources` and `RawSources` can both be specified.
 Derivatives are often aligned to a common spatial reference to allow for the
 comparison of acquired data across runs, sessions, subjects or datasets.
 A file may indicate the spatial reference to which it has been aligned using the
-`space` entity and/or the `SpatialReference` metadata.
+[`space` entity](../99-appendices/09-entities.md#space) and/or the `SpatialReference` metadata.
 
-The `space` entity may take any value in [Image-Based Coordinate Systems][coordsys].
+The [`space` entity](../99-appendices/09-entities.md#space) may take any value in
+[Image-Based Coordinate Systems][coordsys].
 
-If the `space` entity is omitted, or the space is not in the
-[Standard template identifiers][templates] table,
+If the [`space` entity](../99-appendices/09-entities.md#space) is omitted,
+or the space is not in the [Standard template identifiers][templates] table,
 then the `SpatialReference` metadata is REQUIRED.
 
 {{ MACROS___make_metadata_table(
@@ -174,10 +176,12 @@ Examples of preprocessing:
 -   Time-domain filtered EEG data
 -   MaxFilter (for example, SSS) cleaned MEG data
 
-The `space` keyword is recommended to distinguish files with different underlying
+The [`space` entity](../99-appendices/09-entities.md#space)
+is recommended to distinguish files with different underlying
 coordinate systems or registered to different reference maps.
 See [Spatial references](#spatial-references) for details.
-The `desc` (description) keyword is a general purpose field with freeform values,
+The [`desc` entity](../99-appendices/09-entities.md#desc) ("description")
+is a general purpose field with freeform values,
 which SHOULD be used to distinguish between multiple different versions of
 processing for the same input data.