BASIL (command) User Guide

Calling BASIL

A typical call to BASIL would look like:

basil -i asldiffdata.nii.gz -m mask.nii.gz -o basilout --spatial -@ basil_params.txt

You should always supply a parameter file using the -@ option (see parameter file)

We highly recommend the use of the --spatial option for automated spatial regularisation of your data.

Basic options

BASIL can be called from the command line with the following information:

-i <file>	Input file containing label-control differenced data.
-m <file>	Brain mask for the data.
-o <dir>	Name of directory into which results are to be written (default is a subdirectory called basil within the input directory).
--optfile <file>
	Model and sequence parameters (to be passed to FABBER) (was previouosly -@).
--spatial	Apply a spatial regularising prior to the estimated perfusion image, this is preferable to spatial smoothing of the data before analysis.

Model options

BASIL provides a number of options to access more advanced parts of the kinetic curve models, you should consult the literature to determine whether you want to explore these model options (the Further Reading and Literaure sections for BASIL should be a good start):

--infertau	Infer the bolus duration from the data. This option is particularly suitable for pASL data in which the bolus duration is undefined (e.g. when not using QUIPSSII or Q2TIPS)
--inferart	Include an arterial compartment in the model. This option will infer the arterial blood volume (aCBV) and arterial blood arrival time. This option is suitable for data with multiple post-labelling delays, especially where short PLD (or TIs) are used.
--inferpc	Include a non-exchanging compartment in the model. This option might be used to model pre-capillary vessels assuming minimal water exchange. This parameter adds a pre-capillary transit time parameter.
--infert1	Infer the values of T1 and T1b from the data. This option is primarily to account for uncertainty in the T1 values in the inference. ASL data does not have sufficient sensitivity to T1 to estimate it accurately.

Advanced Options

BASIL also has a few more advanced options:

--t1im	For loading a image of T1 (tissue) values to be used in the kinetic modelling (same resolution as the ASL data).
--fast=<value>	Use a value of 2 to perform the analysis in a single step, mostly for use with –spatial. A value of 1 reduces the number of iterations performed in each step.
--pvgm	Perform partial volume correction with the supplied partial volume estimates for grey and white matter (these should be the same resolution as the ASL data).
--pvwm	White matter partial volume estimates (to go with --pvgm).
--init	Initialise BASIL with the results of a previous run - this option expects the finalMVN.nii.gz image from a previous basil run (model specification must match - use with caution).

Kinetc model choice

BASIL also offers a number of variants on the kinetic model used:

--disp=<option>
	Model of the label dispersion --disp=none No dispersion. --disp=gamma Dispersion modelled according to a gamma dispersion kernel (vascular transport function). --disp=gauss Dispersion modelled according to a Gaussian dispersion kernel. --disp=sgauss Dispersion modelled according to a spatially (rather than temporally) derived Gaussian dispersion function.
--exch=<option>
	Model of the exchange of labeled water in the capilliary bed (selects the residue function). --exch=mix Well-mixed single compartment --exch=simple Simple single compartment with T1 of blood (mimics the assumptions made in the white paper) --exch=2cpt A two compartment exchange model following Parkes & Tofts (by default the slow solution is used). --exch=spa An implementation of the single pass approximation from St. Lawrence.

BASIL assumes by default a single well-mixed tissue compartment (--exch=mix) and no dispersion of the bolus of labeled blood water (--disp=none).

BASIL parameter file

BASIL requires a text file in which you specify model parameters, plus information about the collected data.

A generic BASIL options file for single-PLD pcASL (at 3T) might look like (preceding a line with # indicates it is a comment and will be ignored):

# Sequence/scanner parameters
--casl
--t1=1.3
--t1b=1.65
--tau=1.8
# tau specified label/bolus duration

# Data information
--repeats=10 --pld=1.8

An generic file for multi-TI pASL might look like:

 # Sequence/scanner parameters
--t1=1.3
--t1b=1.65
--tau=0.7

# Data information
--repeats=10 --ti1=0.25 --ti2=0.5 --ti3=0.75 --ti4=1.0 --ti5=1.25 --ti6=1.5 --ti7=1.75 --ti8=2.0

Model parameters

By default BASIL assumes that your data is pulsed ASL (pASL), if you are using continuous (cASL) or pseudo continuous (pcASL) labelling then you should set the cASL option:

--casl

Use the cASL version of the model (NOTE: the default ATT value is likely to be poorly suited to pcASL/cASL data, see below).

For the model you can set the appropriate values of T1 (and T1b) as well as the duration of the label as set by your sequence, if these are not specified in the parameter file then the default values are used:

--t1=<value>	The value of T1 (default 1.3 seconds).
--t1b=<value>	The value of T1b (default 1.65 seconds).
--t1wm=<value>	The T1 value of white matter (default 1.1 seconds) - only for partial volume correction.

You can set an appropriate Arterial Transit Time (sometimes called Bolus Arrival Time) value. This will be used as the mean of the prior distribution for the ATT parameter during inference, i.e., the default value for ATT which will be updated based on the data.

--bat=<value>

The value of ATT (aka Bolus Arrival Time) (default 0.7 seconds).

NOTE: in oxford_asl the default ATT is automatically changed from 0.7 seconds to 1.3 seconds for cASL/pcASL. This does not happen in basil, you need to do this using the --bat option.

--batsd=<value>
	The value of the standard deviation for the ATT prior distribution (default 0.316 seconds).

The default value is appropriate if you are treating ATT as a confoud. If you are interested in estimating ATT from multi-PLD/TI ASL you may wish to use --batsd=1, the default value chosen by oxford_asl.

Some models variants will have their own specific options, see Kinetic Model.

Data Parameters

Alongside model information the parameter file also contains information about the data, including the post-label delay(s) for pcASL or the inversion times for pASL and how many repeats of each are contained in the file. You should specify each PLD/TI individually in the order that they appear in the data.

Post Label delay(s)

--pld=<value>	The time (in seconds) for the PLD in single-PLD cASL/pcASL.
--pld1=<value>, --pld2=<value>, --pld-n-=<value>
	The time (in seconds) of the nth PLD in multi-PLD cASL/pcASL.

Inversion time(s)

--ti1=<value>, --ti2=<value>, --ti-n-=<value>
	The time (in seconds) of the nth TI for multi-TI pASL.

Label duration(s)

--tau=<value>	Label bolus duration (default is infinite).
--tau1=<value>, --tau2=<value>, --tau-n-=<value>
	Label duration for the nth PLD measurement. Used where pcASL has been applied with different label durations.

A fixed bolus duration is set in any cASL/pcASL implementation. For pASL a fixed bolus duration is often implemented using QUIPSS2 for example. If the bolus length is not fixed, e.g. FAIR then BASIL can estimate the bolus duration from multi-TI data if you use the infertau option when calling BASIL.

Slice timing

--slicedt

The time (in seconds) between acquisition of different slices in a 2D multi-slice readout. This is used to adjust the PLD for more superior slices (this assumes that the most inferior slice is acquired first with a PLD/TI that matches the value supplied via --pld or --ti).

Look-locker readout (for multi-PLD/TI)

--FA=<value>

The flip angle in a Look-Locker readout scheme.

Flow suppression (multiple phases)

--crush1=<value>, --crush2=<value>, --crush-n-=<value>
	Specification of the flow suppressing crusher direction for the nth PLD/TI. Any one of xyz, -xyz, x-yz, -x-yz.

Time or Hadamard encoding

BASIL is directly compatible with time/hadamard encoding where ‘decoding’ has been performed. In that case the multi-PLD data can be used exactly like any other multi-PLD pcASL with suitable setting of the PLDs and label duration.

BASIL can also directly estimate perfusion from ‘raw’, i.e. not decoded, data. Although this is currently limited to specific cases - largely ones that use the same duration for each of the encoded blocks. To use this option the input data is the raw data as acquired and you tell BASIL the number of cycles to expect, you shoud specify the appropriate single PLD and label duration values.

--hadamard=<value>
	Labeling has been performed using hadamard encoding with the number of cycles specified, and the data has not been ‘decoded’ prior to being input to BASIL.

For this analysis it is necessary to also infer the static tissue component (that would otherwise have been removed during decoding). Thus the following options need to be added to the basil options file: --incstattiss --inferstattiss

--fullhad

When the full Hadamard matrix is needed. This is for the case where the hadamard encoding included the first ‘column’ of all control boluses. (If this doesn’t mean anything to you, the chances are that it isn’t relevant).

Repeated measurements

--repeats=<n>

The number of repeats of each PLD or TI in the data (default is 1).

BASIL processes data where there are multiple measurements at the same PLD/TI, as indicated by the --repeats option: in which case it is assumed that the data comes with the individual time points in the 4th dimension, with repeats at each PLD/TI coming in blocks (gorups). Suitable manipulation of the data can be done using asl_file.

For example: the data contains 8 readings taken at 4 TIs (0.5, 1, 1.5, 2 seconds), repeated twice. It should be presented to BASIL with each TI grouped together

i.e. TI1 TI1 TI2 TI2 TI3 TI3 TI4 TI4

Hence the parameter file would contain:

--ti1=0.5 --ti2=1 --ti3=1.5 --ti4=2 --repeats=2

NOTE that the number of TIs specified multiplied by the number of repeats should equal the number of time points in the 4D input data set.

It is possible to deal with more complicated data by specifying an individual --ti[n]= for every time point in the data, for the above example we could equally input it to BASIL as:

--ti1=0.5 --ti2=0.5 --ti3=1 --ti4=1 --ti5=1.5 --ti6=1.5 --ti7=2 --ti8=2

Results (outputs)

Within the output directory a number of subdirectories will be created containing the results from each step these comprise:

• info.txt Text file containing information from BASIL about what was done in this step.
• paramnames.txt A list of names of the parameters inferred, these will correspond with the names of the results files.
• mean_{paramname}.nii.gz The parameter estimate image for paramname.
• var_{paramname}.nii.gz The estimate variance image for parameter paramname.
• zstat_{paramname}.nii.gz A pseudo z-statistic image for paramname, uses variance information to give a measure of the confidence with which that parameter deviates from 0.
• finalMVN.nii.gz All the parameter estimates and variances (including noise parameters) in one file. This can be interrogated with mvntool and can be used to initalise a further run of BASIL.
• logfile The logfile from FABBER.
• FreeEnergy.nii.gz Images of the free energy from FABBER, see references for more information.

Depending upon the model options chosen there will be a range of parameters for which results will be provided. The multi-step nature of basil means that more parameters are likely to be found in the later steps, as models of increasingly complexity are fit as the step number is increased.

Typical parameter names from BASIL are:

• ftiss (relative) tissue perfusion.
• delttiss arterial transit time (transit time or bolus arrival time to the tissue component).
• fblood (relative) arterial cerebral blood volume, the scaling parameter of the arterial/macrovascular component.
• deltblood bolus arrival time (to arterial component).
• fwm (relative) white matter perfusion.
• deltwm arterial transit time for white matter.

Noise Model (Advanced option)

BASIL assumes that you wish to use a standard white noise model to analyse resting-ASL data. This model assumes that the noise in each voxel can be described by a single noise magnitude, this is sufficient in practice for most ASL data. If you are feeling adventurous (or have good reason) you may instruct BASIL to use different noise magnitudes for different sections of the input data, e.g. a different value at each inversion time.

This is done in the parameter file using the --noise-pattern= option, which is used as follows: Taking the example of data with 4 TIs each repeated 5 times, to get a different noise magnitude at each inversion time use:

--noise-pattern=11111222223333344444

i.e. the first 5 entries correspond to the first TI and these should use the first noise magnitude, the next 5 entries are the next TI and next noise magnitude etc. The numerbs here are purely labels and do not relate to the actual magnitude of the noise, which will be estimed by basil from the data.

NOTE: if you have more than 9 TIs then for the 10th TI and onward letters should be used in place of numbers starting with a, i.e. for 12 TIs and 2 repeats:

--noise-pattern=112233445566778899aabbcc

NOTE: if you have only a small number of repeats (like these examples) then this more complex noise modelling is probably not a good idea.