[SCHEMA] Correlating existing validator issues to schema entries

src/schema/rules/sidecars/asl.yaml

@@ -31,7 +31,23 @@ MRIASLTextOnlySliceTiming:
     - suffix == "asl"
     - sidecar.MRAcquisitionType == "2D"
     fields:
-        SliceTiming: REQUIRED
+        SliceTiming:
+            level: REQUIRED
+            code:
+                SLICE_TIMING_NOT_DEFINED_2D_ASL: |
+                    "You should define SliceTiming', in case 'SequenceType' is set to a
+                    2D sequence. 'SliceTiming' is the time at which each slice was
+                    acquired within each volume (frame) of the acquisition. Slice timing
+                    is not slice order -- rather, it is a list of times containing the
+                    time (in seconds) of each slice acquisition in relation to the beginning
+                    of volume acquisition. The list goes through the slices along the slice
+                    axis in the slice encoding dimension (see below). Note that to ensure the
+                    proper interpretation of the `SliceTiming` field, it is important to check
+                    if the OPTIONAL `SliceEncodingDirection` exists. In particular, if
+                    `SliceEncodingDirection` is negative, the entries in `SliceTiming` are
+                    defined in reverse order with respect to the slice axis, such that the
+                    final entry in the `SliceTiming` list is the time of acquisition of slice 0.
+                    Without this parameter slice time correction will not be possible."
 
 MRIASLTextOnlyFlipAngle:
     selectors:
@@ -40,7 +56,21 @@ MRIASLTextOnlyFlipAngle:
     - suffix == "asl"
     - sidecar.LookLocker == true
     fields:
-        FlipAngle: REQUIRED
+        FlipAngle:
+            level: REQUIRED
+            code:
+                LOOK_LOCKER_FLIP_ANGLE_MISSING: |
+                    "You should define 'FlipAngle' for this file, in case of a
+                    LookLocker acquisition. 'FlipAngle' is the flip angle (FA)
+                    for the acquisition, specified in degrees. Corresponds to
+                    DICOM Tag 0018, 1314 `Flip Angle`. The data type number may
+                    apply to files from any MRI modality concerned with a single
+                    value for this field, or to the files in a file collection
+                    where the value of this field is iterated using the flip entity.
+                    The data type array provides a value for each volume in a 4D
+                    dataset and should only be used when the volume timing is critical
+                    for interpretation of the data, such as in ASL or variable flip
+                    angle fMRI sequences."
 
 # Common metadata fields applicable to both (P)CASL and PASL
 MRIASLCommonMetadataFields:
@@ -81,7 +111,13 @@ MRIASLCommonMetadataFieldsM0Type:
     - suffix == "asl"
     - sidecar.M0Type == "Estimate"
     fields:
-        M0Estimate: REQUIRED
+        M0Estimate:
+            level: REQUIRED
+            code:
+                M0ESTIMATE_NOT_DEFINED: |
+                    You must define 'M0Estimate' for this file, in case 'M0Type' is defined as 'Estimate'.
+                    'M0Estimate' is a single numerical whole-brain M0 value (referring to the M0 of blood),
+                    only if obtained externally (for example retrieved from CSF in a separate measurement).
 
 MRIASLCommonMetadataFieldsBackgroundSuppression:
     selectors:
@@ -160,8 +196,27 @@ MRIASLPASLSpecificBolusCutOffFlag:
     - sidecar.ArterialSpinLabelingType == "PASL"
     - sidecar.BolusCutOffFlag == true
     fields:
-        BolusCutOffDelayTime: REQUIRED
-        BolusCutOffTechnique: REQUIRED
+        BolusCutOffDelayTime:
+            level: REQUIRED
+            code:
+                PASL_BOLUS_CUT_OFF_DELAY_TIME: |
+                    It is required to define 'BolusCutOffDelayTime' for this file,
+                    when 'BolusCutOffFlag' is set to true. 'BolusCutOffDelayTime' is
+                    the duration between the end of the labeling and the start of the
+                    bolus cut-off saturation pulse(s), in seconds. This can be a number
+                    or array of numbers, of which the values must be non-negative and
+                    monotonically increasing, depending on the number of bolus cut-off
+                    saturation pulses. For Q2TIPS, only the values for the first and last
+                    bolus cut-off saturation pulses are provided. Based on DICOM Tag
+                    0018,925F ASL Bolus Cut-off Delay Time.
+        BolusCutOffTechnique:
+            level: REQUIRED
+            code:
+                PASL_BOLUS_CUT_OFF_TECHINIQUE: |
+                    It is required to define 'BolusCutOffTechnique' for this file,
+                    when 'BolusCutOffFlag' is set to true. 'BolusCutOffTechnique',
+                    is the name of the technique used (e.g. Q2TIPS, QUIPSS, QUIPSSII).
+                    Corresponds to DICOM Tag 0018,925E ASL Bolus Cut-off Technique.
 
 # m0scan metadata fields
 MRIASLM0ScanTextOnly:
@@ -183,7 +238,19 @@ MRIASLM0ScanTextOnlyFlipAngle:
     - suffix == "m0scan"
     - sidecar.LookLocker == true
     fields:
-        FlipAngle: REQUIRED
+        FlipAngle:
+            level: REQUIRED
+            code:
+                LOOK_LOCKER_FLIP_ANGLE_MISSING: |
+                    You should define 'FlipAngle' for this file, in case of a LookLocker
+                    acquisition. 'FlipAngle' is the flip angle (FA) for the acquisition,
+                    specified in degrees. Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`.
+                    The data type number may apply to files from any MRI modality concerned
+                    with a single value for this field, or to the files in a file collection
+                    where the value of this field is iterated using the flip entity. The
+                    data type array provides a value for each volume in a 4D dataset and
+                    should only be used when the volume timing is critical for interpretation
+                    of the data, such as in ASL or variable flip angle fMRI sequences.
 
 MRIASLM0Scan:
     selectors:

src/schema/rules/sidecars/eeg.yaml

@@ -15,7 +15,7 @@ EEGGeneric:
     fields:
         TaskName:
             level: REQUIRED
-            addendum: |
+            level_addendum: |
                 A RECOMMENDED convention is to name resting state task using labels
                 beginning with `rest`.
 
@@ -34,7 +34,7 @@ EEGRecommended:
         TaskDescription: RECOMMENDED
         Instructions:
             level: RECOMMENDED
-            addendum: |
+            level_addendum: |
                 This is especially important in context of resting state recordings and
                 distinguishing between eyes open and eyes closed paradigms.
         CogAtlasID: RECOMMENDED
@@ -50,11 +50,11 @@ EEGRequired:
         EEGReference: REQUIRED
         SamplingFrequency:
             level: REQUIRED
-            addendum: |
+            level_addendum: |
                 The sampling frequency of data channels that deviate from the main sampling
                 frequency SHOULD be specified in the `channels.tsv` file.
         PowerLineFrequency: REQUIRED
-        SoftwareFilters": REQUIRED
+        SoftwareFilters: REQUIRED
 
 EEGMoreRecommended:
     selectors:
@@ -88,7 +88,7 @@ EEGCoordsystemGeneral:
     fields:
         IntendedFor:
             level: OPTIONAL
-            addendum: |
+            level_addendum: |
                 This identifies the MRI or CT scan associated with the electrodes,
                 landmarks, and fiducials.
 

src/schema/rules/sidecars/fmap.yaml

@@ -21,7 +21,7 @@ MRIFieldmapIntendedFor:
     fields:
         IntendedFor:
             level: OPTIONAL
-            addendum: |
+            level_addendum: |
                 This field is OPTIONAL, and in case the fieldmaps do not correspond
                 to any particular scans, it does not have to be filled.
 
@@ -72,7 +72,7 @@ MRIFieldmapDirectFieldMapping:
     fields:
         Units:
             level: REQUIRED
-            addendum: |
+            level_addendum: |
                 Fieldmaps must be in units of Hertz (`"Hz"`),
                 radians per second (`"rad/s"`), or Tesla (`"T"`).
 

src/schema/rules/sidecars/func.yaml

@@ -18,7 +18,7 @@ MRIFuncRequired:
         VolumeTiming: REQUIRED
         TaskName:
             level: REQUIRED
-            addendum: |
+            level_addendum: |
                 A RECOMMENDED convention is to name resting state task using labels
                 beginning with `rest`.
 
@@ -37,6 +37,9 @@ MRIFuncTimingParameters:
                 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"
+            code:
+                VOLUME_TIMING_MISSING_ACQUISITION_DURATION: |
+                    The field 'VolumeTiming' requires 'AcquisitionDuration' or 'SliceTiming' to be defined.
         DelayAfterTrigger: RECOMMENDED
 
 # The mutual exclusion table, spread across 5 definitions

src/schema/rules/sidecars/mri.yaml

@@ -119,18 +119,28 @@ MRISpatialEncoding:
                 This parameter is REQUIRED if corresponding fieldmap data is present
                 or when using multiple runs with different phase encoding directions
                 (which can be later used for field inhomogeneity correction).
+            code:
+                PHASE_ENCODING_DIRECTION_MUST_DEFINE: |
+                    You have to define 'PhaseEncodingDirection' for this file.
         EffectiveEchoSpacing:
             level: RECOMMENDED
             level_addendum: |
                 <sup>2</sup> This parameter is REQUIRED if corresponding fieldmap data
                 is present.
+            code:
+                EFFECTIVE_ECHO_SPACING_NOT_DEFINED: |
+                    You should define 'EffectiveEchoSpacing' for this file. If you don't
+                    provide this information field map correction will not be possible.
         TotalReadoutTime:
             level: RECOMMENDED
             level_addendum: |
                 <sup>3</sup> This parameter is 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)).
+            code:
+                TOTAL_READOUT_TIME_MUST_DEFINE: |
+                    You have to define 'TotalReadoutTime' for this file.
         MixingTime: RECOMMENDED
 
 MRITimingParameters:
@@ -142,6 +152,17 @@ MRITimingParameters:
             level_addendum: |
                 REQUIRED if corresponding fieldmap data is present,
                 or the data comes from a multi-echo sequence or Arterial Spin Labeling.
+            code:
+                ECHO_TIME_NOT_DEFINED: |
+                    You must define 'EchoTime' for this file. 'EchoTime' is the echo time (TE)
+                    for the acquisition, specified in seconds. Corresponds to DICOM Tag
+                    0018, 0081 Echo Time (please note that the DICOM term is in milliseconds
+                    not seconds). The data type number may apply to files from any MRI modality
+                    concerned with a single value for this field, or to the files in a file
+                    collection where the value of this field is iterated using the echo entity.
+                    The data type array provides a value for each volume in a 4D dataset and
+                    should only be used when the volume timing is critical for interpretation
+                    of the data, such as in ASL or variable echo time fMRI sequences.
         InversionTime: RECOMMENDED
         SliceTiming:
             level: RECOMMENDED
@@ -175,6 +196,19 @@ MRIRFandContrast:
         FlipAngle:
             level: RECOMMENDED
             level_addendum: REQUIRED if LookLocker is set to `true`.
+            code:
+                LOOK_LOCKER_FLIP_ANGLE_MISSING: |
+                    You should define 'FlipAngle' for this file, in
+                    case of a LookLocker acquisition. 'FlipAngle' is the
+                    flip angle (FA) for the acquisition, specified in degrees.
+                    Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`. The data
+                    type number may apply to files from any MRI modality concerned
+                    with a single value for this field, or to the files in a file
+                    collection where the value of this field is iterated using the
+                    flip entity. The data type array provides a value for each volume
+                    in a 4D dataset and should only be used when the volume timing is
+                    critical for interpretation of the data, such as in ASL or
+                    variable flip angle fMRI sequences.
         NegativeContrast: OPTIONAL
 
 MRIFlipAngleLookLocker: