Merge branch 'master' into schema/notch-type

.github/workflows/schemacode_ci.yml

@@ -26,7 +26,7 @@ jobs:
         os: ["ubuntu-latest"]
         python-version: ["3.11"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
@@ -64,7 +64,7 @@ jobs:
             python-version: 3
     name: ${{ matrix.os }} with Python ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: "Set up Python"
         uses: actions/setup-python@v4
@@ -129,7 +129,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Validate schema
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set Up Python environment
         uses: actions/setup-python@v4
@@ -157,7 +157,7 @@ jobs:
     needs: [test, validate_schema]
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Download artifacts
         uses: actions/download-artifact@v3

.github/workflows/validation.yml

@@ -16,14 +16,14 @@ jobs:
   codespell:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: codespell-project/actions-codespell@master
 
   # Markdown formatting
   remark:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
         with:
           node-version: 14
@@ -36,7 +36,7 @@ jobs:
   yamllint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3
@@ -49,7 +49,7 @@ jobs:
   python-style:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3
@@ -63,7 +63,7 @@ jobs:
   latin-phrases:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3
@@ -86,7 +86,7 @@ jobs:
   validate_cff:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-python@v4
       with:
         python-version: 3

.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.7.0
+    rev: 23.9.1
     hooks:
       - id: black
         files: ^tools/(?!schemacode)

README.md

@@ -1,5 +1,6 @@
 [![Validation](https://github.com/bids-standard/bids-specification/actions/workflows/validation.yml/badge.svg)](https://github.com/bids-standard/bids-specification/actions/workflows/validation.yml)
 [![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=shield)](https://circleci.com/gh/bids-standard/bids-specification)
+[![Mastodon Follow](https://img.shields.io/mastodon/follow/109520103085644521?domain=https%3A%2F%2Ffosstodon.org%2F)](https://fosstodon.org/@bidsstandard)
 [![@BIDSstandard](http://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://twitter.com/BIDSstandard)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3686061.svg)](https://doi.org/10.5281/zenodo.3686061)
 

src/CHANGES.md

@@ -2,7 +2,18 @@
 
 ## [Unreleased](https://github.com/bids-standard/bids-specification/tree/HEAD)
 
+-   \[ENH] Allow Levels field of column descriptions to be objects with TermURLs for each level [#1603](https://github.com/bids-standard/bids-specification/pull/1603) ([Remi-Gau](https://github.com/Remi-Gau))
+-   \[ENH] Add optional low_cutoff and high_cutoff columns for fnirs channels.tsv [#1597](https://github.com/bids-standard/bids-specification/pull/1597) ([Remi-Gau](https://github.com/Remi-Gau))
+-   \[SCHEMA]\[ENH] Remove atlas entity and replace it with seg in prep of BEP038 [#1579](https://github.com/bids-standard/bids-specification/pull/1579) ([melanieganz](https://github.com/melanieganz))
+-   \[FIX] improve longitudinal example [#1576](https://github.com/bids-standard/bids-specification/pull/1576) ([Remi-Gau](https://github.com/Remi-Gau))
+-   Adds Kim Ray as maintainer. [#1571](https://github.com/bids-standard/bids-specification/pull/1571) ([arokem](https://github.com/arokem))
+-   \[ENH] Allow for "echo" entity to be used with T1w and other nonparametric anatomical suffixes [#1570](https://github.com/bids-standard/bids-specification/pull/1570) ([yarikoptic](https://github.com/yarikoptic))
+-   Update `templates` in modality-agnostic-files [#1564](https://github.com/bids-standard/bids-specification/pull/1564) ([sappelhoff](https://github.com/sappelhoff))
+-   \[FIX] Clarify that electrodes.tsv is optional for MEG, for use with simultaneous (i)EEG [#1555](https://github.com/bids-standard/bids-specification/pull/1555) ([effigies](https://github.com/effigies))
+-   \[ENH] Allow UNKNOWN and NONE ContrastBolusIngredients [#1547](https://github.com/bids-standard/bids-specification/pull/1547) ([Remi-Gau](https://github.com/Remi-Gau))
 -   \[FIX] Update links to BIDS examples [#1545](https://github.com/bids-standard/bids-specification/pull/1545) ([Remi-Gau](https://github.com/Remi-Gau))
+-   \[ENH] add schema in appendix [#1543](https://github.com/bids-standard/bids-specification/pull/1543) ([Remi-Gau](https://github.com/Remi-Gau))
+-   \[ENH] add "visual correction" and "head stabilization" metadata [#1539](https://github.com/bids-standard/bids-specification/pull/1539) ([Remi-Gau](https://github.com/Remi-Gau))
 -   \[ENH] Clarify meaning of raw vs derivative datasets [#1537](https://github.com/bids-standard/bids-specification/pull/1537) ([CPernet](https://github.com/CPernet))
 -   \[FIX] match subject label in folder and filename in func example [#1536](https://github.com/bids-standard/bids-specification/pull/1536) ([Remi-Gau](https://github.com/Remi-Gau))
 -   FIX: Trail MEG directory formats with `/` [#1534](https://github.com/bids-standard/bids-specification/pull/1534) ([effigies](https://github.com/effigies))

src/common-principles.md

@@ -513,6 +513,29 @@ Example:
 }
 ```
 
+Each level can be described with a string as in the example above,
+or with an object containing the fields [`Description`](./glossary.md#description-metadata)
+and [`TermURL`](./glossary.md#termurl-metadata)
+like in the example below.
+
+```JSON
+{
+    "sex": {
+        "Description": "sex of the participant as reported by the participant",
+        "Levels": {
+            "M": {
+                "Description": "Male",
+                "TermURL": "https://www.ncbi.nlm.nih.gov/mesh/68008297"
+            },
+            "F": {
+                "Description": "Female",
+                "TermURL": "https://www.ncbi.nlm.nih.gov/mesh/68005260"
+            },
+        }
+    }
+}
+```
+
 ### Key-value files (dictionaries)
 
 JavaScript Object Notation (JSON) files MUST be used for storing key-value

src/derivatives/imaging.md

@@ -153,10 +153,9 @@ Template:
 
 A binary (1 - inside, 0 - outside) mask in the space defined by the [`space` entity](../appendices/entities.md#space).
 If no transformation has taken place, the value of `space` SHOULD be set to `orig`.
-If the mask is an ROI mask derived from an atlas, then the [`label` entity](../appendices/entities.md#label)) SHOULD
-be used to specify the masked structure
-(see [Common image-derived labels](#common-image-derived-labels)),
-and the `Atlas` metadata SHOULD be defined.
+If the mask is an ROI mask derived from an atlas segmentation,
+then the [`label` entity](../appendices/entities.md#label) SHOULD be used to specify the masked structure
+(see [Common image-derived labels](#common-image-derived-labels)).
 
 JSON metadata fields:
 
@@ -170,7 +169,6 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table([
        "derivatives.common_derivatives.MaskDerivatives",
-       "derivatives.common_derivatives.MaskDerivativesAtlas",
        "derivatives.common_derivatives.ImageDerivativeResEntity",
        "derivatives.common_derivatives.ImageDerivativeDenEntity",
    ]) }}
@@ -229,10 +227,10 @@ structure may be concatenated in a single file.
 Segmentations may be defined in a volume (labeled voxels), a surface (labeled
 vertices) or a combined volume/surface space.
 
-If the segmentation can be derived from different atlases,
-the [`atlas` entity](../appendices/entities.md#atlas) MAY be used to
-distinguish the different segmentations.
-If so, the `Atlas` metadata SHOULD also be defined.
+If the segmentation can be generated in different ways,
+for example, following an atlas segmentation,
+the [`seg` entity](../appendices/entities.md#segmentation) MAY be used to
+distinguish the name of the segmentation used.
 
 The following section describes discrete and probabilistic segmentations of
 volumes, followed by discrete segmentations of surface/combined spaces.
@@ -250,7 +248,6 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_sidecar_table([
        "derivatives.common_derivatives.SegmentationCommon",
-       "derivatives.common_derivatives.SegmentationCommonAtlas",
        "derivatives.common_derivatives.ImageDerivativeResEntity",
        "derivatives.common_derivatives.ImageDerivativeDenEntity",
    ]) }}
@@ -268,7 +265,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         anat|func|dwi/
-            <source_entities>[_space-<space>][_atlas-<label>][_res-<label>][_den-<label>]_dseg.nii.gz
+            <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_den-<label>]_dseg.nii.gz
 ```
 
 Example:
@@ -296,8 +293,7 @@ In this case, the mask suffix MUST be used,
 the [`label` entity](../appendices/entities.md#label)) SHOULD be used
 to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)),
-the [`atlas` entity](../appendices/entities.md#atlas) and the
-`Atlas` metadata SHOULD be defined.
+and the [`seg` entity](../appendices/entities.md#segmentation) SHOULD be defined.
 
 For example:
 
@@ -310,8 +306,8 @@ A guide for using macros can be found at
     "pipeline": {
         "sub-001": {
             "anat": {
-                "sub-001_space-orig_atlas-Desikan_label-GM_mask.nii.gz": "",
-                "sub-001_space-orig_atlas-Desikan_label-GM_mask.json": "",
+                "sub-001_space-orig_seg-Desikan_label-GM_mask.nii.gz": "",
+                "sub-001_space-orig_seg-Desikan_label-GM_mask.json": "",
                 },
             },
         }
@@ -333,7 +329,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         func|anat|dwi/
-            <source_entities>[_space-<space>][_atlas-<label>][_res-<label>][_den-<label>][_label-<label>]_probseg.nii.gz
+            <source_entities>[_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_label-<label>]_probseg.nii.gz
 ```
 
 Example:
@@ -407,7 +403,7 @@ Template:
 <pipeline_name>/
     sub-<label>/
         anat/
-            <source_entities>[_hemi-{L|R}][_space-<space>][_atlas-<label>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
+            <source_entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
 ```
 
 The [`hemi-<label>`](../appendices/entities.md#hemi) entity is REQUIRED for GIFTI files storing information about

src/schema/objects/entities.yaml

@@ -25,16 +25,6 @@ acquisition:
     remains at the discretion of the researcher.
   type: string
   format: label
-atlas:
-  name: atlas
-  display_name: Atlas
-  description: |
-    The `atlas-<label>` key/value pair corresponds to a custom label the user
-    MAY use to distinguish a different atlas used for similar type of data.
-
-    This entity is only applicable to derivative data.
-  type: string
-  format: label
 ceagent:
   name: ce
   display_name: Contrast Enhancing Agent
@@ -286,6 +276,16 @@ sample:
     The label MUST be unique per subject and is RECOMMENDED to be unique throughout the dataset.
   type: string
   format: label
+segmentation:
+  name: seg
+  display_name: Segmentation
+  description: |
+    The `seg-<label>` key/value pair corresponds to a custom label the user
+    MAY use to distinguish different segmentations.
+
+    This entity is only applicable to derivative data.
+  type: string
+  format: label
 session:
   name: ses
   display_name: Session

src/schema/objects/metadata.yaml

@@ -177,12 +177,6 @@ AssociatedEmptyRoom:
       format: dataset_relative
     - type: string
       format: bids_uri
-Atlas:
-  name: Atlas
-  display_name: Atlas
-  description: |
-    Which atlas (if any) was used to generate the mask.
-  type: string
 AttenuationCorrection:
   name: AttenuationCorrection
   display_name: Attenuation Correction
@@ -3371,9 +3365,10 @@ TermURL:
   name: TermURL
   display_name: TermURL
   description: |
-    URL pointing to a formal definition of this type of data in an ontology
-    available on the web.
+    URL pointing to a formal definition of this type of data in an ontology available on the web.
+    For example: https://www.ncbi.nlm.nih.gov/mesh/68008297 for "male".
   type: string
+  format: uri
 TimeZero:
   name: TimeZero
   display_name: Time Zero

src/schema/rules/checks/events.yaml

@@ -26,4 +26,4 @@ StimulusFileMissing:
     - suffix == "events"
     - columns.stim_file != null
   checks:
-    - exists(columns.stim_file, "stimuli") == length(columns.stim_file)
+    - exists(columns.stim_file, "stimuli") == length(columns.stim_file) - count(columns.stim_file, "n/a")

src/schema/rules/entities.yaml

@@ -25,7 +25,7 @@
 - split
 - recording
 - chunk
-- atlas
+- segmentation
 - resolution
 - density
 - label

src/schema/rules/sidecars/derivatives/common_derivatives.yaml

@@ -38,33 +38,13 @@ MaskDerivatives:
     Sources: recommended
     RawSources: deprecated
 
-MaskDerivativesAtlas:
-  selectors:
-    - dataset.dataset_description.DatasetType == "derivative"
-    - suffix == "mask"
-    - '"label" in entities'
-  fields:
-    Atlas:
-      level: recommended
-      level_addendum: if `label` entity is defined
-
 SegmentationCommon:
   selectors:
     - dataset.dataset_description.DatasetType == "derivative"
     - 'intersects([suffix], ["dseg", "probseg"])'
   fields:
     Manual: optional
 
-SegmentationCommonAtlas:
-  selectors:
-    - dataset.dataset_description.DatasetType == "derivative"
-    - 'intersects([suffix], ["dseg", "probseg"])'
-    - '"atlas" in entities'
-  fields:
-    Atlas:
-      level: recommended
-      level_addendum: if `atlas` is present
-
 # Derivatives -> Imaging data types
 ImageDerivatives:
   selectors: