The MIRC DICOM Anonymizer

1 Introduction

This article describes how to configure the anonymizer on the DICOM Services contained in MIRC Storage Services. The anonymizer provides automatic modification of the header elements in DICOM objects received by the DICOM Service. Typical applications for the anonymizer are in MIRC Clinical Trial Services and File Services. The intended audience for this information is MIRC system administrators or clinical trial coordinators at field center sites.

2 DICOM Services

Each MIRC site may have one File Service and multiple Storage Services. Storage Services may be configured to be standard teaching file systems or clinical trial services. Each service (File or Storage) has its own DICOM service, and each DICOM service has its own anonymizer and anonymizer configuration, allowing for separate processing of DICOM objects for each purpose.

3 Accessing the Anonymizer Configurator for a Storage Service

The Anonymizer Configurator is part of the Storage Service’s admin service.

To access the Admin Service, go to the query page for the site, select the Storage Service in the list at the top of the query pane, and click the Admin Service button on the right side of the window.

On the Admin page, click the Update Configuration button in the DICOM Service column.

On the DICOM Service Configurator page, click the Update the Anonymizer button in the DICOM Import Service section. The result will be a page that looks like the example in Figure 1.

4 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 the element to be removed from the DICOM object, blank the Replacement text field for the element or, alternatively, 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.

Figure 1

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

4.1.1 @contents(ElementName)

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

4.1.2 @contents(ElementName,”regex”)

The 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: String.replaceAll("regex","").

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

The 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: String.replaceAll("regex","replacement").

4.1.4 @require( )

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

4.1.5 @require(ElementName)

The require function creates an element if the current element does not exist in the object. The 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.

4.1.6 @require(ElementName,”default value”)

The require function creates an element if the current element does not exist in the object. The 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.

4.1.7 @param(@ParameterName)

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

TRIAL
UIDROOT
BASEDATE
PREFIX
SUFFIX
SITENAME
SITEID

Other parameter names can be added manually by editing the anonymizer.properties file and adding properties of the form: param.NAME=

4.1.8 @initials(ElementName)

The initials function returns a string of uppercase characters constructed from the contents of the element named by the argument 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”.

4.1.9 @date(separator)

The date function returns the 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.

4.1.10 @time(separator)

The time function returns the 24-hour time in the format “HH:MM:SS” where “:” 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.

4.1.11 @empty(&mbsp;)

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.

4.1.12 @blank(n)

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

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

4.1.14 @keep(&mbsp;)

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 as described in the section 4.2. This function is equivalent to contents(ElementName), but it is easier to code because you don’t need to supply the ElementName parameter, which would change for each element.

4.1.15 @uid(root,ElementName)

The uid function is designed to create UIDs. The root argument is a text string containing the UID root for the institution (for example, “1.2.840.4267.32.”, without the quotes). The uid function checks a table to determine whether it has created a replacement UID for the value of the element before. If it has, it returns the replacement UID that it created before. If it has not, it creates a new UID by appending a sequential number to the root. It is important to make the root argument end in a period; otherwise, the last field (“32” in the example above) will be prepended to the sequential number. The uid function recognizes a parameter reference in the root argument, in the form: @uid(@UIDROOT,ElementName)

4.1.16 @ptid(ElementName,prefix,first,width,suffix)

The ptid function is designed to re-identify patients, replacing their clinical PatientID field with a trial PatientID field that is assigned automatically by the anonymizer. When the ptid function is called, the anonymizer obtains the contents of the element named by ElementName (typically PatientID) and looks it up in a table to see if a trial PatientID has been assigned to that value. If so, it returns the trial PatientID. If not, it creates a new trial PatientID from a sequential number that starts (at the beginning of the trial) with the numeric value of the “first” argument and increments for each new clinical PatientID that is encountered. If the “width” argument is larger than the number of digits in the number, the function prepends “0” characters until it has the required width. It then prepends the prefix argument and appends the suffix argument to the numeric value and stores it in its internal table opposite the clinical PatientID for future reference. The ptid function recognizes parameter references in either or both of the prefix and suffix arguments, as in: @ptid(PatientID,@PREFIX,1,4,@SUFFIX)

4.1.17 @id(ElementName)

The id function is designed to create IDs (not UIDs) that are unique to a patient and an element but not unique from patient to patient. The id function looks up the value of the element in a table that is indexed by patient ID, (group,element) designation for the named element and the value of the named element. If an entry is found, it is returned. If no entry is found, a sequential number is returned. This function is intended for use in de-identifying non-unique IDs like StudyID.

4.1.18 @accession(ElementName)

The accession function creates sequential integers for a specific element. The accession function looks up the value of the element in a table that is indexed by (group,element) for the named element and the value of the element. If an entry is found, it is returned. If no entry is found, a sequential number is returned. This function is intended for use in de-identifying unique IDs like accession numbers.

4.1.19 @offsetdate(ElementName,BaseDate)

The offsetdate function is designed to de-identify dates by replacing them with dates offset from a base date. The offsetdate function looks up the value of the element in a table that is indexed by patient ID and (group,element) for the named element. If a value is not found in the table, it stores the current value and returns the base date. If a value is found in the table, it computes the time difference between the current value and the table value and adds it to the base date. This preserves time differences while hiding absolute dates.

The offsetdate functions recognizes a parameter reference in the BaseDate argument, as in: @offsetdate(StudyDate,@BASEDATE)

4.2 Global Actions

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

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

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

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

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

4.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 uid function or simply preserved without modification

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

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

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

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

4.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 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. (If it were to appear in script that is executed during every anonymization, it would force the quarantining of every object.)

4.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. (If it were to appear in script that is executed during every anonymization, it would allow PHI through the process.)

4.4 Examples

For the 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(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(PatientID,@PREFIX,1,4,)^CWR For the 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) 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 probably be better to define the ROOT parameter to have the value “1.2.840.123.321.” and code the calls as in: @uid(@ROOT,StudyInstanceUID) This will ensure that all UIDs are mapped to the same root. Note that the root must end in a period. The anonymizer does not force a period between the root and the value automatically generated for the suffix. 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() 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.

The skip function can be used in the following way. 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 will detect the word and skip the anonymization process. Of course, if there were a referring physician named “DONE”, this method will break down, so it would be best to use a different code.

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

6 Enabling the Changes

Changes to the 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.

7 Advanced Configuration

The anonymizer can be extended to meet specialized requirements by editing the dicom-anonymizer.properties file, which drives both the anonymizer itself and the anonymizer configurator in the MIRC DICOM Service and the MIRC FieldCenter and DicomEditor programs. A word to the wise: a certain amount of caution should be observed when editing powerful files. The anonymizer.properties 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 = initial value

The = sign is required. The initial 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= initial value

The ElementName is traditionally the name recogized 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 initial 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.

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

The command most 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 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.