The CTP DICOM Anonymizer

This article describes how to configure the DICOM anonymizer used in the ClinicalTrialProcessor (CTP) application. The intended audience for this information is clinical trial coordinators at principal investigator sites.

Important note: The CTP DICOM anonymizer is different from the anonymizer that is included in the MIRC site and FieldCenter applications. Specifically:

All the functions which use remapping tables have been replaced with ones which use hashing.

Some functions have been removed and replaced with others which are faster.

For information about how to include the DICOM Anonymizer in a clinical trial pipeline, see MIRC Clinical Trial Processor.

1 Accessing the CTP Anonymizer Configurator

The ClinicalTrialProcessor application includes a webserver which is normally configured to listen on the standard port used by most servers (80). Accessing the server with a browser displays a home page containing buttons which link to servlets providing status and configuration information. The DICOM Anonymizer Configurator button displays a page listing all the anonymizers which are currently configured in the application, with their pipeline and stage names and a link pointing to the anonymizer script file. Clicking the link to a script file displays a page containing a table of all the DICOM elements, with Select checkboxes and Replacement text fields. At the bottom of the page is a button which saves any changes that have been made on the page.

2 Modifying DICOM Elements

The anonymizer has a simple scripting language. Each DICOM element can have its own replacement script containing contents and instructions for what to do with the element when it is processed.

To cause the anonymizer to take direct action on an element when a DICOM object is received, place a check in the Select checkbox for the element. Elements that are unchecked are left intact unless they qualify for global action as described later.

To replace the contents of an element with new static text, enter the text in the Replacement text field for the element.

To remove an element from the DICOM object, use the remove( ) function described below.

To insert an empty element or replace the contents of an element with an empty (zero-length) string, use the empty( ) function described below.

Leading and trailing blanks in all Replacement fields are removed before processing.

In the functions described below, wherever an ElementName is required, the keyword this may be used to indicate the element whose replacement value is being constructed.

2.1 Functions

The anonymizer provides several functions that can be used to modify elements. Functions are invoked by a leading @, followed by the name of the function, followed by the arguments (if any) in parentheses. Function calls can be embedded in static text in the Replacement text field. Multiple function calls can appear in one element.

To allow @ characters to appear as static text, the anonymizer recognizes the \ escape character, which forces the next character to be taken literally. To insert a \ character, it is necessary to escape it, e.g. \\.

2.1.1 @append(){script}

The append function adds the value of a script to a multi-valued element. This function is provided to allow an anonymizer to update the DeIdentificationMethod element (0012,0063) with a string describing the anonymization that was done. The script contained in braces is executed like any other script, and it can contain function calls, text, parameter references, etc. For example, an anonymizer script which removes provenance information received from a remote site might use this script for the DeIdentificationMethod element:

@append(){CTP: provenance data removed: @date() - @time()}

2.1.2 @blank(n)

The blank function returns a string of blanks of length n. This function is provided to allow a fixed-length field to be blanked. The function call @blank(0) is equivalent to @empty().

2.1.3 @contents(ElementName)

This contents function returns the contents of the DICOM element named by the argument.

2.1.4 @contents(ElementName,”regex”)

This contents function returns the contents of the DICOM element named by the argument, after removing all the characters selected by the regular expression. If you are not familiar with regular expressions, get an experienced programmer to help you. The effect of the operation is the same as the Java statement:

String.replaceAll("regex","");

2.1.5 @contents(ElementName,”regex”,”replacement”)

This contents function returns the contents of the DICOM element named by the argument, after replacing all the characters selected by the regular expression with the characters contained in the replacement string. If you are not familiar with regular expressions, get an experienced programmer to help you. The effect of the operation is the same as the Java statement:

String.replaceAll("regex","replacement");

2.1.6 @date(separator)

The date function returns the current date in the format YYYY-MM-DD where the “-“ character is replaced by the separator string. The value corresponds to the local date at the instant the anonymizer calls the function. To generate a DICOM-compliant date, use an empty separator string, e.g @date().

2.1.7 @empty( )

The empty function returns a zero-length string. This function is provided to allow differentiation between a blank Replacement text field, which causes deletion of the element from the DICOM object, and an empty element.

2.1.8 @encrypt(ElementName,”key”)

This encrypt function returns the contents of the DICOM element named by the argument, encrypting the value with the specified key. The key is a single-word string of any length.

2.1.9 @encrypt(ElementName,@ParameterName)

This encrypt function returns the contents of the DICOM element named by the argument, encrypting the value using the value of the specified parameter as the key.

2.1.10 @hash(ElementName)

The hash function computes the MD5 hash of an element's value and returns it as a base-10 digit string.

2.1.11 @hash(ElementName,maxCharsOutput)

This version of the hash function computes the MD5 hash of an element's value and returns it as a base-10 digit string of the specified maximum length.

2.1.12 @hashname(ElementName,maxCharsOutput)

The hashname function returns a numeric string of the specified length by computing the secure hash of the identified element's text. The algorithm is:

combine all the words into one string;
remove whitespace, apostrophes, and periods;
convert to uppercase;
compute the secure hash of the resulting string;
convert the binary result to a base-10 string;
return maxCharsOutput characters from the low-order end of the string.

2.1.13 @hashname(ElementName,maxCharsOutput,maxWordsInput)

This version of the hashname function operates like @hashname(ElementName,maxCharsOutput) except that it only accepts the first maxWordsInput words in the input element. This is the preferred method for producing hashed patient names because it can be used to suppress middle names, which may be absent, present as a full name, or present as an initial. In this case, a good approach would be @hashname(PatientName,6,2).

2.1.14 @hashptid(siteID,ElementName)

The hashptid function is designed to re-identify patients, replacing their clinical PatientID field with a trial PatientID field that is generated from the old value. When the hashptid function is called, the anonymizer obtains the contents of the element identified by ElementName (typically PatientID), computes the MD5 hash of the value, and converts it to a base-10 digit string.

The hashptid function recognizes a parameter reference for the siteID, and is typically coded as:

@hashptid(@SITEID,this)

2.1.15 @hashptid(siteID,ElementName,maxCharsOutput)

This version of the hashptid function operates like @hashptid(siteID,ElementName) except that it limits the length of the output string to the specified value.

2.1.16 @hashuid(root,ElementName)

The hashuid function is designed to create replacement UIDs from existing ones. The root argument is a text string containing the UID root for the institution (for example, 1.2.840.4267.32.). The hashuid function creates a new UID by computing the MD5 hash of the existing UID, converting it to a base-10 digit string and prepending the root. If the root does not end in a period, the anonymizer appends a period.

The hashuid function recognizes a parameter reference in the root argument, and is typically coded as:

@hashuid(@UIDROOT,this)

2.1.17 @incrementdate(ElementName,incInDays)

The incrementdate function adds a constant offset to a date. The offset is specified in days in the incInDays argument. The offset can be positive or negative, with positive increments generating later dates.

The incrementdate function recognizes a parameter reference in the incInDays argument, and is typically coded as:

@incrementdate(this,@DATEINC)

2.1.18 @initials(ElementName)

The initials function returns a string of uppercase characters constructed from the contents of the named element by taking the first letter of each field in the element and then placing the first character last in the string. The purpose of this function is to generate the patient’s initials from the contents of a PatientName element which is encoded as Last^First^Middle. In this example, the @initials(PatientName) function call would return FML.

2.1.19 @keep( )

The keep function forces the element to be preserved in the DICOM object. This function is provided to make it easy to preserve elements that would otherwise be removed by a global action. This function is equivalent to @contents(this), but the keep function is preferred because it is less costly and it handles sequence elements that the contents function does not.

2.1.20 @lookup(ElementName,KeyType)

The lookup function maps values through a local lookup table. It is intended to be used for mapping values that are known to the local site. For instance, it can be used to map patient ID values to case numbers by preloading the lookup table with values matching each patient ID with the corresponding case number.

To allow for mapping multiple types of values in one anonymization step, the KeyType argument identifies the category. Its value is any text string that does not contain a colon or equals sign. It is best to use a single descriptive word or abbreviation.

The lookup table is a properties file. The format of the lookup table file is:

KeyType/value = replacement value

For example, if you are remapping patient IDs to case numbers, you might have a lookup table file that looks like:

ptid/22 = 400

ptid/23 = 401

ptid/24 = 402

ptid/25 = 403

ptid/26 = 404

ptid/27 = 405

If the Replacement field for the PatientID element is coded as @lookup(this,ptid) then a PatientID element with the value 25 will be mapped to the value 403.

2.1.21 @modifydate(ElementName,year,month,day)

The modifydate function modifies the individual fields in a date. The year, month, and day parameters replace the corresponding values in the date. If a parameter is an asterisk, the corresponding value in the original date is preserved. The modifydate function recognizes parameter references in the arguments.

For example, if the StudyDate element is coded as @modifydate(this,*,1,1), the StudyDate will be reset to the first of January, leaving the year unmodified.

2.1.22 @param(@ParameterName)

The param function returns the contents of the named parameter. Parameters are stored in the script file and can be accessed by name, allowing their contents to be defined once and used many times in various elements. These parameter names are predefined:

TRIAL
SPONSOR
SITEID
SITENAME
PREFIX
SUFFIX
UIDROOT
DATEINC
KEY

Other parameter names can be added manually by editing the script file and adding properties of the form:

param.NAME=

2.1.23 @remove( )

The remove function forces the element to be removed from the DICOM object. It is equivalent to a blank Replacement field, but it is preferred because it is more visually apparent on the Anonymizer Configurator page.

2.1.24 @require( )

This require function creates an empty element if the current element does not exist in the object.

2.1.25 @require(ElementName)

This require function creates an element if the current element does not exist in the object. The current element’s contents are set to the contents of the named element. If the named element does not exist in the object, the created element is empty.

2.1.26 @require(ElementName,”default value”)

This require function creates an element if the current element does not exist in the object. The current element’s contents are set to the contents of the named element. If the named element does not exist in the object, the created element’s contents are set to the default value.

2.1.27 @round(ElementName,groupsize)

The round function is intended for use on patient age elements to allow them to be binned into groups of groupsize size. The center of the first group is always at zero. Therefore, if the PatientAge element contains 57, the function call @round(PatientAge,10) returns 60.

2.1.28 @time(separator)

The time function returns the current 24-hour time in the format HH:MM:SS where the “:” character is replaced by the separator string. The time corresponds to the local time at the instant the anonymizer calls the function. To generate a DICOM-compliant date, use an empty separator string, e.g. @time().

2.2 Global Actions

The anonymizer supports global commands that either keep or remove entire groups or classes of groups. The format of these commands is described in the advanced sectioin below.

2.2.1 Keep group 18

Checking the “Keep group 18” box causes the anonymizer to preserve all group 18 elements. This selection overrides the “Remove unchecked elements” selection. Actions specified for checked group 18 elements take precedence over all global actions.

2.2.2 Keep group 20

Checking the “Keep group 20” box causes the anonymizer to preserve all group 20 elements. This selection overrides the “Remove unchecked elements” selection. Actions specified for checked group 20 elements take precedence over all global actions.

2.2.3 Keep group 28

Checking the “Keep group 28” box causes the anonymizer to preserve all group 28 elements. This selection overrides the “Remove unchecked elements” selection. Actions specified for checked group 28 elements take precedence over all global actions.

2.2.4 Remove private groups

Checking the “Remove private groups” box causes the anonymizer to remove all elements in odd-numbered groups. These are private groups whose contents are not specified by the DICOM standard. Because these groups often contain PHI, they are usually removed when fully de-identifying a DICOM object. If the box is not checked, elements in private groups are kept.

2.2.5 Remove unchecked elements

Checking the “Remove unchecked elements” box causes the anonymizer to remove all elements that have not been selected in the table for special handling. There are several exceptions to this action, however, where unselected elements are still preserved by default, even when removing unspecified elements:

The SOP Class UID
The SOP Instance UID
The Study Instance UID
Group 28 (the parameters describing the pixels)
Groups 60xx (overlays)

To remove the first three elements requires specific action in their scripts. Generally, those elements are re-identified using the hashuid function or simply preserved without modification

2.2.6 Remove curves

Checking the “Remove curves” box causes the anonymizer to remove all elements in 50xx groups. These are groups which contain curve data.

2.2.7 Remove overlays

Checking the “Remove overlays” box causes the anonymizer to remove all elements in 60xx groups. These are overlays and are sometimes removed when fully de-identifying an object because they can contain PHI as annotations. The notation “not recommended” is simply to discourage an administrator from removing these groups unless he knows exactly what he is doing.

2.3 Conditional Functions

The anonymizer has a limited conditional capability designed to allow it to perform different actions depending on the content of an element. The form of the conditional statement is:

@if(ElementName, condition, x) {true clause} {false clause}

where the third argument, x, is used only if the condition requires it. The third argument can be a quoted string or a parameter reference (@NAME).

Both clauses are required in the statement or the anonymizer will ignore any commands that appear in the replacement script after the true clause. Whitespace within the arguments or between the clauses is ignored.

Multiple if statements are allowed in one Replacement field, but nested if statements are not supported. Function calls are allowed within the conditional clauses.

2.3.1 @if(ElementName,exists)

The exists conditional statement executes the true clause if the named element exists in the object, no matter what its value; otherwise, it executes the false clause.

2.3.2 @if(ElementName,isblank)

The isblank conditional statement executes the true clause if the named element is missing from the object or appears with a zero length or with a non-zero length and contains only blank characters; otherwise, it executes the false clause.

2.3.3 @if(ElementName,equals,"string")

The equals conditional statement executes the true clause if the value of the named element exactly equals the specified string; otherwise, it executes the false clause. The test is not case-sensitive.

2.3.4 @if(ElementName,contains,"string")

The contains conditional statement executes the true clause if the value of the named element contains the specified string; otherwise, it executes the false clause. The test is not case-sensitive.

2.3.5 @if(ElementName,matches,"regex")

The matches conditional statement executes the true clause if the contents of the named element match the regular expression; otherwise, it executes the false clause. If you are not familiar with regular expressions and you need to use this function, get an experienced programmer to help you. This function can be used to execute very complex tests on the contents of an element.

2.3.6 @quarantine( )

The quarantine function causes the anonymizer to abort the anonymization process and place the unmodified object in the quarantine for manual processing. The quarantine function must appear in a conditional clause of an if statement, but this is not enforced programmatically. If it were to appear in script that is executed during every anonymization, it would force the quarantining of every object.

2.3.7 @skip( )

The skip function causes the anonymizer to abort the anonymization process and to allow the unmodified object to continue through the system. It is intended to be used when it is possible to detect that an object has already been anonymized, thus preventing it from being anonymized a second time. The skip function must appear in a conditional clause of an if statement, but this is not enforced programatically. If it were to appear in a script that is executed during every anonymization, it would allow PHI through the process.

2.4 Examples

2.4.1 Patient and Trial Identifiers

For an ACCORD trial, the PatientName element must contain the case number followed by a delimiter character (“^”) and the field center identifier. If the case number is stored by the modality operator in the PatientComments element and the field center identifier is CWR, the Replacement text field for the PatientName element would read:

@contents(PatientComments)^CWR

For an ACCORD trial, the OtherPatientIds element must contain the word ACCORD. The Replacement field for the OtherPatientIds element would then read:

ACCORD

For the WHIMS trial, the PatientName element must contain the patient’s initials followed by a dash, the name of the trial, another dash, and the site’s identifier, which is configured in the SITEID parameter. The Replacement field for the PatientName element would then read:

@initials(PatientName)-WHIMS-@param(@SITEID)

2.4.2 UID Remapping

To generate new UIDs for the StudyInstanceUID using the UID root 1.2.840.123.321, the Replacement field for the StudyInstanceUID element would then read:

@hashuid(1.2.840.123.321.,StudyInstanceUID)

If one were remapping UIDs as in the function call above, it would be more efficient to define the UIDROOT parameter to have the value “1.2.840.123.321.” and code the calls as:

@hashuid(@UIDROOT,StudyInstanceUID)

If all UID replacements are generated in this way, it ensures that all UIDs are mapped to the same root. If the root does not end in a period, the anonymizer appends a period, but it is good form to supply it.

2.4.3 Keeping and Removing Elements

If the Remove unspecified elements box is checked and the value of an element must be preserved, the Replacement field for the element would then read:

@keep()

If the Keep group 18 box is checked, but a specific group 18 element must be removed, the Replacement field for that element would then read:

@remove()

2.4.4 Conditionally Modifying Elements

If the InstitutionName element is to be kept if it is present and non-blank, but replaced with static text if it is missing or blank, the Replacement field for the element would read:

@if(InstitutionName,isblank){My Hospital}{@keep()}

If the StudyComments element is being used to contain a trial patient ID and the ID must have exactly seven numeric digits, and if this element is to be copied to the PatientID element, the Replacement field for the PatientID element would read:

@contents(StudyComments)

And the Replacement field for the StudyComments element would read:

@if(StudyComments,matches,"\\d{7}.*"){@remove()}{@quarantine()}

Note that the coding of the regular expression in this case looks odd because the escape character is doubled. This is necessary because the anonymizer and the regular expression processor both use the same escape character, the backslash. Thus, to get one escape character, it must itself be escaped.

Note also that the true clause will force the StudyComments element to be deleted from the object, which would be reasonable, since its contents are being moved to the PatientID field. If other processing were desired in this situation, it could be placed in the true clause.

In this example, a better script for the PatientID element might be:

@contents(StudyComments,"\\D")

This will delete all non-numeric characters from the string used for the PatientID. Some modalities insert a newline character at the end of entry fields when the operator ends an entry with the Enter key. This script filters out those characters and anything else in the field that is not numeric. Note that the regular expression in the StudyComments script above ended with “.*”. That script will match a seven-digit string ending in a newline.

2.4.5 Conditionally Processing Files

The skip function can be used in the following way to avoid processing files that have already been processed. Suppose that the ReferringPhysicianName element is not used in the clinical trial. Its Replacement field could be coded as:

@if(ReferringPhysicianName,matches,"DONE"){@skip()}{DONE}

This will cause the anonymizer to insert the word DONE in the field on the first pass. If the object were to be processed again, the anonymizer would detect the word and skip the anonymization process.

2.4.6 Filtering Element Content

The contents(ElementName,"regex") function can be used to filter the contents of an element, selecting only a portion of its value. For example, suppose that the StudyComments element is populated by a modality with specially formatted content: a numeric code followed by other information including a user ID:

78.7812 [ADJUSTED: HE41328 - 01/02/2007 13:00:26]

The following function call would retrieve the leading code (78.7812):

@contents(StudyComments,"\\s.*")

The following function call would retrieve the user's ID (HE41328):

@contents(PatientName,"([^:]*:\\s+)|(\\s*-.*)")

3 Advanced Configuration

The anonymizer can be extended to meet specialized requirements by editing the script file. A word to the wise: a certain amount of caution should be observed when editing powerful files.

The script file is a text file that can be edited with any good text editor like TextPad. The content of the file is a set of properties, one per line, in the form:

key = value

Properties beginning with # are disabled. Do not remove disabled properties or the anonymizer configurator will lose knowledge of the property. The order of the lines in the file determines the order in which the anonymizer configurator presents them to the user. There are four basic kinds of keys:

Keys beginning with param. are parameters. Traditionally, parameter names are all in upper case and all the parameters are defined at the top of the file, but there is no programmatic requirement to do so. If you want to define additional parameters for use in the DICOM element scripts, you can add them by appending the parameter name to the prefix, like this:

param.NEWPARAM = value

The = sign is required. The value is optional.

Keys beginning with set. provide replacement scripts for individual DICOM elements. Additional elements can be added. It is best to add them in sequence to make it easy to find them in the anonymizer configurator table, but there is no programmatic requirement to do so. Set keys have the form:

set.[gggg,eeee]ElementName = value

The ElementName is traditionally the name recognized by the dcm4che DICOM class library for the element, although it is the [group,element] designation that determines which element is modified by the script. When adding an element for a private group, you can pick any name you wish, but scripts cannot reference the element by name. The value is optional.

Keys beginning with keep.group immediately followed by the hex value of a DICOM group number, as in keep.group18, are global keep commands. They do not contain scripts. To provide a label for the command in the anonymizer configurator, the value of the property can be supplied, like this:

keep.group18 = Keep group 18 [recommended]

The standard dicom-anonymizer.properties file contains keep commands for groups 18, 20, and 28, and default label values for those groups are defined in the program. They may be overridden by specifying values in the script file. A typical use of this type of property is to provide a convenient way to keep a specific private group, but standard DICOM groups can be added as well.

Keys beginning with remove. are global remove commands. The anonymizer cannot be extended with remove commands.

4 Precedence

It is possible to create a set of instructions that appear to be self-contradicting, so an instruction precedence is required. The principle for defining precedence is:

A command specific to an element takes precedence over global commands.
Global keep commands take precedence over global remove commands.

Thus, if an element is part of a private group and private groups are to be removed, but the element has a script requiring it to be kept, it is kept.

If an element is not selected (e.g., unchecked) and unchecked elements are to be globally removed, but the element is part of a group to be kept, it is kept.

If an element that is part of a private group is not selected and private groups are to be globally removed, but the element’s group is to be kept, the element is kept.

There is one exception to the principle: if overlays are to be globally removed, that command takes precedence over any keep commands that have been defined for individual overlay groups.