adding pydicom_uuid support and docs

Signed-off-by: vsoch <[email protected]>

Author: vsoch

deid/dicom/actions/__init__.py

@@ -1,5 +1,5 @@
 from .jitter import jitter_timestamp, jitter_timestamp_func
-from .uids import basic_uuid, dicom_uuid, suffix_uuid
+from .uids import basic_uuid, dicom_uuid, suffix_uuid, pydicom_uuid
 
 # Function lookup
 # Functions here must take an item, field, and value
@@ -9,4 +9,5 @@
     "dicom_uuid": dicom_uuid,
     "suffix_uuid": suffix_uuid,
     "basic_uuid": basic_uuid,
+    "pydicom_uuid": pydicom_uuid,
 }

deid/dicom/actions/uids.py

@@ -23,6 +23,8 @@
 """
 
 from deid.utils import parse_keyvalue_pairs
+from pydicom.uid import generate_uid as pydicom_generate_uid
+from deid.logger import bot
 import uuid
 
 
@@ -31,6 +33,33 @@ def basic_uuid(item, value, field, **kwargs):
     return str(uuid.uuid4())
 
 
+def pydicom_uuid(item, value, field, **kwargs):
+    """
+    Use pydicom to generate the UID. Optional kwargs include:
+
+    prefix (str): provide a custom prefix
+    stable_remapping (bool): if true, use the orignal value for entropy.
+    This ensures stability across different runs that use the same UID.
+
+    The prefix must match '^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))*\\.$'
+    """
+    opts = parse_keyvalue_pairs(kwargs.get("extras"))
+
+    # We always provide a prefix so the stable remapping is done
+    prefix = opts.get("prefix", "2.25.")
+    stable_remapping = opts.get("stable_remapping", True)
+    entropy_srcs = []
+
+    # They would need to unset the default prefix
+    if stable_remapping is True and not prefix:
+        bot.warning("A prefix must be provided to use stable remapping.")
+
+    if stable_remapping is True:
+        original = str(field.element.value)
+        entropy_srcs.append(original)
+    return pydicom_generate_uid(prefix=prefix, entropy_srcs=entropy_srcs)
+
+
 def suffix_uuid(item, value, field, **kwargs):
     """Return the same field, with a uuid suffix.
 

deid/tests/common.py

@@ -52,8 +52,20 @@ def get_dicom(dataset):
     return read_file(next(dicom_files))
 
 
+def get_same_file(dataset):
+    """
+    get a consistent dicom file
+    """
+    from deid.dicom import get_files
+
+    dicom_files = list(get_files(dataset))
+    return dicom_files[0]
+
+
 def get_file(dataset):
-    """helper to get a dicom file"""
+    """
+    get a dicom file
+    """
     from deid.dicom import get_files
 
     dicom_files = get_files(dataset)

deid/tests/test_dicom_funcs.py

@@ -33,7 +33,7 @@
 from deid.utils import get_installdir
 from deid.data import get_dataset
 from deid.dicom.parser import DicomParser
-from deid.tests.common import get_file, create_recipe
+from deid.tests.common import get_file, get_same_file, create_recipe
 
 uuid_regex = "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
 
@@ -111,6 +111,75 @@ def test_basic_uuid(self):
         print(parser.dicom["ReferringPhysicianName"].value)
         assert re.search(uuid_regex, str(parser.dicom["ReferringPhysicianName"].value))
 
+    def test_pydicom_uuid(self):
+        """
+        %header
+        REPLACE ReferringPhysicianName deid_func:pydicom_uuid
+        """
+        print("Test deid_func:pydicom_uuid")
+
+        dicom_file = get_file(self.dataset)
+        actions = [
+            {
+                "action": "REPLACE",
+                "field": "ReferringPhysicianName",
+                "value": "deid_func:pydicom_uuid",
+            }
+        ]
+        recipe = create_recipe(actions)
+
+        # Create a parser, define function for it
+        parser = DicomParser(dicom_file, recipe=recipe)
+        parser.parse()
+
+        # Randomness is anything, but should be all numbers
+        print(parser.dicom["ReferringPhysicianName"].value)
+        name = str(parser.dicom["ReferringPhysicianName"].value)
+        assert re.search("([0-9]|.)+", name)
+
+        # This is the pydicom default, and we default to stable remapping
+        assert (
+            name == "2.25.39101090714049289438893821151950032074223798085258118413707"
+        )
+
+        # Add a custom prefix
+        # must match '^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))*\\.$'
+        actions = [
+            {
+                "action": "REPLACE",
+                "field": "ReferringPhysicianName",
+                "value": "deid_func:pydicom_uuid prefix=1.55.",
+            }
+        ]
+        recipe = create_recipe(actions)
+        parser = DicomParser(dicom_file, recipe=recipe)
+        parser.parse()
+
+        # Randomness is anything, but should be all numbers
+        print(parser.dicom["ReferringPhysicianName"].value)
+        name = str(parser.dicom["ReferringPhysicianName"].value)
+        assert name.startswith("1.55.")
+
+        # This should always be consistent if we use the original as entropy
+        dicom_file = get_same_file(self.dataset)
+        actions = [
+            {
+                "action": "REPLACE",
+                "field": "ReferringPhysicianName",
+                "value": "deid_func:pydicom_uuid stable_remapping=false",
+            }
+        ]
+        recipe = create_recipe(actions)
+        parser = DicomParser(dicom_file, recipe=recipe)
+        parser.parse()
+
+        # Randomness is anything, but should be all numbers
+        print(parser.dicom["ReferringPhysicianName"].value)
+        name = str(parser.dicom["ReferringPhysicianName"].value)
+        assert (
+            name != "2.25.39101090714049289438893821151950032074223798085258118413707"
+        )
+
     def test_suffix_uuid(self):
         """
         %header

deid/utils/actions.py

@@ -100,7 +100,16 @@ def parse_keyvalue_pairs(pairs):
         if "=" not in pair:
             continue
         key, value = pair.split("=", 1)
-        values[key.strip()] = value.strip()
+        value = value.strip()
+
+        # Ensure we convert booleans and none/null
+        if value == "true":
+            value = True
+        if value == "false":
+            value = False
+        if value in ["none", "null"]:
+            value = None
+        values[key.strip()] = value
     return values
 
 

docs/_docs/contributing/code.md

@@ -16,7 +16,7 @@ See the repository `CONTRIBUTING.md` for these same details.
 ## Contributing a Custom Function
 
 Deid ships (as of version 0.2.3) with deid-provided functions that can be used in
-header parsing. To contribute a recipe you should do the following:
+header parsing. To contribute a custom function you should do the following:
 
 
 1. Add a function to deid/dicom/actions, ideally in the appropriate file (e.g., uid functions in uuid.py, etc)

docs/_docs/user-docs/recipe-funcs.md

@@ -48,6 +48,33 @@ The only change is that we replaced `func` with `deid_func`. Deid will see this
 is provided in its library, and grab it for use.
 
 
+## A Pydicom UUID
+
+Pydicom provides [a function to generate a UUID](https://pydicom.github.io/pydicom/dev/reference/generated/pydicom.uid.generate_uid.html)
+and for most this is likely a good approach to take. The most basic usage (for one run) is to generate a random valid
+unique identifier:
+
+```
+%header
+
+REPLACE ReferringPhysicianName deid_func:pydicom_uuid
+```
+
+The default uses `stable_remapping=true`, which means we use the original UUID as entropy
+to be able to consistently return the same value between runs. You can disable it, however
+we do not recommended it (but maybe could be appropriate for your use case).
+
+You can also optionally define a custom prefix. Note that it needs to match the 
+regular expression `^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))*\\.$` which (in spoken terms)
+is a number followed by a period, another number, and ending also in a period (e.g, `1.55.`).
+
+
+```
+%header
+
+REPLACE ReferringPhysicianName deid_func:pydicom_uuid prefix=1.55.
+```
+
 ## A Dicom UUID
 
 A more "formal" uuid function was added that requires an organization root. Your