Profile Structure

The Profiles page allows you to manage de-identification profiles for your projects in the Karnak interface. This page explains the structure of these profiles and how to create or modify them using YAML files.

Overview

A profile defines how DICOM attributes should be modified during de-identification or tag morphing. It consists of one or more profile elements, each specifying:

• Which DICOM attributes to target
• What action to apply (e.g., remove, replace, keep)
• Optional conditions for applying the action

Important behavior:

• Profile elements are applied sequentially in the order they appear in the YAML file
• Only the first applicable profile element modifies each DICOM attribute
• Once modified, subsequent profile elements won’t affect that attribute

Profile Metadata

Metadata fields help identify and manage your profiles. While optional, we recommend defining at least name and version for clarity.

Profile Element Structure

Each profile element defines a specific de-identification rule.

Required Fields

Optional Fields

DICOM Tag Formats

Tags can be specified in multiple formats:

Conditions

Add optional conditions to control when a profile element applies. The expression is evaluated for each matching tag.

For complete syntax and examples, see the Conditions page.

Basic DICOM Profile

The Basic DICOM Profile is the DICOM standard’s reference profile for removing Personally Identifying Information (PII) from DICOM files. The conditions to apply rules for a specific tag depend on its attribute type (Type 1, Type 2, etc.) based on the Information Object Definition (IOD). Karnak automatically determines the attribute type for each tag during de-identification.

Why Use It?

• Removes all attributes containing identifiable patient information
• Maintains DICOM conformance
• Industry-standard approach to de-identification

How to Include

Reference it by codename in your profile:

- name: "DICOM basic profile"
  codename: "basic.dicom.profile"

Complete Example

Below is a minimal but complete profile 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"

Actions on tags

This page describes profile elements that apply actions to DICOM tags. These actions allow you to selectively keep, remove, or add tags during de-identification.

Actions on specific tags

This profile element applies an action to a tag or group of tags defined by the user.

Required Parameters

Optional Parameters

Example

In this example, all tags starting with 0028 will be removed except (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"

Actions on private tags

This profile element applies an action to private tags or groups of private tags defined by the user. This action is only applied if the tag is private (where the group number is odd).

Required Parameters

Optional Parameters

Example

In this example, all tags starting with 0009 will be kept and all 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"

Add new tags

This profile element adds a tag if it is not already present in the instance. This action is ignored if the tag already exists.

Required Parameters

Optional Parameters

Behavior

When the tag is not present:

• The tag will be added by this action
• Further profile element actions that match this tag won’t be applied

When the tag already exists:

• The add action is ignored
• A subsequent profile element action can be applied to that tag

Use Case

This feature is especially useful when applying masks to non-compliant SOPs by using the Burned In Annotation attribute. See the Cleaning Data Pixel Exceptions page for a complete example.

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"
  tags:
    - "(0028,0302)"

Add new private tags

This profile element adds a private tag if it is not already present in the instance. This action is ignored if the tag already exists or if there is a collision with a different Private Creator ID.

Required Parameters

Optional Parameters

PrivateCreator Management

The privateCreator argument is optional but recommended for consistency.

When the PrivateCreatorID tag does not exist:

• The privateCreator argument must be specified
• The PrivateCreatorID tag will be created automatically

When the PrivateCreatorID tag exists:

• If privateCreator is not specified: The tag will be added as part of the existing PrivateCreatorID
• If privateCreator is specified: The existing value is matched against the argument
  • If they match: The new tag is added
  • If they don’t match: A collision occurs and the tag is not added (a warning is logged)

Example

In this example, we add a private tag containing the value “sample-project” linked to the PrivateCreatorID “KARNAK-PRIVATE”.

- name: "Add Private Tag"
  codename: "action.add.private.tag"
  arguments:
    value: "sample-project"
    vr: "LO"
    privateCreator: "KARNAK-PRIVATE"
  tags:
    - "(0057,1000)"

What happens:

• If the PrivateCreatorID tag (0057,0010) doesn’t exist, it’s created with the value “KARNAK-PRIVATE” and the tag (0057,1000) is added
• If (0057,0010) exists with the value “KARNAK-PRIVATE”, the tag (0057,1000) is added
• If (0057,0010) exists with a different value, the tag (0057,1000) is not added to prevent linking it to the wrong PrivateCreatorID

Complete Profile Examples

Example 1: Basic De-identification Profile

This profile applies the following operations in order:

1. Remove tags matching (0008,00XX) and (0010,00XX) except (0008,0008) and (0008,0013)
2. Keep the previously excluded tags specifically (so they won’t be removed by subsequent profile elements)
3. Remove all private tags
4. Apply the Basic DICOM Profile to all remaining tags

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"

Example 2: Conditional Profile with Private Tags

This profile demonstrates conditional actions and preserving specific private tags:

1. Keep Study Description tag only if it contains ‘R2D2’
2. Keep the Philips PET private group
3. Apply the Basic DICOM Profile

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"

Actions on dates

This profile element applies a specific action to tags containing dates. These actions can only be applied to the following Value Representations: Age String (AS), Date (DA), Date Time (DT), and Time (TM).

Parameters

Required parameters

• name: Description of the action applied
• codename: Must be set to action.on.dates
• option: The action to be applied (see options below)
• arguments: Additional parameters depending on the chosen option

Optional parameters

• condition: Defines a condition to evaluate whether this profile element should be applied to the DICOM instance
• tags: List of tags the action should be applied to. If not specified, the action applies to all tags with AS, DA, DT, or TM Value Representation
• excludedTags: List of tags that will be ignored by this action

Available Options

The option parameter can have one of the following values:

• shift - Apply a fixed time shift
• shift_range - Apply a random time shift within specified ranges
• shift_by_tag - Apply a shift based on values from another DICOM tag
• date_format - Remove date precision (day and/or month)

Shift Option

The shift option applies a fixed shift to dates using the following required arguments:

• seconds: Integer representing the number of seconds for the shift operation
• days: Integer representing the number of days for the shift operation

Behavior by Value Representation:

• Age String (AS): Seconds and days are added to the existing value
• Date (DA), Date Time (DT), Time (TM): Seconds and days are subtracted from the existing value

Example

This example shifts all tags starting with 0010 that have AS, DA, DT, or TM Value Representation by 30 seconds and 10 days:

- name: "Shift Date"
  codename: "action.on.dates"
  arguments:
    seconds: 30
    days: 10
  option: "shift"
  tags:
    - "0010,XXXX"

Shift Range Option

The shift_range option applies a random shift to dates within user-defined ranges.

Arguments

• max_seconds (required): Upper bound for the number of seconds to shift
• max_days (required): Upper bound for the number of days to shift
• min_seconds (optional): Lower bound for the number of seconds to shift (defaults to 0)
• min_days (optional): Lower bound for the number of days to shift (defaults to 0)

The random operation is deterministic and reproducible based on the patient and project.

Example

This example shifts all tags starting with 0008,002 that have AS, DA, DT, or TM Value Representation randomly within 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"

Date Format Option

The date_format option removes date precision by deleting specific date components.

This action can only be applied to Date (DA) and Date Time (DT) Value Representations.

Arguments

• remove: Specifies which date components to remove
  • day: Removes the day information, replacing it with 01
  • month_day: Removes both month and day information, replacing them with 01 for each

Example: Remove Day

This example removes the day from all tags starting with 0008,003 that have DA or DT Value Representation:

  - 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.

Shift By Tag Option

The shift_by_tag option applies a shift based on values contained in other DICOM tags.

Arguments

At least one of the following arguments must be specified:

• seconds_tag: Tag containing the number of seconds for the shift operation
• days_tag: Tag containing the number of days for the shift operation

Example

This example shifts all tags starting with 0010 that have AS, DA, DT, or TM Value Representation 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"

Complete Profile Example

This example demonstrates a complete de-identification profile that applies multiple date actions in sequence:

1. Shift Range: Randomly shift tags matching (0008,003X) and (0008,0012) (except (0008,0030) and (0008,0032)) by 0 to 60 seconds and 10 to 50 days
2. Date Format: Remove month and day from tags (0008,0023) and (0008,0021)
3. Fixed Shift: Shift tags matching (0010,XXXX) (except (0010,0010)) by 30 seconds and 10 days
4. Basic Profile: Apply the Basic DICOM Profile to all remaining tags

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"

Expressions

Actions on specific tags

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.

Parameters

This profile element requires the following parameters:

Expression Context

The expression is contained in the expr argument. When executed, it can either:

• Return an action to be executed
• Return a null value (does nothing and moves to the next profile element)

Available Variables

The following variables are available in the expression context, containing information about the current attribute:

Constants

Constants improve readability and reduce errors:

Utility Functions

The following utility functions help work with tags:

Available Actions

Actions are defined as functions and set the operation to perform on the current tag:

Examples

Conditional replacement based on tag value and type

Replace the Patient Name with the Institution Name if the current value is ‘John’, otherwise keep it unchanged:

  - name: "Expression"
    codename: "expression.on.tags"
    arguments:
      expr: "stringValue == 'John' and tag == #Tag.PatientName? Replace(getString(#Tag.InstitutionName)) : Keep()"
    tags: 
      - "(xxxx,xxxx)"

Remove tags with undefined values

Remove tags with ‘UNDEFINED’ value, otherwise keep them:

  - name: "Expression"
    codename: "expression.on.tags"
    arguments:
      expr: "stringValue == 'UNDEFINED'? Keep() : Remove()"
    tags: 
      - "(0010,0010)" #PatientName
      - "(0010,0212)" #StrainDescription

Concatenate multiple tag values

Replace Study Description with a concatenation of Institution Name and Station Name:

- name: "Expression"
  codename: "expression.on.tags"
  arguments:
    expr: "Replace(getString(#Tag.InstitutionName) + '-' + getString(#Tag.StationName))"
  tags: 
    - "(0008,1030)" #StudyDescription

Compute patient age

Calculate and set the patient’s age at the time of the exam:

- name: "Expression"
  codename: "expression.on.tags"
  arguments:
    expr: "ComputePatientAge()"
  tags: 
    - "(0010,1010)" #PatientAge

Exclude instances conditionally

Exclude all instances that contain a name in the image (where Specimen Label In Image is set to YES):

  - name: "Expression"
    codename: "expression.on.tags"
    arguments:
      expr: "getString(#Tag.SpecimenLabelInImage) == 'YES' ? ExcludeInstance() : null"
    tags: 
      - "(xxxx,xxxx)"

API Actions

Actions with API calls

This profile element uses a call to an API to replace the value of a tag or a group of tags defined by the user.

Parameters

Arguments

URL and Body Arguments

The URL and body may require values directly linked to the instance being transferred, such as the Patient ID.

A specific syntax allows this runtime injection. Parts evaluated at runtime must be enclosed in double brackets. The syntax uses Spring Expression Language (SpEL), with functions and constants defined similarly to Expressions.

URL examples:

http://example.com/{{getString(#Tag.PatientID)}}/endpoint
http://example.com/{{getString(#Tag.ClinicalTrialSponsorName)}}/patient/{{getString(#Tag.PatientID)}}/endpoint

{ 
  "patientId": "{{getString(#Tag.PatientID)}}", 
  "project": "{{getString(#Tag.ClinicalTrialSponsorName)}}" 
}

In the body, hence the JSON format, the expression must be enclosed in double quotes if the expected value is a String.

Examples

Example 1: Replace Patient ID with API response

The profile element below replaces the value of the Patient ID tag with the value retrieved from the url, it extracts the String value from the response at the specified path. Since it is not specified, the HTTP method is GET.

The authConfig argument contains the identifier of the Authentication Configuration used to authenticate the API call.

If an error occurs during the call, this transfer will be aborted. If the defaultValue was specified, it would have been used as the replacement value and the transfer would not have been blocked.

  - name: "Replace Patient ID from API call"
    codename: "action.replace.api"
    arguments:
      url: "http://example.com/{{getString(#Tag.PatientID)}}/endpoint"
      responsePath: "/_embedded/0/value"
      authConfig: "endpoint-auth-config"
    tags:
      - "(0010,0020)"

Example 2: POST request with body and default value

  - name: "Replace Patient Name with fallback"
    codename: "action.replace.api"
    arguments:
      url: "http://example.com/patients"
      method: "POST"
      body: '{"patientId": "{{getString(#Tag.PatientID)}}"}'
      responsePath: "/name"
      authConfig: "endpoint-auth-config"
      defaultValue: "ANONYMOUS"
    tags:
      - "(0010,0010)"

Image modifications

This page describes the profile elements available in Karnak for modifying DICOM image data to remove identifying information.

Overview

Karnak provides two main approaches to protect patient identity in DICOM images:

1. Defacing: Automated removal of facial features from CT images
2. Pixel Data Cleaning: User-defined masks to remove burned-in annotations and identifying information

Both methods ensure that visual identifying information is removed from images while preserving the diagnostic value of the data.

Defacing

Defacing automatically removes facial features from CT images to protect patient identity.

Supported Images

This profile can only be applied to images with Axial orientation in the following SOP Classes:

• 1.2.840.10008.5.1.4.1.1.2 - CT Image Storage
• 1.2.840.10008.5.1.4.1.1.2.1 - Enhanced CT Image Storage

Configuration

This profile element requires the following parameters:

Pixel Data Cleaning

Pixel data cleaning applies user-defined masks to DICOM images to remove identifying information burned into the pixels, such as patient or institution information.

Condition for Automatic Application

This profile is automatically applied to the following SOP Classes:

• 1.2.840.10008.5.1.4.1.1.6.1 - Ultrasound Image Storage
• 1.2.840.10008.5.1.4.1.1.7.1 - Multiframe Single Bit Secondary Capture Image Storage
• 1.2.840.10008.5.1.4.1.1.7.2 - Multiframe Grayscale Byte Secondary Capture Image Storage
• 1.2.840.10008.5.1.4.1.1.7.3 - Multiframe Grayscale Word Secondary Capture Image Storage
• 1.2.840.10008.5.1.4.1.1.7.4 - Multiframe True Color Secondary Capture Image Storage
• 1.2.840.10008.5.1.4.1.1.3.1 - Ultrasound Multiframe Image Storage
• 1.2.840.10008.5.1.4.1.1.77.1.1 - VL Endoscopic Image Storage

Or if the tag Burned In Annotation (0028,0301) is set to "YES"

Configuration

This profile element requires the following parameters:

Using Conditions

The condition parameter allows you to apply cleaning selectively. For example, to exclude images from a specific machine that does not add burned-in annotations, you can use the following configuration:

profileElements:
  - name: "Clean pixel data"
    codename: "clean.pixel.data"
    condition: "!tagValueContains(#Tag.StationName,'ICT256')"

Masks Definition

Masks define rectangular regions to be filled with a solid color, removing any identifying information in those areas.

Mask Parameters

Optional Parameters

Rectangle Definition

Each rectangle is defined by four values:

The coordinate system starts at (0, 0) in the upper-left corner of the image.

The diagram below illustrates a rectangle with parameters (25, 75, 150, 50):

Mask Selection Process

When processing a DICOM instance, Karnak selects the appropriate mask using the following algorithm:

1. Extract image attributes: Retrieve the Rows (0028,0010), Columns (0028,0011), and Station Name (0008,1010) values from the instance
2. Exact match: Search for a mask matching all three values (width, height, and station name)
3. Station match: If no exact match is found, ignore image dimensions and match only on station name
4. Default mask: If no station match is found, use the mask with stationName: "*"

Example Configuration

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"

Complete Example: Equipment-Specific Cleaning

This example demonstrates a profile that handles specific pixel data cleaning for equipment that burns patient information into the images and does not match the conditions for automatic application.

This profile below performs the following actions for images from a machine with Station Name containing “ICT256”:

1. Ensures the Burned In Annotation tag is present and set to “YES”
2. Applies pixel data cleaning with a station-specific mask
3. Applies the basic DICOM de-identification profile

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"

Conditions

Overview

A condition is an expression evaluated against a DICOM instance that returns a boolean value (true or false). Conditions are used in profiles to determine whether specific actions or transformations should be applied to DICOM elements based on the content of the instance.

Quick Reference

Constants

To improve readability and reduce errors, the following constants are available:

• #Tag - Retrieves DICOM tag identifiers by their standard names

  • Example: #Tag.PatientBirthDate → 0010,0030
  • Example: #Tag.StudyDescription → 0008,1030
  • Example: #Tag.Modality → 0008,0060

• #VR - Retrieves DICOM Value Representation types

  • Example: #VR.LO → Long String
  • Example: #VR.DA → Date
  • Example: #VR.PN → Person Name

Using these constants is recommended over hardcoded tag values to make profiles more maintainable and self-documenting.

Available Functions

All utility functions are detailed below with their parameters, return types, and usage examples.

Utility functions are available to define the conditions and are detailed below.

tagValueIsPresent

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

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

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

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

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")

Combining Conditions

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")

How does de-identification work?

This page provides technical details about how Karnak performs DICOM de-identification, including the algorithms used for UID generation, date shifting, and pseudonymization.

Overview

Karnak is a gateway that receives DICOM files and forwards them to one or multiple destinations using DICOM or DICOMWeb protocols. Each destination can be linked to a project that defines the de-identification method and a secret used to generate deterministic values.

Basic Profile

The Basic Profile for de-identifying DICOM objects is provided by the DICOM standard. This profile defines an exhaustive list of DICOM tags and their related actions for proper de-identification.

De-identification Actions

Five different actions are defined in the DICOM standard:

Multiple Actions for IOD Conformance

The DICOM 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 destructive actions like REMOVE won’t be applied on Type 1 or Type 2 attributes.

Combined actions:

Action Selection:

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.

Examples of action resolution:

• Z/D, X/D, X/Z/D → apply action D
• X/Z → apply action Z
• X/Z/U, X/Z/U* → apply action U

Action D: Replace with Dummy Value

The action D replaces the tag value with a dummy one that is consistent with the Value Representation (VR) of the tag.

Default Values by VR

Karnak uses these default values based on the VR when no specific dummy value is defined:

Date Generation

For date and time VRs (AS, DA, DT, TM), the shiftRange() function generates a random value within configurable limits:

• Default maximum days: 365
• Default maximum seconds: 86400

Action U: Generate a New UID

For each U action, Karnak hashes the input value using a one-way function to ensure it’s not possible to revert to the original UID. The function hashes the input UID and generates a new deterministic UID from the result.

Context and Project Secrets

A DICOM study may be de-identified multiple times using different methods. Karnak ensures deterministic UID generation to maintain data quality and usability.

Requirements:

1. A project must be created and associated with the destination
2. The project defines a de-identification method and a secret
3. The project’s secret is used as the key for the HMAC algorithm

Project Secret Format

Users can upload their own secret, but it must be exactly 16 bytes long in hexadecimal format.

Hash Function

The algorithm used is “Message Authentication Code” (MAC). Karnak uses MAC as a one-way function rather than for message authentication.

According to the Java Mac class documentation:

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.

Karnak’s HMAC Configuration:

• Hash function: SHA256
• Secret key: Project’s secret (16 bytes)

UID Generation Process

Karnak generates a new DICOM UID that starts with the OID root "2.25" followed by a decimal representation of a UUID derived from the HMAC hash.

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. See How do you create an OID?

UUID Generation Algorithm

The generated UUID uses the first 16 bytes (128 bits) from the hash value as a UUID type 4 with variant 1.

Pseudocode to ensure correct UUID type and variant:

// Version
uuid[6] &= 0x0F
uuid[6] |= 0x40

// Variant
uuid[8] &= 0x3F
uuid[8] != 0x80

Final UID format:

uuid = “2.25.” + HashedValue[0:16].toPositiveDecimal()

Shift Date: Generate a Random Date

Karnak implements randomized date shifting that is consistent per patient and project, ensuring data consistency across all instances for the same patient.

Algorithm

The random shift uses the HMAC function (defined above) with a configurable range of days or seconds.

Default values:

• Minimum: 0 (if not specified)
• Maximum: User-defined

Process:

1. The Patient ID is hashed using the project’s secret
2. The hash is converted to a numeric value within the specified range
3. The same shift is applied to all date fields for that patient

Pseudocode:

scaleHash(PatientID, scaledMin, scaledMax):
    patientHashed = hmac.hash(PatientID)
    scale = scaledMax - scaledMin

    shift = (patientHashed[0:6].toPositiveDecimal() * scale) + scaledMin

Pseudonymization

This section explains how Karnak handles Patient ID generation to prevent data leakage across different de-identification methods.

The Problem

A patient participating in multiple research projects may encounter different de-identification methods. Most patient identifying information is contained in the Patient Module.

Risk scenario:

If the same pseudonym is used across projects with different de-identification profiles, data can be leaked when studies are reconciled.

Example: Data Leakage Risk

In this example, a patient’s study falls within the scope of two different projects:

• Project 1: Removes the patient birthdate
• Project 2: Keeps the patient birthdate

If the patient pseudonym is used as patient identification and the data is reconciled, the birthdate will be leaked.

The Solution: Project-Specific Patient IDs

Karnak generates a unique Patient ID based on the pseudonym and project-specific characteristics. This prevents reconciliation across projects and eliminates data leakage.

PatientID Generation

The de-identified Patient ID is generated as follows:

1. The patient’s pseudonym is retrieved from an external service or mapping table
2. The pseudonym is hashed using the HMAC function and the project’s secret
3. The Patient ID is set to the first 16 bytes of the hashed pseudonym (in hexadecimal format)

Patient Name:

The pseudonym is used as the Patient’s Name if no other action has been defined during de-identification.

Attributes Added by Karnak

Karnak automatically sets certain attributes during de-identification to maintain compliance and traceability.

SOP Common Module

The following attributes are set in the SOP Common Module:

Patient Module

The following attributes are set in the Patient Module:

De-identification Method Format

Profile element codenames are concatenated and separated by -.

Example:

A profile composed of:

• action.on.specific.tags
• basic.dicom.profile

Will appear as: action.on.specific.tags-basic.dicom.profile

Clinical Trial Subject Module

The following attributes are set in the Clinical Trial Subject Module: