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:
In XNAT 1.8, 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:
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).
XNAT maps entries from DICOM metadata to the XNAT concepts:
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.
Rules for extracting element values operate using three mechanisms:
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
Eg: Project:BobsProj Subject:subj001 Session:subj001_MR1
AA:TRUE
” in this field as well.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.
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:
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.
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.
Pass | Rule Type | Project | Subject | Session | Notes |
---|---|---|---|---|---|
1 | Admin / Regex | Admin defined rules | Admin defined rules | Admin defined rules |
|
2 | Composite String | 0010,4000 | 0010,4000 | 0010,4000 | Project:Project Subject:Subject Session:Session |
3 | Composite String | 0032,4000 | 0032,4000 | 0032,4000 | Project:Project Subject:Subject Session:Session |
4 | Composite String | 0010,21B0 | 0010,21B0 | 0010,21B0 | Project:Project Subject:Subject Session:Session |
5 | Single String | 0008,1030 | 0010,0010 | 0010,0020 | One string item per element mapped to one fixed XNAT concept |
6 | Single String | 0008,0050 | NA | NA | One string item per element mapped to one fixed XNAT concept |