XNAT Data Management

Working With XNAT

Advanced Topics

[Edit Nav]

Data Management in XNAT

Imaging data within XNAT are always associated with a specific subject. To add imaging data and run processing pipelines on it, you will need to create subjects, and possibly the image sessions themselves.

1. Adding subjects

Most experiment data in XNAT is associated directly with a subject. In turn, a subject can have multiple experiments. Subject information can be as brief and simple as an identifier. Or, it can contain in-depth demographic information. Either way, creating a subject is required to add imaging data (as well as subject assessment data).

There are multiple ways to store subjects in XNAT; Create Subject Forms in the website, StoreXML, Upload Spreadsheet, or REST.

Web Interface

Within the website there are two interfaces for creating subjects; Create Subject Page and Image Archive page. The most common mechanism for adding subjects is the Create Subject page. This same interface can be used for creating new subjects or editing existing ones.
The standard XNAT structure allows for each subject to have an identifying string for each project it is a part of. When adding (or editing) the subject you will supply this project-based ID. Behind the scenes every subject will be given a unique ID by XNAT (based on the project it belongs to).

Next, the create/edit form contains entry boxes for all of the variables which have been selected for this subject. This will include the default demographic fields (DOB, Gender, etc), as well as any custom variables you defined through the Custom Variables interface.

As a quick entry point, XNAT allows users to insert the subjects with the image archiving sequence. An interface similar to the one above is included in the archiving page.


Users also have the option of creating an xml document for each subject in their project, and directly storing that document into the application. This can be done through the web interface (Upload XML) or through a command line tool (which uses web services to store the xml). This is especially hellpful for users who are converting from another xml structure, or generating subjects in another programmatic way.

Upload Spreadsheet

The most common way to upload large numbers of subjects is the Upload Spreadsheet feature. This feature allows users to create spreadsheets contain information about each subject (based on a generated template). The subject can then upload that spreadsheet through the web interface. This process allows users to get large projects into XNAT quickly.

Subject Review

Once subjects have been uploaded using one of the mechanisms above, the details about those subjects is easy to review. First, the user can quickly see a summary of information through the subject listing on the Project Report. Then, by clicking on individual subjects, users can review indepth information about the subject on the subject report.
The subject report can be used to navigate a subject’s experiments, add new experiments, and retrieve XML documents. It displays all of the information defined in the project’s variable sets for the subject datatype.

2. Adding imaging data

The most common purpose for XNAT usage is to store imaging data. The list of imaging types which XNAT supports is continually expanding. Currently DICOM, Analyze, ECAT, IMA, and NRD are supported in varying degrees. XNAT supports several modalities, including MRI, CT, and PET.

The method for storing imaging data into XNAT varies according to the usage of XNAT. Some laboratories use XNAT to continually manage on going studies. Other XNAT installations are used to manage completed studies. Depending on their usage, some users upload data directly from image scanners (via a DICOM Send). Other users, upload all of the project data at once, programmatically.

Data is not moved into XNAT’s permanent archive space until its assignment to a project and subject are complete. For this reason, some of the upload methods will move data into a pre-archive space. Users can populate the missing data, and initiate a process to transfer the data to the archive.

HTTP Upload

The easiest method for uploading imaging data is via the Upload Images form in the website.
Using this method, users zip up (or tar.gz) their data and submit it directly through the HTML form. This process supports DICOM, ECAT, and some IMA. The data will be uploaded, extracted, reviewed, and moved into the appropriate project pre-archive space. From this location, users can match the data to pre-created imaging sessions, subjects and projects.

This method works well for users who are uploading a limited amount of data or for testing purposes. When uploading data in bulk, the other methods should be reviewed.

Web Services

Another common way to upload imaging data to XNAT is via Web Services. This is particularly useful to users who are storing data programmaticaly. Often web services are used in a processing workflow. The data will be downloaded from XNAT via a web service (ArcGet) and then the processing results will be uploaded back to XNAT (as assessments or reconstructions) via the RESTful web service.

The RESTful API gives users many options for uploading data. Review the REST documentation for more info.


XNAT can be directly connected to your Image Scanner via a custom XNAT-compliant DICOM Server. This DICOM Server allows users to submit data via a DICOM C-STORE operation, from the scanner or from a desktop application like DICOM Browser.

DICOM Browser is a powerful tool for anonymizing image data and uploading it to an XNAT installation.

For more information review the information on www.xnat.org about DICOM Server and DICOM Browser.

3. Managing Data with the Prearchive (XNAT 1.5)

New in XNAT 1.5 is a refined ability to manage uploaded data in the Prearchive. Full documentation here.

4. Data Access

Once you have data stored in an XNAT installation, there are several ways to retrieve it. The most common method for retrieving data is via HTTP download. However, the web service options may be more in keeping with programmatic needs.

HTTP Download

The easiest way to download imaging data is via the forms within XNAT. There are three routes for downloading data. All three routes will direct you to the Image Download Interface.
The image download interface can be reached from the project report (Download Images Link), a search result page for imaging session types (Download in the drop down list), or from an individual imaging session’s report page (Download link).

The image download interface takes a list of imaging sessions and allows users to select which data to download. It then provides two download mechanisms: Direct Download (Applet) or Catalog XML.

The Direct Download uses a secured Java Applet to retrieve the files individually over HTTP. After approving the applet and selecting a download destination directory, the applet will loop through all of the requested files.

The Catalog XML allows you to determine your own download mechanism. The Catalog XML is an XNAT structure for referencing files on the XNAT server. Using a combination of sub-catalogs and direct image links, users obtain direct links to each file in the requested set. It is up to the user to write a script or program another tool to loop through these links and download the files.

Web Services

Often the need to download imaging data results from a desire to process that data in one manner or another. Doing this often happens offline, and thus can’t rely on the web forms to facilitate data download. To support this need, we’ve built a web service tool which can download data directly from an XNAT site.
The most common script for downloading data is called ArcGet. ArcGet uses a host, username/password, and imaging session id to retrieve data from an application. ArcGet supports a number of parameters which help to streamline exactly which files are downloaded.
For more information, review the web service tools section at XNAT Web Services API or download the tools at www.xnat.org.

4. Workflows / Pipelines

XNAT supports the configuration of complex workflow pipelines. Administrators can describe their workflow process in XML and load the process into XNAT to be executed from the imaging session reports or search results.

A custom pipeline engine has been built to support the management of the workflow process. This engine can be configured to run on multiple operating systems and works seamlessly with XNAT. Several pipelines are available to run on your custom XNAT, including the ‘Transfer’ process which moves files from the pre-archive to the archive and the ‘WebBasedQCImageCreator’ which generates snapshots for your raw data.

For more information, review the Pipeline Engine section here