########################################## 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 .. code-block:: csh ***************************************************** 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) .. code-block:: csh # The basic command required to run the topup script is: run_topup_fmri_prisma -d1 -d2 -i -o 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: .. code-block:: csh # 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. .. code-block:: csh -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: .. code-block:: csh -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. .. code-block:: csh 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 .. code-block:: csh ***************************************************** 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: 1. DTI series containing a full DTI PA acquisition with multiple diffusion directions and a full DTI AP acquisition with multiple diffusion directions .. code-block:: csh 0017_dMRI_dir99_AP 0019_dMRI_dir99_PA 2. 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) .. code-block:: csh 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: .. code-block:: csh run_topup_dif_prisma For data from example #1 (full PA and AP DTI datasets): .. code-block:: csh 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) .. code-block:: csh 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. .. code-block:: csh # Susceptibility induced distortion corrected data .nii.gz dMRI_dir99_topup.nii.gz # From the example above # Eddy current & susceptibility induced distortion corrected data (final product) _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: .. code-block:: csh _V1.nii.gz # 1st eigenvector _V2.nii.gz # 2nd eigenvector _V3.nii.gz # 3rd eigenvector _L1.nii.gz # 1st eigenvalue _L2.nii.gz # 2nd eigenvalue _L3.nii.gz # 3rd eigenvalue _MD.nii.gz # Mean diffusivity _FA.nii.gz # Fractional anisotropy (FA) _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)