The aim of this document is to instruct users on strategies for storing their data in an XNAT instance.
The resources covered in this document are limited to imaging resources (raw, pre-processed and processed).
Introduction to the XNAT hierarchy
The XNAT hierarchy allows for multiple levels of data storage and organization. Imaging resources are typically referenced at the Imaging Session Level (xnat:imageSessionData) and its children.
Project + Subject - Experiments + Imaging Sessions - Scans - Reconstructions - Assessments - Resources
The Scan sub-level represents the individual acquisitions at the scanner (referred to as Series in DICOM terminology). A typical image session often has multiple (sometimes dozens) of separate scan elements. Files related to an individual scan are associated at the Scan sub-level. Such files would include the acquired data (typically DICOM) but could also include additional files (e.g. thumbnails, alternative file formats). A Subject can have multiple Experiments. Imaging Sessions are one type of Experiment. There are extensions of the Imaging Session level for each of the common image modalities (e.g. MR, PET, CT, Ultrasound). Within the Imaging Session level, a number of sub-levels are available for representing the various conceptual blocks of data associated with an imaging study. Files can be stored at each of these levels and can be grouped into collections of related content.
The Reconstruction sub-level represents files that join together data from multiple scans, for example, an image that averages across multiple runs. The reconstruction sub-level is not intended to store complicated data structures (like processing results). Rather it is intended to store simple imaging files which did not have any additional measures of note. Commonly, the files at this level will be used as inputs to further processing streams.
The Assessment sub-level represents derived data generated from processing and analysis of image data. Typically, an assessment will include various measures and generated files (e.g. images, logs, metrics, spreadsheets). Unlike the other sub-levels, there is no generic representation of an assessment which is usable out of the box on an XNAT instance. The assessments level is intended to support data which specifically needs to be customized (to match the processing results). XNAT provides a basic assessment type that includes support for associating files. Specific assessment types are derived from this basic type. The Manual QC Assessment data type is an example assessment that is provided with XNAT. Additional extensions are available in the XNAT extension repository and custom extensions can be easily created by XNAT site administrators to store custom assessment types.
The Resources sub-level represents files that don't fit into any of the above categories. These can be loose files of any format (.xls, pdf, et cetera).
Handling Custom Variables
The XNAT data model captures a large number of attributes which may contain the variables you need. If not, you can customize XNAT to capture your additional variables. There are two methods for doing this:
Method 1: Custom Schema Extensions
This is the most comprehensive method for storing additional variables. You can build a custom XML Schema which extends elements from the core XNAT model, and easily integrate it into your XNAT instance (including generated database tables, reports and edit pages). See: XNAT Developer Docs for data type development guidance, or installing data type plugins for XNAT administrators.
Method 2: Custom Variables
If your variables map one-to-one to individual data elements (like subject, MR Session, etc), then you can use the Project-based "Manage Custom Variables" feature to create new variables for those data types on the fly. These variables will be stored generically in the database and will be searchable through the web interface. This feature is especially helpful on remote XNAT servers (like XNAT Central) where you do not have the ability to create custom XNAT schema. See: Adding Custom Variables to XNAT Projects.
Where do my files go?
To determine the best location for your files, answer the following questions:
- Are my files for the same subject?
If no, then multiple XNAT subjects should be created to store your data. If yes, then a single XNAT subject should be created for your data.
- Are my files from an imaging session?
If not, then your files should not be stored as an imaging session. They may need to be stored as subject resources, project resources, or resources of a custom built experiment type.
- Are my files from the same imaging session?
If not, then you will need to store your data as multiple imaging sessions. Your data should be grouped by imaging session. If yes, then you need to determine the correct modality for your data (MR, PET, CT, etc), and the corresponding image session should be created.
- Can my resources be grouped according to specific scans?
If yes, then your files should be grouped by scan. Additionally, your files should be sub-grouped by data format. If no, then your data should be stored as reconstructions, assessments, or additional resources.
- Do my non-scan files have additional measures?
If no and they are processed versions of the scan files, then they should be stored as reconstructions. If no and they are not processed versions of the scans files, then they should be stored as additional resources. If yes, then follow the next question.
- Are your additional measures limited to a few variables which map one-to-one to the corresponding imaging sessions?
If no, then you need to use a custom schema representation to store your data as image session assessments. Or, if in site-searching of the measures is unnecessary, then your files could be stored as additional resources. If yes, then you may be able to use the project-based Custom Variables feature to store your measures (in which case your files may be stored as additional resources, reconstructions, or custom assessments).