This page includes a number of examples of the use of asl_file. For these exercises you will need the example data from the main BASIL tutorial page.
Exercise 1: Single inflow-time ASL
Calculating a simple perfusion image
The data in data_singleti has 69 repeats all at single inflow-time and contains both the tag and control images interleaved. To create a simple perfusion image we need to do a pairwise subtraction and then take the mean over all the repeats. This can be completed in a single command using asl_file:
asl_file --data=data_singleti/data --ntis=1 --iaf=tc --diff --out=diffdata --mean=diffdata_mean
We have specified the number of inflow times as 1 using --tis and that the data contains tag control pairs (with tag coming as the first volume) with --iaf=tc.
We have asked asl_file to do subtraction prior to output using the --diff option.
We have specified two outputs: the full set of tag-control subtracted 'difference' images with --out=diffdata; the mean difference (perfusion) image with --mean=diffdata_mean
If you run the command you should see:
Number of voxels is:162712 Number of repeats in data is:69 Outputting ASL data mean at each TI Done.
There will be two images output: diffdata.nii.gz with 69 volumes and diffdata_mean with only 1 volume - the (relative) perfusion image.
Extracting the mean control image
We might also want to extract the mean control image from the series, for example if we wanted to use it as the basis of calibration to get perfusion in absolute units (this would assume, as is the case in this data, that background suppression had not been applied).
asl_file --data=data_singleti/data --ntis=1 --iaf=tc --spairs --mean=staticdata_mean
The difference this time is that instead of asking for --diff, we have used the --spairs option to split the pairs.
The output on the command line should look like:
Number of voxels is:162712 Number of repeats in data is:69 Dealing with odd members of pairs Outputting ASL data mean at each TI Dealing with even members of pairs Outputting ASL data mean at each TI Done.
Note that even and odd volumes are both processed, but independently - thus we will get the mean image for both tag and control volumes from this command. As tag images were first in the data then we want the image called staticdata_mean_even.nii.gz which will contain the mean control image. The mean tag image is in static data_mean_odd.nii.gz.
Exercise 2: Multi inflow-time data
In the data_pcasl we have the original tag-control pairs for a data set that has multiple inflow-times (post labelling delays). Before we do any further analysis on this we might want to have done tag control subtraction to get difference data, e.g. ready for oxford_asl or basil. This can easily be achieved with asl_file and as long as we tell it how many inflow times there are it will preserve the individual inflow times.
asl_file --data=data_pcasl/asl_raw_data --ntis=5 --iaf=tc --diff --out=diffdata
The output in this case looks like:
Number of voxels is:98304 Number of repeats in data is:12 Outputting ASL data mean at each TI Done.
Notice that asl_file has correctly recognised that there are 12 repeats of each inflow-time in this data.
The output image diffdata.nii.gz will have 60 volumes (5 inflow times x 12 repeats), the volumes will reflect the same ordering as in the input data, i.e. groups in sets of repeated inflow-times (--obf=rpt since --ibf=rpt and --obf defaults to the input value). this would be correct if we were feeding this data into oxford_asl. However, basil (the command line tool) expects data with repeats of each TI grouped together so we would need to have used --obf=tis - this is unlikely to affect most users since oxford_asl is recommended for most data.
If we want to examine the data by eye - to see the inflow and decay of the label in the voxels (mainly the latter in this case as we mainly have long inflow-times), we could ask asl_file to take the mean over the repeats for each inflow-time using the --mean=<filename> output operation.
asl_file --data=data_pcasl/asl_raw_data --ntis=5 --iaf=tc --diff --out=diffdata_mean
The image diffdata_mean will only have 5 volumes one for each inflow-time.
Exercise 3: Dividing data into epochs
The single inflow-time data data_singleti contains a relatively large number of repeats, thus the acquisition was unusually long for ASL perfusion. We might be interested in how perfusion changed during the duration of the acquisition. However, the signal-to-noise ratio of ASL is too poor to examine individual tag-control difference images (as we created in exercise 1). We might like to divide the data into epochs of a set number of repeats so that we can examine a number of reasonable quality ASL images.
asl_file --data=data_singleti/data --ntis=1 --iaf=tc --diff --epoch=epochdiffmean --elen=8 --eol=0
In this command we have asked asl_file to do tag-control subtraction, but then divide the data into epochs each of length 8 repeats and take the average within the epoch.
The output from the command should look like:
Number of voxels is:162712 Number of repeats in data is:69 Ouput ASL data epochs Number of measurements from end of data discarded: 5 Done.
Notice that 69 tag-control difference volumes does not neatly divide by 8, so asl_file discards the final 5 and provides a warning to that effect.
The files created by this command are all called epochdiffdmean followed by a number , in this case in the range 000 to 007, as there are 8 possible epochs of length 8. Each file represents the mean difference (perfusion) image for each epoch of 8 repeats/volumes in the order of the data so epochdiffmean000.nii.gz is from the start and epochdiffmean007.nii.gz is from near the end.
In the above example we didn't allow the epochs to overlap. However, we can vary the overlap between epochs using the --eol option, for example:
asl_file --data=data_singleti/data --ntis=1 --iaf=tc --diff --epoch=epochdiffmean --elen=9 --eol=3
Which gives an output of
Number of voxels is:162712 Number of repeats in data is:69 Ouput ASL data epochs Done.
Notice that there are no discarded data this time as our choice of epoch length and overlap between epochs allows us to use all the data.
From this command we get 11 perfusion images.