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:
^.*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:
[(0008,103E)]
^.*Sheet.*$
^.*Scanned.*$
^.*Report.*$
STUDY ACQUIRED OUTSIDE HOSPITAL
Other equivalent formats of specifying the DICOM element to validate include:
[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:
[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
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 valueyes
- Create an
xnat:ptScanData
whenModality
isPT
orModality
isMR
andSeriesDescription
isPET Data
- Create an
xnat:mrScanData
whenModality
is not PT andModality
is notMR
andSeriesDescription
isPET Data