Merge branch 'master' into jv/add_chunk_entity_to_MRI_datatype

bids-standard · Sep 25, 2023 · 6dc1e30 · 6dc1e30
2 parents f6282cc + 466e212
commit 6dc1e30
Show file tree

Hide file tree

Showing 48 changed files with 291 additions and 291 deletions.
diff --git a/.github/workflows/schemacode_ci.yml b/.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

diff --git a/.github/workflows/validation.yml b/.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

diff --git a/.pre-commit-config.yaml b/.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)
@@ -38,7 +38,7 @@ repos:
       - id: flake8
         args: [--config=tools/schemacode/setup.cfg]
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.1
+    rev: v3.0.3
     hooks:
       - id: prettier
         files: src/schema/.*/.*\.yaml
@@ -48,7 +48,7 @@ repos:
       - id: codespell
         args: ["--config=.codespellrc", "--dictionary=-", "--dictionary=.codespell_dict"]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.4.1
+    rev: v1.5.1
     hooks:
       - id: mypy
         # Sync with project.optional-dependencies.typing

diff --git a/README.md b/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)
 

diff --git a/src/CHANGES.md b/src/CHANGES.md
@@ -2,7 +2,19 @@
 
 ## [Unreleased](https://github.com/bids-standard/bids-specification/tree/HEAD)
 
+-   FIX: Do not require notch frequencies to be parsed as numbers, accommodating multiples [#1605](https://github.com/bids-standard/bids-specification/pull/1605) ([effigies](https://github.com/effigies))
+-   \[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))

diff --git a/src/common-principles.md b/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

diff --git a/src/derivatives/imaging.md b/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

diff --git a/src/longitudinal-and-multi-site-studies.md b/src/longitudinal-and-multi-site-studies.md
@@ -53,7 +53,8 @@ A guide for using macros can be found at
                 "sub-control01_ses-postdrug_phasediff.json": "",
                 "sub-control01_ses-postdrug_magnitude1.nii.gz": "",
                 }
-            }
+            },
+        "sub-control01_sessions.tsv": "",
         },
     "participants.tsv": "",
     "dataset_description.json": "",
@@ -62,6 +63,19 @@ A guide for using macros can be found at
     }
 ) }}
 
+`sub-control01_sessions.tsv` content:
+
+```Text
+session_id	acq_time	systolic_blood_pressure
+ses-predrug	2009-06-15T13:45:30	120
+ses-postdrug	2009-06-16T13:45:30	100
+```
+
+See this [example dataset](https://github.com/bids-standard/bids-examples/tree/master/7t_trt)
+that has been formatted
+using this specification and can be used
+for practical guidance when curating a new longitudinal dataset.
+
 ## Multi-site or multi-center studies
 
 This version of the BIDS specification does not explicitly cover studies with

diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -98,7 +98,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("mri.MRITimingParameters") }}
+{{ MACROS___make_sidecar_table(["mri.MRITimingParameters", "mri.SliceTimingMRI"]) }}
 
 ### RF & Contrast
 

diff --git a/src/modality-specific-files/magnetoencephalography.md b/src/modality-specific-files/magnetoencephalography.md
@@ -89,17 +89,20 @@ which some installations impose to be run on raw data prior to analysis.
 Such processing steps are needed for example because of active shielding software corrections
 that have to be performed to before the MEG data can actually be exploited.
 
-### Recording EEG simultaneously with MEG
+### Recording (i)EEG simultaneously with MEG
 
-Note that if EEG is recorded with a separate amplifier,
+Note that if (i)EEG is recorded with a separate amplifier,
 it SHOULD be stored separately under a new `/eeg` data type
-(see [the EEG specification](electroencephalography.md)).
+(see the [EEG](electroencephalography.md) and
+[iEEG](intracranial-electroencephalography.md) specifications).
 
-If however EEG is recorded simultaneously **with the same MEG system**,
+If however (i)EEG is recorded simultaneously **with the same MEG system**,
 it MAY be stored under the `/meg` data type.
 In that case, it SHOULD have the same sampling frequency as MEG (see `SamplingFrequency` field below).
-Furthermore, the EEG sensor coordinates SHOULD be specified using MEG-specific coordinate
-systems (see [coordinates section](#coordinate-system-json-_coordsystemjson) below and
+Furthermore, (i)EEG sensor coordinates MAY be recorded in an
+[`electrodes.tsv`](electroencephalography.md#electrodes-description-_electrodestsv)
+file using MEG-specific coordinate systems
+(see [Coordinate System JSON](#coordinate-system-json-_coordsystemjson) below and
 the [Coordinate Systems Appendix](../appendices/coordinate-systems.md)).
 
 ### Sidecar JSON (`*_meg.json`)

diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md
@@ -272,7 +272,9 @@ in the accompanying JSON sidecar as follows (based on the example of the previou
         "ScreenDistance": 1.8,
         "ScreenRefreshRate": 60,
         "ScreenResolution": [1920, 1200],
-        "ScreenSize": [0.472, 0.295]
-    }
+        "ScreenSize": [0.472, 0.295],
+        "HeadStabilization": "none"
+    },
+    "VisionCorrection": "lenses"
 }
 ```
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
@@ -37,6 +37,9 @@ age:
   display_name: Subject age
   description: |
     Numeric value in years (float or integer value).
+
+    It is recommended to tag participant ages that are 89 or higher as 89+,
+    for privacy purposes.
   type: number
   unit: year
 cardiac:
@@ -299,13 +302,11 @@ notch:
   display_name: Notch frequencies
   description: |
     Frequencies used for the notch filter applied to the channel, in Hz.
-    If no notch filter applied, use `n/a`.
-  anyOf:
-    - type: number
-      unit: Hz
-    - type: string
-      enum:
-        - n/a
+    If notch filters are applied at multiple frequencies,
+    these frequencies MAY be specified as a list,
+    for example, `[60, 120, 180]`.
+    If no notch filter was applied, use `n/a`.
+  type: string
 onset:
   name: onset
   display_name: Event onset