aslprep.interfaces.cbf_computation module

Interfaces for calculating CBF.

class BASILCBF(**inputs)

Bases: FSLCommand

Wrapped executable: oxford_asl.

Apply Bayesian Inference for Arterial Spin Labeling (BASIL).

This interface calculates: (1) arterial transit time, (2) CBF with spatial correction, (3) CBF with spatial partial volume white matter correction, and (4) CBF with spatial partial volume correction.

See https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BASIL and https://asl-docs.readthedocs.io.

Mandatory Inputs:

• bolus (a float or a list of items which are a float) – Bolus or tau: label duration. Maps to a command-line argument: --bolus %s.

• in_file (a pathlike object or string representing an existing file) – ASL data after subtracting tag-control or control-tag. This matches with --iaf diff, which is the default. Maps to a command-line argument: -i %s (position: 0).

• m0scale (a float) – Calibration of asl. Maps to a command-line argument: --cgain %.2f.

• m0tr (a float) – The repetition time for the calibration image (the M0 scan). Maps to a command-line argument: --tr %.2f.

• mask (a pathlike object or string representing an existing file) – Mask in the same space as in_file. Maps to a command-line argument: -m %s.

• out_basename (a pathlike object or string representing a file) – Base name of output files. Maps to a command-line argument: -o %s.

• tis (a float or a list of items which are a float) – The list of inflow times (TIs), a comma separated list of values should be provided (that matches the order in the data).

  Note, the inflow time is the PLD plus bolus duration for pcASL (and cASL), it equals the inversion time for pASL. If the data contains multiple repeats of the same set of TIs then it is only necessary to list the unique TIs.

  When using the --tis= you can specify a full list of all TIs/PLDs in the data (i.e., as many entries as there are label-control pairs). Or, if you have a number of TIs/PLDs repeated multiple times you can just list the unique TIs in order and oxford_asl will automatically replicate that list to match the number of repeated measurements in the data. If you have a variable number of repeats at each TI/PLD then either list all TIs or use the --rpts=<csv> option (see below). Maps to a command-line argument: --tis %s.

Optional Inputs:

• alpha (a float) – Inversion efficiency - [default: 0.98 (pASL); 0.85 (cASL)]. This is equivalent the BIDS metadata field ‘LabelingEfficiency’. Maps to a command-line argument: --alpha %.2f.

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• mzero (a pathlike object or string representing an existing file) – M0 scan. Maps to a command-line argument: -c %s.

• output_type (‘NIFTI’ or ‘NIFTI_PAIR’ or ‘NIFTI_GZ’ or ‘NIFTI_PAIR_GZ’) – FSL output type.

• pcasl (a boolean) – Data were acquired using cASL or pcASL labelling (pASL labeling is assumed by default). Maps to a command-line argument: --casl.

• pvc (a boolean) – Do partial volume correction. Maps to a command-line argument: --pvcorr.

• pvgm (a pathlike object or string representing an existing file) – Partial volume estimates for GM. This is just a GM tissue probability map. Maps to a command-line argument: --pvgm %s.

• pvwm (a pathlike object or string representing an existing file) – Partial volume estimates for WM. This is just a WM tissue probability map. Maps to a command-line argument: --pvwm %s.

Outputs:

• out_att (a pathlike object or string representing a file) – Aretrial transist time.

• out_cbfb (a pathlike object or string representing a file) – Cbf with spatial correction.

• out_cbfpv (a pathlike object or string representing a file) – Cbf with spatial correction.

• out_cbfpvwm (a pathlike object or string representing a file) – Cbf with spatial partial volume white matter correction.

class ComputeCBF(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Calculate CBF time series and mean control.

Notes

This interface calculates CBF from deltam and M0 data. It can handle single-PostLabelingDelay and multi-PostLabelingDelay data, single CBF volumes and CBF time series, and PASL and (P)CASL data.

T1blood is set based on the scanner’s field strength, according to Zhang et al.[1], Alsop et al.[2]. If recommended values from these publications cannot be used (i.e., if the field strength isn’t 1.5T, 3T, 7T), then the formula from Zhang et al.[1] will be applied.

Single-PLD CBF, for both (P)CASL and PASL (QUIPSSII BolusCutOffTechnique only) is calculated according to Alsop et al.[2]. Multi-PLD CBF is handled using a weighted average, based on Dai et al.[3], Wang et al.[4].

References

[1] (1,2)

Xiaofei Zhang, Esben T Petersen, Eidrees Ghariq, JB De Vis, AG Webb, Wouter M Teeuwisse, Jeroen Hendrikse, and MJP Van Osch. In vivo blood t1 measurements at 1.5 t, 3 t, and 7 t. Magnetic resonance in medicine, 70(4):1082–1086, 2013.

[2] (1,2)

David C. Alsop, John A. Detre, Xavier Golay, Matthias Günther, Jeroen Hendrikse, Luis Hernandez-Garcia, Hanzhang Lu, Bradley J. MacIntosh, Laura M. Parkes, Marion Smits, Matthias J. P. van Osch, Danny JJ Wang, Eric C. Wong, and Greg Zaharchuk. Recommended Implementation of Arterial Spin Labeled Perfusion MRI for Clinical Applications: A consensus of the ISMRM Perfusion Study Group and the European Consortium for ASL in Dementia. Magnetic resonance in medicine, 73(1):102–116, January 2015. URL: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4190138/ (visited on 2020-04-13), doi:10.1002/mrm.25197.

[3]

Weiying Dai, Philip M Robson, Ajit Shankaranarayanan, and David C Alsop. Reduced resolution transit delay prescan for quantitative continuous arterial spin labeling perfusion imaging. Magnetic resonance in medicine, 67(5):1252–1265, 2012.

[4]

Danny JJ Wang, Jeffry R Alger, Joe X Qiao, Matthias Gunther, Whitney B Pope, Jeffrey L Saver, Noriko Salamon, David S Liebeskind, UCLA Stroke Investigators, and others. Multi-delay multi-parametric arterial spin-labeled perfusion mri in acute ischemic stroke—comparison with dynamic susceptibility contrast enhanced perfusion imaging. NeuroImage: Clinical, 3:1–7, 2013.

Mandatory Inputs:

• cbf_only (a boolean) – Whether data are deltam (False) or CBF (True).

• deltam (a pathlike object or string representing an existing file) – NIfTI file containing raw CBF volume(s). These raw CBF values are the result of subtracting label volumes from control volumes, without any kind of additional scaling. This file may be 3D or 4D.

• m0_file (a pathlike object or string representing an existing file) – M0 nifti file.

• m0scale (a float) – Relative scale between ASL and M0.

• mask (a pathlike object or string representing an existing file) – Mask nifti file.

• metadata (a dictionary with keys which are any value and with values which are any value) – Metadata for the raw CBF file, taken from the raw ASL data’s sidecar JSON file.

Outputs:

• cbf (a pathlike object or string representing an existing file) – Quantitative CBF data, in mL/100g/min.

• mean_cbf (a pathlike object or string representing an existing file) – Quantified CBF, averaged over time.

class ExtractCBF(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Extract CBF time series by subtracting label volumes from control volumes.

TODO: Mock up test data and write tests to cover all of the branches in this interface.

Notes

The M0 information is extracted in the same way as GeReferenceFile, so there’s duplication that could be reduced.

Mandatory Inputs:

• asl_file (a pathlike object or string representing an existing file) – Preprocessed asl file.

• aslcontext (a pathlike object or string representing an existing file) – Aslcontext TSV file for run.

• in_mask (a pathlike object or string representing an existing file) – Mask.

• m0scan (a pathlike object or string representing an existing file or None) – M0scan file associated with the ASL file. Only defined if M0Type is ‘Separate’.

• m0scan_metadata (a dictionary with keys which are any value and with values which are any value or None) – Metadata for M0 scan. Only defined if M0Type is ‘Separate’.

• metadata (a dictionary with keys which are any value and with values which are any value) – Metadata for ASL file.

• name_source (a pathlike object or string representing an existing file) – Raw asl file.

Optional Inputs:

• dummy_vols (an integer) – Remove first n volumes.

• fwhm (a float) – Fwhm.

Outputs:

• m0_file (a pathlike object or string representing a file) – Mean M0 image, after smoothing.

• m0tr (a float or None) – RepetitionTimePreparation for M0 scans.

• metadata (a dictionary with keys which are any value and with values which are any value) – Metadata for the ASL run. The dictionary may be modified to only include metadata associated with the selected volumes.

• out_file (a pathlike object or string representing a file) – Either CBF or deltaM time series.

class ExtractCBForDeltaM(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Load an ASL file and grab the CBF or DeltaM volumes from it.

Mandatory Inputs:

• asl_file (a pathlike object or string representing an existing file) – Raw asl file.

• aslcontext (a pathlike object or string representing an existing file) – Aslcontext TSV file for run.

• file_type (a string) – File type, c for cbf, d for deltam.

• in_aslmask (a pathlike object or string representing an existing file)

Outputs:

out_file (a pathlike object or string representing a file) – Cbf or deltam.

class RefineMask(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Reduce the ASL-derived brain mask using the associated T1w mask.

Mandatory Inputs:

• in_aslmask (a pathlike object or string representing an existing file)

• in_t1mask (a pathlike object or string representing an existing file) – T1 mask.

• transforms (a pathlike object or string representing an existing file) – Transfom.

Outputs:

• out_mask (a pathlike object or string representing a file) – Output mask.

• out_tmp (a pathlike object or string representing a file) – Tmp mask.

class ScoreAndScrubCBF(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Apply the SCORE and SCRUB algorithms.

The Structural Correlation-based Outlier Rejection (SCORE) algorithm is applied to the CBF time series to discard CBF volumes with outlying values [5] before computing the mean CBF. The Structural Correlation with RobUst Bayesian (SCRUB) algorithm is then applied to the CBF maps using structural tissue probability maps to reweight the mean CBF [6].

References

[5]

Sudipto Dolui, Ze Wang, Russell T. Shinohara, David A. Wolk, John A. Detre, and for the Alzheimer’s Disease Neuroimaging Initiative. Structural Correlation-based Outlier Rejection (SCORE) algorithm for arterial spin labeling time series: SCORE: Denoising Algorithm for ASL. Journal of Magnetic Resonance Imaging, 45(6):1786–1797, June 2017. URL: http://doi.wiley.com/10.1002/jmri.25436 (visited on 2020-04-13), doi:10.1002/jmri.25436.

[6]

Sudipto Dolui, David A. Wolk, David A. Wolk, and John A. Detre. Scrub: a structural correlation and empirical robust bayesian method for asl data. International Society for Magnetic Resonance in Medicine, 2016. doi:http://archive.ismrm.org/2016/2880.html.

Mandatory Inputs:

• in_csf (a pathlike object or string representing an existing file) – Csf.

• in_file (a pathlike object or string representing an existing file) – Computed CBF from ComputeCBF.

• in_greyM (a pathlike object or string representing an existing file) – Grey matter.

• in_mask (a pathlike object or string representing an existing file) – Mask.

• in_whiteM (a pathlike object or string representing an existing file) – White matter.

Optional Inputs:

• in_thresh (a float) – Threshold of propbaility matter.

• in_wfun (a string) – Wavelet fun .

• out_avgscore (a pathlike object or string representing a file) – Average score.

• out_score (a pathlike object or string representing a file) – Score timeseries data.

• out_scoreindex (a pathlike object or string representing a file) – Index of volume remove or leave by score.

• out_scrub (a pathlike object or string representing a file) – Average scrub.

Outputs:

• out_avgscore (a pathlike object or string representing a file) – Average score.

• out_score (a pathlike object or string representing a file) – Score timeseries data.

• out_scoreindex (a pathlike object or string representing a file) – Index of volume remove .

• out_scrub (a pathlike object or string representing a file) – Average scrub.

refine_ref_mask(t1w_mask, ref_asl_mask, t12ref_transform, tmp_mask, refined_mask)

Warp T1w mask to ASL space, then use it to mask the ASL mask.

TODO: This should not be a function. It uses interfaces, so it should be a workflow.

regmotoasl(asl, m0file, m02asl)

Calculate mean M0 image and mean ASL image, then FLIRT M0 image to ASL space.

TODO: This should not be a function. It uses interfaces, so it should be a workflow.