CFMRI Prisma - TOPUP Distortion Correction

CFMRI offers the use of custom wrapper scripts to prepare Siemens fMRI & DTI data for use in the FSL topup distortion correction toolbox.

After organizing the data to meet the input requirements of the FSL topup program, the data are automatically used as input in this popular method for estimating and correcting susceptibility induced distortions.

https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup

CFMRI maintains a series of topup related scripts on all our servers used by the imaging community.

fMRI Topup at CFMRI (3T Prisma)

The most commonly used version of CFMRI topup code for fMRI data acquired on the 3T Prisma is “run_topup_fmri_prisma”

Example Imaging Session Including fMRI and DTI from cfmricp_log.txt

*****************************************************
Scan Directories
*****************************************************

0001_localizer_32ch
0002_AAHScout
0003_Localizer_aligned

0004_ABCD_T1w_MPR_vNav_setter
0005_ABCD_T1w_MPR_vNav

0006_ABCD_dMRI_DistortionMap_PA
0007_ABCD_dMRI_DistortionMap_AP
0008_ABCD_dMRI_PA

0009_ABCD_fMRI_DistortionMap_PA
0010_ABCD_fMRI_DistortionMap_AP

0011_ABCD_fMRI_rest
0012_ABCD_fMRI_rest_PMU
0013_ABCD_fMRI_rest
0014_ABCD_fMRI_rest_PMU

0017_dMRI_dir99_AP
0019_dMRI_dir99_PA

0099_PhoenixZIPReport

*****************************************************

Example fMRI Topup Command (used to process the “fMRI_rest” datasets above)

# The basic command required to run the topup script is:

   run_topup_fmri_prisma -d1 <topupDataPA> -d2 <topupDataAP> -i <fmriDataPA> -o <desiredOutputName>

This script is flexible and can accept data format inputs ranging from dicom directories to reconstructed nii.gz files

Using the example dicom data listed in the cfmricp_log.txt file above:

# This command will run directly on the raw dicom directories pulled from the scanner:

   run_topup_fmri_prisma -d1 0009_ABCD_fMRI_DistortionMap_PA -d2 0010_ABCD_fMRI_DistortionMap_AP -i 0011_ABCD_fMRI_rest -o 0011_ABCD_fMRI_rest_topup

# If you already have nii.gz reconstructed versions of the data, you can input those files directly into the topup command, either with nii.gz included in the filename:

   run_topup_fmri_prisma -d1 ABCD_fMRI_DistortionMap_PA.nii.gz -d2 ABCD_fMRI_DistortionMap_AP.nii.gz -i ABCD_fMRI_rest.nii.gz -o ABCD_fMRI_rest_topup

# or without nii.gz included in the filename:

   run_topup_fmri_prisma -d1 ABCD_fMRI_DistortionMap_PA -d2 ABCD_fMRI_DistortionMap_AP -i ABCD_fMRI_rest -o ABCD_fMRI_rest_topup

# Or any combination of dicom directories and/or nii.gz files:

   run_topup_fmri_prisma -d1 0009_ABCD_fMRI_DistortionMap_PA(dicom dir) -d2 0010_ABCD_fMRI_DistortionMap_AP(dicom dir) -i ABCD_fMRI_rest.nii.gz(nifti) -o ABCD_fMRI_rest_topup

Available Optional Input Arguments

It is important to note that the default mode for this code will complete motion correction (3dVolreg) on the fMRI data and delete all temporary files (with the exception of the motion registration parameters).

In some cases, you may wish to complete motion correction using your own preferred methods.

Using the flag below, you can run the entire data prep and topup process without invoking the built-in motion correction option.

-nomoco

If you prefer to hold onto the temporary files created by our wrapper script you can add the following flags to your “run_topup_fmri_prisma” command:

-nocleanup
-tmpdir DirName #Specify your own directory name for the temporary files

Adding the -nocleanup and -tmpdir options to the initial topup command will preserve the files below.

b02b0.cnf
bothb0.nii.gz
bothb0_rs.nii.gz
bothb0_rs.topup_log
cal_ap.nii.gz
cal_pa.nii.gz
epi.nii.gz
epi_regb0.nii.gz
epi_reg.nii.gz
flist
flist1
motion.1D (preserved by default)
my_acq_para.txt

DTI Topup at CFMRI (3T Prisma)

The most commonly used version of CFMRI topup code for DTI data acquired on the 3T Prisma is “run_topup_dif_prisma”

Example Imaging Session Including fMRI and DTI from cfmricp_log.txt

*****************************************************
Scan Directories
*****************************************************

0001_localizer_32ch
0002_AAHScout
0003_Localizer_aligned

0004_ABCD_T1w_MPR_vNav_setter
0005_ABCD_T1w_MPR_vNav

0006_ABCD_dMRI_DistortionMap_PA
0007_ABCD_dMRI_DistortionMap_AP
0008_ABCD_dMRI_PA

0009_ABCD_fMRI_DistortionMap_PA
0010_ABCD_fMRI_DistortionMap_AP

0011_ABCD_fMRI_rest
0012_ABCD_fMRI_rest_PMU
0013_ABCD_fMRI_rest
0014_ABCD_fMRI_rest_PMU

0017_dMRI_dir99_AP
0019_dMRI_dir99_PA

0099_PhoenixZIPReport

*****************************************************

The example above illustrates 2 common variants of DTI data acquired at CFMRI:

DTI series containing a full DTI PA acquisition with multiple diffusion directions and a full DTI AP acquisition with multiple diffusion directions

0017_dMRI_dir99_AP
0019_dMRI_dir99_PA

DTI series containing short distortion maps (PA and AP phase encoding) and a full DTI acquisition with multiple diffusion directions (typically acqired using PA phase encoding)

0006_ABCD_dMRI_DistortionMap_PA
0007_ABCD_dMRI_DistortionMap_AP
0008_ABCD_dMRI_PA

Example DTI Topup Commands

The basic command required to run the DTI topup script is:

run_topup_dif_prisma <dMRI_PA> <dMRI_AP> <desiredOutputName> <maxBval>

For data from example #1 (full PA and AP DTI datasets):

run_topup_dif_prisma 0019_dMRI_dir99_PA 0017_dMRI_dir99_AP dMRI_dir99_topup 3000

For data from example #2 (short distortion maps & full PA DTI dataset)

run_topup_dif_prisma 0013_ABCD_dMRI_PA 0012_ABCD_dMRI_DistortionMap_AP ABCD_dMRI_topup 3000 -fm

Important

The “run_topup_dif_prisma” script requires the PA dataset as the first input and the AP data (full scan or short distortion map) as the second input. If a short distortion map is acquired instead of a full AP DTI dataset, the “-fm” flag must be used at the end of the topup command (see example above).

DTI Topup Output

Upon completion of the run_topup_dif_prisma script, 2 distortion corrected datasets will be generated.

# Susceptibility induced distortion corrected data

<desiredOutputName>.nii.gz
dMRI_dir99_topup.nii.gz # From the example above

# Eddy current & susceptibility induced distortion corrected data (final product)

<desiredOutputName>_eddy.nii.gz
dMRI_dir99_topup_eddy.nii.gz # From the example above

Additionally, FSL “DTIfit” will be run automatically on the topup/eddy corrected dataset.

https://users.fmrib.ox.ac.uk/~behrens/fdt_docs/fdt_dtifit.html

The DTIfit process will generate:

<desiredOutputName>_V1.nii.gz   # 1st eigenvector
<desiredOutputName>_V2.nii.gz   # 2nd eigenvector
<desiredOutputName>_V3.nii.gz   # 3rd eigenvector
<desiredOutputName>_L1.nii.gz   # 1st eigenvalue
<desiredOutputName>_L2.nii.gz   # 2nd eigenvalue
<desiredOutputName>_L3.nii.gz   # 3rd eigenvalue
<desiredOutputName>_MD.nii.gz   # Mean diffusivity
<desiredOutputName>_FA.nii.gz   # Fractional anisotropy (FA)
<desiredOutputName>_S0.nii.gz   # Raw T2 signal with no diffusion weighting

Issues or Questions

If you have questions or encounter into any issues running this script, please contact Aaron Jacobson (ajacobson@ucsd.edu)