#This is a template for a FSL tool sub-section # Create subpages as ToolName/blah # Remember to add this page to the appropriate category <> = 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 [[topup/ApplytopupFurtherInformation#Least-squares restoration|"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.