Contents

  1. Introduction
  2. Topup Users Guide
  3. Example Topup Followed By Applytopup
  4. FAQ
  5. Topup Further Information
  6. Applytopup Further Information

Running applytopup

In order to best understand how one needs to run applytopup for a given set of data one must know the details of how topup was run on those same data. We therefore refer you to the documentation for the sequential use of topup and applytopup.

List of parameters

Parameters explained

--imain

List of files with images that you want to correct. This will not be the same file as you used as input to topup. For topup you needed to put your different acquisitions in the same file, whereas for applytopup you need to keep them separate. A typical use would be

applytopup --imain=my_blipup,my_blipdown --datain=my_parameters --inindex=1,2 --topup=my_field --out=my_good_images where my_blipup is a 4D file containing volumes acquired with positive phase-encode blips and my_blipdown contains volumes acquired with negative blips. The resulting undistorted file will be a combination of the two input volumes, where the details of that combination depends on the --method parameter. Hence, the two files must contain data that is identical save for the acquisition parameters. If e.g. my_blipup consists of a b0 volume followed by three dwis with diffusion gradients [1 0 0], [0 1 0] and [0 0 1], then my_blipdown must contain a b0 volume followed by dwis corresponding to [1 0 0], [0 1 0] and [0 0 1]. The output (my_good_images) will then contain a single copy of a b0 followed by [1 0 0], [0 1 0] and [0 0 1] dwis.

When using --method=jac it is in principle possible to generate one unwarped volume per input volue. However, all files specified together for --imain will be combined into a single output file. If one would want separate distortion corrected images (e.g. if one has scanned different sets of diffusion gradients for the two acquisitions) one can obtain that by applytopup --imain=my_blipup --datain=my_parameters --inindex=1 --topup=my_field --method=jac --out=my_good_blipup_images applytopup --imain=my_blipdown --datain=my_parameters --inindex=2 --topup=my_field --method=jac --out=my_good_blipdown_images If one specifies more than two input files they will all be combined into a single output file. Let us say e.g. one has acquired two repeats with blipup and one repeat with blipdown one can run

applytopup --imain=my_blipup1,my_blipup2,my_blipdown --datain=my_parameters --inindex=1,2,3 --topup=my_field --out=my_good_images in which case my_good_images will represent a combination of all three inputs.

--datain

This is a text-file containing information about the acquisition parameters for the images. For all cases I can think of this will be identical to the file given as input to topup.

--inindex

This is a slightly tricky parameter to understand, and one where I suspect I will be doing a lot of explaining/helping.

It consists of a set of indicies like e.g. --inindex=1,3. The order of these corresponds to the order in which the files to --imain are specified, and their values correspond to the rows in the --datain and --topup files. I think the easiest way to explain it is with an example.

Let us say you have collected data according to the fmrib 29-31 protocol. It consists of two acquisitions, one with 1 b0 volume followed by 29 different dwis. The second acquisition also starts with a b0 volume, followed by 31 different dwis. The 29+31 dwis together constitute 60 unique directions sampled uniformly(ish) on the whole-sphere. Let us further assume that the full protocol has been repeated once for blip-up and once for blip-down acquisition and that the files are named fmrib29_bup, fmrib31_bup, fmrib29_bdn, fmrib31_bdn respectively.

To correct these we would start by extracting all b0 files and collecting them in a single file.

fslroi fmrib29_bup b0_1_bup 0 1 fslroi fmrib31_bup b0_2_bup 0 1 fslroi fmrib29_bdn b0_1_bdn 0 1 fslroi fmrib31_bdn b0_2_bdn 0 1 fslmerge -t all_my_b0 b0_1_bup b0_2_bup b0_1_bdn b0_2_bdn and by creating a --datain file named my_acqu_para.txt containing

0 1 0 0.087 0 1 0 0.087 0 -1 0 0.087 0 -1 0 0.087 We are now ready to run topup with a command like

topup --imain=all_my_b0 --datatin=my_acqu_para.txt --config=my_nifty_parameters --out=my_topup_output This will generate two output files, one .nii file called my_topup_output.nii containing spline coefficients defining the field and a text file called my_topup_output.txt containig 4 sets of movement parameters, one for each volume in all_my_b0

0 0 0 0 0 0 -0.0323452 0 -0.131612 -5.99714e-05 -0.00182856 -0.000162457 0.391246 0 -0.514049 -0.00478399 -0.00929278 0.00235141 0.402124 0 -0.531344 -0.00554897 -0.00924577 0.00213802 These are now used to correct for distortions (and movement between the b0 images) using

applytopup --imain=fmrib29_bup,fmrib29_bdn --datain=my_acqu_para.txt --inindex=1,3 --topup=my_topup_output --out=fmrib29_hifi applytopup --imain=fmrib31_bup,fmrib31_bdn --datain=my_acqu_para.txt --inindex=2,4 --topup=my_topup_output --out=fmrib31_hifi Note how the file fmrib29_bup is given an index 1, that is used to index the row 0 1 0 0.087 in my_acqu_para.txt and the row 0 0 0 0 0 0 in my_topup_output.txt. Equivalently fmrib29_bdn has the index 3, indexing the row 0 -11 0 0.087 in my_acqu_para.txt and the row 0.391246 0 -0.514049 -0.00478399 -0.00929278 0.00235141 in my_topup_output.txt. Note also that the first applytopup command above could equivalently have been written

applytopup --imain=fmrib29_bdn,fmrib29_bup --datain=my_acqu_para.txt --inindex=3,1 --topup=my_topup_output --out=fmrib29_hifi Note also that we could NOT have used

applytopup --imain=fmrib29_bup,fmrib29_bdn,fmrib31_bup,fmrib31_bdn --datain=my_acqu_para.txt --inindex=1,3,2,4 --topup=my_topup_output --out=fmrib_anything_but_hifi since that would have led to averaging across data acquired with different diffusion gradients. I repeat, the above it NOT valid.

--topup

This should be the basename that was given for the --out parameters when running topup. Given --topup=my_filename, --applytopup will assume the existence of my_filename.nii (or my_filename.nii.gz) and my_filename.txt and use these. Back to list of parameters

--out

This will be the (base)name of the corrected output images. Note that there will always only be one output file regardless of the number of input (--imain) files. If one wants separate output files for the different inputs. So e.g.

applytopup --imain=blip_up,blip_down --datain=my_para,txt --inindex=1,2 --topup=my_topup_output --method=jac --out=my_hifi_images will produce a single output whereas

applytopup --imain=blip_up --datain=my_para,txt --inindex=1 --topup=my_topup_output --method=jac --out=my_hifi_blipup_images applytopup --imain=blip_down --datain=my_para,txt --inindex=2 --topup=my_topup_output --method=jac --out=my_hifi_blipdown_images will produce two separate files.

--method

This parameter decides which of the two resampling methods to use. If --method=jac is used there will be a kernel based interpolation described below. If --method=lsr is used a voxel-specific kernel will be estimated and used to deduce a single interpolated value from the data from both (or more) input volumes. N.B. that this voxel-specific kernel will have negative lobes and it can therefore introduce negative values even when given input that has all positive values. Therefore if ones subsequent analysis methods/software assume positive values one should use something like fslmaths my_splinterpolated_images -abs my_positive_splinterpolated_images before proceeding.

--interp

When using --method=jac and the transform x->x' maps to a point that is not on a voxel centre in the --in volume, the pertinent intensity value will have to be deduced from the intensities at the surrounding voxel centres. This process is known as interpolation. In applytopup there are two choices, tri-linear interpolation of cubic B-spline interpolations. In general, spline interpolation is more accurate at the cost of slightly longer execution time. I would strongly recommend spline interpolations, and hence it is the default.

N.B. that spline interpolation can introduce negative values even when given input that has all positive values. Therefore if ones subsequent analysis methods/software assume positive values one should use something like fslmaths my_splinterpolated_images -abs my_positive_splinterpolated_images before proceeding.