Command line User Guide¶
oxford_asl is an automated command line utility that can process ASL
data to produce a calibrated map of resting state tissue perfusion. It
also includes a range of other useful analysis methods inlcuding
- motion correction
- registration to a structural image (and thereby a template space)
- partial volume correction
- distorition correction
- ROI analysis
If you have ASL data to analyse,
oxford_asl is most likely the tool
you will want to use, unless you want a graphical user interface. In
practice, the GUI in BASIL is largely a means to construct the right
What you will need¶
As a minimum to use
oxford_asl all you need are some ASL data (label
and control pairs or already subtracted). In practice you will also most
- a calibration image: normally a proton-density-weighted image (or a close match) acquired with the same readout parameters as the main ASL data. Only once you have a calibration image can you get perfusion in absolute units.
- a structural image: it is helpful to have a structral image to pass
oxford_asland if your data incldues this we strongly suggest you do use it with
oxford_asl. By preference, we strongly suggest you process your structural image with
fsl_anatbefore passing those results to
oxford_asl. This is a good way to get all of the useful information that
oxford_aslcan use, and you can scrutinise this analysis first to check you are happy with it before starting your ASL analysis.
- multi-delay ASL: the methods in
oxford_aslare perfectly applicable to the widely used single delay/PLD ASL acquisition. But, they offer particular advantages if you have multi-delay/PLD data.
Things to note¶
To produce the most robust analysis possible
oxford_asl includes a
number of things in the overall analysis pipeline that you might want
to be aware of:
- spatial regularisation: this feature is now enabled by default for
all analyses and applies to the estimated perfusion image. We do not
recommend smoothing your data prior to passing to
oxford_asl. If you really want to, only do ‘sub-voxel’ level of smoothing.
oxford_aslwill attempt to produce a brain mask in which perfusion quantification will be performed. This is normally derived from any structural images with which it is provided (highly recommened), via registration. Therefore, if the registration is poor there will be an impact on the quality of the mask. Where no structural information is provided, the mask will be derived from the ASL data via brain extraction, this can be somewhat variable depending upon your data. It is thus always worth examining the mask created.
oxford_aslprovides the option to input your own mask where you are not satisfied with the one automatically generated or you need a specific mask for your study.
oxford_aslperforms the final registration using the perfusion image and the BBR cost function. We have found this to be reliable, as long as the perfusion image is of sufficient quality. In practice, an initial registration is done earlier in the pipeline using the raw ASL images and this is used in the mask generation step. You should always inspect the quality of the final registered images.
- multiple repeats: ASL data typically contains many repeats of the
same measurement to increase the overall signal-to-noise ratio of
the data. You should provide this data to
oxford_asl, and not average over all the repeats beforehand (unlike earlier versions of the tool).
oxford_aslnow inlcudes a pipeline where it intially analyses the data having done averaging over the repeats, followed by a subsequent analysis with all the data - to achieve both good robustness and accuracy. If your data has already had the repeats averaged, it is still perfectly reasonable to do analysis with
oxford_asl, if you have very few measurements in the data to pass to
oxford_aslyou might want to use the special ‘noise prior’ option, since this sets information needed for spatial regularisation.
- Avanced analyses: Partial volume correction, or analysis of the
data into separate epochs, are avaialbe as advanecd supplementary
oxford_asl. If you choose these options
oxford_aslwill always run a conventional analysis first, this is used to intialise the subsequent analyses. This also means that you can get both conventional and advanced results in a single run of
- Multi-stage analysis: By default oxford_asl will analyse the data in multiple-stages where appropriate in an attempt to get as accurate and robust a result as possible. The main example of this is a preliminary analysis with the data having been averaged over multiple-repeats (see above). But, this also applies to the registration (see above). This does mean that you might find some differences in the results than if you did an analysis of the data yourself using a combination of other command line tools.
oxford_asl with no options will give the basic usage information, further options are revealed by typing
A typical processing run would usually look something like this:
oxford_asl -i [asl_data] -o [output_dir] <data parameters> <analysis options> -c [M0_calib] <calibration parameters> –fslanat [fsl_anat_output_dir]
This command would analyse the ASL data, including calculation of perfusion in absolute (ml/100g/min) units using the calibration data, and register the results to the strcutural image, as well as producing perfusion maps in MNI152 standard space. In general, the use of an fsl_anat analysis of a structural image with
oxford_asl is recommended, but it is not required: perfusion can be calculated in the native space without the structural information.
The outputs from Oxford_ASL are a resting state perfusion image called
perfusion.nii.gz, which provides blood flow in relative (scanner) units, and an arrival time image called
arrival.nii.gz. If a calibration image has been supplied then a further image
perfusion_calib.nii.gz is also produced, which is a flow map in absolute units (ml/100g/min).
If calibration was performed then in the
calib subdirectory you will find:
- In reference region (single) mode: a text file called
M0b.txt will be created that saves the estimated M0 value from arterial blood. If a CSF mask was not supplied then the automatically generated one will also be saved in the output directory as
- In voxelwise mode (automatic when no structural image is provided): a
M0.nii.gz image will be produced.
Various subdirectories are created:
native_spacein which perfusion and arrival time images in the native resolution of the ASL data are saved.
struct_spaceprovides results in the same space as the structural image (if supplied).
std_spaceprovides results in MNI152 standard space (if an
fsl_anatresults directory has been provided).
If you find the registration to be unsatisfactory, a new registration can be performed without having to repeat the main analysis using the results in
If calibration is enabled, calibrated perfusion outputs are available with the suffix
_calib. These contain quantified perfusion in ml/100g/min
native_space subdirectory, several whole-brain average values are defined:
<output>_gm_mean: These are averages values in pure GM which by default is defined as voxels with more than 80% GM partial volume. This
threshold can be modified using the
<output>_wm_mean: These are averages values in pure WM which by default is defined as voxels with more than 90% WM partial volume. This threshold can be modified using the
<output>_cortical_gm_mean: These are average values in cortical GM which is defined as ‘pure GM’ voxels (see above) that are included in the Harvard-Oxford atlas Left/Right cortical mask (i.e. excluding subcortical GM). -
<output>_cerebral_wm_mean: These are average values in cerebral WM which is defined as ‘pure WM’ voxels (see above) that are included in the Harvard-Oxford atlas Left/Right cortical mask (i.e. excluding subcortical WM).
**Normalized output **
In all spaces, normalized output is produced, regardless of whether calibrated output is also being generated. Normalized output is generated by dividing the relative perfusion values by one of the whole brain averages defined above.
perfusion_norm- This is perfusion normalized by whole brain mean pure GM (perfusion_gm_mean)
perfusion_wm_norm- When partial volume correction is enabled, this is WM perfusion normalized by whole brain mean pure WM (perfusion_wm_mean)
Detailed usage information¶
This section contains a more in-depth look at some of the options available in oxford_asl
|-m <mask>||a brain mask in the native space of the ASL data. This will be generated automatically by |
|--spatial||use spatial regularisation. This option is enable by default and is highly recommended. Use |
|--wp||Do analysis in ‘White Paper Mode’. This analysis will conform to the assumptions made in the white paper about the underlying kinetic model and T1 values. Note, it still uses the Bayesian kinetic inference method in BASIL (thus spatial regularisation can be applied etc) and not the formula in the ‘White Paper’.|
|--mc||Apply motion correction (using |
There are a number of acquisition sepecific parameters that you should set to describe your data to
oxford_asl. Note, it is highly unlikely that the defaults for all of these parameters will be correct for your data - in particular you should pay attention to the follwing options.
|Input ASL format: specifies if the data has already been label-control subtracted (|
|Input block format. Specifically for multi-delay (multi-PLD) ASL data to identify whther the individual delays/PLDs are groups togther or by repeats of the same sequence of PLDs.|
|--casl||Data were acquired using cASL or pcASL labelling (pASL labeling is assumed by default).|
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
|use this to specify the duration of the ASL labeling bolus used in the sequence (in seconds). For pcASL/cASL this will be the value fixed by the sequence, for pASL this will be taken as the inital value for bolus duration estimation (unless the |
|--bolus=<csv>||alternatively supply a list of bolus duration for each TI/PLD in the data (the length of the list should match that provided to |
|For multi-slice (2D) acquisitions where superior slices are acquired later than those below, this option does not apply to 3D readouts. This provides the increase in time (in seconds) after labeling for a superior slice relative to the one directly below. It is assumed that the TIs provided refer to the lowest slice in the dataset.|
There are further acquisition specific parameters that you might need to invoke depending upon your data, although the defaults here are more likely to apply.
|--bat=<value>||A value for Arterial Transit Time (ATT), here called Bolus Arrival Time (BAT). For single delay/PLD ASL this is the value used in the perfusion calculation (and it is set to 0 in ‘White Paper Mode’). For multi-delay/PLD ASL this value will be used to initialise the estimation of ATT from the data. Typically, the ATT is longer in pcASL compared to pASL. The defaults are 0.7 s for pASL and 1.3 s for pcASL based on typical experience.|
|--t1=<value>||The T1 value of tissue, 1.3 s by default (assuming acquisition at 3T).|
|--t1b=<value>||The T1 value of arterial blood, 1.65 s by default (assuming acquisition at 3T).|
|Number of slices per band in a multi-band acquisition.|
|--rpts=<csv>||Number of repeated measurements for each TI/PLD in the TIs list (|
The inclusion of a structural image is optional but highly recommended, as various useful pieces of information can be extracted when this image is used as part of
oxford_asl, and partial volume correction can be done. Generally, we recommend the use of
fsl_anat to process the structural image prior to use with
|-s <image>||High resolution structural image (assumed to be T1 weighted or similar). An alternative to |
|Brain extracted (e.g., using |
|The results of a |
|Generate additional regional analysis of the perfusion map by registration of the image to standard space and comparison with regions in|
the Hardvard-Oxford standard atlas.
Most commonly you will have a calibration image that is some form of (approximately) proton-density-weighted image and thus will use the
|specifies the M0 calibration image that is used to get flow values in absolute units. This should be an image with any repeated measurements stacked in the 4th (time) dimension.|
|--tr=<value>||the repetition time for the calibration image.|
|the inversion efficiency of the labeling process, the defaults are likely to apply for most ASL data: 0.98 (pASL) or 0.85 (pcASL/cASL)|
Specifies whether the calibration is done via a single M0 value calculated from the CSF in the ventricles (
The voxelwise method is the simplest and follows the procedure in the ‘White Paper’, adding a correction for partial volume effects around the edge of the brain. This is is used whenever a structural image is not supplied.
The single method, using CSF for calibration, automatically generates a ventricle mask in ASL space from the segmentation of the structural image. You should inspect this mask to ensure it has been sucessful (in the
|--M0=<value>||A single precomputed value for the value of equilbirum magnetization in arterial blood. Useful when you have already performed calibration, e.g. using |
There are further advanced/extended options for calibraiton:
|--csf=<image>||Image in the same space as the structural that is a mask of voxels containing CSF to be used in calibration. This is a further option of the calibration step and allows the CSF mask to be manually specified if the automated procedure fails.|
|If the calibration image has been acquired with a different gain to the ASL data this can be specified here. For example, when using background suppression the raw ASL signal will be much smaller than the (non background suppressed) calibration image so a higher gain might be employed in the acquisition.|
|Supply a value for the T1 of CSF to be used in the calibration process. Default values are used by asl_calib based on a 3T field strength (these can be checked by calling |
|--te=<value>||Set the echo time (in milliseconds) for the readout so that T2 (or T2*) effects are taken into account in the calibration. If this is not supplied then TE = 0 ms is assumed, i.e. T2/T2* effects are negligible. Default values are assumed by asl_calib for T2/T2* values, you might wish to treat these with caution as these are estimates based on the literature.|
|--t2star||Tells oxford_asl to correct for T2* rather than T2 effects. This simply tells |
|Supply a value for the T2 (in milliseconds) of CSF to be used in the calibration process, only relevant if you supply the TE value. Default values are used by |
|--t2bl=<value>||Supply a value for the T2 of blood to be used in the calibration process, only relevant if you supply the TE value. Default values are used by |
There are some extended options (to be used alongside a structural image) for the purposes of registration.
|an existing ASL to structural image transformation matix, skips the registration process.|
|-r <image>||low resolution structural image used as an extra step in the registration to improve resulting transformation.|
|An alternative image to use as the basis of registration. This should be the same resolution as the ASL data and aligned to it.|
|--artoff||Turn off correction for signal arising from ASL signal still within the (macro) vasculature, this might be appropriate if the acquisition employed flow suppression. This is enabled by default for single-delay/PLD ASL.|
|--fixbolus||Turn off the automatic estimation of bolus duration, this might be appropriate if the bolus duration is well defined by the acquisition sequence and is on by default for cASL and pcASL. It might be appropriate to use this with pASL where the bolus duration has been fixed using QUIPSSII or Q2TIPS.|
|--fixbat||Force basil not to infer the ATT (BAT), this is on by default for single-delay/PLD ASL.|
|--batsd||The standard deviation for the ATT (BAT) prior distribution (default 0.316 seconds for single-PLD, 1.0 second for multi-PLD). See BASIL command line user guide for more information.|
|--infert1||Incorporate uncertainty in the T1 values into the analysis. Strictly this inlcudes the T1 values in the inference process, but dont expect accurate T1 maps from ASL data.|
|--noiseprior||Use the in-built informative prior for noise estimation. This is particuarly useful where you only have a small number of repeats/volumes in the main ASL data (e.g., if your data has already been averaged before you get it). This provides information to |
|--noisesd||The standard deviation of the noise as described by the noise prior, overrides the values set internally and needs to be of the form of the standard deviation of the noise relative to the magnitude of the ASL data (only for very advanced use).|
Distortion correction for (EPI) ASL images follows the methodology used in BOLD EPI distortion correction.
Using a separately acquired fieldmap (structural image is required), this can in principle be in any image space (not necessarily already alinged with the ASL or structural image), the syntax follows
|--fmap=<image>||fieldmap image (in rad/s)|
|fieldmap magnitude image - wholehead extracted|
|fieldmap magnitude image - brain extracted|
|effective EPI echo spacing (sometimes called dwell time) - in seconds|
|--pedir=<dir>||phase encoding direction, dir = x/y/z/-x/-y/-z|
|--nofmapreg||do not perform registration of fmap to T1 (use if fmap already in T1-space)|
Further information on fieldmaps can be found under the
fsl_prepare_fieldmap documentation on the FSL webpages.
Using phase-encode-reversed calibration image (a la
|--cblip||phase-encode-reversed (blipped) calibration image|
|Effective EPI echo spacing (sometimes called dwell time) - in seconds|
|--pedir=<dir>||phase encoding direction, dir = x/y/z/-x/-y/-z|
topup the effective EPI echo spacing is converted to total readout time by multiplication by the number of slices (minus one) in the encode direction. Earlier versions of oxford_asl (pre v3.9.22) interpreted the
--echospacing parameter as total readout time when supplied with a phase-encode-reversed calibration image.
Partial volume correction
Correction for the effect of partial voluming of grey and white matter, and CSF can be performed using
oxford_asl to get maps of ‘pure’ grey (and white) matter perfusion. When partial volume correction is performed a separate subdirectory (
pvcorr) within the main results subdirectories will appear with the corrected perfusion images in: in this directory the
perfusion.nii.gz image is for grey matter,
perfusion_wm.nii.gz contains white matter estimates. Note that, the non-corrected analysis is always run prior to partial volume correction and thus you will also get a conventional perfusion image.
: Do partial volume correction
PV estimates will be taken from:
- fsl_anat dir (
--fslanat), if supplied
- exising fast segmentation (
--fastsrc), if supplied
- FAST segmenation of structural (if using -s and –sbet)
- User supplied PV estimates (–pvgm, –pvwm)
--pvgm : Partial volume estimates for GM --pvwm : Partial volume estimates for WM
The data can also be analysed as separate epochs based on the different measurements (volumes) within the ASL data. This can be a useful way of examining changes in perfusion over the duration of the acquisition, although shorter epochs will contain fewer measurements and thus be more noisy. Epoch analysis is always preceeded by a conventional analysis of the full data and thus the conventional perfusion image will also be generated from the full dataset.
|--elen||Length of each epoch in TIs.|
|--eol||Overlap of each epoch in TIs (default is 0).|
Region analysis involves the generation of summary statistics for perfusion and arterial transit time within defined brain regions, either from standard atlases or from ROI images supplied by the user.
Basic region analysis with oxford_asl
--region-analysis option is specified an additional directory
native_space/region_analysis will be created containing three files:
region_analysis.csv- This file contains region analysis statistics for all voxels within the brain mask
region_analysis_gm.csv- This file contains region analysis statistics for grey matter
region_analysis_wm.csv- This file contains region analysis statistics for white matter
Region analysis is performed by using the registration from the structural image to standard space from an
fsl_anat run. Hence
be used in order to run region analysis.
The output files are in comma-separated format, suitable for loading into most spreadsheet or data processing applications. Within each region the following information is presented:
Nvoxels- The number of voxels identified as being within this region
IQR- Standard summary statistics for the perfusion values within this region
Precision-weighted mean- The mean perfusion weighted by voxelwise precision (1/std.dev) estimates. This measure takes into account the confidence of the inference in the value returned for each voxel and is a standard measure used in meta-analysis to combine results of varying levels of confidence.
I2- A measure of heterogeneity for the voxels within the region expressed as a percentage. A high value of I2 suggests that there is significant variation in perfusion within the region that is not attributable to the inferred uncertainty in the estimates. For a definition of I2 and an overview of its use in meta-analyses, see https://www.ncbi.nlm.nih.gov/pmc/articles/PMC192859/
Definition of grey/white matter voxels
The definition of the included data for GM/WM output files varies according to whether or not you have included partial volume correction in your oxford_asl run.
If you have not used partial volume correction then GM voxels are derived from the structural
segmentation and by default includes voxels with at least 80% GM. This threshold can be modified
--gm-thresh option. WM voxels are those with at least 90% WM, and again this can be
--wm-thresh. The intention here is to restrict the statistics to those voxels
which are near-enough ‘pure’ GM/WM.
If you do have partial volume correction, then oxford_asl will have generated separate perfusion maps for GM and WM which (in principle) only contains the perfusion contribution from these components. We use these single-tissue perfusion maps to generate the GM/WM statistics. However a base threshold of 10% is used to remove voxels that contain very little of the selected tissue type, e.g. the GM stats will ignore voxels with less than 10% GM. This is because the GM perfusion estimates in such voxels will have very high uncertainty and could bias the statistics.
By default, statistics are generated for a standard set of regions as follows:
GM and WM segmentation maps are used to define ‘pure’ GM and WM ROIs thresholded at 80% and 90% respectively. Note that these regions are included in all data files regardless of whether partial volume correction was performed, and are independent of the separation of voxels into GM and WM described above.
A second set of GM and WM ROIs are included based on 10%+ thresholding - i.e. regions including some of the corresponding tissue type.
A further set of standard regions are taken from the Harvard-Oxford cortical and subcortical atlases. Standard space regions are transformed to native ASL space and voxels with probability fraction > 0.5 are considered to lie within a region. At least 10 voxels must be found in order for statistics to be presented.
Using user-specified ROIs
In many cases users will want to provide their own ROIs to generate statistics in. This is supported
--region-analysis-atlas option. This option can contain one or more image files (comma
separated) each of which contains a 3D label image in MNI space. Each voxel contains an integer label
and each unique integer > 1 defines a region in which to generate statistics.
To make the output more readable you can specify the names of the regions for each atlas using the
--region-analysis-atlas-labels option. Again this should be one or more file names (comma separated)
and each file contains a list of text labels, one per line. The number of labels should be equal to the
number of regions defined in the corresponding atlas image.