AslImage module

OXASL - Classes for representing ASL data and constructing instances from command line parameters

Copyright (c) 2008-2020 Univerisity of Oxford

class oxasl.image.AslImage(image, name=None, **kwargs)

Subclass of fsl.data.image.Image which adds ASL structure information

An AslImage contains information about the structure of the data enabling it to perform operations such as reordering and label/control differencing.

As a minimum you must provide a means of determining the number of TIs/PLDs in the data. Specifying the data format and ordering explicitly is recommended, but a default ordering will be used (with a warning) if you do not.

Ordering can be defined in two ways:

1. Setting the order parameters to a sequence of characters (case insensitive):

• l - Labelling images (e.g. label/control pairs, sequence of multi-phases, vessel encoding cycles)
• t - TIs/PLDs
• r - Repeats
• e - TEs (optional)

The sequence is in order from fastest varying (innermost grouping) to slowest varying (outermost grouping). If l is not included this describes data which is already differenced.

2. Specifying the ibf option

• ibf - rpt Blocked by repeats, i.e. first repeat of all TIs, followed by second repeat of all TIs…

  tis Blocked by TIs/PLDs, i.e. all repeats of first TI, followed by all repeats of second TI… When using –ibf, the labelling images (e.g. label/control pairs) are always adjacent

The data format is defined using the iaf parameter:

• iaf - tc = tag then control, ct = control then tag, mp = multiphase, ve = vessel encoded, vediff = Pairwise subtracted vessel encoded, diff = already differenced, hadamard` = Hadamard encoded, ``quant = already quantified

Variables:

• nvols – Number of volumes in data
• iaf – Data format - see above
• order – Data ordering string - see above
• ntc – Number of labelling images in data (e.g. 2 for TC pairs, 1 for differenced data, for vessel encoded or multiphase data the number of encoding cycles/phases, for Hadamard data the size of the Hadamard matrix, e.g. 8)
• casl – If True, acquisition was CASL/pCASL rather than PASL
• phases – List of phases for multiphase data (iaf='mp')
• ntis – Number of TIs/PLDs
• tis – Optional list of TIs
• plds – Optional list of PLDs
• have_plds – True if PLDs were provided rather than TIs
• tau – Bolus durations - one per TI/PLD. If have_plds is True, tis are derived by adding the bolus duration to the PLDs
• rpts – Repeats, one value per TI (may be given as a constant but always stored as list)
• slicedt – Increase in TI/PLD per slice in z dimension for 2D acquisitions (default: 0)
• sliceband – Number of slices per band for multiband acquisitions (default: None)
• artsupp – If True, data was acquired with arterial suppression

derived(image, name=None, suffix='', **kwargs)

Create a derived ASL image based on this one, but with different data

This is only possible if the number of volumes match, otherwise we cannot use the existing information about TIs, repeats etc. If the number of volumes do not match a generic Image is returned instead

Any further keyword parameters are passed to the AslImage constructor, overriding existing attributes, so this can be used to create a derived image with different numbers of repeats, etc, provided the data is consistent with this.

Note that the image space does not have to match, however in this case the ‘header’ kwarg should be passed to create the new image header

Parameters:

• data – Numpy data for derived image
• name – Name for new image (can be simple name or full filename)
• suffix – If name not specified, construct by adding suffix to original image name

Returns:

derived AslImage. However if the AslImage constructor fails, a basic fsl.data.image.Image is returned and a warning is output.

diff(name=None)

Perform tag-control subtraction.

Data will be reordered so the tag/control pairs are together

Note that currently differencing is not supported for multiphase or vessel encoded data. For Hadamard data, the output will be the decoded sub-boli images.

Parameters:name – Optional name for returned image. Defaults to original name with suffix _diff Returns:AslImage instance containing differenced data

get_vol_index(label_idx, ti_idx, rpt_idx, te_idx=0, order=None)

Get the volume index for a specified label, TI and repeat index

Parameters:

• label_idx – Label index starting from 0, e.g. for iaf=ct 0 would be the control image, for iaf=mp 3 would be the 4th phase encoded image
• ti_idx – TI/PLD index, starting from 0
• rpt_idx – Repeat index, starting from 0
• te_idx – TE index for multi-TE data, starting from 0
• order – If specified use custom data ordering string (does not change ordering within this AslImage - use reorder for that)

is_var_repeats()

Returns:True if this data set has repeats which vary by time point

mean(name=None)

Take the mean across all volumes

This takes a naive mean without differencing or grouping by TIs

Parameters:name – Optional name for returned image. Defaults to original name with suffix _mean Returns:3D fsl.data.image.Image. Not an AslImage as timing information has been lost

mean_across_repeats(name=None, diff=True)

Calculate the mean ASL signal across all repeats

Parameters:

• name – Optional name for returned image. Defaults to original name with suffix _mean
• diff – If False do not difference the data before taking the mean (default: True)

Returns:

Label-control subtracted AslImage with one volume per TI/PLD

metadata_summary()

Generate a human-readable dictionary of metadata

Returns:Dictionary mapping human readable metadata name to value (e.g. ‘Label type’ might map to ‘Label-control pairs’). The keys and values are not guaranteed to be fixed and should not be parsed - use the instance attributes instead.

perf_weighted(name=None)

Generate a perfusion weighted image by taking the mean over repeats and then the mean over TIs

Parameters:name – Optional name for returned image. Defaults to original name with suffix _pwi Returns:3D fsl.data.image.Image. Not an AslImage as timing information lost

reorder(out_order=None, iaf=None, name=None)

Re-order ASL data

The order is defined by a string in which r=repeats, l=labelling images, and t=tis/plds. The first character is the fastest varying

So for a tag-control data set with 3 TIs and 2 repeats an order of “ltr” would be: TC (TI1), TC (TI2), TC (TI3), TC(TI1, repeat 2), TC(TI2 repeat 2), etc.

single_ti(ti_idx, order=None, name=None)

Extract the subset of data for a single TI/PLD

FIXME will not correctly set have_plds flag in output if input has PLDs

Parameters:

• ti_idx – Index of the TI/PLD required starting from 0
• order – If specified the ordering string for the returned data
• name – Optional name for returned image. Defaults to original name with suffix _ti<n> where <n> is the TI/PLD index

Returns:

AslImage instance containing data only for the selected TI/PLD

split_epochs(epoch_size, overlap=0, time_order=None)

Split ASL data into ‘epochs’ of a specified size, with optional overlap

summary(log=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Write a summary of the data to a file stream

Parameters:log – Stream-like object to write the summary to. Defaults to sys.stdout

class oxasl.image.Options(fname_opt='-i')

OptionGroup which contains options for describing an ASL image

groups(parser)

Parameters:parser – OptionParser instance Returns:Sequence of OptionGroup instances for this category of options

oxasl.image.data_order(iaf, ibf, order, multite=False)

Determine the data format and ordering from iaf and ibf options

If iaf is not specified (None or empty string), TC pairs are specified if the order parameter is given and contains the l character. Otherwise differenced data is assumed.

If neither ibf nor order are specified, ibf=rpt is guessed.

If iaf is not diff and order does not include the ``l` character it is assumed that the encoded images (e.g. TC pairs) are the fastest varying.

If any parameters had to be guessed (rather than inferred from other information) a warning is output.

Returns:Tuple of: IAF (ASL format, ‘tc’, ‘ct’, ‘diff’, ‘quant’, ‘ve’, ‘vediff’, ‘hadamard’ or ‘mp’), ordering (sequence of 2 or three chars, ‘l’=labelling images, ‘r’=repeats, ‘t’=TIs/PLDs, ‘e’=TEs. The characters are in order from fastest to slowest varying), Boolean indicating whether the block format needed to be guessed

oxasl.image.summary(img, log=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Write a summary of an Image to a stream

For an AslImage the summary method is used which displays all the ASL data in human readable form. For generic Image objects just basic information is displayed

Parameters:

• img – fsl.data.image.Image object which may or may not be an AslImage
• log – Stream-like object - default is sys.stdout