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
| |
| --exch=<option> | |
Model of the exchange of labeled water in the capilliary bed (selects the residue function).
| |
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 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
Within the output directory a number of subdirectories will be created containing the results from each step these comprise:
info.txtText file containing information from BASIL about what was done in this step.paramnames.txtA list of names of the parameters inferred, these will correspond with the names of the results files.mean_{paramname}.nii.gzThe parameter estimate image for paramname.var_{paramname}.nii.gzThe estimate variance image for parameter paramname.zstat_{paramname}.nii.gzA 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.gzAll 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.logfileThe logfile from FABBER.FreeEnergy.nii.gzImages 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.delttissarterial 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.deltbloodbolus arrival time (to arterial component).fwm(relative) white matter perfusion.deltwmarterial transit time for white matter.
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.