Behavior and Neuroimaging Core User Manual
  • About
  • Infrastructure Overview
  • XNAT
    • Getting Started
    • Accessing XNAT
    • BIDS Ready Protocols
    • New XNAT projects
    • Uploading Data
    • Downloading Data
  • Demo Dataset
    • Introduction
    • How to access it
    • Protocol Information
    • Basic analysis example: checks task
  • XNAT to BIDS
    • Getting Started
    • XNAT2BIDS Software
    • Exporting to BIDS using Oscar
      • Oscar Utility Script
        • Running xnat2bids using default configuration
        • Running xnat2bids with a custom configuration
        • Syncing your XNAT project & Oscar data directory
        • Extra tools & features
      • Step-wise via Interact Session
    • BIDS Validation
      • Oscar
      • Docker
    • Converting non-MR data
      • Physiological data
      • EEG data
  • XNAT TO BIDS (Legacy)
    • Oscar SBATCH Scripts
  • BIDS and BIDS Containers
    • Introduction to BIDS
    • mriqc
    • fmriprep
    • BIDS to NIMH Data Archive (NDA)
  • Analysis Pipelines
    • Freesurfer
    • 🚧CONN Toolbox
    • FSL topup and eddy
    • Tractography: DSI Studio
    • Brown University MRS Data Collection and Preprocessing Protocol
    • LC Model
      • Installation
      • Example Run
      • Running LCModel on your own data
    • Quantitative Susceptibility Mapping (QSM)
  • Standalone Tools
    • Multi-session spectroscopy with voxalign
    • dicomsort: a tool to organize DICOM files
    • ironmap
    • convert enhanced multi-frame DICOMs to legacy single-frame
    • DICOM anonymization
  • MRF GUIDES
    • MRI simulator room
      • Motion Trainer: Balloon Task
      • Simulating scanner triggers
    • Stimulus display & response collection
    • Eyetracking at the scanner
    • Exporting data via scannershare
    • EEG in the scanner
    • Exporting spectroscopy RDA files
  • Community
    • MRF/BNC user community meetings
Powered by GitBook
On this page
  • Basic Terminology
  • topup: Correcting for Susceptibility Distortion
  • 1: Create the --imain file
  • 2: Create the parameters file
  • 3: Run topup
  • eddy: Correcting for Eddy Current Distortion
  • 1: Create the index file
  • 2: Create a brain mask
  • 3: Run eddy
  • Additional Resources

Was this helpful?

  1. Analysis Pipelines

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.

PreviousCONN ToolboxNextTractography: DSI Studio

Last updated 10 months ago

Was this helpful?

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.

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.

fslroi sub-001_ses-01_acq-b1500_dir-ap_dwi.nii.gz AP_b0.nii.gz 0 1 \
fslroi sub-001_ses-01_acq-b1500_dir-pa_dwi.nii.gz PA_b0.nii.gz 0 1 \
fslmerge  -t  AP_PA_b0 AP_b0.nii.gz PA_b0.nii.gz

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:

0 -1 0 0.0759
0 1 0 0.0759

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

topup --imain=AP_PA_b0 \
--datain=acqparams.txt \
--config=b02b0.cnf \
--out=topup_AP_PA_b0 \
--iout=topup_AP_PA_b0_iout \
--fout=topup_AP_PA_b0_fout \
--verbose 

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.

#contents of index.txt
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 

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.

fslmaths topup_AP_PA_b0_iout -Tmean hifi_nodif \
bet hifi_nodif hifi_nodif_brain -m -f 0.2

3: Run eddy

eddy --imain=sub-005_ses-session1_acq-b1500_dir-ap_dwi.nii.gz \
--mask=hifi_nodif_brain_mask \
--index=index.txt \
--acqp=acqparams.txt \
--bvecs=sub-005_ses-session1_acq-b1500_dir-ap_dwi.bvec \
--bvals=sub-005_ses-session1_acq-b1500_dir-ap_dwi.bval \
--fwhm=0 \
--topup=topup_AP_PA_b0 \
--flm=quadratic \
--out=eddy_unwarped_images \
--data_is_shelled \
--verbose

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:

To follow this tutorial using the DWI runs acquired in , please download the data from subject 1 session 1. More details on how to do this can be found . In this tutorial, scans 18 and 21 were exported using , 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.

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: .

The code is located at

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:

demodat
here
xnat2bids
https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/ExampleTopupFollowedByApplytopup
https://github.com/brown-bnc/dwi_preprocessing
https://sites.brown.edu/cnrc-core/resources-and-help/
Commands used in FSL distortion correction pipeline
Three diffusion weighted images with b-values of bval=0, 750, and 1500
The brain mask (in red) created using bet, overlaid onto the AP and PA combined hifi_nodif image.
On the left: b0 images acquired in the AP and PA directions, with susceptibility and eddy current distortions. On the right: the combined b0 after distortion correction via TOPUP and eddy