Presentation of the Profile Structure
Definition of the actions applied to specific tags
Definition of the actions applied to dates
Definition of the expressions applied to specific tags
Definition of the masks applied to Pixel Data
Definition of the conditions applied to profile elements
Technical explanations about the de-identification process
In the Karnak user interface, the Profiles page can be accessed using the menu bar on the left. It displays the list of existing profiles and offers to import new profiles.
A profile file is one or a list of profile elements that are defined for a group of DICOM attributes and with a particular action. During de-identification or tag morphing, Karnak will apply the profile elements to the applicable DICOM attributes. Only one profile element can be applied to a DICOM attribute. The profile elements are applied in the order defined in the yaml file and, therefore, the first applicable profile element will modify the value of a DICOM attribute. If other profile elements were applicable to that specific tag, they won’t be applied since it has already been modified.
Currently, the profile must be a yaml file (MIME-TYPE: application/x-yaml) and respect the definition as below.
All these metadata are optional, but for a better user experience we recommend defining at least the name and the version. They will be used to identify and select your profile in a Project.
name - The name of your profile
version - The version of your profile
minimumKarnakVersion - The version of Karnak when the profile has been imported
defaultIssuerOfPatientID - Default value in case the IssuerOfPatientID value is not available in DICOM file, it is used to build the patient’s pseudonym when applying de-identification
profileElements - The list of profile elements, the elements are applied accordingly to their position in the list
A profile element is defined as below in the yaml file.
name - The name of your profile element
codename - The codename represents the type of profile element. The available types of profiles elements and their codename are described in details in this documentation
condition - A boolean condition that defines some requirements to apply this profile element
action - The type of action that will be applied
option - Required for certain types of profile elements, contains a single value
arguments - Required for certain types of profile elements, contains a list of key-value pairs
tags - List of tags or pattern that identifies the DICOM attributes this profile should be applied to
excludedTags - List of tags or pattern that identifies the DICOM attributes this profile should not be applied to. These attributes can then be modified by another profile element if applicable
DICOM Tags can be defined in different formats: (0010,0010); 0010,0010; 00100010;
A tag pattern represent a group of tags and can be defined as follows: e.g. (0010,XXXX) represent all the tags of group 0010.
The pattern (XXXX,XXXX) targets all the DICOM attributes.
A condition can be added to any type of profile element. It contains an expression that will be evaluated for each tag the profile element is applied to.
The syntax and usage of these conditions is detailed in the Conditions page.
The content of the yaml file is validated upon import. If the structure or parameters are not defined correctly, detailed errors will be displayed to the user.
Please refer to the Profiles page for more information.
The Basic DICOM Profile is defined by DICOM to remove all the attributes that could contain Individually Identifying Information (III) about the patient or other individuals or organizations associated with the data. The details of this profile element can be found in the DICOM Standard.
Further details on this profile element and its implementation in Karnak can be found in the How does de-identification work? page.
We strongly recommend including this profile as basis for de-identification.
This profile element can be included in the profile definition by referencing its codename:
- name: "DICOM basic profile"
codename: "basic.dicom.profile"Example of a complete and valid profile yaml file that applies only the Basic DICOM Profile:
name: "Dicom Basic Profile"
version: "1.0"
minimumKarnakVersion: "0.9.2"
defaultIssuerOfPatientID:
profileElements:
- name: "DICOM basic profile"
codename: "basic.dicom.profile"This profile element applies an action on a tag or a group of tags defined by the user. Its codename is action.on.specific.tags.
This profile element requires the following parameters:
name: description of the action appliedcodename: action.on.specific.tagsaction: Remove (X) / Keep (K)tags: list of tags the action should be applied toThis profile element can have these optional parameters:
condition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instanceexcludedTags: list of tags that will be ignored by this actionIn this example, all the tags starting with 0028 will be removed excepted (0028,1199) which will be kept.
- name: "Remove tags"
codename: "action.on.specific.tags"
action: "X"
tags:
- "(0028,xxxx)"
excludedTags:
- "(0028,1199)"
- name: "Keep tags 0028,1199"
codename: "action.on.specific.tags"
action: "K"
tags:
- "0028,1199"This profile element applies an action on a private tag or a group of private tags defined by the user. This action won’t be applied in case the tag is not private.
Its codename is action.on.privatetags.
This profile element requires the following parameters:
name: description of the action appliedcodename: action.on.privatetagsaction: Remove (X) / Keep (K)This profile can have these optional parameters:
condition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instancetags: list of tags the action should be applied to. If not specified, the action is applied to all private tagsexcludedTags: list of tags that will be ignored by this actionIn this example, all tags starting with 0009 will be kept and all the other private tags will be removed.
- name: "Keep private tags starting with 0009"
codename: "action.on.privatetags"
action: "K"
tags:
- "(0009,xxxx)"
- name: "Remove all private tags"
codename: "action.on.privatetags"
action: "X"This profile element adds a tag if it is not already present in the instance. This action will be ignored if the tag is already present in the instance.
Its codename is action.add.tag.
This profile element requires the following parameters:
name: description of the action appliedcodename: action.add.tagarguments:
value: required value to set the tag’s value totags: must contain exactly one tag, the one to addThis profile can have these optional parameters:
condition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instanceRegarding the application of profile elements, if the tag is not initially present in the instance, then it will be added by this action. Further actions that match this tag won’t be applied. If the tag was already present in the instance, then the add action is ignored and a further action can be applied to that tag. It is only possible to add tags at the root level of the DICOM instance. Adding elements in a sequence is not supported.
The attribute must exist in the DICOM Standard, otherwise the profile validation will fail and cannot be added. The VR is retrieved from the Standard as well. If this profile element is applied on a SOP class that does not contain this tag, it won’t be added to prevent corrupting the DICOM instance, and a warning will be generated in the logs
This feature is especially useful when applying masks to non-compliant SOPs by using the attribute Burned In Annotation. Please refer to the Cleaning Data Pixel Exceptions page for an exhaustive example.
In this example, we add the optional tag Recognizable Visual Features (0028,0302).
- name: "Add Recognizable Visual Features tag"
codename: "action.add.tag"
arguments:
value: "YES"
vr: "CS"
tags:
- "(0028,0302)"This profile element adds a private tag if it is not already present in the instance. This action will be ignored if the tag is already present in the instance or if there is a collision with a different Private Creator ID.
Its codename is action.add.private.tag.
This profile element requires the following parameters:
name: description of the action appliedcodename: action.add.private.tagarguments:
value: required value to set the tag’s value tovr: VR of the tagprivateCreator: optional value of the PrivateCreatorID, see belowtags: must contain exactly one tag, the one to addThis profile can have these optional parameters:
condition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instanceThe privateCreator argument is optional. It is recommended to specify it for coherence purposes.
In case the PrivateCreatorID tag does not exist for the private tag to be added, the privateCreator argument must be specified, and it will be created at the same time.
In case the PrivateCreatorID tag exists, if the privateCreator argument is not specified, the tag will be added as a part of it. It the privateCreator argument is specified, the existing PrivateCreatorID tag value will be matched against the privateCreator argument. If it matches, the new tag is added. If it doesn’t, there is a PrivateCreatorID collision and the tag won’t be added to prevent incoherent data in the DICOM instance. A warning will be generated in the logs.
The other specificities of the Add action are the same as above, for non-private tags.
The details about the management of tags and element numbers in private tags are detailed in the DICOM Standard.
In this example, we add a private tag containing the value “sample-project” linked to the PrivateCreatorID “KARNAK-PRIVATE”. The PrivateCreatorID tag (0057,0010) is created with the value “KARNAK-PRIVATE” if it is not present in the DICOM instance. If it exists already and contains the value “KARNAK-PRIVATE”, the (0057,1000) tag will be created.
If the PrivateCreatorID tag (0057,0010) exists already but contains a value different from “KARNAK-PRIVATE”, the tag (0057,1000) won’t be added since it would result in linking it to the wrong PrivateCreatorID.
- name: "Add Private Tag"
codename: "action.add.private.tag"
arguments:
value: "sample-project"
vr: "LO"
privateCreator: "KARNAK-PRIVATE"
tags:
- "(0057,1000)"Example of a complete and valid profile yaml file that applies the following profile elements in order:
name: "De-identification profile"
version: "1.0"
minimumKarnakVersion: "0.9.2"
defaultIssuerOfPatientID:
profileElements:
- name: "Remove tags"
codename: "action.on.specific.tags"
action: "X"
tags:
- "(0008,00XX)"
- "0010,00XX"
excludedTags:
- "0008,0008"
- "0008,0013"
- name: "Keep tags"
codename: "action.on.specific.tags"
action: "K"
tags:
- "0008,0008"
- "0008,0013"
- name: "Remove all private tags"
codename: "action.on.privatetags"
action: "X"
- name: "DICOM basic profile"
codename: "basic.dicom.profile"This example keeps a Study Description tag if that as contain ‘R2D2’ value, keep the Philips PET private group and apply the basic DICOM profile.
The tag patterns (0073,xx00) and (7053,xx09) are defined in Philips PET Private Group by DICOM.
name: "Profile Example"
version: "1.0"
minimumKarnakVersion: "0.9.7"
profileElements:
- name: "Keep StudyDescription tag according to a condition"
codename: "action.on.specific.tags"
condition: "tagValueContains(#Tag.StudyDescription, 'R2D2')"
action: "K"
tags:
- "(0008,1030)"
- name: "Keep Philips PET Private Group"
codename: "action.on.privatetags"
action: "K"
tags:
- "(7053,xx00)"
- "(7053,xx09)"
- name: "DICOM basic profile"
codename: "basic.dicom.profile"This profile element applies a specific action on a tag or a group of tags containing a date. This action can only be applied to the following Value Representations: Age String (AS), Date (DA), Date Time (DT) and Time (TM).
This profile element requires the following parameters:
name: description of the action appliedcodename: action.on.datesoption: the action to be applied, detailed belowarguments: additional parameters depending on the chosen optionThis profile can have these optional parameters:
condition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instancetags: list of tags the action should be applied to. If not specified, the profile element will be applied to all the tags that have a AS, DA, DT or TM VR in the instanceexcludedTags: list of tags that will be ignored by this actionThe parameter option can have one of the following values:
shiftshift_rangeshift_by_tagdate_formatThe shift option applies a shift to a date according to the following required arguments:
seconds: integer representing the number of seconds the shift operation should applydays: integer representing the number of days the shift operation should applyIn the case of a shift action applied to an Age String (AS) Value Representation, the seconds and days will be added to the existing value.
In case of a shift action applied to a Date (DA), Date Time (DT) or Time (TM) Value Representation, the seconds and days will be subtracted to the existing value.
In this example, all the tags starting with 0010 and that have a AS, DA, DT or TM VR will be shifted by 30 seconds and 10 days.
- name: "Shift Date"
codename: "action.on.dates"
arguments:
seconds: 30
days: 10
option: "shift"
tags:
- "0010,XXXX"The shift range option applies a random shift to a date parametrized by ranges defined by the user as follows:
max_seconds (required): integer representing the upper bound of the number of seconds the shift operation should applymax_days (required): integer representing the upper bound of the number of days the shift operation should applymin_seconds (optional): integer representing the lower bound of the number of seconds the shift operation should apply, the default value is 0 is not specifiedmin_days (optional): integer representing the lower bound of the number of days the shift operation should apply, the default value is 0 is not specifiedThe random operation is deterministic and reproducible based on the patient and the project. For more details about the usage of randomization in Karnak, please refer to the Karnak Project.
In this example, all the tags starting with 0008,002 and that have a AS, DA, DT or TM VR will be shifted randomly in a range of 0 to 60 seconds and 50 to 100 days.
- name: "Shift Range Date"
codename: "action.on.dates"
arguments:
max_seconds: 60
min_days: 50
max_days: 100
option: "shift_range"
tags:
- "0008,002X"The date format option applies a partial deletion to a date depending on the specified option:
day: this option will delete the day information and replace it with the first day of the monthmonth_day: this option will delete the day and month information and replace it with the first month and first day of the monthThis action can only be applied to the following Value Representations: Date (DA) and Date Time (DT).
In this example, all the tags starting with 0008,003 and that have a DA or DT VR will have the day information removed.
- name: "Date format"
codename: "action.on.dates"
arguments:
remove: "day"
option: "date_format"
tags:
- "0008,003X"For example, if the value contained in the tag is 20230512, the output value will be 20230501.
In this example, all the tags starting with 0008,003 and that have a DA or DT VR will have the day and month information removed.
- name: "Date format"
codename: "action.on.dates"
arguments:
remove: "month_day"
option: "date_format"
tags:
- "0008,003X"For example, if the value contained in the tag is 20230512, the output value will be 20230101.
The shift by tag option applies a shift to a date according to a value contained in a specified DICOM tag. The arguments are detailed below:
seconds_tag: tag that contains the number of seconds the shift operation should applydays_tag: tag that contains the number of days the shift operation should applyBoth arguments are not required, but at least one of them must be specified in order to apply the action.
In this example, all the tags starting with 0010 and that have a AS, DA, DT or TM VR will be shifted by the number of days stored in the private tag (0015,0011).
- name: "Shift Date By Tag"
codename: "action.on.dates"
arguments:
days_tag: "(0015,0011)"
option: "shift_by_tag"
tags:
- "0010,XXXX"Example of a complete and valid profile yaml file that applies the following profile elements in order:
name: "De-identification profile"
version: "1.0"
minimumKarnakVersion: "0.9.2"
defaultIssuerOfPatientID:
profileElements:
- name: "Shift Range Date with arguments"
codename: "action.on.dates"
arguments:
max_seconds: 60
min_days: 10
max_days: 50
option: "shift_range"
tags:
- "0008,0012"
- "0008,003X"
excludedTags:
- "0008,0030"
- "0008,0032"
- name: "Date Format"
codename: "action.on.dates"
arguments:
remove: "month_day"
option: "format_date"
tags:
- "0008,0023"
- "0008,0021"
- name: "Shift Date with arguments"
codename: "action.on.dates"
arguments:
seconds: 30
days: 10
option: "shift"
tags:
- "0010,XXXX"
excludedTags:
- "0010,1010"
- name: "DICOM basic profile"
codename: "basic.dicom.profile"This profile element applies an expression to a tag or a group of tags defined by the user. An expression is based on Spring Expression Language (SpEL) and returns a value or an action according to a certain condition.
Its codename is expression.on.tags.
This profile element requires the following parameters:
name: description of the action appliedcodename: expression.on.tagsarguments: definition of the expressiontags: list of tags the action should be applied toThis profile can have these optional parameters:
condition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instanceexcludedTags: list of tags that will be ignored by this actionThe expression is contained in the expr argument. The expression will be executed and can either return an action that will be executed, or a null value that will do nothing and move on the next profile element.
Some custom variables are defined in the context of the expression, they contain information relative to the current attribute the profile element is being applied to:
tag contains the current attribute tag, for example (0010,0010)vr contains the current attribute VR, for example PNstringValue contains the current element value, for example ‘John^Doe’Some constants are also defined to improve readability and reduce errors.
#Tag is a constant that can be used to retrieve any tag integer value in the DICOM standard. For example, #Tag.PatientBirthDate corresponds to (0010,0030).#VR is a constant that can be used to retrieve any VR value in the DICOM standard. For example, #VR.LO corresponds to the Long String type.Some utility functions are defined to work with the tags:
getString(int tag) returns the value of the given tag in the DICOM instance, returns null if the tag is not present
tagIsPresent(int tag) returns true if the tag is present in the DICOM instance, false otherwise
The actions are defined as functions, they are used to set the action and its parameters for the profile element.
The possible actions are:
ReplaceNull(): Sets to empty the current tag valueReplace(String dummyValue): Replaces the current tag valueRemove(): Removes the tagKeep(): Keeps the tag unchangedUID(): Replaces the current tag value with a newly generated UID and sets the tag’s VR to UIAdd(int tagToAdd, int vr, String value): Adds a tag to the DICOM instanceComputePatientAge(): Replaces the current tag value with a computed value of the patient’s age at the time of the examIf the current tag corresponds to the Patient Name attribute and its value is ‘John’, its content will be replaced by the value of the Institution Name attribute, otherwise the tag is kept unchanged. This example is applied to all the attributes of the DICOM instance, and returns either a Keep or Replace action for every tag, implying that the following profile elements, if any, will be ignored since all the attributes already had an action applied to them.
- name: "Expression"
codename: "expression.on.tags"
arguments:
expr: "stringValue == 'John' and tag == #Tag.PatientName? Replace(getString(#Tag.InstitutionName)) : Keep()"
tags:
- "(xxxx,xxxx)"If the current tag value is UNDEFINED, it will be kept as is (and it will implicitly block any further potential modifications applied by other profile elements), otherwise the tag is removed. This expression is applied to 2 tags, (0010,0010) and (0010,0212).
- name: "Expression"
codename: "expression.on.tags"
arguments:
expr: "stringValue == 'UNDEFINED'? Keep() : Remove()"
tags:
- "(0010,0010)" #PatientName
- "(0010,0212)" #StrainDescriptionReplacement of the Study Description tag value with a concatenation of the Institution Name and the Station Name of the DICOM instance.
- name: "Expression"
codename: "expression.on.tags"
arguments:
expr: "Replace(getString(#Tag.InstitutionName) + '-' + getString(#Tag.StationName))"
tags:
- "(0008,1030)" #StudyDescriptionComputation of the patient’s age at the time of the exam.
- name: "Expression"
codename: "expression.on.tags"
arguments:
expr: "ComputePatientAge()"
tags:
- "(0010,1010)" #PatientAgeThis profile applies defacing to the image data of the DICOM instance.
This profile can only be applied to images in the Axial orientation of the following SOP:
This profile element requires the following parameters:
name: description of the action appliedcodename: clean.recognizable.visual.featurescondition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instanceThis profile applies a mask defined by the user on the DICOM instance pixel data to remove identifying information burned in the image.
The details on the masks definition can be found below.
This profile is applied only on the following SOP:
Or if the tag value Burned In Annotation (0028,0301) is “YES”
This profile element requires the following parameters:
name: description of the action appliedcodename: clean.pixel.datacondition: optional, defines a condition to evaluate if this profile element should be applied to this DICOM instanceThe condition parameter can be used to exclude the images coming from a specific machine for example.
profileElements:
- name: "Clean pixel data"
codename: "clean.pixel.data"
condition: "!tagValueContains(#Tag.StationName,'ICT256')"The mask definition requires the following parameters:
stationName: source station name that is matched against the attribute Station Name in the DICOM instance. It allows the mask to be specific depending on the station that generated the image. The value can also be set to * to match any station.color: color of the mask in hexadecimalrectangles: defines the list of rectangles to apply to mask identifying informationThe mask definition can have these optional parameters:
imageWidth: mask specific to an image of a given width in pixels, this value will be matched against the value of the Columns attribute in the DICOM instanceimageHeight: mask specific to an image of a given height in pixels, this value will be matched against the value of the Rows attribute in the DICOM instance.The selection of the mask based on the image size requires both attributes to be set, height and width. The definition of the width or height solely is not supported.
A rectangle is defined by the following required parameters:
x: x coordinate of the upper left corner of the rectangley: y coordinate of the upper left corner of the rectanglewidth: width of the rectangleheight: height of the rectangleThe upper left corner of the image corresponds to the coordinates (0,0).
The schema below illustrate the definition of a rectangle having the following parameters (25, 75, 150, 50).
The example below shows how to define a default mask (stationName: *), a mask specific to the R2D2 station and a more specific mask applied only depending on the image size.
Depending on the instance image size and station name, the following actions will be performed:
masks:
- stationName: "*"
color: "ffff00"
rectangles:
- "25 75 150 50"
- stationName: "R2D2"
color: "00ff00"
rectangles:
- "25 25 150 50"
- "350 15 150 50"
- stationName: "R2D2"
imageWidth: 1024
imageHeight: 1024
color: "00ffff"
rectangles:
- "50 25 100 100"In some cases, often based on the manufacturer and equipment, pixel data can contain embedded identifying information. Below is an exhaustive example illustrating how to apply cleaning pixel profile element depending on the station that produced the image, applicable to any DICOM modality.
name: "Clean pixel data"
version: "1.0"
minimumKarnakVersion: "0.9.2"
defaultIssuerOfPatientID:
profileElements:
- name: "Add tag BurnedInAnnotation if does not exist"
codename: "action.add.tag"
condition: "tagValueContains(#Tag.StationName, 'ICT256') && !tagIsPresent(#Tag.BurnedInAnnotation)"
arguments:
value: "YES"
vr: "CS"
tags:
- "(0028,0301)"
- name: "Set BurnedInAnnotation to YES"
codename: "expression.on.tags"
condition: "tagValueContains(#Tag.StationName, 'ICT256')"
arguments:
expr: "Replace('YES')"
tags:
- "(0028,0301)"
- name: "Clean pixel data"
codename: "clean.pixel.data"
- name: "DICOM basic profile"
codename: "basic.dicom.profile"
masks:
- stationName: "*"
color: "ffff00"
rectangles:
- "25 75 150 50"
- stationName: "ICT256"
color: "00ff00"
rectangles:
- "25 25 150 50"
- "350 15 150 50"A condition is an expression evaluated in a certain context and that returns a boolean value (true or false).
Some constants are also defined to improve readability and reduce errors.
#Tag is a constant that can be used to retrieve any tag integer value in the DICOM standard. For example, #Tag.PatientBirthDate corresponds to (0010,0030).#VR is a constant that can be used to retrieve any VR value in the DICOM standard. For example, #VR.LO corresponds to the Long String type.Utility functions are available to define the conditions and are detailed below.
tagValueIsPresent(int tag, String value) or tagValueIsPresent(String tag, String value)
This function will retrieve the tag value of the DICOM and check if the value parameter is the same as the tag value.
# Check if the study description is equals to "755523-st222-GE"
tagValueIsPresent(#Tag.StudyDescription, "755523-st222-GE")
tagValueIsPresent("0008,1030", "755523-st222-GE")
# Check if the study description is not equals to "755523-st222-GE"
!tagValueIsPresent(#Tag.StudyDescription, "755523-st222-GE")
!tagValueIsPresent("0008,1030", "755523-st222-GE")tagValueContains(int tag, String value) or tagValueContains(String tag, String value)
This function will retrieve the tag value of the DICOM and check if the value parameter appears in the tag value.
# Check if the study description contains "st222"
tagValueContains(#Tag.StudyDescription, "st222")
tagValueContains("0008,1030", "st222")
# Check if the study description does not contain "st222"
!tagValueContains(#Tag.StudyDescription, "st222")
!tagValueContains("0008,1030", "st222")tagValueBeginsWith(int tag, String value) or tagValueBeginsWith(String tag, String value)
This function will retrieve the tag value of the DICOM and check if the tag value begins with the parameter value
# Check if the study description begins with "755523"
tagValueBeginsWith(#Tag.StudyDescription, "755523")
tagValueBeginsWith("0008,1030", "755523")
# Check if the study description does not begin with "755523"
!tagValueBeginsWith(#Tag.StudyDescription, "755523")
!tagValueBeginsWith("0008,1030", "755523")tagValueEndsWith(int tag, String value) or tagValueEndsWith(String tag, String value)
This function will retrieve the tag value of the DICOM and check if the tag value ends with the parameter value
# Check if the study description ends with "GE"
tagValueEndsWith(#Tag.StudyDescription, "GE")
tagValueEndsWith("0008,1030", "GE")
# Check if the study description does not end with "GE"
!tagValueEndsWith(#Tag.StudyDescription, "GE")
!tagValueEndsWith("0008,1030", "GE")tagIsPresent(int tag) or tagIsPresent(String tag)
This function will check if the tag is present in the DICOM instance.
# Check if the tag study description is present in the DICOM file
tagIsPresent(#Tag.StudyDescription)
tagIsPresent("0008,1030")
# Check if the tag study description is not present in the DICOM file
!tagIsPresent(#Tag.StudyDescription)
!tagIsPresent("0008,1030")Multiple conditions can be combined using logical operators.
&& corresponds to the AND logical operator
|| corresponds to the OR logical operator
# Check if the tag study description ends with "GE" and if the station name is "CT1234"
tagValueEndsWith(#Tag.StudyDescription, "GE") && tagValueContains(#Tag.StationName, "CT1234")
# Check if the tag study description ends with "GE" or if the station name is "CT1234"
tagValueEndsWith(#Tag.StudyDescription, "GE") || tagValueContains(#Tag.StationName, "CT1234")Karnak is a gateway for sending DICOM files to one or multiple Application Entity Title (AET). Karnak offers the possibility to configure multiple destinations for an AET. These destinations can communicate using the DICOM or DICOM WEB protocol.
A destination contains several configurations for the DICOM endpoint, the credentials, and is also linked to a project.
A project defines the de-idenfication or tag morphing method and a secret that will be used to generate deterministic random values like UIDs or shift date arguments.
The reference profile for de-identifying DICOM objects is provided by the DICOM standard. This profile defines an exhaustive list of DICOM tags and their related action to allow the de-identification of the instance.
In order to properly de-identify the sensitive data, five different actions are defined in the standard:
The Basic Profile defines one or more actions to be applied to a list of tags.
The DICOM’s type is often dependent on the Information Object Definition (IOD) of the instance. To avoid DICOM corruption, multiple actions can be defined for a tag, ensuring that a destructive action like REMOVE won’t be applied on a Type 1 or Type 2 attribute.
Karnak loads the SOPs and attributes as specified in the DICOM Standard. Based on the tag’s type in the current instance, the proper action is set and applied. If the tag cannot be identified in the SOP or its type cannot be inferred, the strictest action will be applied (U/D > Z > X).
Below is a concrete illustration of the action applied in case of multiple actions defined in the Basic Profile:
The action D replaces the tag value with a dummy one. This value must be consistent with the Value Representation (VR) of the tag.
Karnak will use a default value based on the VR in this case, as defined below:
The shiftRange() action will return a random value between a given maximum days and seconds. By default, maximum days is set to 365 and maximum seconds is set to 86400.
The following VRs FL, FD, SL, SS, UL, US are of type Binary. By default, Karnak will set to null the value of this VR.
For each U action, Karnak will hash the input value. A one-way function is created to ensure that it is not possible to revert to the original UID. This function will hash the input UID and generate a new UID from the hashed input.
It’s possible for a DICOM study to be de-identified several times and in different ways, potentially implying the use of multiple hashing and one-way functions. Karnak ensures deterministic generation of UIDs in order to maintain the quality and usability of the data.
To achieve that behavior, a project must be created and associated to the destination that requires de-identification. A project defines a de-idenfication method and a secret, either generated randomly or imported by the user. The project’s secret will be used as key for the HMAC.
The secret is 16 bytes long and randomly defined when the project is created.
A user can upload his own secret, but it must be 16 bytes long. It can be uploaded as a String in hexadecimal format.
The algorithm used for hashing is the “Message Authentication Code” (MAC). Karnak uses the MAC, not as message authentication, but as a one-way function. Below is a definition from the JAVA Mac class used in Karnak:
« A MAC provides a way to check the integrity of information transmitted over or stored in an unreliable medium, based on a secret key. Typically, message authentication codes are used between two parties that share a secret key in order to validate information transmitted between these parties.
A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC. HMAC can be used with any cryptographic hash function, e.g., SHA256 or SHA384, in combination with a secret shared key. HMAC is specified in RFC 2104. »
For each use of the HMAC, it uses the SHA256 hash function combined with the project’s secret.
« What DICOM calls a “UID” is referred to in the ISO OSI world as an Object Identifier (OID) » [1]
To generate a new DICOM UID, Karnak will create an OID beginning with “2.25”, that is an OID encoded UUID.
« The value after “2.25.” is the straight decimal encoding of the UUID as an integer. It MUST be a direct decimal encoding of the single integer, all 128 bits. » [2]
The generated UUID will use the first 16 bytes (128 bits) from the hash value. The UUID is a type 4 with a variant 1. See the pseudocode below to ensure the type and the variant are correct in the UUID:
// Version
uuid[6] &= 0x0F
uuid[6] |= 0x40
// Variant
uuid[8] &= 0x3F
uuid[8] != 0x80The hashed value will be converted in a positive decimal number and appended to the OID root separated by a dot. See the example below:
OID_ROOT = “2.25”
uuid = OID_ROOT + “.” + HashedValue[0:16].toPositiveDecimal()Karnak implements a randomized date shifting action. This shift must be identical based on the project and the patient for data consistency. For example, if a random shift is made for the birthdate of the patient “José Santos”, it must be the same for each instance associated to “José Santos”, even if the instance is loaded later.
The random shift date action will use the HMAC defined above and a range of days or seconds defined by the user. If the minimum isn’t specified, it defaults to 0.
The patientID, along with the project’s secret, will be passed to the HMAC, ensuring data consistency by patient.
The code below illustrates how a random value is generated within a given minimum (inclusive) and maximum (exclusive) range.
scaleHash(PatientID, scaledMin, scaledMax):
patientHashed = hmac.hash(PatientID)
scale = scaledMax - scaledMin
shift = (patientHashed[0:6].toPositiveDecimal() * scale) + scaledMinThis chapter details the problems linked to the PatientID generation for different de-identification methods.
A patient can participate in several studies using different de-identification methods. Depending on the project or the clinical research, the de-identification profile can keep some of the patient’s metadata. A pseudonym and a patientID are generated and affected to the patient in order to identify him in the context of the project.
Most of the patient’s identifying information is contained in the Patient Module.
Below is illustrated a case where some patient’s data could be leaked. During the de-identification, the patient is associated with a pseudonym provided by an external service or mapping table. In this example, a patient’s study falls in the scope of two different projects in Karnak. The first de-identification removes the patient birthdate (3. Apply Project 1) and the second keeps it (5. Apply Project 2). If the patient pseudonym is used as patient identification in the Patient Module, and the data is reconciled between the two study, the birthdate will be leaked.
Below is illustrated an alternative way of handling pseudonyms during the de-identification.
In this example, the patient is still associated with a pseudonym provided by an external service or mapping table. But Karnak will generate a PatientID based on this pseudonym and other characteristics linked to the project specifically. This ID will be used to identify the patient in the context of the project. In case of different de-identification methods in different projects, the patients cannot be reconciled and data won’t be leaked.
Karnak generates a PatientID to solve the problem explained previously. The PatientID is generated using the HMAC function defined in the project, see chapter Action U, Generate a new UID for more details.
The de-identified patientID is generated as follows :
The pseudonym will be used as the patient’s name if no other action has been defined during de-identification.
It is possible to retrieve the patient information once de-identified.
The patientID is generated from the pseudonym and the project’s secret using the hmac function, making it irreversible. The pseudonym is stored in the attribute Clinical Trial Subject ID (0012,0040). Using the mapping table or the service that provided the pseudonym, it is possible to retrieve the original patient identity.
« The Clinical Trial Subject ID (0012,0040) identifies the subject within the investigational protocol specified by Clinical Trial Protocol ID (0012,0020). » [3]
Some attributes are automatically set by Karnak during de-identification in the following modules.
The following attributes are set in the SOP Common module during de-identification:
The following attributes are set in the SOP Common module during de-identification:
The profile element codenames are concatenated and separated by -. For example, a profile composed of the profile elements action.on.specific.tags and basic.dicom.profile will appear as action.on.specific.tags-basic.dicom.profile.
The following attributes are set in the Clinical Trial Subject Module during de-identification: