Split conditional matrices in schema, combine in doc

This implements the following agreed upon suggestions: * Set InversionTime to recommended if `inv` entity is present. (`entities.inversion`) * Move to RepetitionTime and VolumeTiming, rather than RepetitionTime as an array in the variable-timing case. * ReferenceSignal should be uniformly recommended.
bids-standard · May 29, 2024 · 81a26d7 · 81a26d7
1 parent c3b5390
commit 81a26d7
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 72 deletions.
diff --git a/src/modality-specific-files/magnetic-resonance-spectroscopy.md b/src/modality-specific-files/magnetic-resonance-spectroscopy.md
@@ -179,19 +179,7 @@ A guide for using macros can be found at
 
 ### MRS-relevant fields
 
-Metadata fields that MUST be present:
-
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-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("mrs.MRSRequiredFields") }}
-
-SHOULD be present:
+Metadata fields that MUST, SHOULD or MAY be present:
 
 <!-- This block generates a metadata table.
 These tables are defined in
@@ -202,26 +190,17 @@ 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([
-  "mrs.MRSRecommendedFieldsNumTransients",
-  "mrs.MRSRecommendedFields",
+  "mrs.MRSRelevantFields",
+  "mrs.MRSRepetitionTime",
+  "mrs.MRSVolumeTiming",
+  "mrs.MRSConditionalNumTransients",
   "mrs.MRSIRecommendedFields",
-  "mrs.MRSRecommendedFieldsRefSignal",
-  "mrs.MRSRecommendedFieldsAnatomicalImage"
+  "mrs.MRSConditionalInversionTime",
+  "mrs.MRSConditionalAnatomicalImage",
+  "mrs.MRSOptionalFields",
   ])
 }}
 
-MAY be present:
-
-<!-- This block generates a metadata table.
-These tables are defined in
-  src/schema/rules/sidecars
-The definitions of the fields specified in these tables may be found in
-  src/schema/objects/metadata.yaml
-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("mrs.MRSOptionalFields") }}
-
 ### Example `*_svs.json`
 
 ```JSON

diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
@@ -2865,22 +2865,6 @@ RepetitionTime:
   type: number
   exclusiveMinimum: 0
   unit: s
-RepetitionTime__mrs:
-  name: RepetitionTime
-  display_name: Repetition Time
-  description: |
-    The time between repetitions (TR), specified in seconds.
-    For dynamic acquisitions, such as cardiac-triggered acquisitions where the TR
-    may differ over the scan, an array of numbers can be used.
-  anyOf:
-    - type: number
-      exclusiveMinimum: 0
-      unit: s
-    - type: array
-      items:
-        type: number
-        exclusiveMinimum: 0
-        unit: s
 RepetitionTimeExcitation:
   name: RepetitionTimeExcitation
   display_name: Repetition Time Excitation
@@ -3856,12 +3840,10 @@ VolumeTiming:
   description: |
     The time at which each volume was acquired during the acquisition.
     It is described using a list of times referring to the onset of each volume
-    in the BOLD series.
-    The list must have the same length as the BOLD series,
+    in the series.
+    The list must have the same length as the series,
     and the values must be non-negative and monotonically increasing.
-    This field is mutually exclusive with `"RepetitionTime"` and `"DelayTime"`.
-    If defined, this requires acquisition time (TA) be defined via either
-    `"SliceTiming"` or `"AcquisitionDuration"` be defined.
+    This field is mutually exclusive with `"RepetitionTime"`.
   type: array
   minItems: 1
   items:

diff --git a/src/schema/rules/sidecars/func.yaml b/src/schema/rules/sidecars/func.yaml
@@ -41,6 +41,10 @@ MRIFuncVolumeTiming:
     VolumeTiming:
       level: required
       level_addendum: mutually exclusive with `RepetitionTime`
+      description_addendum: |
+        This field is mutually exclusive with `"DelayTime"`.
+        If defined, this requires acquisition time (TA) be defined via either
+        `"SliceTiming"` or `"AcquisitionDuration"` be defined.
 
 # Timing Parameters
 MRIFuncTimingParameters:

diff --git a/src/schema/rules/sidecars/mrs.yaml b/src/schema/rules/sidecars/mrs.yaml
@@ -51,53 +51,64 @@ MRSSequenceSpecifics:
     B0ShimmingTechnique: optional
     B1ShimmingTechnique: optional
 
-MRSRequiredFields:
+MRSRelevantFields:
   selectors:
     - modality == "mrs"
   fields:
     ResonantNucleus: required
     SpectrometerFrequency: required
     SpectralWidth: required
     EchoTime: required
-
-MRSRecommendedFields:
-  selectors:
-    - modality == "mrs"
-  fields:
     NumberOfSpectralPoints: recommended
-    RepetitionTime__mrs: recommended
     MixingTime: recommended
-    InversionTime: recommended for inversion recovery data
     FlipAngle: recommended
     AcquisitionVoxelSize: recommended
-    MatrixSize: recommended for MRSI
-    VolumeAffineMatrix: recommended for MRSI
-    EncodingTechnique: recommended for MRSI
+    ReferenceSignal: recommended
 
-MRSRecommendedFieldsAnatomicalImage:
+MRSRepetitionTime:
   selectors:
     - modality == "mrs"
-    - intersects(dataset.datatypes, ["anat"])
+    - '!("VolumeTiming" in sidecar)'
   fields:
-    AnatomicalImage:
+    RepetitionTime:
       level: recommended
-      level_addendum: if anatomical MRI data are present
+      level_addendum: mutually exclusive with `VolumeTiming`
 
-MRSRecommendedFieldsNumTransients:
+MRSVolumeTiming:
   selectors:
     - modality == "mrs"
-    - intersects([suffix], ["svs", "unloc"])
+    - '!("RepetitionTime" in sidecar)'
   fields:
-    NumberOfTransients: recommended
+    VolumeTiming:
+      level: recommended
+      level_addendum: mutually exclusive with `RepetitionTime`
 
-MRSRecommendedFieldsRefSignal:
+MRSConditionalInversionTime:
   selectors:
     - modality == "mrs"
-    - intersects([suffix], ["mrsref"])
+    - entities.inversion
   fields:
-    ReferenceSignal:
+    InversionTime:
       level: recommended
-      level_addendum: if MRS reference data are present
+      level_addendum: if `inv` entity is present
+
+MRSConditionalAnatomicalImage:
+  selectors:
+    - modality == "mrs"
+    - intersects(dataset.datatypes, ["anat"])
+  fields:
+    AnatomicalImage:
+      level: recommended
+      level_addendum: if anatomical MRI data are present
+
+MRSConditionalNumTransients:
+  selectors:
+    - modality == "mrs"
+    - intersects([suffix], ["svs", "unloc"])
+  fields:
+    NumberOfTransients:
+      level: recommended
+      level_addendum: for SVS and unlocalized acquisitions
 
 MRSIRecommendedFields:
   selectors:
@@ -107,6 +118,15 @@ MRSIRecommendedFields:
     MRAcquisitionType:
       level: recommended
       level_addendum: for MRSI
+    MatrixSize:
+      level: recommended
+      level_addendum: for MRSI
+    VolumeAffineMatrix:
+      level: recommended
+      level_addendum: for MRSI
+    EncodingTechnique:
+      level: recommended
+      level_addendum: for MRSI
 
 MRSOptionalFields:
   selectors: