feat: Add multi-value timestamp support and improve jitter function

- Add support for multi-value DICOM date/time fields (DA, DT) in jitter_timestamp
  - Handle pydicom MultiValue objects from real DICOM files
  - Support list/tuple inputs for programmatic use
  - Return backslash-separated strings per DICOM standard (e.g., "20131220\20131225")

- Add early exit optimization for empty field values
  - Skip jittering in parser when field.element.value is empty (None, "", b"")
  - Return None from jitter_timestamp for empty values
  - Prevents unnecessary processing and warnings for empty fields

- Add comprehensive test coverage
  - Test multi-value date jittering (Case 6)
  - Test unsupported VR types (Case 7 with OB)

This enables proper de-identification of DICOM files that contain multiple acquisition dates/times in a single field.

Author: Simlomb

CHANGELOG.md

@@ -14,6 +14,7 @@ and **Merged pull requests**. Critical items to know are:
 Referenced versions in headers are tagged on Github, in parentheses are for pypi.
 
 ## [vxx](https://github.com/pydicom/deid/tree/master) (master)
+- Add multi-value timestamp support and improve jitter function [#296](https://github.com/pydicom/deid/pull/296) (0.4.11)
 - Optimize KEEP action performance by caching field contenders & fix SyntaxWarning for invalid escape sequences [#293](https://github.com/pydicom/deid/pull/295) (0.4.10)
 - Fix field removal and blanking to clean up child UID references [#293](https://github.com/pydicom/deid/pull/293) (0.4.9)
 - Fix UID lookup for nested sequence fields in DICOM datasets [#292](https://github.com/pydicom/deid/pull/292) (0.4.8)

deid/dicom/actions/jitter.py

@@ -2,6 +2,8 @@
 __copyright__ = "Copyright 2016-2025, Vanessa Sochat"
 __license__ = "MIT"
 
+from pydicom.multival import MultiValue
+
 from deid.logger import bot
 from deid.utils import get_timestamp, parse_keyvalue_pairs
 
@@ -40,44 +42,60 @@ def jitter_timestamp(field, value):
         value = int(value)
 
     original = field.element.value
-    new_value = original
 
-    if original is not None:
+    # Early exit for empty values
+    if not original:
+        return None
+
+    # Normalize to list for uniform processing of multi-value fields
+    is_multi_values = isinstance(original, (list, tuple, MultiValue))
+    values = list(original) if is_multi_values else [original]
+    dcmvr = field.element.VR
+
+    jittered = []
+    for val in values:
         # Create default for new value
-        new_value = None
-        dcmvr = field.element.VR
+        single_value = None
 
         # DICOM Value Representation can be either DA (Date) DT (Timestamp),
         # or something else, which is not supported.
         if dcmvr == "DA":
             # NEMA-compliant format for DICOM date is YYYYMMDD
-            new_value = get_timestamp(original, jitter_days=value, format="%Y%m%d")
+            single_value = get_timestamp(val, jitter_days=value, format="%Y%m%d")
 
         elif dcmvr == "DT":
             # NEMA-compliant format for DICOM timestamp is
             # YYYYMMDDHHMMSS.FFFFFF&ZZXX
             try:
-                new_value = get_timestamp(
-                    original, jitter_days=value, format="%Y%m%d%H%M%S.%f%z"
+                single_value = get_timestamp(
+                    val, jitter_days=value, format="%Y%m%d%H%M%S.%f%z"
                 )
             except Exception:
-                new_value = get_timestamp(
-                    original, jitter_days=value, format="%Y%m%d%H%M%S.%f"
+                single_value = get_timestamp(
+                    val, jitter_days=value, format="%Y%m%d%H%M%S.%f"
                 )
 
         else:
             # If the field type is not supplied, attempt to parse different formats
             for fmtstr in ["%Y%m%d", "%Y%m%d%H%M%S.%f%z", "%Y%m%d%H%M%S.%f"]:
                 try:
-                    new_value = get_timestamp(
-                        original, jitter_days=value, format=fmtstr
-                    )
+                    single_value = get_timestamp(val, jitter_days=value, format=fmtstr)
                     break
                 except Exception:
                     pass
 
             # If nothing works, do nothing and issue a warning.
-            if not new_value:
-                bot.warning("JITTER not supported for %s with VR=%s" % (field, dcmvr))
+            if not single_value:
+                bot.warning(
+                    f"JITTER not supported for tag={field.element.tag}, name={field.name}, VR={dcmvr}"
+                )
+
+        # If jittering failed (single_value is None), keep the original value
+        jittered.append(single_value if single_value else val)
 
-    return new_value
+    # Return in same format as input
+    if is_multi_values:
+        # For multi-value DICOM fields, return as backslash-separated string
+        return "\\".join(str(v) for v in jittered)
+    else:
+        return jittered[0]

deid/dicom/parser.py

@@ -609,6 +609,10 @@ def _run_action(self, field, action, value=None):
 
         # Code the value with something in the response
         elif action == "JITTER":
+            # Skip jittering if field value is empty
+            if not field.element.value:
+                return
+
             value = parse_value(
                 item=self.lookup,
                 dicom=self.dicom,

deid/tests/test_dicom_utils.py

@@ -115,6 +115,26 @@ def test_jitter_timestamp(self):
         expected = None
         self.assertEqual(actual, expected)
 
+        print("Case 6: Testing with multi-value dates")
+        name = "DateOfLastCalibration"
+        tag = get_tag(name)
+        dicom.DateOfLastCalibration = ["20131210", "20131215"]
+        dicom.data_element(name).VR = "DA"
+        field = DicomField(dicom.data_element(name), name, str(tag["tag"]))
+        actual = jitter_timestamp(field, 10)
+        expected = "20131220\\20131225"
+        self.assertEqual(actual, expected)
+
+        print("Case 7: Testing with non supported VR")
+        name = "FrameOriginTimestamp"
+        tag = get_tag(name)
+        dicom.FrameOriginTimestamp = b""
+        dicom.data_element(name).VR = "OB"
+        field = DicomField(dicom.data_element(name), name, str(tag["tag"]))
+        actual = jitter_timestamp(field, 10)
+        expected = None
+        self.assertEqual(actual, expected)
+
 
 if __name__ == "__main__":
     unittest.main()

deid/version.py

@@ -2,7 +2,7 @@
 __copyright__ = "Copyright 2016-2025, Vanessa Sochat"
 __license__ = "MIT"
 
-__version__ = "0.4.10"
+__version__ = "0.4.11"
 AUTHOR = "Vanessa Sochat"
 AUTHOR_EMAIL = "vsoch@users.noreply.github.com"
 NAME = "deid"