XNAT Python Client¶

A new XNAT client that exposes XNAT objects/functions as python objects/functions.

Warning

This is NOT pyxnat, but a new module which is not as mature but uses a different philisophy for the user interface. Pyxnat is located at: https://pythonhosted.org/pyxnat/

The XNAT Python client is open-source (licensed under the Apache 2.0 license) and hosted on bitbucket at https://bitbucket.org/bigr_erasmusmc/xnatpy

To get yourself a copy:

hg clone https://<yourusername>@bitbucket.org/bigr_erasmusmc/xnatpy

or if you have a ssh key pair:

hg clone ssh://hg@bitbucket.org/bigr_erasmusmc/xnatpy

The official documentation can be found at xnat.readthedocs.org

XNAT Client Documentation¶

Introduction¶

A new XNAT client that exposes XNAT objects/functions as python objects/functions.

Getting started¶

To install just use the setup.py normally:

python setup.py install

To get started, create a connection and start querying:

>>> import xnat
>>> session = xnat.connect('https://central.xnat.org', user="", password="")
>>> session.projects['Sample_DICOM'].subjects
>>> session.disconnect()

To see all options for creating connections see the xnat.connect().

The XNAT session is the main class for interacting with XNAT. It contains the main communication functions.

When using IPython most functionality can be figured out by looking at the available attributes/methods of the returned objects.

Credentials¶

To store credentials this module uses the .netrc file. This file contains login information and should be accessible ONLY by the user (if not, the module with throw an error to let you know the file is unsafe).

Status¶

Currently we have basic support for almost all data on XNAT servers. Also it is possible to import data via the import service (upload a zip file). There is also some support for working with the prearchive (reading, moving, deleting and archiving).

Any function not exposed by the object-oriented API of xnatpy, but exposed in the XNAT REST API can be called via the generic get/put/post methods in the session object.

There is at the moment still a lack of proper tests in the code base and the documentation is somewhat sparse, this is a known limitation and can hopefully be addressed in the future.

XNATpy Tutorial¶

XNAT REST API¶

The XNAT REST API allows users to work with xnat via scripts. The REST API is an interface that is language independent and is build on top of HTTP. Operations are carried out by HTTP requests with one of the verbs GET, PUT, POST or DELETE. The GET request is generally used for retrieving data, whereas the PUT, POST, and DELETE are used for modifying data.

A simple GET request can be send by simply putting the target url in a web browser and looking at the result. For a sending more complex HTTP requests, you can for example use curl (a command-line tool for linux), postman (an extension for the chrome browser), or the requests package for Python (on top of which this package as well as pyxnat is build)

To get an idea of how the XNAT REST API works it is helpful to visit the following URLs in your browser:

The first URL give you a table with an overview of all projects you can access on XNAT central. The second and third URL give the same information, but in different machine readable formats (XML and JSON respectively). This is extremely useful when creating scripts to automatically retrieve or store data from XNAT.

Installation¶

The easiest way to install xnat is via to python package index via pip:

pip install xnat

However, if you do not have pip or want to install from source just use the setup.py normally:

python setup.py install

Connecting to a server¶

To get started, create a connection:

>>> import xnat
>>> session = xnat.connect('https://central.xnat.org')

To see all options for creating connections see the xnat.connect(). The connection holds your login information, the server information and a session. It will also send a heartbeat every 14 minutes to keep the connection alive.

When working with a session it is always important to disconnect when done:

>>> session.disconnect()

Credentials¶

It is possible to pass your credentials for the session when connecting. This would look like:

>>> session = xnat.connect('http://my.xnat.server', user='admin', password='secret')

This would work and log in fine, but your password might be visible in your source code, command history or just on your screen. If you only give a user, but not a password xnatpy will prompt you for your password. This is fine for interactive use, but for automated scripts this is useless.

To store credentials this xnatpy uses the .netrc file. On linux the file is located in ~/.netrc. This file contains login information and should be accessible ONLY by the user (if not, the module with throw an error to let you know the file is unsafe). For example:

echo "machine images.xnat.org
>     login admin
>     password admin" > ~/.netrc
chmod 600 ~/.netrc

This will create the netrc file with the correct contents and set the permission correct.

Self-closing sessions¶

When in a script where there is a possibility for unforeseen errors it is safest to use a context operator in Python. This can be achieved by using the following:

>>> with xnat.connect('http://my.xnat.server') as session:
...     print session.projects

As soon as the scope of the with exists (even if because of an exception thrown!) the session will be disconnected automatically.

Exploring your xnat server¶

When a session is established, it is fairly easy to explore the data on the XNAT server. The data structure of XNAT is mimicked as Python objects. The connection gives access to a listing of all projects, subjects, and experiments on the server.

>>> import xnat
>>> session = xnat.connect('http://images.xnat.org', user='admin', password='admin')
>>> session.projects
<XNATListing (sandbox, sandbox project): <ProjectData sandbox project (sandbox)>>

The XNATListing is a special type of mapping in which you can access elements by a primary key (usually the ID or Accession #) and a secondary key (e.g. the label for a subject or experiment). Selection can be performed the same as a Python dict:

>>> sandbox_project = session.projects["sandbox"]
>>> sandbox_project.subjects
<XNATListing (XNAT_S00001, test001): <SubjectData test001 (XNAT_S00001)>>

You can browse the following levels on the XNAT server: projects, subjects, experiments, scans, resources, files. Also under experiments you have assessors which again can contain resources and files. This all following the same structure as XNAT.

Warning

Loading all subjects/experiments on a server can take very long if there is a lot of data. Going down through the project level is more efficient.

Looping over data¶

There are situations in which you want to perform an action for each subject or experiment. To do this, you can think of an XNATListing as a Python dict and most things will work naturally. For example:

>>> sandbox_project.subjects.keys()
[u'XNAT_S00001']
>>> sandbox_project.subjects.values()
[<SubjectData test001 (XNAT_S00001)>]
>>> len(sandbox_project.subjects)
1
>>> for subject in sandbox_project.subjects.values():
...     print(subject.label)
test001

Downloading data¶

If you have the following in your XNAT:

>>> experiment.scans['T1']
<MrScanData T1 (1001-MR3)>

In some cases you might want to download an individual scan to inspect/process locally. This is using:

>>> experiment.scans['T1'].download('/home/hachterberg/temp/T1.zip')
Downloading http://127.0.0.1/xnat/data/experiments/demo_E00091/scans/1001-MR3/files?format=zip:
13035 kb
Saved as /home/hachterberg/temp/T1.zip...

As you can see, the scan is downloaded as a zip archive that contains all the DICOM files.

If you are interested in downloading all data of an entire subject, it is possible to use a helper function that downloads the data and extracts it in the target directory. This will create a data structure similar to that of XNAT on your local disk:

>>> subject = experiment.subject

>>> subject.download_dir('/home/hachterberg/temp/')
Downloading http://120.0.0.1/xnat/data/experiments/demo_E00091/scans/ALL/files?format=zip:
23736 kb
Downloaded image session to /home/hachterberg/temp/ANONYMIZ3
Downloaded subject to /home/hachterberg/temp/ANONYMIZ3

To see what is downloaded, we can use the linux command find from ipython:

$ find /home/hachterberg/temp/ANONYMIZ3
/home/hachterberg/temp/ANONYMIZ3
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR/resources
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR/resources/DICOM
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR/resources/DICOM/files
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR/resources/DICOM/files/IM2.dcm
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR/resources/DICOM/files/IM32.dcm
/home/hachterberg/temp/ANONYMIZ3/ANONYMIZ3/scans/1001-MR2-FLAIR/resources/DICOM/files/IM11.dcm
...

The REST API allows for downloading of data from XNAT. The xnatpy package includes helper functions to make the downloading of data easier. For example, to download all experiments belonging to a subject:

>>> subject = sandbox_project.subjects['test001']
>>> subject.download_dir('./Downloads/test001')

This will download all the relevant experiments and unpack them in the target folder. This is available for projects, subjects, experiments, scans, and resources.

Experiments, scans and resources can also be downloaded in a zip bundle using the download method for experiments, scans, and resources.

Custom variables¶

The custom variables are exposed as a dict-like object in xnatpy. They are located in the field attribute under the objects that can have custom variables:

In [18]: experiment = project.subjects['ANONYMIZ'].experiments['ANONYMIZ']

In [19]: experiment.fields
Out[19]: <VariableMap {u'brain_volume': u'0'}>

In [20]: experiment.fields['brain_volume']
Out[20]: u'0'

In [21]: experiment.fields['brain_volume'] = 42.0

In [22]: experiment.fields
Out[22]: <VariableMap {u'brain_volume': u'42.0'}>

In [27]: experiment.fields['brain_volume']
Out[27]: u'42.0'

Getting external urls of an object¶

Sometimes you want to know the full external URL of a resource in XNAT, for this all XNAT objects have a function to retrieve this:

>>> experiment_01.external_uri()
'https://xnat.server.com/data/archive/projects/project/subjects/XNAT_S09618/experiments/XNAT_E36346'

You can change the query string or scheme used with extra arguments:

>>> experiment_01.external_uri(scheme='test', query={'hello': 'world'})
'test://xnat.server.com/data/archive/projects/project/subjects/XNAT_S09618/experiments/XNAT_E36346?hello=world'

Importing data into XNAT¶

To add new data into XNAT it is possible to use the REST import service. It allows you to upload a zip file containing an experiment and XNAT will automatically try to store it in the correct place:

>>> session.services.import_('/path/to/archive.zip', project='sandbox', subject='test002')

Will upload the DICOM files in archive.zip and add them as scans under the subject test002 in project sandbox. For more information on importing data see import_

As it is dangerous to add data straight into the archive due to lack of reviewing, it is possible to also upload the data to the prearchive first. This can be achieved by adding the destination argument as follows:

# Import via prearchive:
>>> prearchive_session = session.services.import_('/home/hachterberg/temp/ANONYMIZ.zip', project='brainimages', destination='/prearchive')
>>> print(prearchive_session)
<PrearchiveSession brainimages/20161107_114859342/ANONYMIZ>

Once the data is uploaded (either via xnatpy or other means) it is possible to query the prearchive and process the scans in it. To get a list of sessions waiting for archiving use the following:

>>> session.prearchive.sessions()
[<PrearchiveSession brainimages/20161107_114859342/ANONYMIZ>]

Once the data in the prearchive is located it can be archived as follows:

>>> prearchive_session = session.prearchive.sessions()[0]
>>> experiment = prearchive_session.archive(subject='ANONYMIZ3', experiment='ANONYMIZ3')
>>> print(experiment)
<MrSessionData ANONYMIZ3 (demo_E00092)>

Note

It is worth noting that it is possible to inspect the scan before archiving: one can look at the status, move it between projects, list the scans and files contained in the scans.

Prearchive¶

When scans are send to the XNAT they often end up in the prearchive pending review before adding them to the main archive. It is possible to view the prearchive via xnatpy:

>>> session.prearchive.sessions()
[]

This gives a list of PrearchiveSessions in the archive. It is possible to archive, rebuild, move, or delete the session using simple methods. For more information see PrearchiveSession

Object creation¶

It is possible to create object on the XNAT server (such as a new subject, experiment, etc). This is achieved by creating such an object in python and xnatpy will create a version of the server. For example you can create a subject:

>>> import xnat
>>> connection = xnat.connect('https://xnat.example.com')
>>> project = connection.projects['myproject']
>>> subject = connection.classes.SubjectData(parent=project, label='new_subject_label')
>>> subject
<SubjectData new_subject_label>

Note

the parent need to be the correct parent for the type, so an MRSessionData would need a SubjectData to be the parent.

In the connection.classes are all classes known the XNAT, also MRSessionData, CTSessionData. To get a complete list you can do:

>>> dir(connection.classes)

Note

the valid parent for a project (ProjectData) would be the connection object itself

Accessing XNAT files as local files (partial read)¶

There is a helper added in xnatpy that allows you to open a remote file (FileData object) similarly as a local file. Note that it will read the file from the start and until it is done, seeking will download until the seek point.

For example:

>>> import xnat
>>> connection = xnat.connect('https://xnat.server.com')
>>> file_obj = connection.projects['project'].subjects['S'].experiments['EXP'].scans['T1'].resources['DICOM'].files[0]
<FileData 1.3.6.1...-18s1eb2.dcm (1.3.6.1...-18s1eb2.dcm)>
>>> with file_obj.open() as fin:
        data = fin.read(3000)
>>> print(len(data))
3000

You can also use this to read the headers of a dicom file using pydicom:

>>> import pydicom
>>> with file_obj.open() as fin:
        data = pydicom.dcmread(fin, stop_before_pixels=True)

This should read the header and stop downloading once the entire header is read.

Note

The file is read in chucks so there might be a bit too much data downloaded

Note

If you open the file and not close it, the memory buffer might not be cleaned properly

Accessing DICOM headers of scan¶

Sometimes it is desired to read DICOM headers without downloading the entire scan. XNAT has a dicomdump service which can be used:

>>> connection.service.dicom_dump(scan_uri)

For more details see import_. As a helper we added a dicom_dump method to ScanData:

>>> scan.dicom_dump()

See ScanData.dicom_dump for the details.

A limitation of the dicomdump of XNAT is that field values are truncated under 64 characters. If you want to access the entire dicom header, a convenience method is added that reads the header via pydicom:

>>> scan.read_dicom()

This reads only the header and not the pixel data and will only download part of the file. To read the pixel data use:

>>> scan.read_dicom(read_pixel_data=True)

For the details see ScanData.dicom_dump

Note

Only one file is loaded, so the pixel data will only contain a single slice unless it is a DICOM Enhanced file

Example scripts¶

There is a number of example scripts located in the examples folder in the source code. The following code is a small command-line tool that prints all files for a given scan in the XNAT archive:

#!/usr/bin/env python

import xnat
import argparse
import re


def get_files(connection, project, subject, session, scan):
    xnat_project = connection.projects[project]
    xnat_subject = xnat_project.subjects[subject]
    xnat_experiment = xnat_subject.experiments[session]
    xnat_scan = xnat_experiment.scans[scan]
    files = xnat_scan.files.values()
    return files


def filter_files(xnat_files, regex):
    filtered_files = []
    regex = re.compile(regex)
    for file in xnat_files:
        found = regex.match(file.name)
        if found:
            filtered_files.append(file)
    return filtered_files


def main():
    parser = argparse.ArgumentParser(description='Prints all files from a certain scan.')
    parser.add_argument('--xnathost', type=unicode, required=True, help='xnat host name')
    parser.add_argument('--project', type=unicode, required=True, help='Project id')
    parser.add_argument('--subject', type=unicode, required=True, help='subject')
    parser.add_argument('--session', type=unicode, required=True, help='session')
    parser.add_argument('--scan', type=unicode, required=True, help='scan')
    parser.add_argument('--filter', type=unicode, required=False, default='.*', help='regex filter for file names')
    args = parser.parse_args()

    with xnat.connect(args.xnathost) as connection:
        xnat_files = get_files(connection, args.project, args.subject, args.session, args.scan)
        xnat_files = filter_files(xnat_files, args.filter)
        for file in xnat_files:
            print('{}'.format(file.name))


if __name__ == '__main__':
    main()

Changelog¶

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning

0.3.18 - 2019-06-06¶

Improved¶

Added force flag to ScanData.read_dicom
Added open to PrearchiveFile (same as for FileData)
Added read_dicom to PrearchiveScan (same as for ScanData)
Documentation improved, added code reference and changelog into docs

Fixed¶

Flag extension_types=False now also working for 1.7 servers

0.3.17 - 2019-04-04¶

Added¶

Can open FileData object with file.open() to get a file-like object that can be used similar to a local file.
Added read_dicom() to ScanData to read the dicom header/file with pydicom
external_uri method to get a full external uri of an XNAT object

0.3.16 - 2019-03-28¶

Fixed¶

Support for changing subject and experiment labels
Support creation of ScanData types with the id and type set on creation
Fix a bug in scanning extension types where there are new-lines in the xs:schema tag

0.3.14 - 2019-02-22¶

Added¶

Check which user is logged in and expose that in connection.logged_in_user
Check the cookies to set the appropriate heartbeat interval for the server.
Allow getting the session expiration information with connection.session_expiration_time

Changed¶

Refactored some code in the model building, which is optional if you only want to use xnatpy for a convenience layer about requests. Giving no_build_model=True to the connect function will disable the scraping of the server xml structure and not create all classes, but will log in and keep alive a connection. Only the simple connection get, head, put, post, delete, download, upload methods are really safe to use in that case.
XNAT objects (including subject and experiments) will use the listing to get their label and xsitype to avoid the need to get each experiment when creating a listing. This makes listings way more efficient.

Fixed¶

Bug with auth when xnat was not running in the server root, but rather in a subdirectory

0.3.13 - 2019-01-07¶

Fixed¶

Import problem in Python 2 which broke xnatpy

0.3.12 - 2019-01-03¶

Added¶

Adds fields argument to the dicom_dump method to filter on dicom tags server side.
Adds dicom_dump method to prearchive scan.
Allow deleting variables by useing del object.variable, this works in most cases but seem to fail server-side on restriction such as gender (it does not match any valid options)

Changed¶

Beter computation for the uri’s of resources

Fixed¶

Fixed xml deprecation warning due to the use of .getchildren()

0.3.11 - 2018-11-12¶

Fixed¶

Functions with an async parameter had them renamed to asynchronous as async is a keyword as of Python 3.7
Fix a bug in the XSD parsing when an XSD contains a schema-level simpleType
Bug in upload_dir with python3 when using a method based on a temporary file

Added¶

Resource upload methods can now forward kwargs to the connection.upload method.
Resource constructor also optionally takes a data_dir and upload_method arguments for uploading data immediately after creation.

0.3.10 - 2018-08-31¶

Added¶

The experiment.create_resource and scan.create_resource now take two extra arguments: data_dir and method, which allow the uploading of the content of a directory as the content of the newly created resource. The method is the method for resource.upload_dir method
Command line callable scripts that copies an entire project to another xnat. See xnat_cp_project --help

Changed¶

Removed wrong default argument for create_assessor (invalid assessor type)
The lower level get/put/post/delete methods now can process full uris as well as paths as long as the uri start matches the server uri (e.g. instead of using /data/projects you can also give https://serveruri.com/data/projects.

Fixed¶

Fixed a small bug where an incorrect error message was giving when not giving a value for the secondary label during object creation.

0.3.9 - 2018-07-02¶

Fixed¶

xnatpy had issues with shared subjects and sessions as the REST API would return the original object (with sharing information in it). Now xnatpy check the requested uri and makes sure the information of the correct project is used. Now shared objects can be used properly in xnatpy.

Added¶

resource.upload now takes an extract parameter indicating data should be extracted into files after upload
resource.upload_dir to upload an entire directory to a resource, the directory will be added into the resources so that e.g. directory/a.txt becomes resource/a.txt
redirection detections, if the server has moved and is being redirected (e.g. using a 302 or 301 response), xnatpy will detect that and use the new url instead.

0.3.8 - 2018-06-04¶

Added¶

Methods to retrieve the DICOM header dump using the dcmdump service. This can be used via services.dicom_dump(uri) or experiment.dicom_dump to get the dump of the specific experiment

Fixed¶

Strict username checking after login disabled to avoid problems with OIDC
Fix a bug where token result would contain extra data

0.3.7 - 2018-03-12¶

Fixed¶

Fixed a bug where the prompt for the password on Windows would not work

Changed¶

Hide certificate warnings if verify=False, just give a one time warning that things might not be safe, but no spam at every single request

0.3.6 - 2018-03-09¶

Added¶

Support for issuing tokens in the service module

Fixed¶

Allow user to login using a token (the username check will catch this an allow it)

Changed¶

Improved the logging by reducing spam at the INFO/DEBUG levels. The debug parameter on connect can now be used to enable the logging of xnatpy internals.
Give a specific error if the XNAt password is outdated and requires an update.

0.3.5 - 2018-01-02¶

Fixed¶

There were bugs in the prearchive breaking the entire pre-archive funcationaly

0.3.4 - 2017-11-13¶

Fixed¶

Files in assessors would have a path prefixed with a / in some cases (which should never happen)

0.3.3 - 2017-10-18¶

Changed¶

Abstracted the progress bar for downloading to allow other progress hooks (e.g. GUI)

Fixed¶

Set proper minimal versions for requirements (e.g. six can be too old)
Bug in upload for Python3
Bug with getting the file size when there are redirects (issue #8)
Bug with getting files from a project/subject/experiment/scan directly instead of via resource (issue #5)

0.3.2 - 2017-10-15¶

Fixed¶

Bug in the the create_object function in the selection of the non-history object
Bug in the setting of project properties (due to the lack of a parent)

0.3.1 - 2017-09-04¶

Changed¶

FileData now has an id and path, the id is the filename and the path is the path relative from the resource. This makes working with subdirectories in resources possible.

Fixed¶

Bug where history of XNAT was misinterpreted and an old version of an object could be loaded
Resources could loose track of their ID when the cache was cleared
Resources did not invalidate cache after uploading files

0.3.0 - 2017-08-17¶

Added¶

Better support for complex data structures, especially data types that include lists in their data.
Support for extension types, xnatpy automatically searches for all extension xsd files and will create Python classes for those as well.
Listings can be indexed with integers to get their n-th element, the order is the order given by XNAT.
Allow overwriting of files on upload
Support for listing users via /data/users REST endpoint in the session.users

Changed¶

xsd schema parsing is completely rewritten, allows more support for complex data structures

Fixed¶

Support for XNAT 1.7.3
Fixed a bug where opening a second session would ruin the first one, it should now be possible to have multiple sessions open concurently.

0.2.3 - 2017-04-03¶

Added¶

xnatpy now uses the progressbar2 package to deliver fancy progress bars when downloading
Attributes in the session that allow users to skip/alter the checking of responses

Changed¶

Logging now using a logger. You can change the log levels or supply your own logger which xnatpy will use in favour of its own
xnatpy now gets the version information from 1.7 xnat correctly

Fixed¶

A bug in XNAT 1.7 caused the prearchive routes to be wrong, added a work around that fixes the prearchive with xnatpy

Code reference¶

`xnat` Package¶

This package contains the entire client. The connect function is the only function actually in the package. All following classes are created based on the https://central.xnat.org/schema/xnat/xnat.xsd schema and the xnatcore and xnatbase modules, using the convert_xsd.

xnat.connect(server, user=None, password=None, verify=True, netrc_file=None, debug=False, extension_types=True, loglevel=None, logger=None, detect_redirect=True, no_parse_model=False)¶

Connect to a server and generate the correct classed based on the servers xnat.xsd This function returns an object that can be used as a context operator. It will call disconnect automatically when the context is left. If it is used as a function, then the user should call .disconnect() to destroy the session and temporary code file.

Parameters:	server (str) – uri of the server to connect to (including http:// or https://) user (str) – username to use, leave empty to use netrc entry or anonymous login. password (str) – password to use with the username, leave empty when using netrc. If a username is given and no password, there will be a prompt on the console requesting the password. verify (bool) – verify the https certificates, if this is false the connection will be encrypted with ssl, but the certificates are not checked. This is potentially dangerous, but required for self-signed certificates. netrc_file (str) – alternative location to use for the netrc file (path pointing to a file following the netrc syntax) bool (debug) – Set debug information printing on and print extra debug information. This is meant for xnatpy developers and not for normal users. If you want to debug your code using xnatpy, just set the loglevel to DEBUG which will show you all requests being made, but spare you the xnatpy internals. loglevel (str) – Set the level of the logger to desired level logger (logging.Logger) – A logger to reuse instead of creating an own logger detect_redirect (bool) – Try to detect a redirect (via a 302 response) and short-cut for subsequent requests no_parse_model (bool) – Create an XNAT connection without parsing the server data model, this create a connection for which the simple get/head/put/post/delete functions where, but anything requiring the data model will file (e.g. any wrapped classes)
Returns:	XNAT session object
Return type:	XNATSession

Preferred use:

>>> import xnat
>>> with xnat.connect('https://central.xnat.org') as session:
...    subjects = session.projects['Sample_DICOM'].subjects
...    print('Subjects in the SampleDICOM project: {}'.format(subjects))
Subjects in the SampleDICOM project: <XNATListing (CENTRAL_S01894, dcmtest1): <SubjectData CENTRAL_S01894>, (CENTRAL_S00461, PACE_HF_SUPINE): <SubjectData CENTRAL_S00461>>

Alternative use:

>>> import xnat
>>> session = xnat.connect('https://central.xnat.org')
>>> subjects = session.projects['Sample_DICOM'].subjects
>>> print('Subjects in the SampleDICOM project: {}'.format(subjects))
Subjects in the SampleDICOM project: <XNATListing (CENTRAL_S01894, dcmtest1): <SubjectData CENTRAL_S01894>, (CENTRAL_S00461, PACE_HF_SUPINE): <SubjectData CENTRAL_S00461>>
>>> session.disconnect()

`session` Module¶

class xnat.session.XNATSession(server, logger, interface=None, user=None, password=None, keepalive=None, debug=False, original_uri=None, logged_in_user=None)¶

Bases: object

The main XNATSession session class. It keeps a connection to XNATSession alive and manages the main communication to XNATSession. To keep the connection alive there is a background thread that sends a heart-beat to avoid a time-out.

The main starting points for working with the XNATSession server are:

XNATSession.projects
XNATSession.subjects
XNATSession.experiments
XNATSession.prearchive
XNATSession.services
XNATSession.users

Note

Some methods create listing that are using the xnat.core.XNATListing class. They allow for indexing with both XNATSession ID and a secondary key (often the label). Also they support basic filtering and tabulation.

There are also methods for more low level communication. The main methods are XNATSession.get, XNATSession.post, XNATSession.put, and XNATSession.delete. The methods do not query URIs but instead query XNATSession REST paths as described in the XNATSession 1.6 REST API Directory.

For an even lower level interfaces, the XNATSession.interface gives access to the underlying requests interface. This interface has the user credentials and benefits from the keep alive of this class.

Note

XNATSession Objects have a client-side cache. This is for efficiency, but might cause problems if the server is being changed by a different client. It is possible to clear the current cache using XNATSession.clearcache. Turning off caching complete can be done by setting XNATSession.caching.

Warning

You should NOT try use this class directly, it should only be created by xnat.connect.

clearcache()¶: Clear the cache of the listings in the Session object

delete(path, headers=None, accepted_status=None, query=None, timeout=None)¶

Delete the content of a given REST directory.

Parameters:	path (str) – the path of the uri to retrieve (e.g. “/data/archive/projects”) the remained for the uri is constructed automatically headers (dict) – the HTTP headers to include query (dict) – the values to be added to the query string in the uri accepted_status (list) – a list of the valid values for the return code, default [200] timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout)
Returns:	the requests reponse
Return type:	requests.Response

download(uri, target, format=None, verbose=True, timeout=None)¶: Download uri to a target file

download_stream(uri, target_stream, format=None, verbose=False, chunk_size=524288, update_func=None, timeout=None)¶

Download the given uri to the given target_stream.

Parameters:

uri (str) – Path of the uri to retrieve.
target_stream (file) – A writable file-like object to save the stream to.
format (str) – Request format
verbose (bool) – If True, and an update_func is not specified, a progress bar is shown on stdout.
chunk_size (int) – Download this many bytes at a time
update_func (func) –
If provided, will be called every chunk_size bytes. Must accept three parameters:
- the number of bytes downloaded so far
- the total number of bytse to be downloaded (might be None),
- A boolean flag which is False during the download, and True when the download has completed (or failed)
timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout)

download_zip(uri, target, verbose=True, timeout=None)¶: Download uri to a target zip file

experiments¶

Listing of all experiments on the XNAT server

Returns an XNATListing with elements that are subclasses of ExperimentData

get(path, format=None, query=None, accepted_status=None, timeout=None, headers=None)¶

Retrieve the content of a given REST directory.

Parameters:	path (str) – the path of the uri to retrieve (e.g. “/data/archive/projects”) the remained for the uri is constructed automatically format (str) – the format of the request, this will add the format= to the query string query (dict) – the values to be added to the query string in the uri accepted_status (list) – a list of the valid values for the return code, default [200] timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout) headers (dict) – the HTTP headers to include
Returns:	the requests reponse
Return type:	requests.Response

get_json(uri, query=None, accepted_status=None)¶

Helper function that perform a GET, but sets the format to JSON and parses the result as JSON

Parameters:	uri (str) – the path of the uri to retrieve (e.g. “/data/archive/projects”) the remained for the uri is constructed automatically query (dict) – the values to be added to the query string in the uri

head(path, accepted_status=None, allow_redirects=False, timeout=None, headers=None)¶

Retrieve the header for a http request of a given REST directory.

Parameters:	path (str) – the path of the uri to retrieve (e.g. “/data/archive/projects”) the remained for the uri is constructed automatically accepted_status (list) – a list of the valid values for the return code, default [200] allow_redirects (bool) – allow you request to be redirected timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout) headers (dict) – the HTTP headers to include
Returns:	the requests reponse
Return type:	requests.Response

interface¶: The underlying requests interface used.

post(path, data=None, json=None, format=None, query=None, accepted_status=None, timeout=None, headers=None)¶

Post data to a given REST directory.

Parameters:	path (str) – the path of the uri to retrieve (e.g. “/data/archive/projects”) the remained for the uri is constructed automatically data – Dictionary, bytes, or file-like object to send in the body of the `Request`. json – json data to send in the body of the `Request`. format (str) – the format of the request, this will add the format= to the query string query (dict) – the values to be added to the query string in the uri accepted_status (list) – a list of the valid values for the return code, default [200, 201] timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout) headers (dict) – the HTTP headers to include
Returns:	the requests reponse
Return type:	requests.Response

prearchive¶: Representation of the prearchive on the XNAT server, see xnat.prearchive

projects¶

Listing of all projects on the XNAT server

Returns an XNATListing with elements of ProjectData

put(path, data=None, files=None, json=None, format=None, query=None, accepted_status=None, timeout=None, headers=None)¶

Put the content of a given REST directory.

Parameters:	path (str) – the path of the uri to retrieve (e.g. “/data/archive/projects”) the remained for the uri is constructed automatically data – Dictionary, bytes, or file-like object to send in the body of the `Request`. json – json data to send in the body of the `Request`. files – Dictionary of `'name': file-like-objects` (or `{'name': file-tuple}`) for multipart encoding upload. `file-tuple` can be a 2-tuple `('filename', fileobj)`, 3-tuple `('filename', fileobj, 'content_type')` or a 4-tuple `('filename', fileobj, 'content_type', custom_headers)`, where `'content-type'` is a string defining the content type of the given file and `custom_headers` a dict-like object containing additional headers to add for the file. format (str) – the format of the request, this will add the format= to the query string query (dict) – the values to be added to the query string in the uri accepted_status (list) – a list of the valid values for the return code, default [200, 201] timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout) headers (dict) – the HTTP headers to include
Returns:	the requests reponse
Return type:	requests.Response

scan_types¶: A list of scan types associated with this XNATSession instance

scanners¶: A list of scanners referenced in XNATSession

services¶: Collection of services, see xnat.services

session_expiration_time¶

Get the session expiration time information from the cookies. This returns the timestamp (datetime format) when the session was created and an integer with the session timeout interval.

This can return None if the cookie is not found or cannot be parsed.

Returns:	datetime with last session refresh and integer with timeout in seconds
Return type:	tuple

subjects¶

Listing of all subjects on the XNAT server

Returns an XNATListing with elements of SubjectData

upload(uri, file_, retries=1, query=None, content_type=None, method='put', overwrite=False, timeout=None)¶

Upload data or a file to XNAT

Parameters:

uri (str) – uri to upload to
file – the file handle, path to a file or a string of data (which should not be the path to an existing file!)
retries (int) – amount of times xnatpy should retry in case of failure
query (dict) – extra query string content
content_type – the content type of the file, if not given it will default to application/octet-stream
method (str) – either put (default) or post
overwrite (bool) – indicate if previous data should be overwritten
timeout (float or tuple) – timeout in seconds, float or (connection timeout, read timeout)

Returns:

url_for(obj, query=None, scheme=None)¶: Return the (external) url for a given XNAT object :param XNATBaseObject obj: object to get url for :param query: extra query string parameters :param scheme: scheme to use (when not using original url scheme) :return: external url for the object

users¶: Representation of the users registered on the XNAT server

xnat_version¶: The version of the XNAT server

xnat.session.default_update_func(total)¶

Set up a default update function to be used by the Session.download_stream method. This function configures a progressbar.ProgressBar object which displays progress as a file is downloaded.

Parameters:	total (int) – Total number of bytes to be downloaded (might be `None`)
Returns:	A function to be used as the `update_func` by the `Session.download_stream` method.

`core` Module¶

class xnat.core.CustomVariableMap(parent, field)¶: Bases: xnat.core.VariableMap

class xnat.core.VariableMap(parent, field)¶

Bases: collections.abc.MutableMapping

clearcache()¶

data¶

field¶

xnat¶

class xnat.core.XNATBaseListing(parent, field_name, secondary_lookup_field=None, xsi_type=None, **kwargs)¶

Bases: collections.abc.Mapping, collections.abc.Sequence

clearcache()¶

data¶: The data mapping using the primary key

data_maps¶: The generator function (should be cached) of all the data access properties. They are all generated from the same data, so their caching is shared.

key_map¶: The data mapping using the secondary key

listing¶: The listing view of the data

non_unique_keys¶: Set of non_unique keys

sanitize_name(name)¶

uri¶

xnat_session¶

class xnat.core.XNATBaseObject(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: object

SECONDARY_LOOKUP_FIELD = None¶

caching¶

clearcache()¶

data¶: The data of the current object (data fields only)

del_(name)¶

delete(remove_files=True)¶: Remove the item from XNATSession

external_uri(query=None, scheme=None)¶

Return the external url for this object, not just a REST path

Parameters:	query – extra query string parameters scheme – scheme to use (when not using original url scheme)
Returns:	external url for this object

fieldname¶

fulldata¶: The full data of the current object (incl children, meta etc)

fulluri¶

get(name, type_=None)¶

get_object(fieldname, type_=None)¶

id¶

logger¶

mset(values=None, timeout=None, **kwargs)¶

parent¶

set(name, value, type_=None, timeout=None)¶

Set a field in the current object

Parameters:	name (str) – name of the field value – value to set type – type of the field

uri¶

xnat_session¶

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

class xnat.core.XNATListing(uri, filter=None, **kwargs)¶

Bases: xnat.core.XNATBaseListing

data_maps¶: The generator function (should be cached) of all the data access properties. They are all generated from the same data, so their caching is shared.

filter(filters=None, **kwargs)¶

Create a new filtered listing based on this listing. There are two way of defining the new filters. Either by passing a dict as the first argument, or by adding filters as keyword arguments.

For example::

>>> listing.filter({'ID': 'A*'})
>>> listing.filter(ID='A*')

are equivalent.

Parameters:	filters (dict) – a dictionary containing the filters kwargs (str) – keyword arguments containing the filters
Returns:	new filtered XNATListing
Return type:	XNATListing

static merge_filters(old_filters, extra_filters)¶

tabulate(columns=None, filter=None)¶

Create a table (tuple of namedtuples) from this listing. It is possible to choose the columns and add a filter to the tabulation.

Parameters:	columns (tuple) – names of the variables to use for columns filter (dict) – update filters to use (form of {‘variable’: ‘filter*’}), setting this option will try to merge the filters and throw an error if that is not possible.
Returns:	tabulated data
Return type:	tuple
Raises:	ValueError – if the new filters conflict with the object filters

used_filters¶

class xnat.core.XNATNestedObject(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

clearcache()¶

data¶: The data of the current object (data fields only)

fulldata¶: The full data of the current object (incl children, meta etc)

uri¶

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

class xnat.core.XNATObject(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

data¶: The data of the current object (data fields only)

fulldata¶: The full data of the current object (incl children, meta etc)

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

class xnat.core.XNATSimpleListing(parent, field_name, secondary_lookup_field=None, xsi_type=None, **kwargs)¶

Bases: xnat.core.XNATBaseListing, collections.abc.MutableMapping, collections.abc.MutableSequence

data_maps¶: The generator function (should be cached) of all the data access properties. They are all generated from the same data, so their caching is shared.

fulldata¶

insert(index, value)¶: S.insert(index, value) – insert value before index

xnat_session¶

class xnat.core.XNATSubListing(parent, field_name, secondary_lookup_field=None, xsi_type=None, **kwargs)¶

Bases: xnat.core.XNATBaseListing, collections.abc.MutableMapping, collections.abc.MutableSequence

data_maps¶: The generator function (should be cached) of all the data access properties. They are all generated from the same data, so their caching is shared.

fulldata¶

fulluri¶

insert(index, value)¶: S.insert(index, value) – insert value before index

uri¶

xnat_session¶

xpath¶

class xnat.core.XNATSubObject(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

clearcache()¶

data¶: The data of the current object (data fields only)

fulldata¶: The full data of the current object (incl children, meta etc)

uri¶

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

xnat.core.caching(func)¶: This decorator caches the value in self._cache to avoid data to be retrieved multiple times. This works for properties or functions without arguments.

`inspect` Module¶

class xnat.inspect.Inspect(xnat_session)¶

Bases: object

datafields(datatype, pattern='*', prepend_type=True)¶

datatypes(pattern='*', fields_pattern=None)¶

xnat_session¶

`prearchive` Module¶

class xnat.prearchive.Prearchive(xnat_session)¶

Bases: object

sessions(project=None)¶

Get the session in the prearchive, optionally filtered by project. This function is not cached and returns the results of a query at each call.

Parameters:	project (str) – the project to filter on
Returns:	list of prearchive session found
Return type:	list

xnat_session¶

class xnat.prearchive.PrearchiveFile(uri, xnat_session, id_=None, datafields=None, parent=None, fieldname=None)¶

Bases: xnat.core.XNATBaseObject

data¶: The data of the current object (data fields only)

download(path)¶

Download the file

Parameters:	path (str) – the path to download to
Returns:	the path of the downloaded file
Return type:	str

fulldata¶: The full data of the current object (incl children, meta etc)

name¶: The name of the file

open()¶

size¶: The size of the file

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

class xnat.prearchive.PrearchiveScan(uri, xnat_session, id_=None, datafields=None, parent=None, fieldname=None)¶

Bases: xnat.core.XNATBaseObject

data¶: The data of the current object (data fields only)

dicom_dump(fields=None)¶

Retrieve a dicom dump as a JSON data structure See the XAPI documentation for more detailed information: DICOM Dump Service

Parameters:	fields (list) – Fields to filter for DICOM tags. It can either a tag name or tag number in the format GGGGEEEE (G = Group number, E = Element number)
Returns:	JSON object (dict) representation of DICOM header
Return type:	dict

download(path)¶

Download the scan as a zip

Parameters:	path (str) – the path to download to
Returns:	the path of the downloaded file
Return type:	str

files¶: List of files contained in the scan

fulldata¶: The full data of the current object (incl children, meta etc)

read_dicom(file=None, read_pixel_data=False, force=False)¶

series_description¶: The series description of the scan

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

class xnat.prearchive.PrearchiveSession(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

archive(overwrite=None, quarantine=None, trigger_pipelines=None, project=None, subject=None, experiment=None)¶

Method to archive this prearchive session to the main archive

Parameters:	overwrite (str) – how the handle existing data (none, append, delete) quarantine (bool) – flag to indicate session should be quarantined trigger_pipelines (bool) – indicate that archiving should trigger pipelines project (str) – the project in the archive to assign the session to subject (str) – the subject in the archive to assign the session to experiment (str) – the experiment in the archive to assign the session content to
Returns:	the newly created experiment
Return type:	xnat.classes.ExperimentData

autoarchive¶

data¶: The data of the current object (data fields only)

delete(asynchronous=None)¶

Delete the session from the prearchive

Parameters:	asynchronous (bool) – flag to delete asynchronously
Returns:	requests response

download(path)¶

Method to download the zip of the prearchive session

Parameters:	path (str) – path to download to
Returns:	path of the downloaded zip file
Return type:	str

folder_name¶

fulldata¶: The full data of the current object (incl children, meta etc)

id¶: A unique ID for the session in the prearchive :return:

label¶

lastmod¶

move(new_project, asynchronous=None)¶

Move the session to a different project in the prearchive

Parameters:	new_project (str) – the id of the project to move to asynchronous (bool) – flag to move asynchronously
Returns:	requests response

name¶

prevent_anon¶

prevent_auto_commit¶

project¶

rebuild(asynchronous=None)¶

Rebuilt the session in the prearchive

Parameters:	asynchronous (bool) – flag to rebuild asynchronously
Returns:	requests response

scan_date¶

scan_time¶

scans¶: List of scans in the prearchive session

status¶

subject¶

tag¶

timestamp¶

uploaded¶: Datetime when the session was uploaded

xpath¶: The xpath of the object as seen from the root of the data. Used for setting fields in the object.

`services` Module¶

class xnat.services.Services(xnat_session)¶

Bases: object

The class representing all service functions in XNAT found in the /data/services REST directory

dicom_dump(src, fields=None)¶

Retrieve a dicom dump as a JSON data structure See the XAPI documentation for more detailed information: DICOM Dump Service

Parameters:	src (str) – The url of the scan to generate the DICOM dump for fields (list) – Fields to filter for DICOM tags. It can either a tag name or tag number in the format GGGGEEEE (G = Group number, E = Element number)
Returns:	JSON object (dict) representation of DICOM header
Return type:	dict

import_(path, overwrite=None, quarantine=False, destination=None, trigger_pipelines=None, project=None, subject=None, experiment=None, content_type=None)¶

Import a file into XNAT using the import service. See the XNAT wiki for a detailed explanation.

Parameters:

path (str) – local path of the file to upload and import
overwrite (str) – how the handle existing data (none, append, delete)
quarantine (bool) – flag to indicate session should be quarantined
trigger_pipelines (bool) – indicate that archiving should trigger pipelines
destination (str) – the destination to upload the scan to
project (str) – the project in the archive to assign the session to
subject (str) – the subject in the archive to assign the session to
experiment (str) – the experiment in the archive to assign the session content to
content_type (str) – overwite the content_type (by the mimetype will be guessed)

Returns:

issue_token(user=None)¶

Issue a login token, by default for the current logged in user. If username is given, for that user. To issue tokens for other users you must be an admin.

Parameters:	user (str) – User to issue token for, default is current user
Returns:	Token in a named tuple (alias, secret)

xnat_session¶

class xnat.services.TokenResult(alias, secret)¶

Bases: tuple

alias¶: Alias for field number 0

secret¶: Alias for field number 1

`users` Module¶

class xnat.users.User(data)¶

Bases: object

Representation of a user on the connected XNAT systen

data¶

email¶: The email of the user

first_name¶: The first name of the user

id¶: The id of the user

last_name¶: The last name of the user

login¶: The login name of the user

class xnat.users.Users(xnat_session)¶

Bases: collections.abc.Mapping

Listing of the users on the connected XNAT installation

data¶

xnat_session¶

`xnatbases` Module¶

class xnat.xnatbases.AbstractResource(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, data_dir=None, upload_method=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

SECONDARY_LOOKUP_FIELD = 'label'¶

data¶: The data of the current object (data fields only)

download(path, verbose=True)¶

download_dir(target_dir, verbose=True)¶

Download the entire resource and unpack it in a given directory

Parameters:	target_dir (str) – directory to unpack to verbose (bool) – show progress

file_count¶

file_size¶

files¶

fulldata¶: The full data of the current object (incl children, meta etc)

upload(data, remotepath, overwrite=False, extract=False, **kwargs)¶

upload_dir(directory, overwrite=False, method='tgz_file', **kwargs)¶

Upload a directory to an XNAT resource. This means that if you do resource.upload_dir(directory) that if there is a file directory/a.txt it will be uploaded to resource/files/a.txt

The method has 5 options, default is tgz_file:

per_file: Scans the directory and uploads file by file
tar_memory: Create a tar archive in memory and upload it in one go
tgz_memory: Create a gzipped tar file in memory and upload that
tar_file: Create a temporary tar file and upload that
tgz_file: Create a temporary gzipped tar file and upload that

The considerations are that sometimes you can fit things in memory so you can save disk IO by putting it in memory. The per file does not create additional archives, but has one request per file so might be slow when uploading many files.

Parameters:	directory (str) – The directory to upload overwrite (bool) – Flag to force overwriting of files method (str) – The method to use

class xnat.xnatbases.DerivedData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

create_resource(label, format=None, data_dir=None, method=None)¶

download(path, verbose=True)¶

files¶

fulluri¶

resources¶

class xnat.xnatbases.ExperimentData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

SECONDARY_LOOKUP_FIELD = 'label'¶

label¶

class xnat.xnatbases.ImageScanData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

SECONDARY_LOOKUP_FIELD = 'type'¶

create_resource(label, format=None, data_dir=None, method='tgz_file')¶

dicom_dump(fields=None)¶

Retrieve a dicom dump as a JSON data structure See the XAPI documentation for more detailed information: DICOM Dump Service

Parameters:	fields (list) – Fields to filter for DICOM tags. It can either a tag name or tag number in the format GGGGEEEE (G = Group number, E = Element number)
Returns:	JSON object (dict) representation of DICOM header
Return type:	dict

download(path, verbose=True)¶

download_dir(target_dir, verbose=True)¶

files¶

read_dicom(file=None, read_pixel_data=False, force=False)¶

resources¶

class xnat.xnatbases.ImageSessionData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

create_assessor(label, type_)¶

download(path, verbose=True)¶

download_dir(target_dir, verbose=True)¶

Download the entire experiment and unpack it in a given directory. Note that this method will create a directory structure following $target_dir/{experiment.label} and unzip the experiment zips as given by XNAT into that. If the $target_dir/{experiment.label} does not exist, it will be created.

Parameters:	target_dir (str) – directory to create experiment directory in verbose (bool) – show progress

files¶

share(project, label=None)¶

class xnat.xnatbases.ProjectData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

SECONDARY_LOOKUP_FIELD = 'name'¶

download_dir(target_dir, verbose=True)¶

Download the entire project and unpack it in a given directory. Note that this method will create a directory structure following $target_dir/{project.name}/{subject.label}/{experiment.label} and unzip the experiment zips as given by XNAT into that. If the $target_dir/{project.name} does not exist, it will be created.

Parameters:	target_dir (str) – directory to create project directory in verbose (bool) – show progress

experiments¶

files¶

fulluri¶

resources¶

subjects¶

class xnat.xnatbases.SubjectAssessorData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

fulluri¶

subject¶

class xnat.xnatbases.SubjectData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.core.XNATBaseObject

SECONDARY_LOOKUP_FIELD = 'label'¶

download_dir(target_dir, verbose=True)¶

Download the entire subject and unpack it in a given directory. Note that this method will create a directory structure following $target_dir/{subject.label}/{experiment.label} and unzip the experiment zips as given by XNAT into that. If the $target_dir/{subject.label} does not exist, it will be created.

Parameters:	target_dir (str) – directory to create subject directory in verbose (bool) – show progress

files¶

fulluri¶

label¶

share(project, label=None)¶

Generated XSD classes¶

`XSD Classes` Documentation¶

This is an overview of all generated classes based on the XSD files of central.xnat.org, without any extension types (only the default XSD files that come with XNAT 1.7)

class xnat.classes.AbstractDemographicData(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶: Bases: xnat.classes.XNATNestedObjectMixin

class xnat.classes.AbstractProtocol(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶

Bases: xnat.classes.XNATNestedObjectMixin

data_type¶: Property of type: str

description¶: Property of type: str

id¶: Property of type: str

name¶: Property of type: str

class xnat.classes.AbstractResource(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, data_dir=None, upload_method=None, **kwargs)¶

Bases: xnat.classes.XNATObjectMixin

SECONDARY_LOOKUP_FIELD = 'label'¶

data¶: The data of the current object (data fields only)

download(path, verbose=True)¶

download_dir(target_dir, verbose=True)¶

Download the entire resource and unpack it in a given directory

Parameters:	target_dir (str) – directory to unpack to verbose (bool) – show progress

file_count¶

file_size¶

files¶

fulldata¶: The full data of the current object (incl children, meta etc)

label¶: Property of type: str

note¶: Property of type: str

tags¶: listing of xnat.classes.AbstractResourceTags

upload(data, remotepath, overwrite=False, extract=False, **kwargs)¶

upload_dir(directory, overwrite=False, method='tgz_file', **kwargs)¶

Upload a directory to an XNAT resource. This means that if you do resource.upload_dir(directory) that if there is a file directory/a.txt it will be uploaded to resource/files/a.txt

The method has 5 options, default is tgz_file:

per_file: Scans the directory and uploads file by file
tar_memory: Create a tar archive in memory and upload it in one go
tgz_memory: Create a gzipped tar file in memory and upload that
tar_file: Create a temporary tar file and upload that
tgz_file: Create a temporary gzipped tar file and upload that

The considerations are that sometimes you can fit things in memory so you can save disk IO by putting it in memory. The per file does not create additional archives, but has one request per file so might be slow when uploading many files.

Parameters:	directory (str) – The directory to upload overwrite (bool) – Flag to force overwriting of files method (str) – The method to use

class xnat.classes.AbstractResourceTags(uri=None, xnat_session=None, id_=None, datafields=None, parent=None, fieldname=None, overwrites=None, **kwargs)¶