Getting started

This tutorial is intended as an introduction on how to work with XNAT and pyxnat. Reading the XNAT documentation, especially on the pages on the REST Web Services, can be a huge help to deeper understand XNAT and consequently pyxnat design decisions.

Prerequisites

Before starting, make sure that you have the pyxnat distribution installed. In the Python shell, the following should run without raising an exception:

>>> import pyxnat

This tutorial also assumes that you have access to an XNAT instance. You may also use XNAT Central, which is a public instance managed by the XNAT team and updated on a regular basis.

Setting up a connection

The first step when working with pyxnat is to connect to an XNAT instance with Interface. For this, you will need valid credentials. Make sure you have them or request them through the web interface of the targeted host.

>>> from pyxnat import Interface
>>> central = Interface(server="https://central.xnat.org",
...                     user='my_login',
...               password='my_pass')

Warning

Depending on the server configuration, you may have to include the port in the server URL, as well as the name of the XNAT tomcat application. You might end up with something like: http://server_ip:port/xnat

Alternative connections

If at least one of server, user and password arguments is missing, the user will be prompted for it (them). In this mode, a connection to the server will be attempted at the object creation and will raise an exception if something is wrong.

>>> central = Interface(server="https://central.xnat.org")
    User:my_login
    Password:

There are two types of configuration files that pyxnat uses. The first one is used with the config parameter.

>>> central = Interface(config='central.cfg')

The easiest way to create this configuration file is to use the save_config() method on an existing interface.

>>> central.save_config('central.cfg')

The second one is the XNAT format config file, which is placed at a default location (i.e. ~/.xnatPass in Linux). It is used without passing any argument to the Interface object. It is formatted as follows and supports multiple accounts and servers, the active one being the one selected by a + sign:

+loginone@http://central.xnat.org=password
-logintwo@http://central.xnat.org=password
-logintwo@http://localhost=password

>>> central = Interface()

Note

If Interface is used without any parameter and any configuration file at default location, user will be prompted for server, user and password.

Warning

You may prefer not to have your password either displayed onscreen or embedded in your programs. Two alternatives for interactive sessions and scripts: if you omit any of these three required parameters, the call to Interface(.) will prompt for the missing ones, and will not display the password as you enter it from the keyboard. Alternately, you can prompt for the password in the same way by using Python’s getpass.getpass(.) method, some variations of which are demonstrated in examples below.

You can save an entire configuration to a file and then load it later. Note that the configuration file contains the password, so be sure only to save this file in an access-protected location.

Traversing the database

Traversing the database requires basic knowledge of XNAT data model. This information is available in the structure() method of the inspect sub-interface, which prints the hierarchical organization of the data and helps constructing valid paths for accessing the data. The select sub-interface allows for data selection and basic filtering through Python objects or paths, more akin to native REST calls.

Simple requests:

>>> central.select.projects().get()
[..., 'CENTRAL_OASIS_CS', 'CENTRAL_OASIS_LONG', ...]
>>> central.select('/projects').get()
[..., 'CENTRAL_OASIS_CS', 'CENTRAL_OASIS_LONG', ...]

Nested requests:

>>> central.select.projects().subjects().get()
>>> central.select('/projects/*/subjects').get()
>>> central.select('/projects/subjects').get()
>>> central.select('//subjects').get()
['IMAGEN_000000001274', 'IMAGEN_000000075717', ...,'IMAGEN_000099954902']

Filtered requests:

>>> central.select.projects('*OASIS_CS*').get()
>>> central.select('/projects/*OASIS_CS*').get()
['CENTRAL_OASIS_CS']

>>> central.select.project('IMAGEN').subjects('*55*42*').get()
>>> central.select('/projects/IMAGEN/subjects/*55*42*').get()
['IMAGEN_000055203542', 'IMAGEN_000055982442', 'IMAGEN_000097555742']

Operating the database

Python resource Objects that are retrieved from the select interface support a range of operations to interact and insert data in XNAT. EObject objects support operations for creation, deletion and existence checking.

>>> subject.insert()
>>> subject.exists()
True
>>> subject.delete()
>>> subject.exists()
False

Working with Files

XNAT was built to store images which means it can handle files. Files resources in pyxnat are just EObject objects with a few additional methods to upload and download the data.

>>> file.get()
'<cachedir>/hash_of_file_uri.extension'
>>> file.get('/tmp/image.nii')
'/tmp/image.nii'
>>> file.put('/tmp/modified_image.nii')