Merge pull request #2116 from effigies/fix/reduce-recommendation-levels

effigies · web-flow · commit df9ea95245fe · 2025-06-17T16:32:27.000-04:00
FIX: Rescope or downgrade excess RECOMMENDED fields
diff --git a/src/metaschema.json b/src/metaschema.json
@@ -595,8 +595,7 @@
             },
             "required": ["level"],
             "additionalProperties": false
-          },
-          { "type": "string", "pattern": "recommended.*" }
+          }
         ]
       },
       "issue": {
diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -161,7 +161,7 @@ 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.MRIB0FieldIdentifier",
+     "fmap.MRIFieldmapB0FieldIdentifier",
      "mri.MRIEchoPlanarImagingAndB0FieldSource",
    ])
 }}
diff --git a/src/schema/rules/checks/fmap.yaml b/src/schema/rules/checks/fmap.yaml
@@ -65,3 +65,19 @@ EPISmallBVals:
     - '"bval" in associations'
   checks:
     - min(associations.bval.values) < 100
+
+TotalReadoutTimeMustDefine:
+  issue:
+    code: TOTAL_READOUT_TIME_MUST_DEFINE
+    message: |
+      You must provide enough metadata to determine the TotalReadoutTime of this file.
+      `TotalReadoutTime` or `EffectiveEchoSpacing` satisfy this criterion.
+    level: error
+  selectors:
+    - datatype == "fmap"
+    - suffix == "epi"
+    - match(extension, "^\.nii(\.gz)?$")
+  checks:
+    - |
+      sidecar.TotalReadoutTime ||
+      sidecar.EffectiveEchoSpacing
diff --git a/src/schema/rules/sidecars/eeg.yaml b/src/schema/rules/sidecars/eeg.yaml
@@ -74,7 +74,10 @@ EEGRecommended:
     TriggerChannelCount: recommended
     RecordingDuration: recommended
     RecordingType: recommended
-    EpochLength: recommended
+    EpochLength:
+      level: optional
+      # Implemented in rules.sidecars.electrophys
+      level_addendum: recommended if RecordingType is "epoched"
     EEGGround: recommended
     HeadCircumference: recommended
     EEGPlacementScheme: recommended
diff --git a/src/schema/rules/sidecars/electrophys.yaml b/src/schema/rules/sidecars/electrophys.yaml
@@ -0,0 +1,8 @@
+# Common rules for electrophysiological types
+---
+EpochedData:
+  selectors:
+    - intersects([datatype], ['eeg', 'meg', 'ieeg'])
+    - sidecar.RecordingType == 'epoched'
+  fields:
+    EpochLength: recommended
diff --git a/src/schema/rules/sidecars/fmap.yaml b/src/schema/rules/sidecars/fmap.yaml
@@ -23,7 +23,16 @@ MRIFieldmapB0FieldIdentifier:
     - match(extension, '\.nii(\.gz)?$')
     - '!("IntendedFor" in sidecar)'
   fields:
-    B0FieldIdentifier: recommended
+    B0FieldIdentifier:
+      level: recommended
+      issue:
+        code: B0_FIELD_IDENTIFIER_RECOMMENDED
+        message: |
+          File is missing B0FieldIdentifier metadata and IntendedFor metadata,
+          so it will not be possible to use to perform susceptibility distortion correction.
+          B0FieldIdentifier metadata permits the flexible selection of images
+          for estimating B0 inhomogeneity fields, and B0FieldSource permits EPI
+          images to indicate the identifier of the estimated field to use.
 
 # Case 1: Phase-difference map and at least one magnitude image
 MRIFieldmapPhaseDifferencePhasediff:
@@ -60,15 +69,27 @@ MRIFieldmapDirectFieldMapping:
         Fieldmaps must be in units of Hertz (`"Hz"`),
         radians per second (`"rad/s"`), or Tesla (`"T"`).
 
-# Case 4: Multiple phase encoded directions ("pepolar")
+# Case 4: Multiple phase-encoded directions ("pepolar")
 MRIFieldmapPepolar:
   selectors:
     - datatype == "fmap"
     - suffix == "epi"
     - match(extension, '\.nii(\.gz)?$')
   fields:
-    PhaseEncodingDirection: required
-    TotalReadoutTime: required
+    PhaseEncodingDirection:
+      level: required
+      issue:
+        code: PHASE_ENCODING_DIRECTION_MUST_DEFINE
+        message: |
+          You have to define 'PhaseEncodingDirection' for this file.
+    TotalReadoutTime:
+      level: optional
+      level_addendum: |
+        required if other methods for calculating readout time are not present
+    EffectiveEchoSpacing:
+      level: optional
+      level_addendum: |
+        required if other methods for calculating readout time are not present
 
 TB1EPI:
   selectors:
diff --git a/src/schema/rules/sidecars/func.yaml b/src/schema/rules/sidecars/func.yaml
@@ -53,16 +53,16 @@ MRIFuncTimingParameters:
     - suffix == "bold"
     - match(extension, "^\.nii(\.gz)?$")
   fields:
-    NumberOfVolumesDiscardedByScanner: recommended
-    NumberOfVolumesDiscardedByUser: recommended
-    DelayTime: recommended
+    NumberOfVolumesDiscardedByScanner: optional
+    NumberOfVolumesDiscardedByUser: optional
+    DelayTime: optional
     AcquisitionDuration:
-      level: recommended
+      level: optional
       level_addendum: |
         required for sequences that are described with the `VolumeTiming`
         field and that do not have the `SliceTiming` field set to allow for
         accurate calculation of "acquisition time"
-    DelayAfterTrigger: recommended
+    DelayAfterTrigger: optional
 
 # fMRI task information
 MRIFuncTaskInformation:
diff --git a/src/schema/rules/sidecars/ieeg.yaml b/src/schema/rules/sidecars/ieeg.yaml
@@ -80,7 +80,10 @@ iEEGRecommended:
     TriggerChannelCount: recommended
     RecordingDuration: recommended
     RecordingType: recommended
-    EpochLength: recommended
+    EpochLength:
+      level: optional
+      # Implemented in rules.sidecars.electrophys
+      level_addendum: recommended if RecordingType is "epoched"
     iEEGGround: recommended
     iEEGPlacementScheme: recommended
     iEEGElectrodeGroups: recommended
diff --git a/src/schema/rules/sidecars/meg.yaml b/src/schema/rules/sidecars/meg.yaml
@@ -102,7 +102,10 @@ MEGRecommended:
     TriggerChannelCount: recommended
     RecordingDuration: recommended
     RecordingType: recommended
-    EpochLength: recommended
+    EpochLength:
+      level: optional
+      # Implemented in rules.sidecars.electrophys
+      level_addendum: recommended if RecordingType is "epoched"
     ContinuousHeadLocalization: recommended
     HeadCoilFrequency: recommended
     MaxMovement: recommended
diff --git a/src/schema/rules/sidecars/mri.yaml b/src/schema/rules/sidecars/mri.yaml
@@ -38,8 +38,8 @@ MRIHardware:
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended
     NumberReceiveCoilActiveElements: optional
-    GradientSetType: recommended
-    MRTransmitCoilSequence: recommended
+    GradientSetType: optional
+    MRTransmitCoilSequence: optional
     MatrixCoilMode: recommended
     CoilCombinationMethod: recommended
     NumberTransmitCoilActiveElements: optional
@@ -96,19 +96,27 @@ MRISequenceSpecifics:
       description_addendum: |
         Corresponds to [DICOM Tag 0018, 0020](https://dicomlookup.com/dicomtags/(0018,0020)) `Scanning Sequence`.
     SequenceVariant: recommended
-    ScanOptions: recommended
+    ScanOptions: optional
     SequenceName: recommended
     PulseSequenceDetails: recommended
-    NonlinearGradientCorrection: |
-      recommended, but required if [PET](./positron-emission-tomography.md) data are present
-    MRAcquisitionType: recommended, but required for Arterial Spin Labeling
-    MTState: recommended
+    NonlinearGradientCorrection:
+      level: recommended
+      level_addendum: required if [PET](./positron-emission-tomography.md) data are present
+    MRAcquisitionType:
+      level: recommended
+      level_addendum: required for Arterial Spin Labeling
+    MTState:
+      level: optional
+      level_addendum: required if the `mt` entity is present
     MTOffsetFrequency: optional
     MTPulseBandwidth: optional
     MTNumberOfPulses: optional
     MTPulseShape: optional
     MTPulseDuration: optional
-    SpoilingState: recommended
+    NumberShots:
+      level: optional
+      level_addendum: required for some qMRI sequences
+    SpoilingState: optional
     SpoilingType: optional
     SpoilingRFPhaseIncrement: optional
     SpoilingGradientMoment: optional
@@ -168,22 +176,54 @@ MRISpatialEncoding:
     - modality == "mri"
     - match(extension, "^\.nii(\.gz)?$")
   fields:
-    NumberShots: recommended
-    ParallelReductionFactorInPlane: recommended
-    ParallelReductionFactorOutOfPlane: recommended
-    ParallelAcquisitionTechnique: recommended
-    PartialFourier: recommended
-    PartialFourierDirection: recommended
+    ParallelReductionFactorInPlane:
+      level: optional
+      level_addendum: recommended if `ParallelAcquisitionTechnique` is defined
+    ParallelReductionFactorOutOfPlane:
+      level: optional
+      level_addendum: recommended if `ParallelAcquisitionTechnique` is defined
+    ParallelAcquisitionTechnique: optional
+    PartialFourier: optional
+    PartialFourierDirection:
+      level: optional
+      level_addendum: recommended if PartialFourier is defined
     EffectiveEchoSpacing:
-      level: recommended
-      level_addendum: required if corresponding fieldmap data present
+      level: optional
+      level_addendum: recommended if corresponding fieldmap data present
       description_addendum: <sup>2</sup>
-    MixingTime: recommended
+    MixingTime:
+      level: optional
+      level_addendum: required for some qMRI sequences
+
+MRIPartialFourier:
+  selectors:
+    - modality == "mri"
+    - match(extension, "^\.nii(\.gz)?$")
+    - type(sidecar.PartialFourier) != "null"
+  fields:
+    PartialFourierDirection: recommended
+
+MRIParallelReductionFactorInPlane:
+  selectors:
+    - modality == "mri"
+    - match(extension, "^\.nii(\.gz)?$")
+    - type(sidecar.ParallelAcquisitionTechnique) == "string"
+  fields:
+    ParallelReductionFactorInPlane: recommended
+
+MRIParallelReductionFactorOutOfPlane:
+  selectors:
+    - modality == "mri"
+    - match(extension, "^\.nii(\.gz)?$")
+    - type(sidecar.ParallelAcquisitionTechnique) == "string"
+    - sidecar.MRAcquisitionType == "3D"
+  fields:
+    ParallelReductionFactorOutOfPlane: recommended
 
 PhaseEncodingDirectionRec:
   selectors:
     - modality == "mri"
-    - suffix != "epi"
+    - intersects(suffix, ["bold", "sbref", "dwi", "asl"])
     - match(extension, "^\.nii(\.gz)?$")
   fields:
     PhaseEncodingDirection:
@@ -194,32 +234,13 @@ PhaseEncodingDirectionRec:
         (which can be later used for field inhomogeneity correction).
     TotalReadoutTime:
       level: recommended
+      description_addendum: <sup>3</sup>
       level_addendum: |
         required if corresponding 'field/distortion' maps
         acquired with opposing phase encoding directions are present
         (see [Case 4: Multiple phase encoded
         directions](#case-4-multiple-phase-encoded-directions-pepolar))
 
-PhaseEncodingDirectionReq:
-  selectors:
-    - datatype == "fmap"
-    - suffix == "epi"
-    - match(extension, "^\.nii(\.gz)?$")
-  fields:
-    PhaseEncodingDirection:
-      level: required
-      issue:
-        code: PHASE_ENCODING_DIRECTION_MUST_DEFINE
-        message: |
-          You have to define 'PhaseEncodingDirection' for this file.
-    TotalReadoutTime:
-      level: required
-      description_addendum: <sup>3</sup>
-      issue:
-        code: TOTAL_READOUT_TIME_MUST_DEFINE
-        message: |
-          You have to define 'TotalReadoutTime' for this file.
-
 MRITimingParameters:
   selectors:
     - modality == "mri"
@@ -237,7 +258,9 @@ MRITimingParameters:
         [ASL](SPEC_ROOT/modality-specific-files/magnetic-resonance-imaging-data.md#\
         arterial-spin-labeling-perfusion-data)
         or variable echo time fMRI sequences.
-    InversionTime: recommended
+    InversionTime:
+      level: optional
+      level_addendum: required if `inv` entity is present
     DwellTime: recommended
 
 EchoTimeRequiredASL:
@@ -259,7 +282,7 @@ SliceTimingMRI:
       level_addendum: |
         required for sparse sequences that do not have the `DelayTime` field set,
         and Arterial Spin Labeling with `MRAcquisitionType` set on `2D`.
-    SliceEncodingDirection: recommended
+    SliceEncodingDirection: optional
 
 SliceTimingASL:
   selectors:
@@ -346,7 +369,7 @@ MRISliceAcceleration:
     - modality == "mri"
     - match(extension, "^\.nii(\.gz)?$")
   fields:
-    MultibandAccelerationFactor: recommended
+    MultibandAccelerationFactor: optional
 
 MRIAnatomicalLandmarks:
   selectors:
@@ -356,20 +379,23 @@ MRIAnatomicalLandmarks:
   fields:
     AnatomicalLandmarkCoordinates__mri: recommended
 
-MRIB0FieldIdentifier:
-  selectors:
-    - datatype == 'fmap'
-    - match(extension, '\.nii(\.gz)?$')
-  fields:
-    B0FieldIdentifier: recommended
-
 MRIEchoPlanarImagingAndB0FieldSource:
   selectors:
     - intersects(datatype, ['dwi', 'func', 'perf'])
     - intersects(dataset.datatypes, ['fmap'])
     - match(extension, "^\.nii(\.gz)?$")
   fields:
-    B0FieldSource: recommended
+    B0FieldSource:
+      level: recommended
+      issue:
+        code: B0_FIELD_SOURCE_RECOMMENDED
+        message: |
+          File is missing B0FieldSource metadata, so it may not be possible to
+          perform susceptibility distortion correction on it.
+          B0FieldIdentifier metadata permits the flexible selection of images
+          for estimating B0 inhomogeneity fields, and B0FieldSource permits EPI
+          images to indicate the identifier of the estimated field to use.
+          If associations are fully specified with `IntendedFor`, there is no need to change this.
 
 MRIInstitutionInformation:
   selectors:
diff --git a/tools/schemacode/src/bidsschematools/render/utils.py b/tools/schemacode/src/bidsschematools/render/utils.py
@@ -2,6 +2,7 @@
 
 import math
 import posixpath
+import re
 
 
 def _link_with_html(string, html_path=None, heading=None, pdf_format=False):
@@ -337,10 +338,12 @@ def normalize_requirements(text):
     -------
     text : str
     """
-    for level in ("optional", "recommended", "required", "deprecated"):
-        # Replace both "optional" and "Optional" with "OPTIONAL"
-        text = text.replace(level.title(), level).replace(level, level.upper())
-    return text
+    return re.sub(
+        r"\b(optional|recommended|required|deprecated)\b",
+        lambda m: m.group(1).upper(),
+        text,
+        flags=re.IGNORECASE,
+    )
 
 
 def normalize_breaks(text):
diff --git a/tools/schemacode/src/bidsschematools/tests/test_render_tables.py b/tools/schemacode/src/bidsschematools/tests/test_render_tables.py
