Skip to content

Uploading data to your XNAT project§

Collaborator or Owner members of a project can add data. There are a number of different mechanisms for uploading data to XNAT project suited to different purposes:

  • XNAT Desktop Client is the best method if you are working with DICOM files and you don't need to upload many subjects at once.
  • Compressed File Uploader is a simple method of uploading multiple DICOM subjects and series contained in a single zip file, without having to install any additional software, but it requires the zip file to be correctly structured.
  • DICOM Push may be suitable if your data is stored on a DICOM system within the UCL network and are already anonymised
  • XNAT File Manager is useful for adding individual resource (non-image) files to projects and can be customised to simplify upload for your end users.
  • XNAT REST API is the most flexible method and allows for automated workflows but is typically implemented through scripting or other software which requires more technical understanding.

XNAT Desktop Client§

The XNAT Desktop client is often the best upload method if you are working with DICOM files and only need to upload a small number of subjects at any one time. XNAT Desktop Client is a software application that you install on your machine.

Connecting to the UCL XNAT Servers with XNAT Desktop Client§

  • If you haven't yet installed XNAT Desktop Client, download it from the XNAT website and run the installer
  • Launch XNAT Desktop Client on your machine
  • If you are presented with the Login in screen, select the XNAT server to log into Log in
  • If you are already logged in to the correct server, you can skip this step.
  • If you are logged into a different server, click on Welcome (your username) and click Logout
  • If you have not previously logged in, you need to select ADD NEW XNAT SERVER: User login
    • Enter the full XNAT server URL (e.g. ucl-collab-xnat.cs.ucl.ac.uk)
    • If you are using the internal server, check Allow unverified certificates. Otherwise, leave this unchecked.
    • Enter your XNAT username. For UCL users this will be your UCL Single Sign-on, but do not include @ucl.ac.uk.
  • Enter your XNAT password. For UCL users this is your current SSO password.
  • Click Login

Uploading data with XNAT Desktop Client§

Note: you must upload data one subject at a time, but you can upload multiple scans for the same subject.

  • Launch XNAT Desktop Client and log in if necessary (see above) Upload files
  • Select Upload files: Select project
  • Under Select Project:, choose the project you want to upload data to.
  • :warning: If your project does not appear, you may be logged in the wrong server, or you may not have the permissions to add data to that project
  • Under Select Subject: choose the existing subject you wish to add the data to.
  • If this data is for a new subject not currently in your project, click Create new subject, choose a subject ID, then click Add New Subject (the Research Group field is optional)
  • Click Next
  • Under Select Folder choose the folder on your machine containing the subject data.
  • Under Review Files you still see details of the scans that will be uploaded. Review Files
  • You can uncheck scans here if you do not want them to be uploaded
  • Click Next
  • If you see the Required Visual Check for Burned-in PHI dialog, you now need to visually check some of the images to see if they contains any text that might contain personal identifiable data
  • If any parts of the image contain possible PHI, use the Select Area tool to draw a box completely covering the text. XNAT will black out this region of the image before uploading the data.
  • Click Save Scan and repeat for any other scans shown in the left pane
  • Click Finish and Upload to complete.
  • The Progress Monitor will show you the current upload status Review Files
  • Click Upload Another Session to upload more data.

Compressed file uploader§

You can upload a .zip or .tar.gz file from your computer containing DICOM or ECAT files. This can include multiple series and subjects. Unlike the XNAT Desktop Client, the compressed uploader can be rum from the XNAT web interface without additional software being installed. However, the zip file needs to be structured in a very specific way to allow XNAT to create the subjects and sessions correctly. Hence, it is most useful if you can set up an automated process that creates the zip file with the correct structure.

Your data must be anonymised prior to upload. The Compressed file uploader does not anonymise data before upload.

To use the Compressed Image Uploader:

  • Compress the files into a .zip or .tar.gz file on your computer. See the XNAT Documentation for details of the zip file format.
  • Log into XNAT
  • Select the Upload dropdown and choose Images and Compressed Uploader
  • Choose your project from the Project dropdown
  • Select Archive to attempt to store data directly in your project. The Prearchive option allows you to review data before archiving into the project
  • Click Begin Upload
  • If the zip file is not correctly formatted, some of the scans may still be uploaded, but may be sent to the Prearchive instead of directly to your project. See below for how to use the prearchive.

DICOM push§

You can push data to the XNAT server from a DICOM server application (for example Horos, dch4chee or a PACS). The UCL XNAT servers only accept DICOM data pushed from within the UCL network.

To configure your DICOM PUSH application, add a DICOM location (receiver):

  • Address: hostname or IP address of the XNAT server hosting your project
  • AE Title: Usually XNAT but verify by logging into the XNAT server and selecting Upload->Images->DICOM SCP
  • Port: Usually 8104 or 104 but verify by logging into the XNAT server and selecting Upload->Images->DICOM SCP

DICOM data received will normally go to the Prearchive instead of directly to your project. See below for how to use the prearchive.

Uploading non-imaging data with the XNAT File Manager§

You can directly upload files in the XNAT web interface using the XNAT File Manager. This can be used to store any type of file in XNAT.

Uploading imaging data in this way requires additional work, as you need to create the subjects, experiments and scans manually for each dataset you wish to upload. However, it can be a useful way of attaching additional files to existing data sessions. Non-imaging data files added in this way are called Resources.

  • See Adding Or Removing Resource Files for more details of how to manually add resources.
  • If you will be regularly adding resource files to your project, you may wish to Create a Custom Resource Uploader to simplify the upload process for you or your users.
  • Alternatively you may manage resources using the XNAT API in your custom uploading code.

To upload files using the XNAT File Manager§

  • Navigate to the session, subject or project where you wish to add data files.
  • From the Actions menu, click Manage Files.
  • Note: Manage Files operates on the item you launch it from. To add files to a session, you must navigate to the session before clicking Mange Files.
  • From the File Manager, click Add Folder
  • If you are uploading source data
  • Under Level, select Scans
  • Under Item, select the scan to upload to to files to
  • For non DICOM data, Choose Resources and enter a folder name for these resource files.
  • Fill in other details if desired

Manual creation of subjects and sessions§

XNAT will typically create subjects and sessions (experiments) as part of the data upload process. You can also create these using the XNAT API, or manually on the web interface using Add Subject on the project Actions menu, or Add Experiment on Subject Actions menu, or by using New from the top toolbar. Once created, you can add scan and resource files using the XNAT File Manager (see above).

Metadata upload§

Metadata, such as subjects, sessions and their associated variables, can be changed on the XNAT interface or through the XNAT API. XNAT also provides ways of creating or modifying these in bulk, which can be useful when creating uploading processes for dealing with custom data.

  • XML upload allows you to create or modify subjects, sessions and their corresponding metadata by modifying XNAT's XML definitions.

  • CSV spreadsheet upload is a method of bulk uploading custom variables through a spreadsheet import.

XNAT REST API§

XNAT provides a comprehensive REST API which can be used to upload and download data.

Using the REST API requires some knowledge of handling REST calls and the secure use of authentication and session IDs. In particular you must not use plaintext authentication to connect to the XNAT servers as this may compromise your account.

Details of the XNAT API

  • XnatDataClient If you want to call the REST API from the command-line or a shell script, XNAT provides a convenience command-line tool XnatDataClient. You can also use standard command-line tools such as curl, or wget. You can also execute REST calls from within programming languages, although using intermediate libraries such as pyxnat are preferable if available.

  • pyXNAT and other software libraries

Software libraries such as pyxnat simplify communication with the XNAT REST API, allowing higher-level access to your project data.

DICOM Inbox§

The DICOM inbox is a method of uploading data directly from a file store accessible to the server, rather than going through the web interface. It may be useful if you are uploading a very large amount of data from a UCL or CS file store. It requires action by the MIRSG team to set up.

  • Contact MIRSG if you think the DICOM Inbox is the appropriate upload method for your project.

XNAT Desktop Upload Assistant§

The XNAT Desktop Upload Assistant is a legacy application which replaced the uploading applet provided in previous versions of XNAT. It is recommended to use the XNAT Desktop Client instead.

Using the prearchive§

XNAT will temporarily store uploaded data in the prearchive when it does not know which project or subject to attach the data to. For example, data sent by DICOM push or uploaded via the Compressed File Uploader may appear here in some circumstances. If your uploaded data has not appeared in your project, you should check the prearchive and move the data over.

To move data from the prearchive§

  • Click Upload > Go to prearchive This will show all sessions currently in the prearchive. Prearchive
  • You can use the Filters (bottom-right of panel) to narrow down the sessions that are displayed. For example, you can select your project name from the Projects: to show just sessions that have been tagged with your project. Prearchive filter by project
  • If you don't see your sessions after filtering by project, they might not be tagged with a project. Remove the project filter by clicking the X
  • In the list of sessions, put a check next to each session you want to move to your project
  • Check that the Project column shows your project name.
  • If the Project name is correct, click Archive
  • If the project name is wrong or empty, click Change Projects, select your project and click OK

Further methods for uploading data§

See Further methods for Importing Data