Merge branch 'bids-standard:master' into master

Author: markmikkelsen

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ ci:
 exclude: 'tools/schemacode/src/bidsschematools/tests/data/broken_dataset_description.json'
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer

src/common-principles.md

@@ -545,16 +545,21 @@ and a guide for using macros can be found at
             "RECOMMENDED",
             "The description of the column.",
         ),
+        "Format": "OPTIONAL",
         "Levels": "RECOMMENDED",
         "Units": "RECOMMENDED",
         "Delimiter": "OPTIONAL",
         "TermURL": "RECOMMENDED",
         "HED": "OPTIONAL",
+        "Maximum": "OPTIONAL",
+        "Minimum": "OPTIONAL",
    }
 ) }}
 
 Please note that while both `Units` and `Levels` are RECOMMENDED, typically only one
 of these two fields would be specified for describing a single TSV file column.
+In the absence of `Format`, `Units` implies the column contains numeric values,
+and `Levels` implies the column contains strings.
 
 Example:
 
@@ -563,6 +568,7 @@ Example:
   "test": {
     "LongName": "Education level",
     "Description": "Education level, self-rated by participant",
+    "Format": "integer",
     "Levels": {
       "1": "Finished primary school",
       "2": "Finished secondary school",
@@ -572,7 +578,9 @@ Example:
   },
   "bmi": {
     "LongName": "Body mass index",
+    "Format": "number",
     "Units": "kg/m^2",
+    "Minimum": 0,
     "TermURL": "https://purl.bioontology.org/ontology/SNOMEDCT/60621009"
   }
 }

src/introduction.md

@@ -169,24 +169,28 @@ For example:
 
 #### NIRS
 
--   Luke, R., Oostenveld, R., Cockx, H., Niso, G., Shader, M., Orihuela-Espina, F.,
-    Innes-Brown, H., Tucker, S., Boas, D., Gau, R., Salo, T., Appelhoff, S., Markiewicz, C
-    McAlpine, D., BIDS maintainers, Pollonini, L. (2023).
-    **fNIRS-BIDS, the Brain Imaging Data Structure Extended to Functional Near-Infrared Spectroscopy**.
-    PsyArXiv.
-    [doi:10.31219/osf.io/7nmcp](https://doi.org/10.31219/osf.io/7nmcp)
+-   Luke, R., Oostenveld, R., Cockx, H., Niso, G., Shader, M.J., Orihuela-Espina, F., Innes-Brown, H.,
+    Tucker, S., Boas, D., Yücel, M.A., Gau, R., Salo, T., Appelhoff, S., Markiewicz, C.J., McAlpine, D.,
+    The BIDS Maintainers, Pollonini, L. (2025)
+    **NIRS-BIDS: Brain Imaging Data Structure Extended to Near-Infrared Spectroscopy**.
+    Scientific Data 12, (159).
+    [doi:10.1038/s41597-024-04136-9](https://doi.org/10.1038/s41597-024-04136-9)
 
 #### Motion
 
 -   Jeung, S., Cockx, H., Appelhoff, S., Berg, T., Gramann, K., Grothkopp, S., Warmerdam, E., Hansen, C.,
-    Oostenveld, R., BIDS maintainers, Welzel, J. (2023).
-    **Motion-BIDS: extending the Brain Imaging Data Structure specification to organize motion data for reproducible research**.
-    PsyArXiv.
-    [doi:10.31234/osf.io/w6z79](https://doi.org/10.31234/osf.io/w6z79)
+    Oostenveld, R., BIDS Maintainers, Welzel J. (2024).
+    **Motion-BIDS: an extension to the brain imaging data structure to organize motion data for reproducible research**.
+    Scientific Data 11, (716).
+    [doi:10.1038/s41597-024-03559-8](https://doi.org/10.1038/s41597-024-03559-8)
 
 #### MRS
 
--   (publication forthcoming)
+-   Bouchard, A.E., Wong, D., Bogner, W., Gau, R., Halchenko, Y.O., Lamb, D.G., Markiewicz, C.J., Mullins, P.G.,
+    Niso, G., Oeltzschner, G., BIDS Maintainers, Clarke, W.T., Wilson, M., Mikkelsen, M. (2025).
+    **MRS-BIDS, an extension to the Brain Imaging Data Structure for magnetic resonance spectroscopy**.
+    Scientific Data 12, (13841).
+    [doi:10.1038/s41597-025-05543-2](https://doi.org/10.1038/s41597-025-05543-2)
 
 ### Research Resource Identifier (RRID)
 

src/schema/meta/expression_tests.yaml

@@ -74,6 +74,14 @@
 # General expressions
 - expression: 1 + 2
   result: 3
+- expression: 1 - 2
+  result: -1
+- expression: 3 * 4
+  result: 12
+- expression: 3 / 2
+  result: 1.5
+- expression: 3 % 2
+  result: 1
 - expression: '"cat" + "dog"'
   result: 'catdog'
 - expression: match('string', '.*')

src/schema/objects/columns.yaml

@@ -38,12 +38,14 @@ 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.
+    For privacy purposes, participant ages should be capped at 89.
+    Using "89+" for ages above 88 is DEPRECATED.
   definition: {
     "LongName": "Subject age",
     "Description": "Subject age in postnatal years",
+    "Format": "number",
     "Units": "year",
+    "Maximum": 89,
   }
 cardiac:
   name: cardiac
@@ -52,6 +54,7 @@ cardiac:
     continuous pulse measurement
   definition: {
     "Description": "continuous pulse measurement",
+    "Format": "number",
     "Units": "mV"
   }
 channel:
@@ -101,8 +104,7 @@ detector_type:
   display_name: Detector Type
   description: |
     The type of detector. Only to be used if the field `DetectorType` in `*_nirs.json` is set to `mixed`.
-  anyOf:
-    - type: string
+  type: string
 derived_from:
   name: derived_from
   display_name: Derived from
@@ -176,15 +178,14 @@ group__channel:
     Which group of channels (grid/strip/seeg/depth) this channel belongs to.
     This is relevant because one group has one cable-bundle and noise can be shared.
     This can be a name or number.
-  anyOf:
-    - type: string
-    - type: number
+  type: string
 handedness:
   name: handedness
   display_name: Subject handedness
   definition: {
     "LongName": "Subject handedness",
     "Description": "String value indicating one of \"left\", \"right\", or \"ambidextrous\".",
+    "Format": "string",
     "Levels": {
       "left": "Left-handed",
       "l": "Left-handed",
@@ -362,7 +363,8 @@ pathology:
     The pathology may be specified in either `samples.tsv` or
     `sessions.tsv`, depending on whether the pathology changes over time.
   definition: {
-    "Description": "Description of the pathology of the sample or type of control."
+    "Description": "Description of the pathology of the sample or type of control.",
+    "Format": "string",
   }
 participant_id:
   name: participant_id
@@ -418,6 +420,7 @@ respiratory:
     continuous breathing measurement
   definition: {
     "Description": "continuous measurements by respiration belt",
+    "Format": "number",
     "Units": "mV"
   }
 response_time:
@@ -483,6 +486,7 @@ sex:
   definition: {
     "LongName": "sex",
     "Description": "String value indicating phenotypical sex.",
+    "Format": "string",
     "Levels": {
       "F": "Female",
       "FEMALE": "Female",
@@ -537,8 +541,7 @@ source__optodes:
   display_name: Source type
   description: |
     The type of source. Only to be used if the field `SourceType` in `*_nirs.json` is set to `mixed`.
-  anyOf:
-    - type: string
+  type: string
 species:
   name: species
   display_name: Species
@@ -550,7 +553,8 @@ species:
     `homo sapiens`.
   definition: {
     "Description":
-      "binomial species name from the NCBI Taxonomy (https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi)"
+      "Latin binomial species name from the NCBI Taxonomy (https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi).",
+    "Format": "string",
   }
 status:
   name: status
@@ -592,7 +596,8 @@ strain:
     For species different from `homo sapiens`, string value indicating
     the strain of the species, for example: `C57BL/6J`.
   definition: {
-    "Description": "name of the strain of the species"
+    "Description": "Name of the strain of the species.",
+    "Format": "string",
   }
 strain_rrid:
   name: strain_rrid
@@ -635,6 +640,7 @@ trigger:
     continuous measurement of the scanner trigger signal
   definition: {
     "Description": "continuous measurement of the scanner trigger signal",
+    "Format": "number",
     "Units": "arbitrary"
   }
 # type column in channels.tsv files

src/schema/objects/metadata.yaml

@@ -609,7 +609,7 @@ DeidentificationMethodCodeSequence:
   type: array
   items:
     type: object
-    recommended_fields:
+    recommended:
       - CodeValue
       - CodeMeaning
       - CodingSchemeDesignator
@@ -1000,7 +1000,7 @@ EditPulse:
   type: object
   additionalProperties:
     type: object
-    recommended_fields: [FrequencyOffset, PulseDuration]
+    recommended: [FrequencyOffset, PulseDuration]
     properties:
       FrequencyOffset:
         anyOf:
@@ -1199,6 +1199,39 @@ FlipAngle:
         unit: degree
         exclusiveMinimum: 0
         maximum: 360
+Format:
+  name: Format
+  display_name: Value format
+  description: |
+    Permitted formats for values in the described column.
+  type: string
+  # Keep synced with objects.formats
+  enum:
+    # Type formats
+    - string
+    - number
+    - integer
+    - boolean
+    # Numeric/alphanumeric strings
+    - index
+    - label
+    # Dates/times
+    - date
+    - datetime
+    - time
+    # Units
+    - unit
+    # URIs
+    - uri
+    - rrid
+    - bids_uri
+    # Paths
+    - dataset_relative
+    - file_relative
+    - participant_relative
+    - stimuli_relative
+    # Miscellaneous
+    - hed_version
 FrameAcquisitionDuration:
   name: FrameAcquisitionDuration
   display_name: Frame Acquisition Duration
@@ -2153,6 +2186,12 @@ MaxMovement:
     as measured by the head localization coils (for example, `4.8`).
   type: number
   unit: mm
+Maximum:
+  name: Maximum
+  display_name: Maximum value
+  description: |
+    Maximum value a column entry is permitted to have.
+  type: number
 MeasurementToolMetadata:
   name: MeasurementToolMetadata
   display_name: Measurement Tool Metadata
@@ -2191,6 +2230,12 @@ MetaboliteRecoveryCorrectionApplied:
     If `true`, the `hplc_recovery_fractions` column MUST be present in the
     corresponding `*_blood.tsv` file.
   type: boolean
+Minimum:
+  name: Minimum
+  display_name: Minimum value
+  description: |
+    Minimum value a column entry is permitted to have.
+  type: number
 MiscChannelCount:
   name: MiscChannelCount
   display_name: Misc Channel Count

src/schema/rules/checks/func.yaml

@@ -41,9 +41,17 @@ RepetitionTimeMismatch:
     - type(sidecar.RepetitionTime) != "null"
     - type(nifti_header) != "null"
   checks:
-    # Implement millisecond rounding via AND
-    - sidecar.RepetitionTime - nifti_header.pixdim[4] < 0.001
-    - sidecar.RepetitionTime - nifti_header.pixdim[4] > -0.001
+    # Use index(...) % 3 to treat unknown units like seconds
+    - |
+      nifti_header.pixdim[4]
+        * 10 ** (-3 * (index(["sec", "msec", "usec", "unknown"], nifti_header.xyzt_units.t) % 3))
+      - sidecar.RepetitionTime
+      > -0.001
+    - |
+      nifti_header.pixdim[4]
+        * 10 ** (-3 * (index(["sec", "msec", "usec", "unknown"], nifti_header.xyzt_units.t) % 3))
+      - sidecar.RepetitionTime
+      < 0.001
 
 # 54
 BoldNot4d:

tools/schemacode/src/bidsschematools/expressions.py

@@ -62,7 +62,7 @@ def parse(expression_string: str) -> "ASTNode":
 notOp = Literal("!")
 compOp = one_of(("==", "!=", "<", "<=", ">", ">=", "in"))
 addOp = one_of(("+", "-"))
-mulOp = one_of(("*", "/"))
+mulOp = one_of(("*", "/", "%"))
 expOp = Literal("**")
 
 lpar, rpar = Suppress("("), Suppress(")")

tools/schemacode/src/bidsschematools/tests/test_schema.py

@@ -182,6 +182,11 @@ def test_formats(schema_obj):
             )
 
 
+def test_format_consistency(schema_obj):
+    """Test that the "Format" field is consistent with objects.formats."""
+    assert set(schema_obj.objects.metadata.Format.enum) == schema_obj.objects.formats.keys()
+
+
 def test_dereferencing():
     orig = {
         "ReferencedObject": {