We will use an example data folder, DATA_1, to walk through the TORTOISE pipeline. In this example we are using data folder that contains dicom files. If your data is saved as a nifti file at the scanner and has associated bvals and bvecs file, the import routine also shows the example commands for that scenario.The processing steps following both types of routine will be the same. Other data type imports will be explained further in the import section of the documentation.
The intention of this demonstration if to lay out the skeleton for the various processing steps involved in the pipeline.The commands used here in each step will assume default settings and the subsequent pages can guide the user in understanding more the additional tags/quality checks and information about the output files generated.
Step1: You acquire diffusion data and it is now contained in a dicom folder. In certain circumstances, you will have data acquired in opposite phase encoding directions i.e blip up blip down data and data may be distributed into two folders, i.e DATA_1_AP and DATA_1_PA.
Step2: It is strongly adviced that you rename the data folders, such that the final outputs post processing will be easily identifiable as belonging to certain group/subject. An example to rename if the data is of Control_1, then the data folders can be renamed as Cont_001_AP and Cont_001_PA. Now you can be assured that after import, the name will be migrated through all the steps of TORTOISE.
Step3: If you have acquired a T2w fat suppressed data for the subject, please prepare the anatomical image to be used in the processing using the procedures detailed in the section ‘Preparing an anatomical image for distortion correction’. This will result in a structural image T2_acpc.nii or T2_axialized.nii. We will use T2_acpc.nii in our example here.
Step3: IMPORT
There are various types of import routines. In this example the data folders contains dicom (.dcm or .IMA) files.
ImportDICOM -i Cont_001_AP
Or
If data folder contains Cont_001_AP.nii, bvals and bvecs file, acquired with phase encoding along the vertical (AP) axis, then use the nifti import routine:
ImportNIFTI -i Cont_001_AP.nii -b bval -v bvec -p vertical
Please note: A same import routine, needs to be repeated for the other data folder, Cont_001_PA
Step4: The former step now generates Cont_001_AP_proc and if you have the blip down data import, then also Cont_001_PA_proc. Each of these proc folders will contain the .list, .bmatrix and .nii files. Please refer to the section in the documentation, ‘your import results-what to expect’, to get more details on the contents of these files.
Perform DIFFPREP (eddy, motion distortion correction) routine of the pipeline. You may provide the entire path to the list file if you intend to batch process multiple data folders. In this example Cont_001_AP.list and Cont_001_PA.list are housed in the following folder, /raid/study/Cont_001/Cont_001_AP_proc and /raid/study/Cont_001/Cont_001_PA_proc, respectively. So the two DIFFPREP processes for the two folders can be run as follows:
DIFFPREP -i /raid/study/Cont_001/Cont_001_AP_proc /Cont_001_AP.list -s /raid/study/Cont_001/T2_acpc.nii
DIFFPREP -i /raid/study/Cont_001/Cont_001_PA_proc /Cont_001_PA.list -s /raid/study/Cont_001/T2_acpc.nii
Please note: you can provide any number of such DIFFPREP processes, for any number of folders or subjects and paste it into a terminal to run it sequentially.
Step5: Please refer to the section ‘DIFFPREP: outputs of DIFFPREP’ for more details on the files generated after DIFFPREP processing. Unless specified in DIFFPREP, the above basic command has performed an image based EPI correction on the data using the structural data provided. If you only have AP or PA data i.e no blip up blip down data, then your processing ends here and you can continue with fitting the tensor in DIFFCALC section.
If you have AP, PA data, then you will perform DRBUDDI correction. Please note that if you have performed all steps of DIFFPREP using the basic command shown above, then as mentioned before EPI correction will be performed on AP and PA separately. Since DRBUDDI performs EPI correction, you can shorten the DIFFPREP procedure by only using it to do the eddy, motion correction and then proceeding to DRBUDDI.
DIFFPREP -i /raid/study/Cont_001/Cont_001_AP_proc /Cont_001_AP.list -s /raid/study/Cont_001/T2_acpc.nii --will_be_drbuddied 1
DIFFPREP -i /raid/study/Cont_001/Cont_001_PA_proc /Cont_001_PA.list -s /raid/study/Cont_001/T2_acpc.nii --will_be_drbuddied 1
Step6: DRBUDDI needs _proc.list from both AP and PA data to proceed. DIFFPREP command generates _proc.list files inside the proc folders. These files are generated regardless of if you have only AP or have AP-PA or if you have run entire DIFFPREP or only with will_be_drbuddied tag.
DRBUDDI --up_data /raid/study/Cont_001/Cont_001_AP_proc /Cont_001_AP_proc.list --down_data /raid/study/Cont_001/Cont_001_PA_proc /Cont_001_PA_proc.list --structural /raid/study/Cont_001/T2_acpc.nii
More details about output of DRBUDDI in the DRBUDDI section of the documentation.
Step7: the outputs from either DIFFPREP or DRBUDDI can be used in the tensor fitting. DIFFCALC has command line tensor fitting options with linear or nonlinear weighted least square options.
Example is shown if you only have AP folder and diffprep output fitting
i) EstimateTensorNLLS -i /raid/study/Cont_001/Cont_001_AP_proc /Cont_001_AP_DMC.list
Or
If you have DRBUDDI output
ii) EstimateTensorNLLS -i /raid/study/Cont_001/Cont_001_AP_DRBUDDI_proc/Cont_001_AP_DRBUDDI_final.list
Step8: Output of step 7 is Cont_001_AP_DMC_N1_DT.nii or Cont_001_AP_DRBUDDI_final_N1_DT.nii
Please use the DT.nii to computer other tensor maps such as Fractional Anisotropy (FA), Trace (TR) etc. The commands are all housed inside the DIFFCALCv<3x> folder.