midom 0.1.0__py3-none-any.whl

midom/components.py

@@ -0,0 +1,168 @@
+"""Python definition of the parts"""
+from typing import Dict, List
+
+from dicomcriterion import Criterion
+from dicomcriterion.exceptions import CriterionError
+from pydantic import BaseModel, ConfigDict, field_validator
+from pydantic.functional_serializers import field_serializer
+
+from midom.constants import ActionCode, ActionCodes
+from midom.identifiers import (
+    PrivateBlockTagIdentifier,
+    TagIdentifier,
+    tag_identifier_from_string,
+)
+
+
+class PixelArea(BaseModel):
+    area: tuple[int, int, int, int]
+
+
+class TagAction(BaseModel):
+    """Describes the action to take for a single identifier (tag or tag group) and the
+    reason for this action.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True
+    )  # for TagIdentifier
+
+    identifier: TagIdentifier
+    action: ActionCode
+    justification: str
+
+    @field_serializer("identifier")
+    def serialize_identifier(self, value, _info):
+        return value.key()
+
+    @field_validator("identifier", mode="before")
+    @classmethod
+    def deserialize_identifier(cls, value):
+        if isinstance(value, TagIdentifier):
+            return value
+        elif isinstance(value, str):
+            return tag_identifier_from_string(value)
+        else:
+            raise ValueError(
+                f'Invalid input data for TagAction.identifier: "{value}"'
+            )
+
+    @field_serializer("action")
+    def serialize_action(self, value, _info):
+        return value.key
+
+    @field_validator("action", mode="before")
+    @classmethod
+    def deserialize_action(cls, value):
+        if isinstance(value, ActionCode):
+            return value
+        elif isinstance(value, str):
+            return ActionCodes.from_string(value)
+        else:
+            raise ValueError(
+                f'Invalid input data for TagAction.identifier: "{value}"'
+            )
+
+
+class CriterionString(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    content: Criterion
+
+    @field_serializer("content")
+    def serialize_identifier(self, value, _info):
+        return value._expression
+
+    @field_validator("content", mode="before")
+    @classmethod
+    def deserialize_tag(cls, value):
+        if isinstance(value, Criterion):
+            return value
+        elif isinstance(value, str):
+            try:
+                return Criterion(value)
+            except CriterionError as e:
+                raise ValueError(
+                    f'Could not parse "{value}" as criterion. Original error: {e}'
+                ) from e
+        else:
+            raise ValueError(
+                f"Expected Criterion or str as input but "
+                f'found f"{type(value)}" for "{value}'
+            )
+
+
+class Filter(BaseModel):
+    criterion: CriterionString
+    justification: str
+
+
+class PixelOperation(BaseModel):
+    description: str
+    criterion: CriterionString
+    areas: List[PixelArea]
+
+
+class PrivateAllowGroup(BaseModel):
+    # Allow arbitrary for PrivateBlockTagIdentifier
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    elements: List[PrivateBlockTagIdentifier]
+    justification: str
+
+    @field_serializer("elements")
+    def serialize_identifier(self, value, _info):
+        return [x.key() for x in value]
+
+    @field_validator("elements", mode="before")
+    @classmethod
+    def deserialize_tag(cls, values):
+        if not isinstance(values, list):
+            ValueError(f"elements should be a list, got {values}")
+        deserialized = []
+        for x in values:
+            if isinstance(x, TagIdentifier):
+                deserialized.append(x)
+            elif isinstance(x, str):
+                deserialized.append(tag_identifier_from_string(x))
+            else:
+                raise ValueError(
+                    f'Invalid input data for TagAction.identifier: "{x}"'
+                )
+        return deserialized
+
+
+class Protocol(BaseModel):
+    """Defines how to handle the deidentification of any incoming dataset. It does
+    not say anything about implementation, it only prescribes what should be done
+    to each part of a dataset and under which circumstances to reject it outright.
+
+    Overview of elements:
+    tags: Dict[str, List[TagAction]]
+        SOPInstanceUID that can contain wildcards: List of what to do with DICOM tags
+
+    filters: List[Filter]
+        If any of these filters matches, reject the DICOM dataset
+
+    pixel: List[PixelOperation]
+        What to do with pixel data. Where to put black boxes if a rule matches
+
+    private: List[PrivateAllowGroup]
+        Which private tags to allow and why
+    """
+
+    tags: Dict[str, List[TagAction]]
+    filters: List[Filter]
+    pixel: List[PixelOperation]
+    private: List[PrivateAllowGroup]
+
+    def sort_tags(self):
+        """Sort tag list for each SOPInstanceUID according to generality. The more
+        general, the lower in the list. This means you can take any DICOM tag and
+        try to match each element in the list until one hits.
+        """
+        for key, action_list in self.tags.items():
+            self.tags[key] = sorted(
+                action_list,
+                key=lambda x: x.identifier.number_of_matchable_tags(),
+            )

midom/constants.py

@@ -0,0 +1,77 @@
+"""Implementations of some of the MIDOM constants and objects"""
+from pydantic.dataclasses import dataclass
+
+
+class DeltaCodes:
+    """How has a DICOM element changed?"""
+
+    UNCHANGED = "UNCHANGED"
+    CHANGED = "CHANGED"
+    REMOVED = "REMOVED"
+    EMPTIED = "EMPTIED"
+    CREATED = "CREATED"
+
+    ALL = {UNCHANGED, CHANGED, REMOVED, EMPTIED, CREATED}
+
+
+@dataclass(frozen=True)
+class ActionCode:
+    key: str
+    var_name: str
+
+
+class ActionCodes:
+    """NEMA specifications from table E1-1. Indicates what to do with each tag"""
+
+    DUMMY = ActionCode("D", "DUMMY")  # replace with dummy
+    EMPTY = ActionCode("Z", "EMPTY")  # replace with zero length
+    REMOVE = ActionCode("X", "REMOVE")  # remove
+    KEEP = ActionCode("K", "KEEP")  # keep
+    CLEAN = ActionCode("C", "CLEAN")  # clean
+    UID = ActionCode("U", "UID")  # replace with consistent UID
+    EMPTY_OR_DUMMY = ActionCode("Z/D", "EMPTY_OR_DUMMY")
+    REPLACE_OR_DUMMY = ActionCode("X/Z", "REPLACE_OR_DUMMY")  # X unless Z is
+    # required for consistency
+    REMOVE_OR_EMPTY = ActionCode("X/Z", "REMOVE_OR_EMPTY")  # X unless Z is
+    # required for consistency
+    REMOVE_OR_DUMMY = ActionCode("X/D", "REMOVE_OR_DUMMY")  # X unless D is
+    # required for consistency
+    REMOVE_OR_EMPTY_OR_DUMMY = ActionCode(
+        "X/Z/D", "REMOVE_OR_EMPTY_OR_DUMMY"
+    )  # X unless Z or D is required
+    REMOVE_OR_EMPTY_OR_UID = ActionCode(
+        "X/Z/U*", "REMOVE_OR_EMPTY_OR_UID"
+    )  # X unless Z or U is required
+    UNDEFINED = ActionCode(
+        "?", "Undefined"
+    )  # not part of ALL below, special case
+
+    ALL = {
+        DUMMY,
+        EMPTY,
+        REMOVE,
+        KEEP,
+        CLEAN,
+        UID,
+        EMPTY_OR_DUMMY,
+        REMOVE_OR_EMPTY,
+        REMOVE_OR_DUMMY,
+        REMOVE_OR_EMPTY_OR_DUMMY,
+        REMOVE_OR_EMPTY_OR_UID,
+    }
+
+    PER_KEY = {x.key: x for x in ALL}
+    PER_VAR_NAME = {x.var_name: x for x in ALL}
+
+    @classmethod
+    def from_string(cls, key_or_var_name: str):
+        """I've got a string with either a full name or a key. Which action
+        code is this?
+        """
+        try:
+            return (cls.PER_KEY | cls.PER_VAR_NAME)[key_or_var_name]
+        except KeyError as e:
+            raise ValueError(
+                f"Unknown action code '{key_or_var_name}'. I "
+                f"know {','.join([str(x) for x in cls.ALL])}"
+            ) from e