Merge pull request #1974 from effigies/fix/acquisitionduration

[ENH] Update AcquisitionDuration definition to match DICOM, define FrameAcquisitionDuration for sparse sequences

Author: effigies

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

@@ -600,13 +600,13 @@ to be populated for functional sequences. Note that all these options can be
 used for non sparse sequences but that only options B, D and E are valid for
 sparse sequences.
 
-|          | **`RepetitionTime`** | **`SliceTiming`** | **`AcquisitionDuration`** | **`DelayTime`** | **`VolumeTiming`** |
-| -------- | -------------------- | ----------------- | ------------------------- | --------------- | ------------------ |
-| option A | \[ X ]               |                   | \[ ]                      |                 | \[ ]               |
-| option B | \[ ]                 | \[ X ]            |                           | \[ ]            | \[ X ]             |
-| option C | \[ ]                 |                   | \[ X ]                    | \[ ]            | \[ X ]             |
-| option D | \[ X ]               | \[ X ]            | \[ ]                      |                 | \[ ]               |
-| option E | \[ X ]               |                   | \[ ]                      | \[ X ]          | \[ ]               |
+|          | **`RepetitionTime`** | **`SliceTiming`** | **`FrameAcquisitionDuration`** | **`DelayTime`** | **`VolumeTiming`** |
+| -------- | -------------------- | ----------------- | ------------------------------ | --------------- | ------------------ |
+| option A | \[ X ]               |                   | \[ ]                           |                 | \[ ]               |
+| option B | \[ ]                 | \[ X ]            |                                | \[ ]            | \[ X ]             |
+| option C | \[ ]                 |                   | \[ X ]                         | \[ ]            | \[ X ]             |
+| option D | \[ X ]               | \[ X ]            | \[ ]                           |                 | \[ ]               |
+| option E | \[ X ]               |                   | \[ ]                           | \[ X ]          | \[ ]               |
 
 **Legend**
 

src/schema/objects/metadata.yaml

@@ -20,9 +20,8 @@ AcquisitionDuration:
   name: AcquisitionDuration
   display_name: Acquisition Duration
   description: |
-    Duration (in seconds) of volume acquisition.
+    Duration (in seconds) of scan acquisition, including all volumes for multi-volume scans.
     Corresponds to [DICOM Tag 0018, 9073](https://dicomlookup.com/dicomtags/(0018,9073)) `Acquisition Duration`.
-    This field is mutually exclusive with `"RepetitionTime"`.
   type: number
   exclusiveMinimum: 0
   unit: s
@@ -1200,6 +1199,15 @@ FlipAngle:
         unit: degree
         exclusiveMinimum: 0
         maximum: 360
+FrameAcquisitionDuration:
+  name: FrameAcquisitionDuration
+  display_name: Frame Acquisition Duration
+  description: |
+    Duration (in seconds) of volume acquisition.
+    Corresponds to DICOM Tag 0018, 9220 `Frame Acquisition Duration`.
+  type: number
+  exclusiveMinimum: 0
+  unit: s
 FrameDuration:
   name: FrameDuration
   display_name: Frame Duration

src/schema/rules/checks/func.yaml

@@ -12,6 +12,7 @@ PhaseSuffixDeprecated:
     level: warning
   selectors:
     - datatype == "func"
+    - match(extension, "^\.nii(\.gz)?$")
   checks:
     - suffix != "phase"
 
@@ -67,6 +68,7 @@ SliceTimingGreaterThanRepetitionTime:
     level: error
   selectors:
     - suffix == "bold"
+    - match(extension, "^\.nii(\.gz)?$")
     - type(sidecar.SliceTiming) != "null"
     - type(sidecar.RepetitionTime) != "null"
   checks:
@@ -88,24 +90,24 @@ VolumeTimingRepetitionTimeMutex:
       or 'VolumeTiming' when variable times are used.
     level: error
   selectors:
-    - type(nifti_header) != "null"
     - intersects([suffix], ["asl", "bold"])
+    - match(extension, "^\.nii(\.gz)?$")
     - type(sidecar.VolumeTiming) != "null"
   checks:
     - type(sidecar.RepetitionTime) == "null"
 
-RepetitionTimeAcquisitionDurationMutex:
+RepetitionTimeFrameAcquisitionDurationMutex:
   issue:
     code: REPETITION_TIME_AND_ACQUISITION_DURATION_MUTUALLY_EXCLUSIVE
     message: |
-      The fields 'RepetitionTime' and 'AcquisitionDuration' for this file are mutually exclusive.
+      The fields 'RepetitionTime' and 'FrameAcquisitionDuration' for this file are mutually exclusive.
       To specify acquisition duration, use 'SliceTiming' or 'DelayTime'
-      (RepetitionTime - AcquisitionDuration).
+      (RepetitionTime - FrameAcquisitionDuration).
     level: error
   selectors:
-    - type(nifti_header) != "null"
     - intersects([suffix], ["asl", "bold"])
-    - type(sidecar.AcquisitionDuration) != "null"
+    - match(extension, "^\.nii(\.gz)?$")
+    - type(sidecar.FrameAcquisitionDuration) != "null"
   checks:
     - type(sidecar.RepetitionTime) == "null"
 
@@ -114,24 +116,44 @@ VolumeTimingDelayTimeMutex:
     code: VOLUME_TIMING_AND_DELAY_TIME_MUTUALLY_EXCLUSIVE
     message: |
       The fields 'VolumeTiming' and 'DelayTime' for this file are mutually exclusive.
-      To specify acquisition duration, use 'AcquisitionDuration' or 'SliceTiming'.
+      To specify acquisition duration, use 'FrameAcquisitionDuration' or 'SliceTiming'.
     level: error
   selectors:
-    - type(nifti_header) != "null"
     - intersects([suffix], ["asl", "bold"])
+    - match(extension, "^\.nii(\.gz)?$")
     - type(sidecar.VolumeTiming) != "null"
+    - type(sidecar.RepetitionTime) == "null"
   checks:
     - type(sidecar.DelayTime) == "null"
 
-VolumeTimingMissingAcquisitionDuration:
+VolumeTimingMissingFrameAcquisitionDuration:
   issue:
     code: VOLUME_TIMING_MISSING_ACQUISITION_DURATION
     message: |
-      The field 'VolumeTiming' requires 'AcquisitionDuration' or 'SliceTiming' to be defined.
+      The field 'VolumeTiming' requires 'FrameAcquisitionDuration' or 'SliceTiming' to be defined.
     level: error
   selectors:
-    - type(nifti_header) != "null"
     - intersects([suffix], ["asl", "bold"])
+    - match(extension, "^\.nii(\.gz)?$")
+    - type(sidecar.VolumeTiming) != "null"
+    - type(sidecar.RepetitionTime) == "null"
+  checks:
+    - |
+      "SliceTiming" in sidecar ||
+      "FrameAcquisitionDuration" in sidecar ||
+      "AcquisitionDuration" in sidecar
+
+DeprecatedAcquisitionDuration:
+  issue:
+    code: DEPRECATED_ACQUISITION_DURATION
+    message: |
+      The 'AcquisitionDuration' field has been replaced with 'FrameAcquisitionDuration'
+      to indicate the duration of volume acquisition in sparse acquisition sequences.
+    level: warning
+  selectors:
+    - intersects([suffix], ["asl", "bold"])
+    - match(extension, "^\.nii(\.gz)?$")
     - type(sidecar.VolumeTiming) != "null"
+    - type(sidecar.FrameAcquisitionDuration) == "null"
   checks:
-    - '"SliceTiming" in sidecar || "AcquisitionDuration" in sidecar'
+    - '!("AcquisitionDuration" in sidecar)'

src/schema/rules/sidecars/func.yaml

@@ -44,7 +44,7 @@ MRIFuncVolumeTiming:
       description_addendum: |
         This field is mutually exclusive with `"DelayTime"`.
         If defined, this requires acquisition time (TA) be defined via either
-        `"SliceTiming"` or `"AcquisitionDuration"`.
+        `"SliceTiming"` or `"FrameAcquisitionDuration"`.
 
 # Timing Parameters
 MRIFuncTimingParameters:
@@ -56,13 +56,18 @@ MRIFuncTimingParameters:
     NumberOfVolumesDiscardedByScanner: optional
     NumberOfVolumesDiscardedByUser: optional
     DelayTime: optional
-    AcquisitionDuration:
+    FrameAcquisitionDuration:
       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: optional
+    AcquisitionDuration:
+      level: deprecated
+      description_addendum: |
+        This field was previously used to indicate volume acquisition duration
+        for BOLD data. The `FrameAcquisitionDuration` field should be used instead.
 
 # fMRI task information
 MRIFuncTaskInformation:

src/schema/rules/sidecars/mri.yaml

@@ -262,6 +262,7 @@ MRITimingParameters:
       level: optional
       level_addendum: required if `inv` entity is present
     DwellTime: recommended
+    AcquisitionDuration: optional
 
 EchoTimeRequiredASL:
   selectors: