#This is a template for a FSL tool sub-section # Create subpages as ToolName/blah # Remember to add this page to the appropriate category

<<FslToolContents>>

= Usage =
`Oxford_ASL` is an automated command line utility that processes ASL data to produce a calibrated map of resting state tissue perfusion. Typical usage would be:

{{{
oxford_asl -i <asl_data> -o <output_dir_name> --tis=3.2 --bolus=1.8 --casl
}}}
This command would process the data specified by `<asl_data>` which has contains multiple volumes of tag-control difference images from a pcASL (pseudo-continuous labelling) acquisition with inflow-time 3.2 s (post labelling delay 1.8 s) and labelling duration 1.8 s. this data may for example have been acquired using the recommendation from the ASL consensus paper: Alsop et al., MRM, 2014. It would calculate a relative perfusion map using an inversion of the standard ASL kinetic model with the default parameters specified in `oxford_asl`.

{{{#!highlight console numbers=disable
oxford_asl -i <asl_data> -o <output_dir_name> -s <struct_image> -t <struct2std_trans.mat> -c <M0_calib_image> --tr=5 --tis=0.2,0.4,0.6,0.8,1.0,1.2,1.4,1.6,2.0,2.2
}}}
This command would process the data specified by `<asl_data>` that has been acquired with a pASL (pulsed labelling) acquisition that contains multiple volumes of tag-control difference images with the list of inflow-times (inversion-times) `--tis`. The resulting tissue perfusion map would registered into standard space by way of the structural image `<struct_image>` and structural to standard transformation matrix `<struct2std_trans.mat>`. Finally a calibrated perfusion map (in ml/100g/min) would be produced using the calibration image `<M0_calib>` (a proton density weighted image with TR of 5 s) using CSF as a reference to calculate the equilibrium magnetisation of blood within an automatically generated CSF mask (from a segmentation of the structural image). Results are provided both in the native space of the original perfusion image, as well as in standard space (in case the registration needs to be revisited later).

When a structural image is supplied `Oxford_asl` will try to register the resulting CBF image to the structural image. '''It is very important to inspect whether the registration has worked by examining the final result'''. In practice the current default registration is only robust for some forms of ASL data. There are a couple of options that can improve the robustness of registration (see below). Advanced custom registration can be done using the `native_space` results directly and either `asl_reg` or `flirt`.

== Changes from FSL 5.0.6 onward ==
`Oxford_asl` was modified in FSL 5.0.6 to make it more consistent with the ASL consensus paper. Thus T1 values differ from the earlier releases and the inversion efficiency is now included by default (this can be 'turned off' by setting `--alpha=1`) - the new defaults for these can be found by typing `oxford_asl` on the command line and consulting the usage information. `Oxford_asl` now also expects all structural images to have already been brain extracted (in the past `bet` was run internally). This now leaves it up to the user to choose their preferred `bet` options and get the brain extraction they wish without any further modification by `oxford_asl`.

= Output =
The outputs from `Oxford_ASL` are a resting state perfusion image called `perfusion.nii.gz`, which provides blood flow in relative (scanner) units, and, fi data at multiple inflow-times is supplied, an arrival time image called `arrival.nii.gz`. If calibration has been requested 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 using a CSF reference then 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 (from segmentation of the structural image) will also be saved in the output directory as `csf_mask.nii.gz`. It is good practice to examine this to ensure that any voxels in the mask are well within the CSF of the low resolution ASL images.

A subdirectory is always created called `native_space` in which perfusion and arrival time images in the native resolution of the ASL data are saved. These are useful if you find the registration to be unsatisfactory, allowing a new registration to be performed without having to repeat the main analysis.

= Main options =
Typing `oxford_asl` with no options will give the basic usage information, the following is a more detailed version.

''Some options are only present in more recent releases of'' `oxford_asl`

 * `-i <asl_data>`                       this is the ASL data with the individual ASL images stacked in the time (4th) dimension. The number of volumes should match the number of TIs.
 * `-o `(optional)` <output_dir_name>`   use this to place the result in a different directory to the current working directory.
 * `-m` (optional)` <mask_file> `        user specified brain mask (in same space as ASL data) in which analysis will be performed. If not set then one will automatically be generated from data provided.
 * `--spatial`    Use spatial prior on the estimated perfusion image. This exploits the spatial homogeneity (or smoothness) of the perfusion image. This is somewhat similar to spatial smoothing the raw data, but it is adaptive and does not interact unfavorably with the non-linear kinetic curve modelling.

== acquisition specific ==
At the very least you need to specify the inflow-time(s) (inversion times for pASL, bolus duration plus post-labelling delay of pcASL) for the data acquisition along with the labelling strategy (pASL or pcASL) and bolus duration (label duration).
 * `--tis=<TI1,TI2,TI3...>`         This option specifies the list of inflow-times used in the data acquisition, a comma separated list of values should be provided (that matches the order in the data). If the data contains multiple repeats of the same TI or set of TIs then it is only necessary to list the unique TIs. For multi-TI data `oxford_asl` will take the mean of the values for each TI before model-fitting, if you dont want it to do this then use the `--fulldata` option.
 * `--casl`       Data was acquired using cASL or pcASL labelling, default is pASL labelling.
 * `--bolus=<bolus_duration>`     use this to specify the duration of the ASL labelling bolus used in the sequence (in seconds), for pcASL this is the label duration. This is assumed to be 1 second by default, the actual bolus duration is estimated as part of the processing, unless your data only contains a single TI or you supply the `--fixbolus` option. For (mutli-TI) pASL the value is not determined ''a priori'' by the sequence, but the value specified by this option is used as the initial guess to estimate it from the data.
 * `--bat=<BAT_value>`    An approximate bolus arrival time value, defaults to 0.7 s for pASL and 1.3 s for pcASL (based on experience). For single-TI data this value should make only a small difference to the quantification (and a value of 0 may be used if preferred and to be consistent with the ASL consensus paper). For multi-TI data this value is only used as prior information on the typical BAT data expected in the data, the actual value will be estimated from the data.
 * `--t1=<T1_value>`      The T1 value of tissue, 1.3 s by default (assuming acquisition at 3T).
 * `--t1b=<T1b_value>`    The T1 value of arterial blood, 1.65 s by default (assuming acquisition at 3T).
 * `--slicedt=<timing_difference_value>`  For multi-slice acquisitions where superior slices are acquired later than those below., this provides the increase in time 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.

== Structural image ==
The structural image is used as a reference for registration, to generate a CSF mask for absolute quantification (if called for) and to provide partial volume estimates for correction of perfusion for partial volume effects (if requested). The bias field from the structural image may also be used to correct for coil sensitivity variations.

 * `-s` (optional) `[struct_image]`       high resolution structural image (assumed to be T1 weighted or similar). If this is not provided then results will be provided in native space only.
 * `--senscorr`                      use bias field estimated from structural image to correct for variations in coil sensitivity.

== Output ==
By default `oxford_asl` will generate perfusion (and arrival time) images in the same space as the original data and also at higher resolutions if a structural image (and transformation to standard space) has bee supplied. Further detailed results and summaries can also be produced:
 * `--vars`    includes images that contain the estimated variance on the pefsuion (and arrival time). This might be used as VARCOPE for higher-level GLM analysis.
 * `--report`  calculates are reports the mean perfusion within a grey matter mask (requires a structural image or partial volume estimates of grey matter).
 * `--norm`    creates perfusion maps normalised by the mean grey matter perfusion (sets the `--report` option to calculate the means).
 
== Calibration ==
 * `--M0 [value]          a single precomputed value for the M0 of arterial blood, for example from a separate calibration process using `asl_calib`. If you have an 'M0'image then use the `-c` option and `--cmethod=voxel`.
 * `--alpha [value]       the inversion efficiency of the labelling strategy, default values are derived from the ASL consensus paper.
Using the following options it is possible to request `asl_calib` perform the calibration required to get the M0 of arterial blood and apply it to the perfusion images. More options are available, see the advanced options. This uses `asl_calib` and a custom calibration calculation can be performed using that tool.
 * `-c [M0_calib_image]`  specifies the M0 calibration image that is used to get flow values in absolute units, assumed to be a proton density weighted image (for saturation recovery data use `asl_calib` directly). This should be an image with the repeated measurements stacked in the time dimension.
 * `--tr`                 the TR of the calibration data.
 * `--cmethod`            the method to be used for calibration:
                          `single` in this mode a single M0 value will be computed using the CSF as a reference. This requires either a structural image from which a CSF mask can be derived  or a CSF mask (in the same space as the ASL data). This is the default option if a structural image is supplied.
                          `voxel`  in this mode an image of M0 with a value in very voxel within the brain mask is computed, this follows the recommendation of the ASL consensus paper and is the default when a structural image is not supplied.
 
= Advanced options =
A list of all the extended options (plus notes) can be found with the `--more` command:
{{{
oxford_asl --more
}}}

== Analysis ==
Various options exist for efine the analysis performed on the ASL data, the majority of these apply to multi inflow-time data where more options exist in the form of kinetic model to be used to quantify perfusion.
 * `--artoff`     Turn off correction for signal arising from ASL signal still within the (macro) vascualture, this would be appropriate if the acquisition employed flow suppression or only uses long inflow times. This is a default option for single inflow-time data.
 * `--fixbolus`   Turn off the automatic estimation of bolus duration, this would be appropriate if the bolus (label) duration is well defined by the acquisition sequence, generally true for pcASL, as well as when using pASL plus QUIPSSII. This is a default option for single inflow-time data, since bolus duration cannot be estimated with only a single inflow time.
 * `--fixbat`     Fixes the bolus arrival time to the value specified by the `--bat` command. This is a default option for ingle inflow-time data, since BAT cannot be estimated using only a single-inflow time.
 * `--infert1`     Incorporate uncertainty in the T1 values into the analysis. This will attempt to update the T1 values voxel-wsie based on the ASL data and also incorporates assumptions about the  prior variability in the T1 value(s). This would normally only be used for multi inflow-time data, but it would also update the variances (from `--vars`) if applied to single inflow-time data.
 * `--exch` [model] This sets the model assumes for the exchange of labeled water once it has reached the tissue.
                     `mix`     Makes a well-mixed tissue compartment assumption with venous outflow, see Buxton MRM 1998.
                     'simple'  Assumes a single tissue compartment with no outflow, matches the assumptions in the ASL consensus paper (this is used for the `--wp` option).
 * `--fulldata`    Instructs `oxford_asl` to process the full data without taking the mean at each inflow-time. The advantage of this option is that BASIL is able to make a better estimate of the noise in the data and thus may be more accurate (especially at estimating variances). The disadvantage is slower computation times. This option is recommended if your data has a few inflow-times (<5) repeated many times (otherwise BASIL is working with only a small number of data points after averaging at each inflow time).
 * `--noiseprior`  BASIL uses the data to estimate the noise level starting from a non-informative initial guess. This option attempts a rough initialisation of the noise estimate using the data and a standard assumption about the SNR of ASL data. This might be a good option if your data has few averages.
 * `--noisesd`     Use with `--noiseprior` to set the standard deviation of the noise on the data.

* `-t` (optional) `[struct2std_trans.mat]`       transformation matrix that takes the structural image into standard space. This matrix is an output from the registration process carried out by FLRIT (this is a normal part of FEAT processing for fMRI data for a subject). If this is not supplied data will be output in structural space.
 * `-S` (optional) `[std_image]`  use to specify the standard brain to which registration takes place - this should be the same image as was used in the production of the structural to standard transformation matrix. By default the MNI152_T1_2mm image is used, this is commonly used in other FSL tools.

 





=== Registration ===
 * `-r` (optional) `[low_res_struct]`      low resolution structural image used as an extra step in the registration to improve resulting transformation.

 * `--regfrom` (optional) `[reg_source]`  An alternative image to use as the basis of registration. This should be the same resolution as the ASL data and aligned to it. The raw data before tag-control differencing or the calibration image are often a better reference for registration than the CBF image.



* `--csf` (optional)` [csf_mask]`        Image in the same space as the structural (or low res structural image if supplied) 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.
 * `--cgain` (optional) `[relative_gain_value]`   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.
 * `--t1csf` (optional) `[T1 value for CSF in s]`         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 `asl_calib` at the command line).
 * `--te` (optional) `[Echo time for readout in ms]`      Set the echo time for the reaodut so that T2(*) effects are taken into account in the calibration. If this is not supplied then TE = 0 ms is assumed, i.e. T2(*) effects are negligible. Default values are assumed by `asl_calib` for T2(*) values, you might wish to treat these with caution as these are estimates based on the literature.
 * `--t2star` (optional)  Tells oxford_asl to correct for T2* rather than T2 effects. This simply tells asl_calib to use the default values for T2* in place of T2 in the calculations.
 * `--t2csf` (optional) `[T2 value for CSF]`      Supply a value for the T2 of CSF to be used in the calibration process, only relevant if you supply the TE value. Default values are used by `asl_calib` based on a 3T field strength (these can be checked by calling `asl_calib` at the command line).
 * `--t2bl` (optional) `[T2 value for blood]`     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 `asl_calib` based on a 3T field strength (these can be checked by calling `asl_calib` at the command line).


----
[[CategoryBASIL]]