How XNAT Scans DICOM to Map to Project/Subject/Session

Change in Process Introduced in XNAT 1.8

Setting aside the mostly defunct dicom-project.rules, prior to the 1.8 release, XNAT used two general methods to scan DICOM metadata and populate Project / Subject / Session data:

• A static set of routing rules

• An administrator-configurable routing rule for setting only the project, available only with REST.

In XNAT 1.8 and above, the handling of the configurable rule has been greatly improved to allow the administrator to customize the routing rules in core XNAT without the need of writing a plugin. The improvements include:

• Configurable rules have been added for subject and session.

• The rules can all now be easily set by the administrator in the UI.

• The rules have been moved from the end of the extraction hierarchy to the start.

Existing and new users will want to review changes on this page including notes at the bottom that are more explicit about the change in behavior.

This page has also been restructured to eliminate the concept of passes through DICOM metadata and instead describes the order of extraction rules for each different XNAT concept (Project, Subject, Session).

See: XNAT Custom DICOM Routing Rules in the Admin UI

Description of Extraction Process

XNAT maps entries from DICOM metadata to the XNAT concepts:

• Project

• Subject

• Session

To support workflow and data entry practices within your institution and/or project, XNAT supports an ordered set of rules for extracting DICOM metadata values to identify project, subject and session entries in the XNAT database.  We use the term routing to mean the process of finding the proper metadata value that will be used to direct (route) incoming DICOM data to the proper project/subject/session. As you read the material below, keep in mind that XNAT uses the extraction rules to separately determine values to identify the project, subject and session. That is, the project might be determined using one of the rules described below while the subject and session are determined using different rules.

Element Extraction Rules

Rules for extracting element values operate using three mechanisms:

• Administrator Defined Rules

• Composite Entry in a DICOM Element

• Single Entry in a DICOM Element

Administrator Defined Rules: The XNAT site administrator can define routing rules as described here: XNAT Custom DICOM Routing Rules in the Admin UI. The administrator can enter a list of rules with regular expressions for any of the three items (project, subject, session). Your system might use administrator defined rules to identify the project from DICOM metadata and default to one of the other methods for determining the subject and session.

Composite Entry in a DICOM Element: XNAT has a hard coded method for extracting project, subject and session data from longer comment elements in a DICOM image.  XNAT will parse strings stored in DICOM Patient Comments (0010,4000) or Study Comments (0032,4000). These are typically free text fields that a technologist can enter at the console.

XNAT recognizes this syntax for parsing these fields:

Project:Project Subject:Subject Session:Session

For example, the following entry will create a new image session labeled “subj001_MR1” and associate it with the subject “subj001” in the project “BobsProj”: 

Project:BobsProj Subject:subj001 Session:subj001_MR1

• To force bypass of the prearchive, add “AA:TRUE” in this field as well.

• The metadata fields should be separated by whitespace (as above), commas, or semi-colons. All other content is ignored.

• The metadata values should have no spaces or special characters in them (underscores are ok).

• Project_ID should match an existing project in the XNAT host to which the images are being sent.

Single Entry in a DICOM Element: XNAT has further hard coded rules to extract single values as described below. No parsing is employed to distinguish the type of item (project, subject, session). XNAT uses an internal table of DICOM elements targeted for specific XNAT items.

Order of Scanning / Extraction

Project

When locating the proper project, XNAT will match a string from the DICOM metadata to the XNAT Project ID or any of the aliases defined for the project. In the case where DICOM metadata might match multiple projects, XNAT uses the first matching project using this order:

1. Search for Project ID or Project alias using administrator defined rules

2. Search for Project ID or Project alias using composite entry mechanism in (0010,4000) Patient Comments

3. Search for Project ID or Project alias using composite entry mechanism in (0032,4000) Study Comments

4. Search for Project ID or Project alias using composite entry mechanism in (0010,21B0) Additional Patient History

5. Search for Project ID or Project alias using single entry mechanism in (0008,1030) Study Description

6. Search for Project ID or Project alias using single entry mechanism in (0008,0050) Accession Number

7. Search for Project ID or Project alias using rules laid out in configuration file dicom-project.rules. Each line of this file contains one rule, and the first rule matching the received file will be applied, ignoring any later matching rules. Note that if any changes are made to the rules file, the webapp must be redeployed and the Tomcat server restarted.

8. Error condition: the project is not identified. This can mean either there was no candidate string in the above tags, or there was but it didn't match an existing project in XNAT.

Subject

1. Search for or define Subject label using administrator defined rules

2. Search for or define Subject label using composite entry mechanism in (0010,4000) Patient Comments

3. Search for or define Subject label using composite entry mechanism in (0032,4000) Study Comments

4. Search for or define Subject label using composite entry mechanism in (0010,21B0) Additional Patient History

5. Search for or define Subject label using single entry mechanism in (0010,0010) Patient Name

6. Error condition: the subject is not identified. This means there was no candidate string in the above tags.

Session

1. Search for or define Session label using administrator defined rules

2. Search for or define Session label using composite entry mechanism in (0010,4000) Patient Comments

3. Search for or define Session label using composite entry mechanism in (0032,4000) Study Comments

4. Search for or define Session label using composite entry mechanism in (0010,21B0) Additional Patient History

5. Search for or define Session label using single entry mechanism in (0010,0020) Patient ID

6. Error condition: the session is not identified. This means there was no candidate string in the above tags.

Error Handling / Unmatched Metadata

If XNAT has not satisfactorily matched or identified the metadata, it leaves these fields marked as invalid in the generated XML document.

If no Project was identified, the DICOM files will be placed in the “Unassigned” prearchive box.

If Project was identified, but Subject and/or Session was not, the DICOM files will be placed in the appropriate project prearchive box. However, the automatic matching tool will not be functional, and additional data entry will be required.

Practical Notes

Common Patterns

The documentation above separates the mapping of DICOM metadata by project, subject and session. Existing users of XNAT will likely be using an existing pattern where they inform their technologists to enter data using one of the schemes listed below. Previous XNAT documentation discussed passes through the DICOM metadata. You can use the table below to see common patterns in use for DICOM metadata mapping and the order in which the rules are applied.