FSL topup and eddy
FSL offers command line tools for susceptibility distortion and eddy current correction. This is often the first step in preparing diffusion data for analysis.
Basic Terminology
B-value: A factor which describes the amount of diffusion weighting, i.e., the duration, amplitude, and time between the application of diffusion gradients. Higher b-values indicate stronger diffusion effects and are achieved by increased amplitude/duration of gradient pulses as well widening the intervals between the pulses (Abou khadrah & Imam, 2019). The higher the b-value, the lower the signal. Volumes with a b-value of 0 are those with no diffusion gradient applied.
B-vector: A 3x1 vector (x, y, and z) for each volume, which describes the direction that the diffusion gradient will be applied.
B-table: A table where each row has four entries: the b-value followed by the x, y, and z components of the b-vector. This repeats with one row for each volume. B-tables are embedded in the DWI protocol on the MRI console, and are used to control the strength, direction, and duration of the diffusion gradients at the scanner level. B-tables are also used in many common diffusion preprocessing software, including dsi-studio (where it is transformed into the b-matrix and used to create diffusion tensor images).
Shell: The number of shells of a DWI protocol describes the number of non-zero b-values used. Single-shell protocols have one b-value which repeats with varying directions of the diffusion gradient. Multi-shell protocols acquire two or more b-values at multiple directions.
Susceptibility Distortion: Susceptibility is the property of a substance that determines if it becomes magnetized when placed in a magnetic field. Further, substances can be diamagnetic (resulting in a repelling/dispersion of the magnetic field around it), or paramagnetic (resulting in an attraction/concentration of the magnetic field around it). Most biological tissues such as bone, muscle, and fat are slightly diamagnetic. Air, such as that in the sinuses, is also slightly diamagnetic. Metallic ions are slightly paramagnetic, and when they are grouped into clusters or accumulated, they can exhibit superparamagnetism. The most concentrated forms of these ions (ie, solid metals with iron/nickel, etc) are ferrous, or ferromagnetic, and result in the largest susceptibility artifacts.
Eddy Currents: Electrical currents (eddy currents) appear in nearby conductive materials (coils, shields, the participant) when an MRI is creating a rapidly changing magnetic field. The magnitude of the eddy current increases as the rate of change of the magnetic field increases. Because of this, EPI, DWI, MR Spectroscopy, and anything else with a short echo time will be affected. It is an issue in MRI processing because it results in image distortions (shearing/scaling artifacts, global position shifts) and in the case of DWI, it can result in spuriously high ADC values.
topup: Correcting for Susceptibility Distortion
1: Create the --imain file
topup requires at least one volume in each of the two opposite phase encoding (PE) directions. topup can work if the PE directions are different but not opposite (for example, A->P and R->L), but the distortion correction may not be as high quality as using two opposing acquisitions. For diffusion imaging, you may use one B0 image per PE direction, or you may merge multiple B0 images before inputting to topup.
To follow this tutorial using the DWI runs acquired in demodat, please download the data from subject 1 session 1. More details on how to do this can be found here. In this tutorial, scans 18 and 21 were exported using xnat2bids, which converts them to NIFTI and names them according to the BIDS format. If you choose not to use xnat2bids and instead download the DICOMs directly, please use dcm2niix to convert the DICOM images to NIFTI.
The first two volumes of each demodat DWI run are b0 images. We will extract the first volume of both runs using the command fslroi, and merge them over time using fslmerge. The end result of these transformations is one image named AP_PA_b0, which contains 2 b0 volumes- one in each PE direction.
2: Create the parameters file
The parameters file is a simple text file, with one line for each volume in the --imain file. Since we just merged the first B0 files for each PE dir, there will be 2 lines.
For each line, the first three values describe the phase encoding direction vector, in the x, y, and z planes respectively. The fourth column of this file describes the total readout time, which can be found in the .json file corresponding to each run. This number is typically the same for each row in the column and does not change with differing PE directions unless otherwise specified in your sequence protocol.
Name this file acqparams.txt. Its contents should look like this:
A -1 in the second column means that k-space was traversed Anterior→Posterior and a 1 means that it was traversed Posterior→Anterior.
3: Run topup
Remember: topupproduces an --iout file, which contains as many volumes as are in the --imain file (in this example, 2 volumes), corrected for susceptibility distortion. This is not the full corrected dataset. If you would like a susceptibility distortion corrected dataset, you must use the command applytopup and provide a full dwi acquisition.Documentation on applytopup can be found here: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/ExampleTopupFollowedByApplytopup.
If you would like both susceptibility and eddy current distortion correction, you can move directly to eddy without using applytopup first.
eddy: Correcting for Eddy Current Distortion
1: Create the index file
The text-file index.txt contains a row of numbers, one for each volume in your dwi data, specifying that those volumes were acquired with the parameters specified by the corresponding row in acqparams.txt. We will be inputting the AP dwi scan into eddy, thus our index.txt file will contain a row of 1s. If we were to input the PA run, it would contain a row of 2s.
2: Create a brain mask
Regardless of the pipeline you are using, it is recommended that the brain mask is created after susceptibility distortion correction, but before eddy current correction (Tax et al., 2022). This is because the signal pile up/reduction due to susceptibility artifact can lead to inaccurate masking.
First, use fslmaths to combine the AP and PA outputs of topup into one file. the -Tmean option tells fslmaths to take the mean across time, resulting in a 3D dataset (one volume) named hifi_nodif (high fidelity, no diffusion). Then, that volume will be input into bet (Brain Extraction Tool) to create a brain mask.
3: Run eddy
Additional Resources
If you would like to run topup and eddy as a batch script on multiple subjects/sessions, please refer to the excellent documentation written by Hannah Swearingen (Brown Clinical Neuroimaging Research Core), found here:
The code is located at https://github.com/brown-bnc/dwi_preprocessing
https://sites.brown.edu/cnrc-core/resources-and-help/ provides a "Diffusion Preprocessing" powerpoint which goes step by step in running the batch script
For a detailed explanation of the commands used in this tutorial, and what their options signify, please refer to this slideshow: Commands used in FSL distortion correction pipeline
Last updated
