[FIX] Rescope or downgrade excess RECOMMENDED fields #2116

effigies · 2025-05-15T20:49:17Z

Adopts the recommendations from #2040 (comment).

Closes #2040.
Closes bids-standard/bids-validator#183.

nellh

I did some testing of this with example datasets and everything here looks good to me.

effigies

Some notes for reviewers with links to impacts on the rendered spec.

effigies · 2025-06-03T11:23:39Z

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

 {{ MACROS___make_sidecar_table([
-     "mri.MRIB0FieldIdentifier",
+     "fmap.MRIFieldmapB0FieldIdentifier",
     "mri.MRIEchoPlanarImagingAndB0FieldSource",
   ])
 }}


Before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/magnetic-resonance-imaging-data.html#case-4-multiple-phase-encoded-directions-pepolar

After

https://bids-specification--2116.org.readthedocs.build/en/2116/modality-specific-files/magnetic-resonance-imaging-data.html#case-4-multiple-phase-encoded-directions-pepolar

effigies · 2025-06-03T11:26:46Z

src/schema/rules/sidecars/mri.yaml

-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.
-


Duplicates table in fmap.yaml.

effigies · 2025-06-03T11:28:01Z

src/schema/rules/sidecars/mri.yaml

-MRIB0FieldIdentifier:
-  selectors:
-    - datatype == 'fmap'
-    - match(extension, '\.nii(\.gz)?$')
-  fields:
-    B0FieldIdentifier: recommended
-


Duplicates table in fmap.yaml.

effigies · 2025-06-03T11:29:31Z

src/schema/rules/sidecars/mri.yaml

+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


Conditional promotions of fields from OPTIONAL to RECOMMENDED, based on other sidecar fields.

effigies · 2025-06-03T11:32:51Z

src/schema/rules/sidecars/eeg.yaml

+    EpochLength:
+      level: optional
+      # Implemented in rules.sidecars.electrophys
+      level_addendum: recommended if RecordingType is "epoched"


https://bids-specification--2116.org.readthedocs.build/en/2116/modality-specific-files/electroencephalography.html#sidecar-json-_eegjson

effigies · 2025-06-03T11:40:08Z

src/schema/rules/sidecars/mri.yaml

        (which can be later used for field inhomogeneity correction).
    TotalReadoutTime:
      level: recommended
+      description_addendum: <sup>3</sup>


This was misplaced in the table being removed below and not rendered before. Now:

https://bids-specification--2116.org.readthedocs.build/en/2116/modality-specific-files/magnetic-resonance-imaging-data.html#in-and-out-of-plane-spatial-encoding

effigies · 2025-06-03T11:42:11Z

src/schema/rules/sidecars/mri.yaml

-    InversionTime: recommended
+    InversionTime:
+      level: optional
+      level_addendum: required if `inv` entity is present


https://bids-specification--2116.org.readthedocs.build/en/2116/modality-specific-files/magnetic-resonance-imaging-data.html#timing-parameters

effigies · 2025-06-03T11:42:34Z

src/schema/rules/sidecars/mri.yaml

-    SliceEncodingDirection: recommended
+    SliceEncodingDirection: optional


https://bids-specification--2116.org.readthedocs.build/en/2116/modality-specific-files/magnetic-resonance-imaging-data.html#timing-parameters

effigies · 2025-06-03T11:42:56Z

src/schema/rules/sidecars/mri.yaml

  fields:
-    MultibandAccelerationFactor: recommended
+    MultibandAccelerationFactor: optional


https://bids-specification--2116.org.readthedocs.build/en/2116/modality-specific-files/magnetic-resonance-imaging-data.html#slice-acceleration

effigies · 2025-06-03T13:28:54Z

src/schema/rules/sidecars/mri.yaml

+    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.


Converts generic sidecar warning to a more helpful message that indicates when it can be safely ignored.

markmikkelsen · 2025-06-05T17:29:32Z

This looks good to me.

I know that we had recurring conversations when working on the MRS BEP about which fields should be recommended and which should be optional. I think I've come to the conclusion that: 1) any parameter that's needed to correctly and faithfully process (load, preprocess, quality-control) and analyze (run statistical inferences on) a dataset should be required; 2) any parameter that could influence the interpretation of experimental results should be recommended; and 3) any parameter that otherwise could be useful to know (particularly for expert users) but would not change the interpretation of the data outcomes should be optional. But this is coming from a software tools developer who would want a "maximal" amount of information in the metadata.

effigies force-pushed the fix/reduce-recommendation-levels branch 2 times, most recently from 86a62a7 to 5d0af72 Compare May 16, 2025 01:23

effigies force-pushed the fix/reduce-recommendation-levels branch 2 times, most recently from 9e5dd42 to 572364b Compare May 30, 2025 13:40

effigies added 5 commits May 30, 2025 10:03

FIX: Reduce the requirement levels of some metadata fields

79c51e1

FIX: Replace TotalReadoutTime check to allow alternatives

24082ee

metaschema: Disable implicit level addenda

e1832c0

test: Fix tests to allow any requirement levels

18013e5

Add specific warnings for B0Field*, deduplicate sidecar tables

09d4114

effigies force-pushed the fix/reduce-recommendation-levels branch from 572364b to 09d4114 Compare May 30, 2025 14:05

effigies marked this pull request as ready for review May 30, 2025 14:07

effigies requested a review from erdalkaraca as a code owner May 30, 2025 14:07

effigies mentioned this pull request May 30, 2025

Reduce Cumbersome BIDS Validator Warnings for SIDECAR_KEY_RECOMMENDED Missing Metadata #2040

Closed

effigies added the needs-review label May 30, 2025

effigies added 2 commits May 30, 2025 12:06

feat: Recommend EpochLength only if RecordingType is epoched

a89bb6e

feat: Recommend EpochLength only if RecordingType is epoched

4f2a898

effigies mentioned this pull request May 30, 2025

Warning for EpochLength with continuous recording data (MEG) bids-standard/bids-validator#183

Closed

nellh approved these changes Jun 3, 2025

View reviewed changes

effigies commented Jun 3, 2025

View reviewed changes

effigies added the copenhagen For discussion in Copenhagen label Jun 4, 2025

effigies assigned christinerogers, ericearl, nellh, bendhouseart and julia-pfarr Jun 11, 2025

christinerogers removed their assignment Jun 11, 2025

nellh removed their assignment Jun 12, 2025

shnizzedy approved these changes Jun 17, 2025

View reviewed changes

effigies merged commit df9ea95 into bids-standard:master Jun 17, 2025
24 of 25 checks passed

effigies deleted the fix/reduce-recommendation-levels branch June 17, 2025 20:32

ericearl mentioned this pull request Jun 27, 2025

output maintainers meeting openneuropet/outreach#52

Open

effigies changed the title ~~FIX: Rescope or downgrade excess RECOMMENDED fields~~ [FIX] Rescope or downgrade excess RECOMMENDED fields Aug 26, 2025

		SliceEncodingDirection: recommended
		SliceEncodingDirection: optional

[FIX] Rescope or downgrade excess RECOMMENDED fields #2116

[FIX] Rescope or downgrade excess RECOMMENDED fields #2116

Uh oh!

Conversation

effigies commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nellh left a comment

Choose a reason for hiding this comment

Uh oh!

effigies left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markmikkelsen commented Jun 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

effigies commented May 15, 2025 •

edited

Loading