[SCHEMA] MRS schema updates

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

src/schema/meta/context.yaml

@@ -329,6 +329,10 @@ context:
           name: 'sform code'
           description: 'Use of the affine fields.'
           type: integer
+        mrs:
+          name: 'NIfTI-MRS extension'
+          description: 'NIfTI-MRS JSON fields'
+          type: object
     ome:
       name: 'Open Microscopy Environment fields'
       description: 'Parsed contents of OME-XML header, which may be found in OME-TIFF or OME-ZARR files'

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
@@ -3851,12 +3835,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:

src/schema/rules/checks/mrs.yaml

@@ -0,0 +1,29 @@
+---
+MRSNiftiConsistency:
+  issue:
+    code: MRS_NIFTI_CONSISTENCY
+    message: |
+      ResonantNucleus and/or SpectrometerFrequency fields are inconsistent
+      between the NIfTI-MRS header extension and the BIDS sidecar.
+    level: error
+  selectors:
+    - datatype == "mrs"
+    - type(nifti_header.mrs) != "null"
+  checks:
+    - sidecar.ResonantNucleus == nifti_header.mrs.ResonantNucleus
+    - sidecar.SpectrometerFrequency == nifti_header.mrs.SpectrometerFrequency
+
+MRSMatrixSize:
+  issue:
+    code: MRS_MATRIX_SIZE
+    message: |
+      MatrixSize metadata must match NIfTI header field `dim[1:4]`.
+    level: error
+  selectors:
+    - datatype == "mrs"
+    - type(nifti_header) != "null"
+    - type(sidecar.MatrixSize) != "null"
+  checks:
+    - sidecar.MatrixSize[0] == nifti_header.dim[1]
+    - sidecar.MatrixSize[1] == nifti_header.dim[2]
+    - sidecar.MatrixSize[2] == nifti_header.dim[3]

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:

src/schema/rules/sidecars/mrs.yaml

@@ -30,10 +30,21 @@ MRSSample:
   fields:
     BodyPart:
       level: optional
+      level_addendum: required if `voi` entity is present
       description_addendum: Corresponds to DICOM Tag 0018, 0015 `Body Part Examined`.
-    BodyPartDetails: optional
+    BodyPartDetails:
+      level: optional
+      level_addendum: required if `voi` entity is present
     BodyPartDetailsOntology: optional
 
+MRSSampleVOI:
+  selectors:
+    - modality == "mrs"
+    - '"volume" in entities'
+  fields:
+    BodyPart: required
+    BodyPartDetails: required
+
 MRSSequenceSpecifics:
   selectors:
     - modality == "mrs"
@@ -51,53 +62,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:
+    VolumeTiming:
+      level: recommended
+      level_addendum: mutually exclusive with `RepetitionTime`
+
+MRSConditionalInversionTime:
+  selectors:
+    - modality == "mrs"
+    - entities.inversion
   fields:
-    NumberOfTransients: recommended
+    InversionTime:
+      level: recommended
+      level_addendum: if `inv` entity is present
 
-MRSRecommendedFieldsRefSignal:
+MRSConditionalAnatomicalImage:
   selectors:
     - modality == "mrs"
-    - intersects([suffix], ["mrsref"])
+    - intersects(dataset.datatypes, ["anat"])
   fields:
-    ReferenceSignal:
+    AnatomicalImage:
       level: recommended
-      level_addendum: if MRS reference data are present
+      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 +129,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: