User Guides

• 1: Getting Started
• 1.1: UQ members
• 1.2: Other AAF members
• 1.3: Non-AAF members
• 1.4: HIRF users
• 2: Logging into XNAT
• 2.1: AAF login
• 2.2: Alias tokens
• 3: Using XNAT
• 3.1: Projects
• 3.1.1: Granting Access
• 3.1.2: Request Storage
• 3.2: Subjects
• 3.3: Sessions
• 3.3.1: Scans
• 3.4: Search
• 4: Managing Data
• 4.1: Downloading Data
• 4.1.1: Zip Download
• 4.1.2: Desktop client
• 4.1.3: Download Scan
• 4.2: Viewing Images
• 4.3: Uploading Data
• 4.3.1: Web Upload
• 4.3.2: Resource uploader
• 4.3.3: Prearchive
• 4.4: Syncing Data
• 4.5: Anonymising Data
• 4.5.1: Project anonymiser
• 4.5.2: Site anonymiser
• 5: Processing Data
• 5.1: Command line tools
• 6:

1 - Getting Started

1.1 - UQ members

Signing into XNAT

Step 1

Open https://xnat.rcc.uq.edu.au

Step 2

Login in with the AAF Single sign-on button (shown below).

Follow the AAF login process for your organisation

Step 3

After the AAF sign-in, you should be redirected back to XNAT (Example below)

There will be no projects listed when signing in for the first-time, as your user account would have just been created.

Proceed to to next section for setting up an XNAT project

Creating XNAT project

For UQ users, XNAT uses UQ-RDM HPC collections for storage allocation.
For any general questions about UQ-RDM, please refer to the library guides

Step 1

Before creating an XNAT project, you’ll require a UQ-RDM HPC Collection

• HPC collections ends with -Q and a 4-digit numerical identifier (e.g. PROJ001-Q0189)
• Non-HPC collections end with -A (e.g. PROJ001-A0189) or -I (PROJ001-I0189)

To create a new UQ-RDM HPC Collection, proceed with the following

Open https://rdm.uq.edu.au/create-record and sign-in

Fill in the record as per your project details

REQUEST DATA STORAGE when complete

Move on to the next step after the RDM collection is provisioned
You should have an RDM collection name ready (e.g. PROJ001-Q0189)

Step 2

Open a ticket with RCC support

Example below (replace __________ with your details)

Step 3

The support ticket will inform you when the project is set up.

• An XNAT project will be created with the matching name (e.g. PROJ001-Q0189)
• An xnat directory will be created in the RDM collection for storing the XNAT data files
• Please do not write or modify anything under the xnat directory

XNAT Project setup typically takes around ~24 hours from ticket submission
An automated email from XNAT will be sent through when project is ready, and your user has been added

1.2 - Other AAF members

This guide is for users from Australian Universities and AAF member organisations, including:

• QUT, Griffith, CQU, JCU, USQ, USC
• CSIRO, Australian Universities
• AAF VHO accounts

Other AAF members usually require UQ AIS XNAT access for:

• Management of data acquisition from sites such as CAI, HIRF, TRI
• Collaborating on projects managed on UQ AIS XNAT

Full list of AAF members found here
For all other organisations, use the Non-AAF members guide

Signing into XNAT

Step 1

Open https://xnat.rcc.uq.edu.au

Step 2

Login in with the AAF Single sign-on button (See below).

Follow the AAF login process for your organisation

Step 3

After the AAF sign-in, you should be redirected back to XNAT (Example below)

There will be no projects listed when signing in for the first-time, as your user account would have just been created.

Accessing XNAT Project

If you are Acquiring data at HIRF, CAI or TRI

• The respective facility will organise the project creation.
• You will receive a follow up email when access has been granted
• Contact rcc-support@uq.edu.au if you have not received access within 5 working days

If you are collaborating on an existing XNAT project

• Contact the project lead to grant you access to the XNAT project

1.3 - Non-AAF members

This is for users from non-AAF member organisations, including:

• QLD Health, TRI, QIMR, QLD Xray

Non-AAF members usually require XNAT access for:

• Management of data acquisition from sites such as CAI, HIRF, TRI
• Collaborating on projects managed on UQ-RCC XNAT

XNAT uses AAF for login. QCIF/QRIScloud can provide AAF Virtual Home (VHO) accounts for non-AAF users.

Creating an AAF VHO account

Step 1

Open a ticket with RCC support to request an AAF account

Example below (replace __________ with your details)

Step 2

AAF’s VHO account will return an email regarding the VHO account registration process

Step 3

After account is provisioned, continue on to the Signing into XNAT guide

Signing into XNAT

Step 1

Open https://xnat.rcc.uq.edu.au

Step 2

Login in with the AAF Single sign-on button (See below).

Select the AAF Virtual Home option (See below) and login with your AAF VHO credentials.

Step 3

After the AAF sign-in, you should be redirected back to XNAT (Example below)

There will be no projects listed when signing in for the first-time, as your user account would have just been created.

Accessing XNAT Project

If you are Acquiring data at HIRF, CAI or TRI

• The respective facility will organise the project creation.
• You will receive a follow up email when access has been granted
• Contact rcc-support@uq.edu.au if you have not received access within 5 working days

If you are collaborating on an existing XNAT project

• Contact the project lead to grant you access to the XNAT project

1.4 - HIRF users

Data acquired at HIRF can be sent to the UQ-RCC XNAT repository

To get started, refer to the relevant guide below:

• UQ members
  • UQ Staff and Students
• Other AAF members
  • QUT, Griffith, CQU, JCU, USQ, USC, Bond
  • CSIRO, QCIF, Australian Universities
  • Full list of AAF members found here
• Non-AAF members
  • TRI, QIMR
  • QLD Health, QLD Xray, Pacific Radiology

If you have any questions, contact rcc-support@uq.edu.au or HIRFAdministration@health.qld.gov.au

2 - Logging into XNAT

AAF

If your organisation is part of the Australian Access Federation (AAF), you can use your AAF credentials to sign up. See here

For more details on the Australian Access Federation, see https://aaf.edu.au

RCC Authenticate

To use this login, you would have received an email from a UQ XNAT administrator with the login information.

2.1 - AAF login

If your organisation is part of the Australian Access Federation (AAF), you can use your AAF credentials to sign up. Follow the steps below to sign-up/login using AAF.

1. Open https://xnat.rcc.uq.edu.au
2. Login in with the AAF Single sign-on button (shown below)

This will take you to your XNAT home page.

2.2 - Alias tokens

AAF is used for logging into the XNAT website itself.

But there are a lot of tools and services that will require a connect to the XNAT server externally

These could include

• Windows or Mac desktop clients, like XNAT Desktop
• Command line tools such as xnatpy, pyxnat, xnatutils etc
• XSYNC

All of these tools and services need a way to authenticating to your XNAT account without AAF.

An alias token is a time-limited, long, randomised username and password used for authenticating from external services, without compromising your AAF account or credentials. They can be generated and revoked easily

We’ll look at how to generate them next

Generating Alias tokens

To access the alias token Click your name on the top right of the website. This will take you to your user profile management page

Then click the “Manage Alias Tokens” option

There, you’ll find the option to “Create an Alias Token”

When you create the alias token, it will appear as a new entry

Alias tokens expire 60 days after creation There will be an expiration date column.

You can have multiple alias tokens. And they can be deleted and created as needed to revoke permissions. Each one will be randomised and unique.

Lets have a look at the alias token details which you can access by clicking on the token.

The key attributes that we need are the alias and the secret The alias is your username And secret is your password

So you can use the alias and secret for any external clients requesting a username and password.

Just note, the alias and secret are effectively a temporary set of login credentials. Do not reveal the secret. It is effectively your temporary password. If you no longer require the alias token, or suspect a secret has been compromised, just delete the alias token.

3 - Using XNAT

For further information refer to the XNAT official guides on browsing data

3.1 - Projects

When you login into the home page, the list of projects that you have access to will be on the left

• All datasets have to go into Projects
• User access is controlled at the project level

3.1.1 - Granting Access

Switch to the Access tab. Use Add User or Add Users from List to select the user to add

Select role from

1. Owners
2. Members
3. Collaborators

User roles

The following table outlines the permissions given to each role.

3.1.2 - Request Storage

Use the following steps to request to request an increase in storage size and/or file count limit:

Step 1

Go to rdm.uq.edu.au, login and select your RDM collection

Step 2

Click the Request more storage button (shown below)

Step 3

Fill the form with the relevant details and submit.

E.g. For a project with 2 years of data acquisition, collecting a total of 1TB and 1 million files, the request form could look like this:

3.2 - Subjects

The Project page will have a list of Subjects If we click one of the subjects… it will take us to the subject page

The Subject will have some associated metadata and name extracted from the DICOM headers of the datasets

Editing Subjects

We can edit subject details and metadata from the actions panel on the right

For instance, if you want to rename the subject You click the button next to the Subject ID

This will pop-up the following dialog box for you enter the new subject. Click modify, and then submit for the changes to take effect.

Just note, subject renaming can take a few minutes to take effect

3.3 - Sessions

Sessions are divided into three types, based on modality information extracted from the DICOM metadata

• MR
• CT
• PET

The following is an example MR session

Editing Sessions

We can edit session details and metadata from the actions panel on the right

Here we can change some of the key properties of the sessions, such as

• Change session name
• Move sessions to other projects
• Move sessions to other subjects
• Create a new subject, and move session to that subject
• Fix invalid or blank session names

3.3.1 - Scans

The Scans themselves are listed at the bottom with the relevant series descriptions and other information If you hover over one of them, and click the highlighted view details button. This will open up a more details and an image preview window

Here we can also view View DICOM headers

And see the DICOM headers as shown on the right

3.4 - Search

You can search across Projects, Subjects or Sessions And Sessions are broken up into MR, PET and CT

For instance, we can fill a couple of fields on the MR Sessions search You don’t have to specify all the fields

And XNAT will provide a list of results.

4 - Managing Data

4.1 - Downloading Data

1. Navigate to Scan or Session (See guide on browsing data)
2. Select Download from controls on top right.
3. Use the following settings for downloading dataset as zip

For further information refer to the XNAT official guide on downloading data

4.1.1 - Zip Download

The Project, Subject and Sessions page has the option to Download Images from the right hand side menu

Select Option 2: ZIP download

Filter out the Session and scans from the first two columns and select Submit

4.1.2 - Desktop client

The XNAT Desktop client is maintained by the XNAT development team. For information see the link below.

XNAT Desktop client

https://www.xnat.org/download/desktop-client/

Install client

Download and install the client for you operating system

Download images

The Project, Subject and Sessions page has the option to Download Images from the right hand side menu

Select Option 1: Download via Desktop Client

Click Download Via App

Select a local destination folder

Download should start, and progress can be monitored

4.1.3 - Download Scan

Induvidual scans can be downloaded from the Sessions page

Multiple scans can be selected and downloaded using Bulk Actions

4.2 - Viewing Images

XNAT OHIF Viewer

AIS XNAT instances come with the XNAT OHIF Image viewer Which is a plugin developed by the Institute for Cancer Research in London

Just note, if your publication uses the OHIF viewer, they have an article for citation. This information is all available at the link below

Documentation

https://wiki.xnat.org/documentation/xnat-ohif-viewer

Using the XNAT OHIF Viewer

https://wiki.xnat.org/documentation/xnat-ohif-viewer/using-the-xnat-ohif-viewer-122978515.html

Opening images in OHIF viewer

You can access the viewer from Session page

Just click View Image on the actions panel

This will take you to the OHIF Viewer

4.3 - Uploading Data

1. Web Upload (Compressed image uploader)
2. XNAT data client
3. CTP

For further information refer to the image session upload methods in XNAT

4.3.1 - Web Upload

Uploading DICOM datasets

1. De-identify DICOM on scanner or upload pc
2. Zip DICOM files into a zip file
3. Login to XNAT (see Login to XNAT)
4. From the top panel, select Upload → Images → Compressed Uploader

5. Specify the following options:
   • Project
   • Destination: Select Prearchive
   • Choose file to select zipped file with DICOMs

6. Click Begin Upload Wait for:
   • Upload percent bar to finish (**percent bar may not appear for small datasets)
   • Background processes panel to appear on bottom right
   • Green tick on under Upload extraction/review for archival

In case of Background process errors, expand panel using double arrows on bottom right for more details

For further information refer to the XNAT official guide on using the compressed image uploader

4.3.2 - Resource uploader

This is to create a web upload form for repeated uploads of any data type.

Navigate to Project → Manage → Project Resource Settings → Start

Select Image Sessions. Enter the following required fields

• Title: e.g. Rawdata
• Resource Folder: e.g. RAW
• Extract compressed files by default

Select Add when complete

To upload file(s) using the resource uploader, Upload Additional Files from the Sessions page

4.3.3 - Prearchive

If a dataset has not arrived into your XNAT project, the prearchive would be the place to check

This usually happens when:

• a DICOM dataset matching an existing session gets resent
• a part of a session gets uploaded separately

Accessing the prearchive

Go to Upload on the top menu, and Go to prearchive

The following is an example of a session that is in conflict. We can select the session and choose Details.

Here we can download the session, or individual scans. And review the datasets

• Choose Archive if you want the dataset merged into the existing one on the archive,
• choose Modify and Archive if any details need to be changed before archiving, or if you don’t want this dataset to merge with the existing one

4.4 - Syncing Data

The UQ-RCC XNAT may be able to sync datasets to other XNATs in Australia.

To see if your project is able to be synced, send a ticket to RCC support (rcc-support@uq.edu.au)

They will need the details of the XNAT that you wish to share data with.

4.5 - Anonymising Data

4.5.1 - Project anonymiser

The Project level anonymiser uses a scripting syntax called DicomEdit to modify, reassign or blank DICOM tags. You can actually use this to create automated workflow for renaming DICOM metadata on datasets

Dicomedit

https://wiki.xnat.org/xnat-tools/dicomedit/dicomedit-6-3-language-reference

version "6.1"
project != "Unassigned" ? (0008,1030) := project
(0010,0010) := subject
(0010,0020) := session

The example in this screenshot basically replicates the behaviour in the HIRF onsite anonymiser for remapping the ReferringPhysicianName, PatientName and PatientID

You can use DICOMedit to enforce a particular naming and tagging scheme across your entire project this way.

Anonymising existing sesssions

The Project level anonymiser works best for new sessions, as it runs when the dataset is being ingested into the XNAT archive, or when sessions are renamed. By default, it does not anonymise sessions that are sitting in the archive already.

If you need to trigger your anonymisation on an existing session

• Edit a session name. Modify
• Then edit it back to its original name

This will trigger the anonymisation script.

4.5.2 - Site anonymiser

HIRF and CAI data are anonymised on-site by default with the following protocols

Modified Tags

Blanked Tags

5 - Processing Data

5.1 - Command line tools

XnatUtils

https://github.com/Australian-Imaging-Service/xnatutils

Install xnatutils using

pip3 install xnatutils

Authenticating using .netrc

1. Create an alias token. Or use an existing alias token
2. Create a .netrc file in your home directory with the following details

machine https://xnat.rcc.uq.edu.au
user <your-alias-token>
password <your-alias-secret>

xnatpy

https://xnat.readthedocs.io/en/latest/

Pyxnat

https://pyxnat.github.io/pyxnat

6 -

Example

Example