datman.xnat module

Module to interact with the xnat server

class datman.xnat.XNATExperiment(project, subject_name, experiment_json)[source]

Bases: datman.xnat.XNATObject

assign_scan_names(config, ident)[source]

Assign a datman style name to each scan in this experiment.

This will populate the XnatScan.names and XnatScan.tags fields for any scan that matches the study’s export configuration.

Parameters
download(xnat, dest_folder, zip_name=None)[source]

Download a zip file containing all data for this session. Returns the path to the new file if download is successful, raises an exception if not

Parameters

  • xnat – An instance of datman.xnat.xnat()

  • dest_folder – The absolute path to the folder where the zip should be deposited

  • zip_name – An optional name for the output zip file. If not set the zip name will be session.name

get_autorun_ids(xnat)[source]

Find the ID(s) of the ‘autorun.xml’ workflow

XNAT has this obnoxious, on-by-default and seemingly impossible to disable, ‘workflow’ called AutoRun.xml. It appears to do nothing other than prevent certain actions (like renaming subjects/experiments) if it is stuck in the running or queued state. This will grab the autorun ID for this experiment so that it can be modified.

Sometimes more than one pipeline gets launched for a subject even though the GUI only reports one. This will grab the ID for all of them.

Returns

A list of string reference IDs that can be used to change

the status of the pipeline for this subject using XNAT’s API, or the empty string if the pipeline is not found.

Return type

list

Raises

XnatException – If no AutoRun.xml pipeline instance is found or the API response can’t be parsed.

get_resources(xnat_connection)[source]

Returns a list of all resource URIs from this session.

is_shared()[source]

Detect if the experiment is shared from another XNAT Project.

Shared sessions have identical metadata to their source sessions, the only way to tell a link apart from source data is to look for a ‘sharing/share’ entry and check its xnat label.

class datman.xnat.XNATObject[source]

Bases: abc.ABC

class datman.xnat.XNATScan(experiment, scan_json)[source]

Bases: datman.xnat.XNATObject

download(xnat_conn, output_dir)[source]

Download all dicoms for this series.

This will download all files in the series, and if successful, set the download_dir attribute to the destination folder.

Parameters

  • xnat_conn (datman.xnat.xnat) – An open xnat connection to the server to download from.

  • output_dir (str) – The full path to the location to download all files to.

Returns

True if the series was downloaded, False otherwise.

Return type

bool

is_derived()[source]
is_multiecho()[source]
is_usable(strict=False)[source]
raw_dicoms_exist()[source]
set_datman_name(base_name, tags)[source]
set_tag(tag_map)[source]
class datman.xnat.XNATSubject(subject_json)[source]

Bases: datman.xnat.XNATObject

datman.xnat.get_auth(username=None, file_path=None)[source]
datman.xnat.get_connection(config, site=None, url=None, auth=None, server_cache=None)[source]

Create (or retrieve) a connection to an XNAT server

Parameters

  • config (datman.config.config) – A study’s configuration

  • site (str, optional) – A valid site for the current study. If given, site-specific settings will be searched for before defaulting to study or organization wide settings. Defaults to None.

  • url (str, optional) – An XNAT server URL. If given the configuration will NOT be consulted. Defaults to None.

  • auth (tuple, optional) – A (username, password) tuple. If given configuration / environment variables will NOT be consulted. Defaults to None.

  • server_cache (dict, optional) – A dictionary used to map URLs to open XNAT connections. If given, connections will be retrieved from the cache as needed or added if a new URL is requested. Defaults to None.

Raises

XnatException – If a connection can’t be made.

Returns

A connection to the required XNAT server.

Return type

datman.xnat.xnat

datman.xnat.get_port_str(config=None, port=None)[source]

Returns a port string of the format :portnum

Will raise KeyError if port is None and config file doesn’t define XnatPort

datman.xnat.get_server(config=None, url=None, port=None)[source]
class datman.xnat.xnat(server, username, password)[source]

Bases: object

auth = None
create_resource_folder(study, session, experiment, label)[source]

Creates a resource subfolder and returns the xnat identifier.

delete_resource(project, session, experiment, resource_group_id, resource_id, retries=3)[source]

Delete a resource file from xnat

dismiss_autorun(experiment)[source]

Mark the AutoRun.xml pipeline as finished.

AutoRun.xml gets stuck as ‘Queued’ and can cause failures at renaming and deletion. This marks the pipeline as ‘Complete’ to prevent it from interfering.

Parameters

subject (datman.xnat.XNATExperiment) – An XNAT experiment to dismiss the pipeline for.

find_project(subject_id, projects=None)[source]

Find the project a subject belongs to.

Parameters

  • subject_id (str) – The subject to search for.

  • projects (list, optional) – A list of projects to restrict the search to. Defaults to None.

Returns

The name of the XNAT project the subject belongs to. Note:

if the same ID is found in more than one project only the first match is returned.

Return type

str

find_subject(project, exper_id)[source]

Find the parent subject ID for an experiment.

Parameters

  • project (str) – An XNAT project to search.

  • exper_id (str) – The experiment to find the parent ID for.

Returns

The ID of the parent subject. Note that this returns the ID,

not the label. The label and ID can be used interchangeably to query XNAT but the ID tends to not conform to any naming convention.

Return type

str

get_dicom(project, session, experiment, scan, filename=None, retries=3)[source]

Downloads a dicom file from xnat to filename If filename is not specified creates a temporary file and returns the path to that, user needs to be responsible for cleaning up any created tempfiles

get_experiment(project, subject_id, exper_id, create=False)[source]

Get an experiment from the XNAT server.

Parameters

  • project (str) – The XNAT project to search within.

  • subject_id (str) – The XNAT subject to search.

  • exper_id (str) – The name of the experiment to retrieve.

  • create (bool, optional) – Whether to create an experiment matching exper_id if a match is not found. Defaults to False.

Raises

XnatException – If the experiment doesn’t exist and can’t be made or the server/API can’t be accessed.

Returns

An XNATExperiment instance

matching the given experiment ID.

Return type

datman.xnat.XNATExperiment

get_experiment_ids(project, subject='')[source]

Retrieve all experiment IDs belonging to an XNAT subject.

Parameters

  • project (str) – An XNAT project ID.

  • subject (str, optional) – An existing XNAT subject within ‘project’ to restrict the search to. Defaults to ‘’.

Raises

XnatException – If server/API access fails.

Returns

A list of string experiment IDs belonging to ‘subject’.

Return type

list

get_projects(project='')[source]

Query the XNAT server for project metadata.

Parameters

project (str, optional) – The name of an XNAT project to search for. If unset, metadata from all accessible projects on the server will be returned. Defaults to the empty string.

Raises

XnatException – If failure is experienced while attempting to access the server’s API.

Returns

A list with one dictionary for each study found. Beware - the

formats of the dictionaries returned by a server-wide versus a single project search differ greatly in structure. This is a consequence of XNAT’s API.

Return type

list

get_resource(project, session, experiment, resource_group_id, resource_id, filename=None, retries=3, zipped=True)[source]

Download a single resource from xnat to filename If filename is not specified creates a temporary file and returns the path to that, user needs to be responsible for cleaning up any created tempfiles

get_resource_archive(project, session, experiment, resource_id, filename=None, retries=3)[source]

Download a resource archive from xnat to filename If filename is not specified creates a temporary file and returns the path to that, user needs to be responsible format cleaning up any created tempfiles

get_resource_ids(study, session, experiment, folderName=None, create=True)[source]

Return a list of resource id’s (subfolders) from an experiment

get_resource_list(study, session, experiment, resource_id)[source]

The list of non-dicom resources associated with an experiment returns a list of dicts, mostly interested in ID and name

get_scan(project, subject_id, exper_id, scan_id)[source]

Get a scan from the XNAT server.

Parameters

  • project (str) – The XNAT project to search within.

  • subject_id (str) – The XNAT subject to search.

  • exper_id (str) – The XNAT experiment to search.

  • scan_id (str) – The ID of the scan to retrieve.

Raises

XnatException – If the scan does not exist or the server/API can’t be accessed.

Returns

An XNATScan instance matching the

scan ID from the given experiment.

Return type

datman.xnat.XNATScan

get_scan_ids(project, subject, experiment)[source]

Retrieve all scan IDs for an XNAT experiment.

Parameters

  • project (str) – An XNAT project ID.

  • subject (str) – An existing subject within ‘project’.

  • experiment (str) – An existing experiment within ‘subject’.

Raises

XnatException – If server/API access fails.

Returns

A list of scan IDs belonging to ‘experiment’.

Return type

list

get_subject(project, subject_id, create=False)[source]

Get a subject from the XNAT server.

Parameters

  • project (str) – The XNAT project to search within.

  • subject_id (str) – The XNAT subject to retrieve.

  • create (bool, optional) – Whether to create a subject matching subject_id if a match is not found. Defaults to False.

Raises

XnatException – If access through the API failed or if the subject does not exist and can’t be made.

Returns

An XNATSubject instance matching

the given subject ID.

Return type

datman.xnat.XNATSubject

get_subject_ids(project)[source]

Retrieve the IDs for all subjects within an XNAT project.

Parameters

project (str) – The ‘Project ID’ for a project on XNAT.

Raises

XnatException – If the project does not exist or access fails.

Returns

A list of string subject IDs found within the project.

Return type

list

headers = None
make_experiment(project, subject, experiment)[source]

Make a new (empty) experiment on the XNAT server.

Parameters

  • project (str) – The ‘Project ID’ of an existing XNAT project.

  • subject (str) – The subject that should own the experiment.

  • experiment (str) – The ID to create the new experiment under.

Raises

XnatException – If experiment creation fails.

make_subject(project, subject)[source]

Make a new (empty) subject on the XNAT server.

Parameters

  • project (str) – The ‘Project ID’ of an existing XNAT project.

  • subject (str) – The ID to create the new subject under.

Raises

XnatException – If subject creation fails.

open_session()[source]

Open a session with the XNAT server.

put_dicoms(project, subject, experiment, filename, retries=3)[source]

Upload an archive of dicoms to XNAT filename: archive to upload

put_resource(project, subject, experiment, filename, data, folder, retries=3)[source]

POST a resource file to the xnat server

Parameters

  • filename – string to store filename as

  • data – string containing data (such as produced by zipfile.ZipFile.read())

rename_experiment(project, subject, old_name, new_name)[source]

Change an experiment’s name on XNAT.

Parameters

  • project (str) – The name of the project the experiment can be found in.

  • subject (str) – The ID of the subject this experiment belongs to.

  • old_name (str) – The current experiment name.

  • new_name (str) – The new name to give the experiment.

Raises

  • XnatException – If unable to rename the experiment because: 1) The experiment doesnt exist 2) A stuck AutoRun.xml pipeline can’t be dismissed 3) An experiment exists under ‘new_name’ already

  • requests.HTTPError – If any unexpected behavior is experienced while interacting with XNAT’s API

rename_subject(project, old_name, new_name, rename_exp=False)[source]

Change a subjects’s name on XNAT.

Parameters

  • project (str) – The name of the XNAT project that the subject belongs to.

  • old_name (str) – The current name on XNAT of the subject to be renamed.

  • new_name (str) – The new name to apply.

  • rename_exp (bool, optional) – Also change the experiment name to the new subject name. Obviously, this should NOT be used when subjects and experiments are meant to use different naming conventions. Defaults to False.

Raises

  • XnatException – If unable to rename the subject (or the experiment if rename_exp=True) because: 1) The subject doesn’t exist. 2) A stuck AutoRun.xml pipeline can’t be dismissed 3) A subject exists under the ‘new_name’ already

  • requests.HTTPError – If any unexpected behavior is experienced while interacting with XNAT’s API

server = None
session = None
share_experiment(source_project, source_sub, source_exp, dest_project, dest_exp)[source]

Share an experiment into a new xnat project.

Note: The subject the experiment belongs to must have already been shared to the destination project for experiment sharing to work.

Parameters

  • source_project (str) – The original project the experiment belongs to.

  • source_sub (str) – The original subject ID in the source project.

  • source_exp (str) – The original experiment name in the source project.

  • dest_project (str) – The project the experiment is to be added to.

  • dest_exp (str) – The name to apply to the experiment when it is added to the destination project.

Raises

  • XnatException – If the destination experiment ID is already in use or the source experiment ID doesnt exist.

  • requests.HTTPError – If any unexpected behavior is experienced while interacting with XNAT’s API.

share_subject(source_project, source_sub, dest_project, dest_sub)[source]

Share an xnat subject into another project.

Parameters

  • source_project (str) – The name of the original project the subject was uploaded to.

  • source_sub (str) – The original ID of the subject to be shared.

  • dest_project (str) – The new project to add the subject to.

  • dest_sub (str) – The ID to give the subject in the destination project.

Raises

  • XnatException – If the destination subject ID is already in use or the source subject doesn’t exist.

  • requests.HTTPError – If any unexpected behavior is experienced while interacting with XNAT’s API