Uploading Image Sessions
Install the DXM Settings plugin for access to more project-specific upload settings, including date verification and default labeling schemes
With an authenticated XNAT connection, you can select image sessions to upload. Click "Upload Files" on the home screen or the menu to get started.
Selecting a Project
The Desktop Client will display a list of projects that you have permission to upload image session files to. This permission is given to project owners and members, and potentially to other custom roles. If you need to upload to a project but do not see that project in this listing, contact that project owner or request access to that project through the XNAT UI.
Once you select a project, the Desktop Client will query XNAT to retrieve a set of settings that affect upload performance and behavior. These settings include:
| Setting | Description | How to Change This Setting |
|---|---|---|
| Anonymization scripts (Site wide & Project) | If these scripts exist (as indicated by a checkmark icon), then DicomEdit anonymization will run on your data during the upload process. However, unlike other upload methods, the XNAT Desktop Client will run the anonymization in your client before sending data to XNAT. Note: It's typical for an XNAT to have either site-wide or project-specific anonymization, but not both. Running multiple anon scripts on incoming data can yield unexpected results. | |
| Allow Subject Creation (Site wide & Project) | If set to false either at the site-wide or project level, subjects must be registered in your XNAT project before any uploaded image sessions can be archived for them. You will not be able to create a new subject during the upload process. | Site: Legacy XNAT Site Configuration API Site-wide API: PUT - /data/config/applet/allow-create-subject Project: Setting Project Defaults for Desktop Client Behavior |
| Series Import Filter (Site wide & Project) | If these filters have been defined, XNAT will only allow image scan series that either (A) match a defined whitelist, or (B) are not included in a defined blacklist. Scan series that have been filtered out will simply be rejected. They will not be visible in the Prearchive or anywhere else in your XNAT system. | |
| Upload Destination | This is a project-specific preference determining whether your uploaded sessions will be held in the Prearchive awaiting a manual archiving process. You can also set a preference for how merging newly uploaded data with existing scans will be handled. | |
| Date Verification Required | This is a security/convenience setting, where a project owner can require that the uploading user correctly enters the date of the image session. It is designed to discourage the uploading of data to the wrong project. | |
| Allow Bulk Uploading | This is a security/convenience setting, where a project owner can require image sessions to be uploaded singly, rather than in bulk. |
Selecting Image Session Data
After selecting a project and subject to upload to, you will be prompted to select a folder on your desktop that contains one or more DICOM image sessions. Select the folder that has your image session data in it. Once your folder is selected, the Desktop Client will do a quick read of its files to determine how many image sessions have been included. Depending on your project configuration, you may be restricted to selecting a single session to upload. Otherwise, you may select some or all sessions to upload.
Restricting Uploads to a Single Session
There are two main reasons why you may be restricted to uploading one image session at a time:
- Your project explicitly prevents bulk uploading (See above)
- Your site or project uses a DICOM anonymization script that requires custom variables, which are not supported in a bulk upload workflow
Verifying the Visit Date
This step may or may not be required depending on your XNAT's configuration, or the configuration of the project you are uploading to.
You may need to enter the visit date of the image session that you are uploading, before proceeding. This is an error-prevention measure, to ensure that users don't inadvertently upload the wrong session to a given project.
(Note: selecting "I don't know the dates of these sessions" will let you proceed without this check, but you may be violating your project's recommended business processes.
Using the Bulk Upload Process
If you have multiple image sessions queued, you will be taken to the Bulk Upload Screen, which differs from the Single-session upload process in a few key ways.
- You will not be given the option to exclude scans from the upload, until you get to the pixel anonymization step.
- You will be given multiple options for auto-labeling subjects and sessions, including the option of using a CSV upload manifest for relabeling.
- Pixel anonymization for scans across multiple sessions uses a much different UI.
Using Standard Subject and Session Labeling Patterns
There are several built-in labeling patterns commonly used in XNAT projects that can be applied to subjects and sessions. Each of these methods checks your project's existing subject and session listings to ensure that duplicate experiment IDs are not chosen, though users can choose to override this via manual entry.
See: Subject and Session Labeling Schemes for Uploads
Relabeling via CSV Manifest
If you are uploading more image sessions than comfortably fit in the UI, or you have a CSV manifest that you are already working from, you may find it helpful to do your relabeling in a CSV document rather than in the Desktop Client UI. Click "Download CSV" to get a spreadsheet of the sessions you have queued for upload. You can open this in the editor of your choice, save changes, and reupload it using the "Upload CSV" link. Any changes you made in the document will be immediately reflected in the UI.
Some notes on proper use of this form:
- The only columns that can accept edits are grouped to the right: "XNAT Subject ID", "Session Label", and "PET Tracer"
- Edits to other columns will either be ignored, or may cause unusual behavior
- "PET Tracer" is only used for sessions with scans of PET modality
- If you delete any row in this document prior to uploading, the corresponding image session will be removed from the upload queue
Pixel Anonymization for Bulk Uploads
The workflow for pixel anonymization on bulk uploads differs from the single-session upload. Scans are temporarily reorganized into review groups based on their pixel dimensions and other factors that affect pixel anonymization.
See: Applying Pixel Anonymization for Bulk Uploads
Initiating the Upload Transfer
Once you start the upload, you will be taken to the transfer manager screen. You can watch the progress of the upload, or start another workflow. As long as the application is running and you have an active network connection, the upload will proceed in the background. You can check on the progress of your data transfer at any time.
Uploading A Single Image Session
Uploading a single image session is a more straightforward process than the bulk upload process, and also offers access to more functionality than the bulk upload process, including:
- Applying custom anonymization variables as specified in your project's DICOM anon script
- Selecting from a list of existing subjects in your project to upload to
- Selecting a PET Tracer from an enumerated list of tracers defined in your project
- Selecting only certain scan series to upload
- Integration with Visits and Protocols (requires the Visits and Protocols Plugin)
Select or Create a Subject
You will be provided with a list of subjects found in your selected project, and can assign this image session to one of those subjects. Or, if your project allows, you can create a new subject and upload this session to that subject. (See: Setting Project Defaults for Desktop Client Behavior)
Specifying Session Label
The Desktop Client will auto-generate a session label, based on the subject label and other variables. You can override this label if you like.
Uploading PET Sessions: Select PET Tracer
If the Desktop Client recognizes your image session as a PET session, the PET Tracer field will be added to the list of configurable inputs. You can set a list of default tracers in the Desktop Client's application settings, if you like. Click on the "Settings" gear icon in the upper right of the main navigation.
Setting Custom Values
The DICOM anonymization script specified by the XNAT site or the selected project may specify additional variables that will be included in the session's metadata. For example, the following project anonymization script, if enabled, will create a custom field in the desktop client upload UI:
(0008,1030) := my_varThese custom variables will appear above the scan selection table.
Selecting Scans to Upload
By default, all scans in the image session will be selected to upload. You can select a subset of these scans to upload if you like.
Pixel Anonymization in Single Scan Uploads
After you have selected your scans, you have the opportunity to inspect your scan images for burned-in PHI, and draw pixel anonymization templates to remove that PHI during the upload process.
See: Applying Pixel Anonymization During the Upload Process
Initiating the Upload Transfer
Once you start the upload, you will be taken to the transfer manager screen. You can watch the progress of the upload, or start another workflow. As long as the application is running and you have an active network connection, the upload will proceed in the background. You can check on the progress of your data transfer at any time.