Example of running topup followed by applytopup

These examples pertains to the sequential use of topup and applytopup.

The simplest, and typical use of topup is when you have two acquisitions and have manipulated your acquisitions so that the phase-encode direction is anterior<->posterior and is anti-parallel in the two acquisitions (i.e. the phase-encode blips are reversed). Let us further assume that you have repeated your entire experiment with the two differene acquisition parameters, i.e. you have acquired your b0 and all your dwis with both blip polarities. Let us further assume that these data are contained in two 4D image files that you have named blip_up.nii.gz and blip_down.nii.gz. The first thing we need to is to decide which of our data we want to use for the estimation of the field. This would typically be the b0 images from the two acquisitions. The reason for this is the these have higher SNR than the dwis, and because, unlike the dwis, they will be unafflicted by and additional source of distortions known as "eddy current-induced distortions". So, let us now say that the first volume of each of blip_up.nii.gz and blip_down.nii.gz is the b0 images for the respective acquisitions. We then extract these and put them into a single file using something like

fslroi blip_up b0_blip_up 0 1
fslroi blip_down b0_blip_down 0 1
fslmerge -t both_b0 b0_blip_up b0_blip_down

which results in both_b0 being a 4D-file containing two volumes, the first acquired with positive phase-encode blips and the second with negative. The second thing to do is to create a text file that informs topup how the images were acquired. In this case the file, which we name my_acq_param.txt would contain

0 1 0 0.087
0 -1 0 0.087

where the three first columns of each row is a signed, normalised "phase-encode direction vector" and the final column is the time (in seconds) between the readout of the centre of the first echo and the centre of the last echo (equal to dwell-time multiplied by # of phase-encode steps minus one). The [0 1 0] vector in the first row indicates that the first scan in the both_b0 file was acquired with phase-encoding in the y-direction (anterior<->posterior) using positive phase-encode blips and correspondingly the [0 -1 0] in the second row that the second scan in both_b0 was acquired with negative blips.

The fourth column indicates that total readout times was 87ms for both acquisitons. When the readout time is identical for all acquisitions this simply serves to ensure that the estimated field is correctly scaled in Hz, but it doesn't affect the result in terms of undistorted images. If one e.g. sets it to 1 it simply means the field will be scaled as "voxels displacement" instead. When the different scans have different readout times it becomes crucial that they are entered correctly.

These two file are now used to execute topup with the command

topup --imain=both_b0 --datain=my_acq_param.txt --config=b02b0.cnf --out=my_topup_results

which will upon completion create the two files my_topup_results_fieldcoef.nii.gz and my_topup_results_movpar.txt.

As of yet no images have been corrected so the next step will be to use these results to run applytopup. We want to correct all the images, not just the b=0 images, so we now return to the original files blip_up.nii.gz and blip_down.nii.gz. The command we use is

applytopup --imain=blip_up,blip_down --inindex=1,2 --datatin=my_acq_param.txt --topup=my_topup_results --out=my_hifi_images

where --inindex=1,2 specifies the relation between the list of files given by --imain and the acquisition parameters in my_acq_param.txt and the movement parameters in my_topup_results_movpar.txt. The index 1 (from --inindex=1,2) specifies that for the file blip_up.nii.gz applytopup should use the first line of my_acq_param.txt when correcting the distortions and the first line of my_topup_results_movpar.txt when correcting the movements. Correspondently the index 2 specifies that for the file blip_down.nii.gz applytopup should use the second line of my_acq_param.txt and of my_topup_results_movpar.txt.

It may be helpful to note (and understand) that

applytopup --imain=blip_down,blip_up --inindex=2,1 --datatin=my_acq_param.txt --topup=my_topup_results --out=my_hifi_images

is exactly analogous to the applytopup command above.

The output of this is a file named my_hifi_images.nii.gz which will contain as many volumes as blip_up.nii.gz (or blip_down.nii.gz for that matter) where each pair of images in blip_up.nii.gz and blip_down.nii.gz has been combined into a single image in my_hifi_images.nii.gz using the "Least-Squares Restoration" method. Because the pairs of images are combined into a single image it is of course crucial that the data in blip_up and blip_down has been collected using identical protocols, i.e. if volume i in blip_up was acquired with a diffusion weighting given by the vector g_i then volume i in blip_down must also have been acquired with g_i. It is the users responsibility to ensure this since there is no way for applytopup to verify it.