Main entry point to access a XNAT server.
>>> central = Interface(server='http://central.xnat.org:8080',
user='login',
password='pwd',
cachedir='/tmp'
)
Or with config file:
>>> central = Interface(config='/home/me/.xnat.cfg')
Or for interactive use:
>>> central = Interface('http://central.xnat.org')
Note
The interactive mode is activated whenever an argument within server, user or password is missing. In interactive mode pyxnat tries to check the validity of the connection parameters.
Attributes : | _mode: online | offline :
_memtimeout: float :
|
---|
Loads a configuration file and replaces current connection parameters.
Parameters : | location: string :
|
---|
Saves current configuration - including password - in a file.
Warning
Since the password is saved as well, make sure the file is saved at a safe location with appropriate permissions.
Parameters : | location: string :
|
---|
Data selection interface. Callable object that indicates the data to be returned to the user.
Examples
>>> interface.select('/projects/myproj/subjects').get()
>>> columns = ['xnat:subjectData/PROJECT',
'xnat:subjectData/SUBJECT_ID'
]
>>> criteria = [('xnat:subjectData/SUBJECT_ID', 'LIKE', '*'),
'AND'
]
>>> interface.select('xnat:subjectData', columns
).where(criteria)
Select clause to specify what type of data is to be returned.
Parameters : | datatype_or_path: string :
columns: list :
|
---|
Access a particular project.
Parameters : | ID: string :
|
---|
Returns the list of all visible projects for the server.
Parameters : | id_filter: string :
|
---|
Database introspection interface.
Returns the datatypes used at the assessor level in this database.
See also
Inspector.set_autolearn
Look for the values at the assessor level for a given experiment type in the database.
Note
The experiment type should be one of Inspector.experiment_types()
Warning
Depending on the number of elements the operation may take a while.
Parameters : | datatype: string :
project: string :
|
---|
Discovers the datatypes and datafields of the database.
Parameters : | pattern: string :
fields_pattern: string :
|
---|---|
Returns : | list : datatypes or datafields depending on the argument usage. |
Returns the datatypes used at the experiment level in this database.
See also
Inspector.set_autolearn
Look for the values a the experiment level for a given datatype in the database.
Note
The datatype should be one of Inspector.experiment_types()
Parameters : | datatype: string :
project: string :
project: string :
|
---|
Look for the values a specific datafield takes in the database.
Look for the values a the project level in the database.
Note
Is equivalent to interface.select.projects().get()
Returns the datatypes used at the reconstruction level in this database.
See also
Inspector.set_autolearn
Look for the values at the reconstruction level for a given experiment type in the database.
Note
The experiment type should be one of Inspector.experiment_types()
Warning
Depending on the number of elements the operation may take a while.
Parameters : | datatype: string :
project: string :
|
---|
Returns the datatypes used at the scan level in this database.
See also
Inspector.set_autolearn
Look for the values at the scan level for a given experiment type in the database.
Note
The experiment type should be one of Inspector.experiment_types()
Warning
Depending on the number of elements the operation may take a while.
Parameters : | datatype: string :
project: string :
|
---|
Once in a while queries will persist additional information on the server. This information is available through the following methods of this class:
- experiment_types
- assessor_types
- scan_types
- reconstruction_types
It is also transparently used in insert operations.
Parameters : | auto: boolean :
tick: int :
|
---|
See also
EObject.insert
Displays the keywords structure used in XNAT REST API.
Look for the values a the subject level in the database.
Note
Is equivalent to interface.select(‘//subjects’).get()
Search interface. Handles operations to save and get back searches on the server.
Examples
>>> row = 'xnat:subjectData'
>>> columns = ['xnat:subjectData/PROJECT',
'xnat:subjectData/SUBJECT_ID'
]
>>> criteria = [('xnat:subjectData/SUBJECT_ID', 'LIKE', '*'),
'AND'
]
>>> interface.manage.search.save('mysearch', row, columns,
criteria, sharing='public',
description='my first search'
)
Removes the search from the server.
Deletes a search template.
Returns the results of the query saved on the XNAT server or the query itself to know what it does.
Parameters : | name: string :
out_format: string :
|
---|
Get a saved template, either as an xml document, or as a pyxnat representation, with the keys to be used in the template between the parentheses in %()s.
Parameters : | name: str :
as_xml: boolean :
|
---|
Saves a query on the XNAT server.
Parameters : | name: string :
row: string :
columns: list :
constraints: list :
sharing: string | list :
|
---|
See also
Search.where
Define and save a search template. Same as the save method, but the values in the constraints are used as keywords for value replacement when using the template.
Parameters : | name: string :
row: string :
columns: list :
constraints: list :
sharing: string | list :
|
---|
Returns the names of accessible saved search on the server.
Returns the names of accessible saved search templates on the server.
Parameters : | name: string :
values: dict :
|
---|
Examples
>>> interface.manage.search.use_template(name,
{'subject_id':'ID',
'age':'32'
})
Define constraints to make a complex search on the database.
This Search is available at different places throughout the API:
>>> interface.select(DATA_SELECTION).where(QUERY)
>>> interface.manage.search.save('name', TABLE_DEFINITION, QUERY)
Examples
>>> query = [('xnat:subjectData/SUBJECT_ID', 'LIKE', '%'),
('xnat:projectData/ID', '=', 'my_project'),
[('xnat:subjectData/AGE', '>', '14'),
'AND'
],
'OR'
]
Triggers the search.
Parameters : | contraints: list :
|
---|---|
Returns : | results: JsonTable object :
|
Generic Object for an element URI.
Returns the children levels of this element.
Parameters : | show_name: boolean :
|
---|
Examples
>>> subject_object.children()
['experiments', 'resources']
>>> subject_object.children(False)
<Collection Object> 170976556
Creates the element if it does not exists. Any non-existing ancestor will be created as well.
Warning
An element resource both have an ID and a label that can be used to access it. At the moment, XNAT REST API defines the label when creating an element, but not the ID, which is generated. It means that the name given to a resource may not appear when listing the resources because the IDs will appear, not the labels.
Note
To set up additional variables for the element at its creation it is possible to use shortcuts defined in the XNAT REST documentation or xpath in the schema:
- element.create(ID=’theid’)
- subject.create(**{‘xnat:subjectData/ID’:’theid’})
Parameters : | params: keywords :
|
---|
See also
EObject.id, EObject.label, EObject.datatype
Examples
>>> interface.select('/project/PROJECT/subject'
'/SUBJECT/experiment/EXP/scan/SCAN'
).create(experiments='xnat:mrSessionData',
scans='xnat:mrScanData'
)
Returns the type defined in the XNAT schema for this element resource.
EObject possible xsi types Project xnat:projectData Subject xnat:subjectData Experiment xnat:mrSessionData xnat:petSessionData
Deletes an element resource.
Parameters : | delete_files: boolean :
|
---|
Test whether an element resource exists.
Retrieves the XML document corresponding to this element.
Returns the element resource id.
Creates the element if it does not exists. Any non-existing ancestor will be created as well.
Warning
An element resource both have an ID and a label that can be used to access it. At the moment, XNAT REST API defines the label when creating an element, but not the ID, which is generated. It means that the name given to a resource may not appear when listing the resources because the IDs will appear, not the labels.
Note
To set up additional variables for the element at its creation it is possible to use shortcuts defined in the XNAT REST documentation or xpath in the schema:
- element.create(ID=’theid’)
- subject.create(**{‘xnat:subjectData/ID’:’theid’})
Parameters : | params: keywords :
|
---|
See also
EObject.id, EObject.label, EObject.datatype
Examples
>>> interface.select('/project/PROJECT/subject'
'/SUBJECT/experiment/EXP/scan/SCAN'
).create(experiments='xnat:mrSessionData',
scans='xnat:mrScanData'
)
Returns the element resource label.
Tag the element.
Remove a tag for the element.
Generic Object for a collection resource.
A collection resource is a list of element resources. There is however several ways to obtain such a list:
a collection URI e.g. /REST/projects
a list of element URIs
- a list of collections
e.g. /REST/projects/ONE/subjects AND /REST/projects/TWO/subjects
a list of element objects
a list a collection objects
Examples
>>> interface.select.projects()
<Collection Object> 173667084
>>> for project in interface.select.projects():
>>> print project
>>> for subject in interface.select.projects().subjects():
>>> print subject
Returns every element.
Warning
If a collection needs to issue thousands of queries it may be better to access the resources within a for-loop.
Parameters : | args: strings :
|
---|
Returns the first element of the collection.
Returns the first element of the collection.
Returns every element.
Warning
If a collection needs to issue thousands of queries it may be better to access the resources within a for-loop.
Parameters : | args: strings :
|
---|
Tag the collection.
Remove the tag from the collection.
Only the element objects whose subject that are matching the constraints will be returned. It means that it is not possible to use this method on an element that is not linked to a subject, such as a project.
See also
Examples
>>> for experiment in interface.select('//experiments'
).where([('atest/FIELD', '=', 'value'), 'AND']):
>>> print experiment
>>> for experiment in interface.select('//experiments'):
for assessor in experiment.assessors(
).where([('atest/FIELD', '=', 'value'), 'AND']):
>>> print assessor
>>> for project in interface.select('//projects'
).where([('atest/FIELD', '=', 'value'), 'AND']):
>>> print project
Gets project accessibility.
Adds a custom variable to a specified group
Parameters : | custom_variables: a dictionary : allow_data_deletion : a boolean |
---|
Examples
>>> variables = {'Subjects' : {'newgroup' : {'foo' : 'string', 'bar' : 'int'}}}
>>> project.add_custom_variables(variables)
Adds a user to the project. The user must already exist on the server.
Parameters : | login: string :
role: owner | member | collaborator :
|
---|
Gets collaborator of this project.
Gets project current archive folder on the server.
Retrieves custom variables as a dictionary
It has the format {studyProtocol: { setname : {field: type, ...}}}
Gets the last modified dates for all the project subjects.
If any element related to a subject changes, experiment, variable, scan, image etc... the date will be changed.
Gets members of this project.
Gets owners of this project.
Gets project prearchive code.
Gets project quarantine code.
Removes a user from the project.
Parameters : | login: string :
|
---|
Sets project accessibility.
Note
Write access is given or not by the user level for a specific project.
Parameters : | accessibility: public | protected | private :
|
---|
Sets project prearchive code.
Parameters : | code: 0 to 4 : |
---|
Sets project quarantine code.
Parameters : | code: 0 to 1 : |
---|
Changes project current archive subfolder on the server.
Gets the user level of the user for this project.
Parameters : | login: string :
|
---|---|
Returns : | string : owner | member | collaborator |
Gets all registered users for this project.
EObject for files stored in XNAT.
Returns : | dict : a dictionnary with the file attributes |
---|
Gets the file content description.
Uploads a file to XNAT.
Parameters : | src: string :
format: string :
content: string :
tags: string :
|
---|
Deletes the file on the server.
Gets the file format.
Downloads the file to the cache directory.
Note
The default cache path is computed like this: path_to_cache/md5(uri + query_string)_filename
Parameters : | dest: string | None :
force_default: boolean :
|
---|---|
Returns : | string : the file location. |
Downloads the file to the cache directory but creates a copy at the specified location.
Parameters : | dest: string | None :
|
---|---|
Returns : | string : the copy location. |
Uploads a file to XNAT.
Parameters : | src: string :
format: string :
content: string :
tags: string :
|
---|
Gets the file labels.
Uploads a file to XNAT.
Parameters : | src: string :
format: string :
content: string :
tags: string :
|
---|
Gets the file size.
Accessor class to resource fields.
>>> subject.attrs()
['xnat:subjectData/sharing',
'xnat:subjectData/sharing/share',
'xnat:subjectData/resources',
...
'xnat:subjectData/experiments/experiment'
]
All paths are not valid but they give an indication of what is available. To retrieve the paths, the corresponding schemas must be downloaded first through the schema management interface in order to be parsed:
>>> interface.manage.schemas.add('xnat.xsd')
>>> interface.manage.schemas.add('myschema/myschema.xsd')
Get an attribute value.
Note
The value is always returned in a Python string. It must be explicitly casted or transformed if needed.
Parameters : | path: string :
|
---|---|
Returns : | A string containing the value. : |
Set multiple attributes at once.
It is more efficient to use this method instead of multiple times the get() method when getting more than one attribute because only a single HTTP call is issued to the server.
Parameters : | paths: list :
|
---|---|
Returns : | list: ordered list of values (in the order of the : requested paths) : |
Set multiple attributes at once.
It is more efficient to use this method instead of multiple times the set() method when setting more than one attribute because only a single HTTP call is issued to the server.
Parameters : | dict_attrs: dict :
|
---|
Set an attribute.
Parameters : | path: string :
value: string :
|
---|
Class to annotate processed data with provenance information. The following parameters are available:
- program
- program_version
- program_arguments
- timestamp
- cvs
- user
- machine
- platform
- platform_version
- compiler
- compiler_version
Examples
>>> prov = {'program':'young',
'timestamp':'2011-03-01T12:01:01.897987',
'user':'angus',
'machine':'war',
'platform':'linux',
}
>>> element.provenance.set(prov)
>>> element.provenance.get()
>>> element.delete()
Removes the provenance attached to this object.
Warning
doesn’t work because of a bug with the allowDataDeletion flag in XNAT
Gets all the provenance information for that object.
Returns : | A list of dicts. : |
---|
Set provenance information for the data within this element.
Note
If some required parameters are not provided, theses parameters will be extracted from the current machine and set automatically. Those parameters are:
- machine
- platform
- timestamp
- user
Warning
overwrite option doesn’t work because of a bug with the allowDataDeletion flag in XNAT
Parameters : | process_steps: list or dict :
overwrite: boolean :
|
---|
Database user management interface. It is used to retrieve information on users registered on a server.
Note
At the moment user creation and deletion is not supported through the REST API but it will be at some point.
See also
Project.users, Project.add_user, Project.remove_user
Examples
>>> interface.manage.users()
['list_of_users']
>>> interface.manage.users.firstname('nosetests')
'nose'
Returns the email of the user.
Returns the firstname of the user.
Returns the id of the user.
Returns the lastname of the user.
Returns the resources of the user.
Database introspection interface.
Returns the datatypes used at the assessor level in this database.
See also
Inspector.set_autolearn
Look for the values at the assessor level for a given experiment type in the database.
Note
The experiment type should be one of Inspector.experiment_types()
Warning
Depending on the number of elements the operation may take a while.
Parameters : | datatype: string :
project: string :
|
---|
Discovers the datatypes and datafields of the database.
Parameters : | pattern: string :
fields_pattern: string :
|
---|---|
Returns : | list : datatypes or datafields depending on the argument usage. |
Returns the datatypes used at the experiment level in this database.
See also
Inspector.set_autolearn
Look for the values a the experiment level for a given datatype in the database.
Note
The datatype should be one of Inspector.experiment_types()
Parameters : | datatype: string :
project: string :
project: string :
|
---|
Look for the values a specific datafield takes in the database.
Look for the values a the project level in the database.
Note
Is equivalent to interface.select.projects().get()
Returns the datatypes used at the reconstruction level in this database.
See also
Inspector.set_autolearn
Look for the values at the reconstruction level for a given experiment type in the database.
Note
The experiment type should be one of Inspector.experiment_types()
Warning
Depending on the number of elements the operation may take a while.
Parameters : | datatype: string :
project: string :
|
---|
Returns the datatypes used at the scan level in this database.
See also
Inspector.set_autolearn
Look for the values at the scan level for a given experiment type in the database.
Note
The experiment type should be one of Inspector.experiment_types()
Warning
Depending on the number of elements the operation may take a while.
Parameters : | datatype: string :
project: string :
|
---|
Once in a while queries will persist additional information on the server. This information is available through the following methods of this class:
- experiment_types
- assessor_types
- scan_types
- reconstruction_types
It is also transparently used in insert operations.
Parameters : | auto: boolean :
tick: int :
|
---|
See also
EObject.insert
Displays the keywords structure used in XNAT REST API.
Look for the values a the subject level in the database.
Note
Is equivalent to interface.select(‘//subjects’).get()
Management interface for the cache.
Available disk on partition. Default location is cache folder.
Clears all files tracked by pyxnat.
Checks the status of the disk. Basically if there is enough space left. The default location is cache dir.
Customize cache usage.
Parameters : | mode: string :
expiration: float :
|
---|
Returns the amount of space taken by the cache.
Parameters : | unit: str :
|
---|---|
Returns : | size: float : |
Total disk on partition. Default location is cache folder.
Used disk on partition. Default location is cache folder.
Management interface for XNAT schemas.
The aim is to provide a minimal set of functionalities to parse and look at XNAT schemas.
Loads an additional schema.
Parameters : | url: str :
|
---|
Removes a schema.