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 three 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
Modality Map: Allows more complex treatment of scan series importing based on various DICOM criteria

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

Writing a Modality Map

The syntax for a modality map uses JavaScript to perform more advanced checks, and each filter is defined as a key:value where the key is a specific type of operation to perform and the value is the JavaScript boolean expression to test. Just as in a whitelist or black list, each filter must be written on its own line in the editor.

Valid Keys

"exclude": Excludes the scan series if the condition is met
"MR": Classify the scan series modality as xnat:mrScanData if the condition is met
"PT": Classify the scan series modality as xnat:ptScanData if the condition is met

Other modalities such as CT, CR, and any other image scan modalities installed in your XNAT can also be used as keys.

Checking Against DICOM Fields

The default field used in series whitelist or blacklist filters is (0008,103E) Series Description. A modality map Javascript expression can check any other field by including the field name (without whitespace) between a set of "#" characters.

Example

CODE

exclude: /^yes$/i.test('#BurnedInAnnotation#')
PT: '#Modality#' == 'PT' || ('#Modality#' == 'MR' && '#SeriesDescription#' == 'PET Data')
MR: '#Modality#' != 'PT' && !('#Modality#' == 'MR' && '#SeriesDescription#' == 'PET Data')

That should:

Exclude series where BurnedInAnnotation has the value yes
Create an xnat:ptScanData when Modality is PT or Modality is MR and SeriesDescription is PET Data
Create an xnat:mrScanData when Modality is not PT and Modality is not MR and SeriesDescription is PET Data