iDIO

iDIO is a software toolkit for processing diffusion-weighted MRI data. It integrates the functionalities of modern MRI software packages to constitute a complete data processing pipeline for structural connectivity analysis of the human brain.

Installation Guide

iDIO can be run in Linux and macOS environment (Most recommend: Linux) . Its major functionalities come from Mrtrix3, FSL, ANTS, and PreQual . Details for each software tools can be found in the links below:

Currently, iDIO relies on command-line shell functions from MRtrix3, FSL, and ANTs, and therefore these software tools and their relevant dependencies need to be installed before using iDIO. iDIO also relies on Python3 to perform (1) bias correction in DWI data (namely DWI signal drifting), (2) scaling the connectivity matrix with mu and (3). Requires a few Python3 library: including argparse(1.4.0), numpy(1.18.1), pandas(0.24.2), scipy(1.2.1), nibabel(3.2.0), scikit-image(0.18.1) and matplotlib(3.0.3), you may install those library with pip

you can install those library with:

$ pip install argparse numpy pandas nibabel scikit-image matplotlib

Setting

before started, it is necessary to export the home directory of iDIO as iDIO_HOME.

$ export iDIO_HOME = iDIO pipeline location

Tutorial

Data preparing

The iDIO pipeline require DWI data and T1 data to be stored in Brain Imaging Data Structure (BIDS) format, where the modality is indicated in the suffix of each image file. JSON file for each sequence is necessary for iDIO preprocess. iDIO also support DWIs with only one phase encoding.

an example is as follows:

sub-001
├── anat
│    ├── sub-001_T1w.json
│    └── sub-001_T1w.nii.gz
└── dwi
	 ├── sub-001_acq-multibandAP_dwi.bval
	 ├── sub-001_acq-multibandAP_dwi.bvec
	 ├── sub-001_acq-multibandAP_dwi.json
	 ├── sub-001_acq-multibandAP_dwi.nii.gz
	 ├── sub-001_acq-multibandPA_dwi.bval
	 ├── sub-001_acq-multibandPA_dwi.bvec
	 ├── sub-001_acq-multibandPA_dwi.json
	 └── sub-001_acq-multibandPA_dwi.nii.gz

One-click solution: run Main.sh with argument file (SetUpOGIOArg.sh)

Synopsis Performing the iDIO pipeline with predefined options.

Usage

bash Main.sh -bids InputDir -proc OutputDir -arg SetUpiDIOArg.sh

-bids InputDir: Data path that including two directories - anat (T1w.nii.gz/T1w.json) and dwi (dwiPHASE.nii.gz, dwiPHASE.bval, dwiPHASE.bvec, dwiPHASE.json) (As shown in the ** Data preparing** section above. Note: T1w and dwi are case sensitive)
-proc OutputDir: Provide a output path for saving the output processed data
-arg SetUpiDIOArg.sh: Provide a script that include all needed predefined options. [default = ${IDIO_HOME}/SetUpiDIOArg.sh if not provided] (For more details, please see Options below)

Options All options need to be predefined are list in the ** SetUpiDIOArg.sh** file. A template file is stored in the home directory of iDIO. iDIO pipeline include eight steps in the following order, (1) data preprocessing, (2) bias correction, (3) eddy correction, (4) T1 preprocessing, (5) diffusion tensor fitting, (6) constrained spherical deconvolution processing, (7)network construction and (8)quality control

Step: Set the wanted processing steps to perform [default=1.2.3.4.5.6.7.8]
first/second: If the series number is not recorded in the JSON file, please provide the filename by the scan order [default=None]
cuda : A boolean value to indicate whether to run the CUDA version of eddy to speed up the processing procedure. iDIO will automatically selected the supported cuda version (8.0/9.1/10.2) if the processing server has discrete GPU installed with CUDA. [default=0]
stv: A boolean value to indicate whether to perform the slice-to-volume correction. Slice-to-volume correction only implemented for CUDA version. [default=0]
rsimg: Specifies the isotropic voxel size (mm) of DWIs, which will be apply before step (5) diffusion tensor fitting and step (6) constrained spherical deconvolution. [default=0 (no resize)]
bzero: Specifies the values to determine the null image with certain b-value threshold [default = 10]
AtlasDir: Default needed files were save in ${iDIO_HOME}/share with several folders, we recommend not to change this path, but save Atlas you need in ${iDIO_HOME}/share/Atlas instead. [default = ${iDIO_HOME}/share]
trkNum: Specifies the desired number of streamlines to be selected when generating the tractogram [default = 10M]

Recommended imaging acquisition

There are some recommendation for imaging acquisition for further iDIO preprocessing.

Assured that image acquisition did not undergo an image interpolation to prevent change in noise distribution. (turn off the interpolation option on the vendor machine to prevent this issue).
Gibbs ring removal relies on full k-space coverage data, data that did not meet the requirement have to be aware of a suboptimal result.
Evenly distributed interleaved b=0 images may provide a better estimation of the image signal drifting profile.
Acquiring diffusion data using an entire sphere diffusion encoding manner with phase encode reversed image (at least with b=0 images), which may be able to run all corrections of susceptibility-induced distortion, eddy current-induced distortion and subject movement.
Tips in image acquisition with Siemens simultaneous multi-slice images: number of slices divided by the multiband factor has to be and odd number to prevent the artifactually bright slices in the image (Andersson et al., 2017; Center for Magnetic Resonance Research, 2012.
If diffusion tensor fitting is required, at least 13 diffusion directions are needed with a b-value lower than 1500 s/mm². For CSD, multi-shell diffusion weighted imaging is recommended. At least one low b-value shell and one high b-value shell (greater than 2000 s/mm²) with more than 45 diffusion directions is recommended to provide better angular resolution of CSD modelling and have advantages in modelling multi-tissue response function (Tournier et al., 2013)

Details of each step

Step 0: CheckData.sh

Synopsis

This is not embeded in the main script. This script aims to Initially check the data accessibility with proper reverse phase diffusion images in matched folder.

Usage

bash 0_CheckData.sh -b BIDSDir

-b InputDir datapath that including two directory- anat (T1w.nii.gz/T1w.json) and dwi (dwiPHASE.nii.gz, dwi.bval, dwi.bvec, dwi.json)

Step 1: 1_DWIprep.sh

Synopsis DWI data preparation (identify phase encoding of DWI image and generate needed description files in 0_BIDS_NIFTI and 1_DWIprep folders)

└── OutputDir
	 ├── 0_BIDS_NIFTI
	 │   ├── T1w.json
	 │   ├── T1w.nii.gz
	 │   ├── dwi_AP.bval
	 │   ├── dwi_AP.bvec
	 │   ├── dwi_AP.json
	 │   ├── dwi_AP.nii.gz
	 │   ├── dwi_PA.bval
	 │   ├── dwi_PA.bvec
	 │   ├── dwi_PA.json
	 │   └── dwi_PA.nii.gz
	 ├── 1_DWIprep
	 │   ├── Acqparams_Topup.txt
	 │   ├── Eddy_Index.txt
	 │   ├── Index_PE.txt
	 │   └── MBF.txt

Usage

bash 1_DWIprep.sh -b InputDir -p OutputDir [ options ]

-b InputDir datapath that including two directory- anat (T1w.nii.gz/T1w.json) and dwi (dwiPHASE.nii.gz, dwiPHASE.bval, dwiPHASE.bvec, dwiPHASE.json) Note: T1w and dwi are case sensitive.
-p OutputDir Provide a output path for saving the output processed data

Options

-first 1stFilename filename of the former acquired diffusion data, no need to specifty the filename extension (i.e. dwi1)
-second 2ndFilename filename of the latter acquired diffusion data, no need to specifty the filename extension (i.e. dwi2)

Reference

2_BiasCo.sh

Synopsis implement the 4D signal denoise, gibbs ringing correction, and drifting correction

Usage

bash 2_BiasCo.sh [ options ]

└── OutputDir
         ├── 2_BiasCo
	 │   ├── Drifting_Correction_B0only.png
	 │   ├── Drifting_Correction_allData.png
	 │   ├── Drifting_val.csv
	 │   ├── Res.nii.gz
     	 │   ├── dwi_AP-denoise.nii.gz
	 │   ├── dwi_AP-noise.nii.gz
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo.nii.gz
	 │   ├── dwi_APPA-denoise-deGibbs.nii.gz
	 │   ├── dwi_APPA.bval
         │   ├── dwi_APPA.bvec
	 │   └── dwi_APPA.nii.gz

Options

-p OutputDir the OutputDir has to include the 1_DWIprep folder (includes the converted files) [default = pwd directory]

3_EddyCo.sh

Synopsis implement the distortion and eddy correction. Preprocessed_data folder will be generated when 3_Eddyco is finished

└── OutputDir
	 ├── 3_EddyCo
	 │   ├── Acqparams_Topup.txt
	 │   ├── B0.nii.gz
	 │   ├── B0.topup_log
	 │   ├── DWI.json
	 │   ├── Eddy_Index.txt
	 │   ├── Field.nii.gz
	 │   ├── Mean_Unwarped_Images.nii.gz
	 │   ├── Mean_Unwarped_Images_Brain.nii.gz
	 │   ├── Mean_Unwarped_Images_Brain_mask.nii.gz
	 │   ├── Topup_Output_fieldcoef.nii.gz
	 │   ├── Topup_Output_movpar.txt
	 │   ├── Unwarped_Images.nii.gz	      
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo-BiasField.nii.gz
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo-unbiased.nii.gz
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.bval
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.bvec	      
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_cnr_maps.nii.gz
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_command_txt
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_movement_rms
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_outlier_map
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_outlier_n_sqr_stdev_map
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_outlier_n_stdev_map
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_outlier_report
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_parameters
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_post_eddy_shell_PE_translation_parameters
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_post_eddy_shell_alignment_parameters
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_restricted_movement_rms
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.eddy_values_of_all_input_parameters
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.nii.gz
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo-EddyCo.qc
	 │   │   ├── avg_b0.png
	 │   │   ├── avg_b1000.png
	 │   │   ├── avg_b3000.png
	 │   │   ├── qc.json
	 │   │   ├── qc.pdf
	 │   │   ├── ref.txt
	 │   │   └── ref_list.png
	 │   ├── dwi_APPA-denoise-deGibbs-DriftCo.nii.gz
	 │   ├── first_B0.nii.gz
	 │   └── second_B0.nii.gz

Usage

bash 3_eddyCo.sh [ options ]

Options

-p OutputDir The OutputDir has to include the 1_DWIprep and 2_BiasCo folder (includes the converted files). [default = pwd directory]
-c Boolean Usng CUDA to accelerate the correction process. Both CUDA v8.0, v9.1 and v10.2 are available. [default = 0]
-m Boolean with -c, -m is applicable for slice-to-volume motion correction. [default = 0]
-r size(mm) Resize dwi image to isotropic voxel with input value size [default =0 (do not resize)].
-t B0thr Bzero threshold; [default = 10];

4_T1preproc.sh

Synopsis T1 preprocessing: Creating brain mask, registration of T1w and Diff images. Negative values on preprocessed image wil be reported （ Negative values in preprocessed T1 image, which could be generated during the Gibbs ring removal step, will be replaced with zeros to prevent errors in other T1 processing. ）

└── OutputDir     
    ├── 4_T1preproc
    │   ├── 5tt.nii.gz
    │   ├── 5tt2dwispace.nii.gz
    │   ├── Average_b0-brain.nii.gz
    │   ├── Reg_matrix
    │   │   ├── epi2str.mat
    │   │   ├── epi2str_init.mat
    │   │   ├── str2epi.mat
    │   │   └── str2epi.txt
    │   ├── T1maskindwispace.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Brain.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Brain_pve_0.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Brain_pve_1.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Brain_pve_2.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Brain_pveseg.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Mask.nii.gz
    │   ├── T1w-deGibbs-BiasCo-Prior0GenericAffine.mat
    │   ├── T1w-deGibbs-BiasCo.nii.gz
    │   ├── T1w-deGibbs.nii.gz
    │   ├── T1w.nii.gz
    │   ├── T1w_BiasField.nii.gz
    │   ├── T1w_preprocessed.nii.gz
    │   └── WMseg.nii.gz

Usage

bash 4_T1preproc.sh [ options ]

Options

-p OutputDir The ProcPath has to include the 2_BiasCo and 3_EddyCo folder (includes the converted files). [default = pwd directory]
-a AtlasDir The Atlas directory with MNI normalized images [default = ${iDIO_HOME}/share/]

5_DTIFIT.sh

Synopsis Diffusion tensor estimation. Only low-b (b<1500 s/mm^2) images were used for further fitting.

└── OutputDir     
         ├── 5_DTIFIT
         │   ├── Average_b0.nii.gz
         │   ├── Process-preproc-lowb-data.bval
         │   ├── Process-preproc-lowb-data.bvec
         │   ├── Process-preproc-lowb-data.nii.gz
         │   ├── Process-preproc.bval
         │   ├── Process-preproc.bvec
         │   ├── Process-preproc.nii.gz      
	 │   ├── POST_OPT_DEC.nii.gz
         │   ├── Process_FA.nii.gz
         │   ├── Process_L1.nii.gz
         │   ├── Process_L2.nii.gz
         │   ├── Process_L3.nii.gz
         │   ├── Process_MD.nii.gz
         │   ├── Process_MO.nii.gz
         │   ├── Process_RD.nii.gz
         │   ├── Process_S0.nii.gz
         │   ├── Process_V1.nii.gz
         │   ├── Process_V2.nii.gz
         │   ├── Process_V3.nii.gz      
	 │   ├── POST_OPT_sse.nii.gz	
         │   └── T1w_mask_inDWIspace.nii.gz

Usage

bash 5_DTIFIT.sh [ options ]

Options

-p OutputDir The ProcPath has to include the 2_BiasCo and 3_EddyCo folder (includes the converted files). [default = pwd directory]
-t B0thr Bzero threshold; [default = 10];

6_CSDpreproc.sh

Synopsis DWI preprocessing of constrained spherical deconvolution with Dhollanders algorithms

└── OutputDir      
    ├── 6_CSDpreproc
    │   ├── S1_Response
    │   │   ├── odf_csf.mif
    │   │   ├── odf_csf_norm.mif
    │   │   ├── odf_gm.mif
    │   │   ├── odf_gm_norm.mif
    │   │   ├── odf_wm.mif
    │   │   ├── odf_wm_norm.mif
    │   │   ├── response_csf.txt
    │   │   ├── response_gm.txt
    │   │   └── response_wm.txt
    │   ├── T1w_mask_inDWIspace.nii.gz
    │   ├── dwi_preprocessed.bval
    │   ├── dwi_preprocessed.bvec
    │   ├── dwi_preprocessed.mif
    │   └── dwi_preprocessed.nii.gz

Usage

bash 6_CSDpreproc.sh [ options ]

Options

-p OutputDir The OutputDir has to include the 3_EddyCo and 4_DTIFIT folder (includes the converted files). [default = pwd directory]
-t B0thr Bzero threshold. [default = 10];

7_NetworkProc.sh

Synopsis Generate the tractogram based (anatomical constrained tractography with dynamic seeding and SIFT). Connectivity matrix with different scaled (SIFT2 weights, SIFT2 with mu and length) will be generated with four atlases (AAL3, HCPMMP w/o Subcortical regions(HCPex), and Yeo400) and save in Connectivity_Matrix folder. A

, cropping the streamline endpoints at GM-WM interface and enabling the ‘backtracking’ mechanism. Minimal and maximal streamline length was set as 5 and 250, respectively, and other options remain default (see tckgen command for the details).

└── OutputDir  
    ├── 7_NetworkProc
    │   ├── Reg_matrix
    │   │   ├── T12MNI_0GenericAffine.mat
    │   │   ├── T12MNI_1InverseWarp.nii.gz
    │   │   ├── T12MNI_1Warp.nii.gz
    │   │   ├── T12MNI_InverseWarped.nii.gz
    │   │   └── T12MNI_Warped.nii.gz
    │   ├── SIFT2_weights.txt
    │   ├── SIFT_mu.txt
    │   └── Track_DynamicSeed_10M.tck
    ├── Connectivity_Matrix
    │   ├── Assignment
    │   │   ├── AAL3_Assignments.csv
    │   │   ├── HCPMMP_Assignments.csv
    │   │   ├── HCPex_Assignments.csv
    │   │   └── Yeo400_Assignments.csv
    │   ├── Atlas
    │   │   ├── AAL3_inDWI.nii.gz
    │   │   ├── AAL3_inT1.nii.gz
    │   │   ├── HCPMMP_inDWI.nii.gz
    │   │   ├── HCPMMP_inT1.nii.gz
    │   │   ├── HCPex_inDWI.nii.gz
    │   │   ├── HCPex_inT1.nii.gz
    │   │   ├── Yeo400_inDWI.nii.gz
    │   │   └── Yeo400_inT1.nii.gz
    │   ├── Mat_Length
    │   │   ├── AAL3_Length.csv
    │   │   ├── HCPMMP_Length.csv
    │   │   ├── HCPex_Length.csv
    │   │   └── Yeo400_Length.csv
    │   ├── Mat_SIFT2Wei
    │   │   ├── AAL3_SIFT2.csv
    │   │   ├── HCPMMP_SIFT2.csv
    │   │   ├── HCPex_SIFT2.csv
    │   │   └── Yeo400_SIFT2.csv
    │   └── Mat_ScaleMu
    │       ├── AAL3_ScaleMu.csv
    │       ├── HCPMMP_ScaleMu.csv
    │       ├── HCPex_ScaleMu.csv
    │       └── Yeo400_ScaleMu.csv

Usage

bash 7_NetworkProc.sh [ options ]

Options

-p OutputDir The OutputDir has to include the 5_CSDpreproc folder (includes the converted files). [default = pwd directory]
-a AtlasDir The Atlas directory [default = ${iDIO_HOME}/share/]
-n TrackNum Select track number; [default = 10M] (Please be aware of storage apace)

run_IDIOQC.py

synopsis Implement the quality control process and generate a report for iDIO diffusion preprocessing pipeline with pre-/post- processing comparison and related statistic values in a csv file.

└── OutputDir       
	├── 8_QC
	│   ├── N0001_POST_OPT_QC.pdf
	│   └── stats.csv

Usage

python run_IDIOQC.py -p OutputDIr -a AtlasDir -t B0thr

Options

-p OutputDIr Path of the iDIO PreprocDir (at least with directories from step 1 to 4)
-a AtlasDir Path of the Template directory (include /MNI/QC/JHU-ICBM-FA-1mm.nii.gz and /MNI/QC/JHU-ICBM-labels-1mm.nii.gz)
-t B0thr Bzero threshold. [default = 10]

Preprocessed_data and mainlog.txt

For other purpose that may need preprocessed dwi and T1 image data, we save the preporcessed data in the Preprocessed_data folder. a log file with all options and information with processing time were save in the mainlog.txt in the main output dir.

└── OutputDir         
    ├── Preprocessed_data
    │   ├── DWI.json
    │   ├── T1w_mask.nii.gz
    │   ├── T1w_mask_inDWIspace.nii.gz
    │   ├── T1w_preprocessed.nii.gz
    │   ├── dwi_preprocessed-Average_b0-brain.nii.gz
    │   ├── dwi_preprocessed-Average_b0.nii.gz
    │   ├── dwi_preprocessed.bval
    │   ├── dwi_preprocessed.bvec
    │   └── dwi_preprocessed.nii.gz
    └── mainlog.txt

References

Please cite the following articles if iDIO is utilized in your research publications:

iDIO4dMRI/iDIO

iDIO

Installation Guide

Setting

Tutorial

Data preparing

One-click solution: run Main.sh with argument file (SetUpOGIOArg.sh)

Recommended imaging acquisition

Details of each step

Step 0: CheckData.sh

Step 1: 1_DWIprep.sh

2_BiasCo.sh

3_EddyCo.sh

4_T1preproc.sh

5_DTIFIT.sh

6_CSDpreproc.sh

7_NetworkProc.sh

run_IDIOQC.py

Preprocessed_data and mainlog.txt

References

FSL

MRtrix3

ANTs

Others