The StoreXAR feature allows users to upload Imaging data into XNAT from the command-prompt. It uses the XNAT web service structure to connect to the server and complete the upload process.

Basic instructions

Steps for executing the StoreXAR:

  • Download the (version 1.4+).
  • Pre-store necessary meta-data (subjects if you’re storing sessions, sessions if you’re storing assessments).
  • Build the relevant xml file (see below and samples)
  • Build the expected Directory Structure.
  • Zip the directory structure into a single archive.
  • Upload each session/assessment individually (for now).
  • Create a User Session (CreateUserSession -host -u … -p …)
  • Execute the StoreXAR (using the session_id from the previous step):

    StoreXAR -host -user_session -f
  • Review the database (particularly the Download Images link on the session report) to confirm success.

Image Session Uploading

Expected Directory Structure

>>> FILES…
>>> FILES…
>>> FILES…

Project IDs

The session.xml should represent either a MRSession, PETSession or CTSession. The structure of these documents is defined in the XNAT.xsd.

There are several key attributes which must be populated properly for your session.xml to store properly. These mainly relate to the project & label tags, and the subject_ID tag. In this example I will use MRSession (but the same structure is present in PETSession and CTSession).

<MRSession project="(1)" ID="(2)" label="(3)">
  • MRSession.project::attribute=
    • This is the ID of the project which will own this data.
  • MRSession.ID::attribute=
    • This is the id which is generated by XNAT. Unless you are restoring a previously stored item, this should be blank.
  • MRSession.label::attribute=
    • This is the label which will uniquely identify this experiment within XNAT. The MRSession.label (3) must uniquely identify this experiment within all of the XNAT experiments.
  • Subject ID=
    • The value in the <xnat:subject_ID> tag of your document must match either the stored Subject ID (which XNAT generated for your project) or the project-based identifier which you supplied when you created your subject.

Resource Reference

The connection between your session.xml and the files in the XAR are crucial to having a properly stored document. All URIs should be relative from SESSION_FOLDER.

There are two complexTypes defined in the XNAT.xsd for referencing files on the file system. They each extend the xnat:abstractResource. All of the complexTypes can contain format, content, and label information. The commonly used resource extensions are:

  • xnat:imageResource
    • This is the simplest way to reference a single file from within the xml. Simply add the relative path to the file in the URI attribute.
  • xnat:resourceCatalog
    • This is the expected way to reference a collection of files. Using the cat:Catalog schema structure, users can define catalog files (placed among, or above the image data) which contain the list of files for a given resource. The xnat:resourceCatalog
      URI attribute simply points to the catalog, in the same way that the xnat:imageResource points to the image data. The URIs within the catalog should be the relative paths to the image data from the location of the catalog itself.

By convention, we try to use the resourceCatalogs wherever possible. However, when referencing a single file, this may be overkill and the individual file can be referenced directly via the xnat:imageResource.

These complexTypes can be placed at six locations in an image session xml. Each locations provides inherent information about the relation of the data to the imaging session. (Once again, I’ll use MRSession as my example, but PETSession and CTSession use the same structure).

  • MRSession/scans/scan/file[]
    • These resources are the RAW data for a session. The files themselves are expected to be located in a RAW folder within the session folder. By convention, we build a catalog on the file system for each scan.
  • MRSession/reconstructions/reconstructedImage/in/file[]
    • These are the resources which were used to generate a specific reconstructed image. They often refer directly to the catalogs defined in the scans/scan section of the xml.
  • MRSession/reconstructions/reconstructedImage/out/file[]
    • These are the resource of the actual reconstructed image files.
  • MRSession/assessors/assessor /in/file[]
    • These are the resources which were used to generate a particular assessment.
  • MRSession/assessors/assessor /out/file[]
    • These are the resources which were output by the assessment scripts.
  • MRSession/resources/resource[]
    • These are collections of data which are associated with the MRSession, but don’t fit properly into the other categories. Previously, they’ve mainly been used to define resources which were uploaded by users (Tagged-uploads). However, we see the usage of this ‘Additional Resources’ section expanding quickly.

Generally, if your data can fit into the scan, reconstruction, or ‘additional’ resources sections, that will be the easiest route to pursue. Making use of the Assessments section usually requires using a different complexType (defined by us or you) which will store meta-data about the assessment and will be treated by XNAT as data of special interest (meaning it will have its own listings and reports). Because of their specialized nature, these assessments are often uploaded separately (See the Assessment Upload section).

Assessment Upload

The ability to upload specialized assessment data is an important feature of XNAT. It works similarly to the Image Session Upload. However, the upload does not include an RAW, PROCESSED, or extra resource data.

Expected Directory Structure

>> FILES … (in any structure)

Image Session ID

The value in the <xnat:imageSession_ID> tag of your assessor document should match either the stored MRSession ID of the assessed session, or the project-based identifier which you use to refer to that MRSession.

Otherwise, follow the guidelines above in the Project IDs and Resource Reference sections, to build your xmls.