API Reference¶

Authentication¶

yaxil.test_auth(auth)¶

Validate credentials against XNAT

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> yaxil.test_auth(auth)
True

yaxil.auth2(alias=None, host=None, username=None, password=None, cfg='~/.xnat_auth')¶

Create authentication object from an xnat_auth file, function arguments, or environment variables (XNAT_HOST, XNAT_USER, and XNAT_PASS), in that order

Example:

>>> import os
>>> import yaxil
>>> os.environ['XNAT_HOST'] = 'https://xnat.example.com'
>>> os.environ['XNAT_USER'] = 'username'
>>> os.environ['XNAT_PASS'] = '*****'
>>> yaxil.auth2()
XnatAuth(url='https://xnat.example.com', username='username', password='*****')

yaxil.auth(alias=None, url=None, cfg='~/.xnat_auth')¶

Read connection details from an xnat_auth XML file

Example:

>>> import yaxil
>>> yaxil.auth('doctest')
XnatAuth(url='...', username='...', password='...')

Parameters:

alias (str) – XNAT alias
url (str) – XNAT URL
cfg (str) – Configuration file

Returns:

Named tuple of (url, username, password)

Return type:

yaxil.XnatAuth

Session¶

yaxil.session(auth)¶

Create a session context to avoid passing auth to every function.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> with yaxil.session(auth) as ses:
...   aid = ses.accession('TestSession01')
...   print(aid)
XNAT_E...

Parameters:: auth (yaxil.XnatAuth) – XNAT authentication
Returns:: YAXIL session object
Return type:: yaxil.session.Session

Subjects¶

yaxil.subjects(auth, label=None, project=None)¶

Retrieve Subject tuples for subjects returned by this function.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> for subject in yaxil.subjects(auth, project='TestProject01'):
...   print(subject)
Subject(uri='/data/subjects/XNAT_S...', label='...',
    id='XNAT_S...', project='TestProject01')

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication
label (str) – XNAT Subject label
project (str) – XNAT Subject Project

Returns:

Subject objects

Return type:

yaxil.Subject

Experiments¶

yaxil.experiments(auth, label=None, project=None, subject=None, daterange=None, insert_daterange=None)¶

Retrieve Experiment tuples for experiments returned by this function.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> for experiment in yaxil.experiments(auth, 'TestSession01'):
...   print(experiment)
Experiment(uri='...', label='...', id='...', project='...', 
  subject_id='...', subject_label='...', archived_date='...')
>>>

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication
label (str) – XNAT Experiment label
project (str) – XNAT Experiment Project
subject (yaxil.Subject) – YAXIL Subject
daterange (tuple) – Start and end dates
insert_daterange (tuple) – Insertion start and end dates

Returns:

Experiment object

Return type:

yaxil.Experiment

Scans¶

yaxil.scansearch(auth, label, filt, project=None, aid=None)¶

Search for scans by supplying a set of SQL-based conditionals.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> query = {
...   'sr': 'note LIKE "%Structured Report%"',
...   'anat': 'series_description="t1_mpr_1mm_p2_pos50" OR note LIKE "%ANAT%"'
... }
>>> result = yaxil.scansearch(auth, 'TestSession01', query)
>>> print(json.dumps(result, indent=2))
{
  "sr": [
    "99"
  ],
  "anat": [
    "4"
  ]
}

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication object
label (str) – XNAT MR Session label
filt (dict) – Scan search filter/query
project (str) – XNAT MR Session project
aid (str) – XNAT Accession ID

Returns:

Same dictionary that was passed in, but values are now matching scans

Return type:

dict

yaxil.scans(auth, label=None, scan_ids=None, project=None, experiment=None)¶

Get scan information for a MR Session as a sequence of dictionaries

Example:

>>> import json
>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> for scan in yaxil.scans(auth, 'TestSession01'):
...   print(json.dumps(scan, indent=2))
{
  "ID": "...",
  "date_archived": "...",
  ...
}
{
  "ID": "...",
  "date_archived": "...",
  ...
}
...

yaxil.download(auth, label, scan_ids=None, project=None, aid=None, out_dir='.', in_mem=True, progress=False, attempts=1, out_format='flat')¶

Download scan data from XNAT.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> yaxil.download(auth, 'TestSession01', ['1', '2'], out_dir='./data')

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication object
label (str) – XNAT MR Session label
scan_ids (list) – Scan numbers to return; use None for all
project (str) – XNAT MR Session project
aid (str) – XNAT Accession ID
out_dir (str) – Output directory
out_format – Extract all files or leave native structure
in_mem (bool) – Keep download content in memory; faster but uses more memory
progress (int) – Show download progress every N bytes
attempts (int) – Number of download attempts

Miscellaneous¶

yaxil.accession(auth, label, project=None)¶

Get the Accession ID for any Experiment.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> yaxil.accession(auth, 'TestSession01')
'XNAT_E...'

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication
label (str) – XNAT Experiment label
project (str) – XNAT Experiment Project

Returns:

Accession ID

Return type:

str

yaxil.has(auth, xsitype, project=None)¶

Test if a project contains any items of a particular xsi:type.

Example:

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> yaxil.has(auth, 'neuroinfo:anatqc', project='TestProject01')
True

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication
xsitype – XNAT xsi:type
xsitype – str
project (str) – XNAT Project

Returns:

True or False

Return type:

bool

yaxil.exists(auth, xnatid, datatype='experiments')¶

Test if an object exists

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication
xnatid – XNAT object ID
xnatid – str
datatype (str) – XNAT data type

Returns:

True or False

Return type:

bool

yaxil.get(auth, path, autobox=False, fmt=None, params=None)¶

Make a GET request to XNAT and optionally autobox the response content. Autoboxing will convert the response content to an lxml.etree object for XML, dict for JSON, or csv.reader for CSV.

Example::

>>> import yaxil
>>> auth = yaxil.auth('doctest')
>>> path = '/data/config'
>>> yaxil.get(auth, path).content
b'...'

yaxil.storerest(auth, artifacts_dir, resource_name)¶

Store data into XNAT over REST API

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication
artifacts_dir (str) – Filesystem location of assessor artifacts
resource_name (str) – Resource name

Assessments: neuroinfo¶

yaxil.assessments.neuroinfo.session(auth)¶

Create a session context to avoid explicitly passing authentication to every function.

Example:

>>> import json
>>> import yaxil.assessments.neuroinfo as neuroinfo
>>> auth = yaxil.auth('doctest')
>>> with neuroinfo.session(auth) as ses:
...   for qc in ses.anatqc('TestSession01'):
...     print(json.dumps(qc, indent=2))
{
  "id": "TestSession01_ANAT_30_AQC",
  ...
}

Parameters:: auth (yaxil.XnatAuth) – XNAT authentication
Returns:: YAXIL session object
Return type:: yaxil.assessments.neuroinfo.session.Session

yaxil.assessments.neuroinfo.boldqc(auth, label=None, scan_ids=None, project=None, aid=None)¶

Get BOLDQC data as a sequence of dictionaries.

Example:

>>> import json
>>> import yaxil.assessments.neuroinfo as neuroinfo
>>> auth = yaxil.auth('doctest')
>>> for qc in neuroinfo.boldqc(auth, 'TestSession01'):
...   print(json.dumps(qc, indent=2))
{
  "id": "TestSession01_BOLD_17_EQC",
  ...
}

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication object
label (str) – XNAT MR Session label
scan_ids (list) – Scan numbers to include
project (str) – XNAT MR Session project
aid (str) – XNAT MR Session Accession ID

Returns:

Generator of BOLDQC data dictionaries

Return type:

dict

yaxil.assessments.neuroinfo.anatqc(auth, label, scan_ids=None, project=None, aid=None)¶

Get AnatQC data as a sequence of dictionaries.

Example:

>>> import json
>>> import yaxil.assessments.neuroinfo as neuroinfo
>>> auth = yaxil.auth('doctest')
>>> for qc in neuroinfo.anatqc(auth, 'TestSession01'):
...   print(json.dumps(qc, indent=2))
{
  "id": "TestSession01_ANAT_30_AQC",
  ...
}

Parameters:

auth (yaxil.XnatAuth) – XNAT authentication object
label (str) – XNAT MR Session label
scan_ids (list) – Scan numbers to include
project (str) – XNAT MR Session project
aid (str) – XNAT MR Session Accession ID

Returns:

Generator of AnatQC data dictionaries

Return type:

dict

Lower-Level Classes¶

class yaxil.XnatAuth(url, username, password, cookie)¶: Container to hold XNAT authentication information. Fields include the url, username, and password.

class yaxil.Format¶: A container to hold possible XNAT response formats Format.JSON, Format.XML, and Format.CSV.

class yaxil.Experiment(uri, label, id, project, subject_id, subject_label, archived_date, note)¶: Container to hold XNAT Experiment information. Fields include the Experiment URI uri, Accession ID id, Project project, Label label, Subject Accession ID subject_id, Subject label subject_label, and archive date archived_date.

class yaxil.Subject(uri, label, id, project)¶: Container to hold XNAT Subject information. Fields include the Subject URI uri, Accession ID id, Project project, and Label label.

API Reference¶

Authentication¶

Session¶

Subjects¶

Experiments¶

Scans¶

Miscellaneous¶

Assessments: neuroinfo¶

Lower-Level Classes¶

YAXIL

Navigation

Related Topics