How to Write a Series Import Filter

Series Import filters can be set at the site-wide level in the Admin UI, or on a project-by-project basis in the Manage tab of the project report page. Each instance of a series import filter can be one of these types:

Whitelist: Allows only scan series whose series descriptions match the filter
Blacklist: Allows all scan series, except those whose series descriptions match the filter

The Modality Map filter type has been deprecated as of XNAT 1.8.10 and is no longer supported.

Here is guidance on writing these import filters:

Writing a Whitelist or Blacklist

The syntax for a whitelist or blacklist filter is the same. The only difference is whether XNAT uses the filter to include or exclude content that matches the filter.

The user can define any number of filters to check, with each one on its own line. These types of series filters can be written as exact string matches, but also can be regular expressions. The regular expressions are evaluated using the Java regular expression syntax. These expressions are case-insensitive, i.e. the string "SAG LOCALIZER" will also match "Sag Localizer".

For example, you might have a blacklist that looks like this:

CODE

^.*Sheet.*$
^.*Scanned.*$
^.*Report.*$
STUDY ACQUIRED OUTSIDE HOSPITAL

Additionally, validation against other DICOM headers can be performed by specifying the header, followed by one or more lines of validations to perform. For example, the previous blacklist is equivalent to:

CODE

[(0008,103E)]
^.*Sheet.*$
^.*Scanned.*$
^.*Report.*$
STUDY ACQUIRED OUTSIDE HOSPITAL

Other equivalent formats of specifying the DICOM element to validate include:

CODE

[0008,103E]
[SeriesDescription]

It's recommended to use either of the numeric representation formats for the element as the lookup via element description may not work for elements newly introduced to the DICOM standard. In addition to validation on arbitrary standard elements, there is also some special syntax for checks not on the value of a DICOM element, but rather whether the element exists at all. For example, the series import filter below would match if the series contains (0008,1030) Study Description regardless of value or doesn't contain (0028,0301) Burned In Annotation regardless of value:

CODE

[0008,1030]
EXISTS

[0028,0301]
!EXISTS

Using Series Instance Filtering in Anonymization Scripts

As of XNAT 1.8.10 and DicomEdit 6.6, users can add instance file filtering logic directly in their anonymization script. This has the advantage of running during the session building process as well as during XSync operations.

Series Instance Filtering does not run when anonymization is performed on files already archived. This can happen when an image session is renamed or associated with another subject, and the project anonymization script is set to update the DICOM with subject or experiment label data.

Filtering instances during anonymization is accomplished with the reject script function. The reject function causes a signal to be sent to the anonymization process. The anonymization process can be configured to enable or disable reject processing. If reject-processing is enabled, the reject function causes further processing to stop immediately and the processor will respond to the reject signal. The exact nature of the response depends on the context in which the anonymization is occurring. The nominal response is for the instance to be removed from the processing flow. If reject-processing is disabled, the reject function is ignored and processing continues unaffected.

The exact response to the reject function is dependent on the anonymization processor enabling rejection and on the context in which the processor is running.

The following script fragments illustrate some typical uses for the reject function.

CODE

// do not accept secondary-capture images.
imageType := (0008,0008)
if( imageType ~ ".*SECONDARY.*") {
    reject[]
}

CODE

// whitelist these modalities.
modality := (0008,0060)
isExcludedModality := "true"
modality = "MR"? isExcludedModality := "false"
modality = "CT"? isExcludedModality := "false"
modality = "PT"? isExcludedModality := "false"
isExcludedModality = "true"? reject[]

The ability to disable the reject function allows the same script to be used in different contexts. The primary example of this is the project-wide anonymization script. It is very common to want to restrict data uploads to specific data types in the context of first uploading data to a project. The reject function is well suited to this purpose. However, other operations also trigger the application of a project-wide anonymization script. Transferring data from an existing project will trigger the project anonymization of the receiving project, for example. Disabling instance rejection in that context can prevent surprises from some existing data not transferring.

See: DicomEdit 6 Language Reference