Revision as of 09:12, 23 May 2014 by Evast (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



XNAT provides a REST interface for data management. To make this interface more usable, the Pyxnat library can be used. This is a Python module that acts as a wrapper for the XNAT REST interface. Installation instruction for Pyxnat can be found on http://pythonhosted.org/pyxnat/installing.html. Note that Windows users should use the source code instead of the released version because of a specific bug. The prerequisets on the installation webpage should still be matched, but instead of using easy_install one should download the version on https://github.com/pyxnat/pyxnat/ (right part of website, download as zip) and execute python setup.py install in the directory of the downloaded zip using commandline/terminal. Extensive documentation and examples on the Pyxnat library can be found on their websites (see references below).


To get users started, the following block shows an example script to upload data to XNAT.

 import glob
 import os
 import pyxnat
 from pyxnat import Interface
 xnat = Interface(server='https://bigr-xnat.erasmusmc.nl', user='USER', password='PASSWORD', cachedir='CACHE')
 theProject = xnat.select.project('PROJECTNAME')
 for i in range (8, 27):
   theSubject = theProject.subject('subject'+str(i))
   if (not theSubject.exists()):
   theSession = theSubject.experiment('training'+str(i))
   if (not theSession.exists()):
   scantypes = ['BB', 'Left', 'PC', 'PCM', 'Right']
   for scantype in scantypes:
     filelist = glob.glob("subject"+str(i)+"_"+scantype+".*")
     for file in filelist:
       extension = file.split('.')[-1]
       theSession.scan(scantype).resource(extension.upper()).file(os.path.basename(file)).insert(file, format=extension)

The above script cannot be directly used. Most Pyxnat script are for a specific dataset, including this script. The user should also change the script accordingly to match it with their dataset. Also the username and password should be set for the user's account and the cachedir to a local directory on disk. The projectname should be the id of the project as shown in XNAT. These options can be changed in the top of the script. The resource upload function has two 'file' arguments. The first one is how the remote file will be named, the second one is the local file path. For the first argument, only the filename e.g. os.path.basename(...) should be given and not the complete path stored in 'file'. Otherwise, the complete path will be stored in XNAT, which is possible, but can be a nuisance when the dataset is download as it creates all the subdirectories of the complete path.

To upload assessors instead of scans, the following code can be used:

 theSession.assessor('1').out_resource('csv').file('test.csv').insert('test.csv', format='csv')

Or to upload resources:

 theSession.scan('lumen').resource('PDF').file('test.pdf').insert('test.pdf', format='PDF')

See XNAT: Datastructure for more information about the structure of the data.


To download the data, you can load the project, subject and session as above. Then download the scans to the given download directory in a for-loop:

 import pyxnat

 from pyxnat import Interface
 xnat = Interface(server='https://bigr-xnat.erasmusmc.nl', user='USER', password='PASSWORD', cachedir='CACHE')
 theProject = xnat.select.project("PROJECTNAME")
 theSubject = theProject.subject("SUBJECT")
 theSession = theSubject.experiment("SESSION")
 allscans = theSession.scans()
 for scan in allscans:
   allscans.download("DOWNLOADDIR", type='ALL', extract=True)

You can also load the project, subject and session in one line with the following example:

 import pyxnat

 from pyxnat import Interface
 xnat = Interface(server='https://bigr-xnat.erasmusmc.nl', user='USER', password='PASSWORD', cachedir='CACHE')
 allscans = xnat.select.project("PROJECTNAME").subject("SUBJECT").experiment("SESSION").scans()
 for scan in allscans:
   allscans.download("DOWNLOADDIR", type='ALL', extract=True)

Setting variables

Several variables for the subject and experiment are automaticly extracted from the DICOM tags when DICOM's are archived. This is not done for files that are uploaded via Pyxnat. It is still possible so set these variables after the upload with Pyxnat scripting. Changing variables of datasets that are not uploaded with Pyxnat e.g. webinterface, DICOM is also possible, but only after the data is moved to the archive. Below are several examples which consider the variables that are set for DICOM files.

theSubject.attrs.set('xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/age', '10')
theSubject.attrs.set('xnat:subjectData/demographics[@xsi:type=xnat:demographicData]/gender', 'Male')
theSession.attrs.set('xnat:imageSessionData/scanner', 'SIEMENS Definition AS+')
theSession.attrs.set('xnat:imageSessionData/dcmpatientname', 'John')
theSession.attrs.set('xnat:experimentData/date', '20120102')
theSession.attrs.set('xnat:experimentData/time', '10:09:12')
theSession.attrs.set('xnat:imageSessionData/acquisition_site', 'ErasmusMC')

A complete list of all possible variables that can be set can be found in the XNAT REST API. Note that the variables have to be set on different levels. For example, the age and gender (see above) have to be set for the subject, while the patient name and the acquisition site for the session. This is noted in the XNAT REST API above each list of variables.


Pyxnat website: http://pythonhosted.org/pyxnat/

Pyxnat tutorial: http://pythonhosted.org/pyxnat/starters_tutorial.html

Pyxnat source: https://github.com/pyxnat