The CTP DICOM Anonymizer

IMPORTANT: THIS ARTICLE IS UNDER CONSTRUCTION.

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.

Please note that the CTP DICOM anonymizer is different from that used in the MIRC site software. Specifically:

• The calling sequences of the functions have been changed to make them consistent with the XML Anonymizer.
• 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 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.

If you want to replace the contents of an element with new static text, enter the text in the Replacement text field for the element.

If you want an element to be removed from the DICOM object, use the remove( ) function described below.

If you want 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.

1.1 Special 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. \\.

1.1.1 @contents(ElementName)

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

1.1.2 @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","");.

1.1.3 @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");.

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

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

1.1.6 @require( )

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

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

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

1.1.9 @param(@ParameterName)

The param function returns the contents of the named parameter. Parameters are stored in the dicom-anonymizer.properties 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
• UIDROOT
• BASEDATE
• PREFIX
• SUFFIX
• SITENAME
• SITEID

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

param.NAME=

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

1.1.11 @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:

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

1.1.12 @hashname(ElementName,maxCharsOutput,maxWordsInput)

This numerichash function operates like @numerichash(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).

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

The groupsize argument can also be a parameter. For example, if a parameter called AGEBINSIZE has been defined, the function call could be coded as:

@round(PatientAge,@AGEBINSIZE)

1.1.14 @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().

1.1.15 @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().

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

1.1.17 @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().

1.1.18 @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 more visually apparent on the Anonymizer Configurator page.

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

1.1.20 @hash(ElementName)

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

1.1.21 @hashuid(root,ElementName)

The hashuid function is designed to create 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).

1.1.22 @hashptid(siteID,ElementName,prefix,suffix)

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. It then prepends the prefix argument and appends the suffix argument to the numeric value.

The hashptid function recognizes parameter references in the siteID and either or both of the prefix and suffix arguments, as in:

@hashptid(@SITEID,PatientID,@PREFIX,@SUFFIX).

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

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

The ElementName argument can be replaced with the this keyword when the value to be remapped is the value of the current DICOM element.

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 named lookup-table.properties that must be located in the same directory as the dicom-anonymizer.properties file. On a MIRC site, this is Tomcat/webapps/[storage service name]/trial. The format of the lookup table file is:

     KeyType/value = remapped 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.

1.2 Global Actions

At the bottom of the Anonymizer Configurator page, the last lines in the table look like this:

Error creating thumbnail: Unable to save thumbnail to destination

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

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

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

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

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

1. The SOP Class UID
2. The SOP Instance UID
3. The Study Instance UID
4. Group 28 (the parameters describing the pixels)
5. Groups 60xx (overlays)

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

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

1.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 parameter, x, is used only if the condition requires it. 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.

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

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

1.3.3 @quarantine( )

The quarantine function causes the anonymizer to abort the anonymization process and place the unmodified object in the quarantine for manual processing. On a MIRC site, this processing must be done by the administrator or someone who has access to the MIRC site’s computer. At a site running the FieldCenter program, the program itself provides editing functions to allow the object to be manipulated and resubmitted to the anonymizer. 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.

1.3.4 @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 must appear in a conditional clause of an if statement, but this is not enforced programatically. Nevertheless, if it were to appear in a script that is executed during every anonymization, it would allow PHI through the process.

1.4 Examples

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

If the ptid function were to be used to generate the PatientID automatically in the form Pt-nnnn (e.g., with no suffix), then the Replacement text field for the PatientName element would read:

@ptid(@SITEID,PatientID,Pt-,1,4,)^CWR

If the PREFIX parameter were defined to have the value “Pt-“, the above function call could also be written as:

@ptid(@SITEID,PatientID,@PREFIX,1,4,)^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)

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

     @uid(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:

     @uid(@UIDROOT,StudyInstanceUID)

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

1.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()

1.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}.*”){}{@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.

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

1.4.6 Parsing Element Content

The contents(ElementName,"regex") function can be used to parse the contents of an element, retrieving only a portion of its value. Suppose that the StudyComments element is populated by a modality operator 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*-.*)")

2 Saving the Changes

After configuring the Select checkboxes and Replacement fields, scroll to the bottom of the window and click the Update anonymizer.properties button. The page, with any changes made, will be redisplayed. At that point, you can continue editing the page or close it.

3 Enabling the Changes

Changes to the dicom-anonymizer.properties file are not enabled until the DICOM service is started (or restarted, if it is already running). To do so, click the Start/Restart button in the DICOM Service column on the Admin page. In the FieldCenter program, changes to the anonymizer configuration go into effect immediately after clicking the Save button.

4 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 dicom-anonymizer.properties 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.1 Precedence

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

1. The command most specific to an element takes precedence over global commands.
2. 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 defining it to be kept, it is kept. This can be tricky because the DICOM class library does not enforce any rules on private groups, so you must be sure to keep group length elements if you are going to partially keep private groups.

For another example, if an element is not selected (checked) and unchecked elements are to be globally removed, but the element is part of a group to be kept, it is kept.

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