Reference documentation

The Interface class

class pyxnat.restapi.Interface(server, user, password, datastore=None, mode='online')

Class that holds the properties to access a XNAT server.

>>> interface = Interface( server='http://central.xnat.org:8080',
                           user='login',
                           password='pwd',
                           datastore='/tmp'
                         )
project(ID)
Parameters:

ID: string :

Identifier of the resource.

projects(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

request(uri, check_id=True)
Utility method to enter a REST compliant URI and get back the relevant ResourceObject.

The ResourceObject class

All REST resources objects are derived from ResourceObject which contains the common mechanisms to read and write on the server.

class pyxnat.restapi.ResourceObject(uri, interface, check_id=True)

All REST resources objects are derived from ResourceObject which contains the common mechanisms to read and write on the server.

create(xsi_type=None)

Creates the corresponding element on the XNAT server.

Note

The xsi_type is defined in the XNAT XML Schema. It allows a generic type such as xnat:experimentData to be derived in xnat:mrSessionData and xnat:petSessionData to be given some specific attributes.

Parameters:

xsi_type: string or None :

If not None, it will affect the given schema type to the created element. If None, a default schema type is given, depending on the object type.

delete(delete_files=True)

Deletes the corresponding resource on the XNAT server.

Parameters:

delete_files: True or False :

Files attached to the resource may be kept or not on the server when the object is deleted. Defaults to True.

exists()

Test whether this object actually exists.

Returns:True or False :
id()
It depends on the resource, but some resources may be accessed through their id or through their label. The method returns the actual id of the resource.
label()
It depends on the resource, but some resources may be accessed through their id or through their label. The method returns the actual label of the resource if available. If not, it will return a valid id.
level()
Returns the level of the resource corresponding to this object. e.g. ‘project’, ‘subject’ etc...
xsi_type()

Returns the xnat_type or xsi_type``which is defined in the XNAT schema of this ``ResourceObject.

ResourceObject possible xsi types
Project xnat:projectData
Subject xnat:subjectData
Experiment xnat:mrSessionData xnat:petSessionData

The CollectionObject class

Collection of ResourceObjects.

class pyxnat.restapi.CollectionObject(resource_objects=[])

A CollectionObject provides a collection of ResourceObject.

It is mainly useful because it is iterable and enables the following behaviour:

>>> for p in interface.projects():
>>>     print p.subjects()

Specific elements in the collection can be accessed either by their ID or by their index in the corresponding list:

>>> projects = interface.projects()
>>> print projects
['A', 'B', 'C']
>>> projects[1] == projects['B']
True

The Project class

class pyxnat.restapi.Project(uri, interface, check_id=True)

Specialized ResourceObject class for projects.

subject(ID)
Parameters:

ID: string :

Identifier of the resource.

subjects(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

The Subject class

class pyxnat.restapi.Subject(uri, interface, check_id=True)

Specialized ResourceObject class for subjects.

experiment(ID)
Parameters:

ID: string :

Identifier of the resource.

experiments(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

file(ID)
Parameters:

ID: string :

Identifier of the resource.

files(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

resource(ID)
Parameters:

ID: string :

Identifier of the resource.

resources(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

The Experiment class

class pyxnat.restapi.Experiment(uri, interface, check_id=True)

Specialized ResourceObject class for experiments.

assessor(ID)
Parameters:

ID: string :

Identifier of the resource.

assessors(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

file(ID)
Parameters:

ID: string :

Identifier of the resource.

files(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

reconstruction(ID)
Parameters:

ID: string :

Identifier of the resource.

reconstructions(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

resource(ID)
Parameters:

ID: string :

Identifier of the resource.

resources(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

scan(ID)
Parameters:

ID: string :

Identifier of the resource.

scans(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

The Scan class

class pyxnat.restapi.Scan(uri, interface, check_id=True)

Specialized ResourceObject class for scans.

file(ID)
Parameters:

ID: string :

Identifier of the resource.

files(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

resource(ID)
Parameters:

ID: string :

Identifier of the resource.

resources(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

The Resource class

class pyxnat.restapi.Resource(uri, interface, check_id=True)

Specialized ResourceObject class for resources.

file(ID)
Parameters:

ID: string :

Identifier of the resource.

files(id_filter='*')
Parameters:

id_filter: string :

Filters the identifiers list according to the given pattern.

The File class

class pyxnat.restapi.File(uri, interface)

Specialized ResourceObject class for files.

content()
Returns:

The specified content for this file. :

e.g. T1, DTI, sequence preview, table :

delete()
Removes the file from the server and from the cache if necessary.
format()
Returns:

The specified format for this file. :

e.g. NIFTI, DICOM, jpeg, txt, csv :

get()

Downloads the file if it is not in the local cache.

Note

The data in the cache is kept up to date using the cache HTTP headers. If an external program were to modify the data without updating the headers, the data would no longer be synchronized correctly. This is why the returned file descriptor is read-only. Use get_copy() if you wish to modify the data.

Returns:A read-only file descriptor. :

See also

File.get_copy

get_copy(dest=None)

Downloads the file if it is not in the local cache and creates a copy.

Parameters:

dest: string | None :

Destination of the copy. If None, a default path within the cache directory is chosen.

Returns:

The file path as a string. :

See also

File.get

put(local_file, format='undefined', content='unknown', tags='none')

Uploads a local file on the server.

Returns:True if successful, False otherwise. :
size()
Returns:The size of the file in bytes as a string. :
tags()
Returns:The specified tags for this file. :

The CacheManager class

class pyxnat.cachemanager.CacheManager(robj)

Manual manager for the cached data.

The cache management is mainly transparent but it is useful sometimes to do theses actions manually.

A cache manager is linked to a ResourceObject and only works upon the cached data related to this object.

e.g. If the ResourceObject is a subject, related data may be:
  • its files
  • its experiments
  • the list of subjects from its project

The cache manager should be accessed through the cache attribute of its corresponding resource.

>>> subject.cache(pattern='*', files=True, recursive=True)
>>> subject.cache.clear()
__init__(robj)
Parameters:

robj: ResourceObject :

The ResourceObject the cache manager is linked to.

__call__(pattern='*', files=True, attrib=False)

Put all the resources related to this object in the local datastore.

Parameters:

attrib: True or False :

Caches the objects attributes.

files: True or False :

Downloads attached files if any.

recursive: True or False :

Iterates through the object descendants and caches them as well with the same ‘attrib’ and ‘files’ parameters.

files()
Returns the list of URIs of the files resources in cache.
resources()
Returns the list of URIs of the non-files resources in cache.
clear(datatype='all')

Clears the cached data for this object.

Parameters:

data: ‘all’ | ‘resources’ | ‘files’ :

Optional parameter to delete partially the cache.

The SearchManager class

class pyxnat.search.SearchManager(interface)

Define constraints to make a complex search on the database.

A search manager is available as an Interface attribute. Its main usage is simply to be called to create a Search object which will be responsible for specifying the returned data and for submitting the actual query.

Some additional methods are provided to list, retrieve and delete saved search.

Example:
>>> query = [ ('xnat:subjectData/SUBJECT_ID', 'LIKE', '%'), 
              ('xnat:projectData/ID', '=', 'my_project'),
              [ ('xnat:subjectData/AGE', '>', '14'),
                'AND'
              ],
              'OR'
            ]
>>> search = interface.search('my_search', query)
>>>
>>> # no search is saved because it was not submitted
>>> interface.search.names()
[]
>>> # submit and get results
>>> search.get_subjects()
[...]
>>> # now the search is saved
>>> interface.search.names()
['my_search']
>>> 
>>> same_search = interface.search.get('my_search')
__call__(name, query)

Setups and returns a Search object.

Warning

The search itself is not submitted here. The search is executed when a Search method like get_subjects(), which defines what kind of data is to be returned is called.

Parameters:

name: string :

Gives a name to the search to be able to retrieve it later. A name must be unique for a specific query.

query: list :

This is the query that will be submitted to the server
A query is an unordered list that contains
  • 1 or more constraints

  • 0 or more sub-queries (lists as this one)

  • 1 comparison method between the constraints

    (‘AND’ or ‘OR’)

A constraint is an ordered tuple that contains
  • 1 valid searchable_type/searchable_field
  • 1 operator among ‘=’, ‘<’, ‘>’, ‘<=’, ‘>=’, ‘LIKE’

See also

Search.get_table, Search.get_subjects, Search.get_experiments

types(name_filter='*')
List the searchable types on the XNAT server.
type_fields(searchable_type, prepend_type=False)
List the searchable fields for the given type on the XNAT server.
names()
Returns the list of the saved queries names.
get(name)
Get saved query by name.
delete(name)
Delete saved query by name.
queries()
Returns the dictionnary of the saved queries contraints. {name:query}
tables()
Returns the dictionnary of the saved queries returned data. {name:[columns]}

The Search class

class pyxnat.search.Search(name, query, interface)
get_experiments(experiment_type='xnat:mrSessionData')
Returns a list of Experiment objects matching the query constraints.
get_subjects()
Returns a list of Subject objects matching the query constraints.
get_table(row_type, columns=[])

Submits the defined search and returns a table.

Parameters:

row_type: string :

The returned table will have one line for every matching occurence of this type.

e.g. xnat:subjectData/SUBJECT_ID

columns: list of strings :

The returned table will have all the given columns. The valid columns names are found through the types() and type_fields() methods of SearchManager.

Returns:

A JsonTable object containing the results. :