Reference documentation

The Interface class

class pyxnat.xobject.Interface(server, user, password, datastore=None)

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.

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.xobject.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(xnat_type=None)

Creates the corresponding element on the XNAT server.

Note

The xnat_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:

xnat_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...
type()

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

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

The Project class

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

Specialized ResourceObject class for projects.

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.

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.xobject.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.xobject.Experiment(uri, interface, check_id=True)

Specialized ResourceObject class for experiments.

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.

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.xobject.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.xobject.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.xobject.File(uri, interface)

Specialized ResourceObject class for files.

content()
Returns:

The specified content for this file. :

e.g. T1, DTI, sequence preview :

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 :

get()

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

Note

It is not possible to define a custom path for the download because files are kept in the datastore and managed with the cache manager.

Returns:The file path as a string. :
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.xobject.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.checkout(attrib=True, files=True, recursive=True)
>>> subject.cache.update()
>>> subject.cache.clear()
__init__(robj)
Parameters:

robj: ResourceObject :

The ResourceObject the cache manager is linked to.

status()
Returns the URIs of the cached data related to the ResourceObject.
checkout(attrib=False, files=False, recursive=True)

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.

update()
Go through all the cached data and checks whether or not it matches the data on the server. Non-matching data is updated.
clear()
Clears the cached data for this object.

The SearchManager class

class pyxnat.xobject.SearchManager(interface)

Define constraints to make a complex search on the database.

A search manager is avalaible 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.saved()
[]
>>> # submit and get results
>>> search.get_subjects()
[...]
>>> # now the search is saved
>>> interface.search.saved()
['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’
types(name_filter='*')
List the searchable types on the XNAT server.
type_fields(searchable_type)
List the searchable fields for the given type on the XNAT server.
saved(asdict=False)

Returns the list of saved search.

Warning

Note that only submitted search are saved.

Parameters:

asdict: True or False :

If False only the names of the saved searches are returned.
If True, a dictionnary with the names as keys and the corresponding queries as values is returned.
Defaults to False.
get(name)

Returns a Search object for a saved search.

Parameters:

name: string :

Search name.

delete(name)

Removes a saved search and its results from the cache.

Parameters:

name: string :

Search name.

Returns:

True if something was deleted. :

False if no search with that name existed. :

The Search class

class pyxnat.xobject.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. :