This is a bash script that automatically computes the diffusion along perivascular spaces (ALPS) metric from diffusion-weighted images (dwi).
The ALPS index has been described by Taoka et al. (Japanese Journal of Radiology, 2017)
As of 2024-02-03, there is a new option (-f) to specify whether the transformation of the tensors to the template space should be performed with FSL flirt/applywarp (default option) or with the FSL function vecreg, as suggested in PMIDs 36472803 and 37162692.
The default option remains flirt/applywarp, because according to my data, the ALPS index seems to be more robust this way.
If you use this script, please cite our work AND report the link to this repository:
- Paper: Liu, X, Barisano, G, et al., Cross-Vendor Test-Retest Validation of Diffusion Tensor Image Analysis along the Perivascular Space (DTI-ALPS) for Evaluating Glymphatic System Function, Aging and Disease (2023). DOI: https://doi.org/10.14336/AD.2023.0321-2
- Link to this repository: https://github.com/gbarisano/alps/
If you have any question, please contact me: barisano [at] stanford [dot] edu.
- FSL v. 6.0.6 or newer (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation) (it should work with older versions of FSL, but you might need to get the b02b0_1.cnf configuration file from newer FSL versions and specify the
eddycommand to use via the option-e. This configuration file is needed in case your dwi input has odd number of slices. Older versions of FSL will also give you LESS consistent results, i.e., if you launch the script 100 times with the same inputs, you will have 100 slightly different ALPS results, with a variability in the order of about 0.001). - MRtrix3 (https://www.mrtrix.org/download) (only needed for preprocessing steps)
This script assumes that FSL and MRtrix3 are in your $PATH.
You must define these elements (except when -s 1, read Optional arguments):
-a: 4DNIfTIfile ofdwi(the first volume should be a B0 image)-b:bvalfile-c:bvecfile-m: BIDS sidecarjsonfile including the metadata of the inputdwi(not required, but HIGHLY RECOMMENDED)
If you provide this file, then the script wil B8E6 l try to perform eddy correction based on the acquisition parameters reported in thejsonfile. The DTI fitting will use the eddy corrected data as input. If you do not provide this file, then NO eddy correction will be performed (unless using the-e 3option, see below), and the DTI fitting will be performed on the rawdwiinput or the preprocesseddwiinput (if preprocessing is enabled). If you do not have a metadata file but you still want to try to perform eddy correction, please use option-e 3to runeddy_correctfunction.
The script has been tested with json files generated from dcm2niix (https://github.com/rordenlab/dcm2niix)
A second dwi dataset with opposite phase encoding (PE) direction to correct for susceptibility-induced distortions.
To correct for susceptibility-induced distortions, the user must define the following 4 additional inputs:
-i: 4DNIfTIfile of the seconddwiinput (the first volume must be a B0 image and the PE direction must be opposite to the PE of the firstdwidataset in order to be used)-j:bvalfile of the seconddwiinput. If not provided together with the seconddwiinput, the first volume of the seconddwiinput will be assumed to have b-value equal to that of the firstdwiinput.-k:bvecfile of the seconddwiinput. Not needed.-n: BIDS sidecarjsonfile of the seconddwiinput. If not provided together with the seconddwiinput, the PE direction of the seconddwiinput will be assumed to be opposite to the PE direction of the firstdwiinput.
If the user does not specify these options, the script will use the default argument for each of them (see below)
-d: determines which preprocessing steps need to be performed on thedwiinput(s) [default = 1]- 0 = skip
- 1 [default] = both denoising and unringing
- 2 = only denoising
- 3 = only unringing
-e: determines which EDDY program to use [default = 1]- 0 = skip eddy correction (not recommended) (this is the same as running
alps.shwithout specifying thejsonfile with the-moption, but using only the inputs-a,-b, and-c); - 1 [default] = use
${FSLDIR}/bin/eddy_cpu(should take 1-to-2 hours to run, for most inputs); (this was updated on 09.26.2024: previous versions usededdy_openmpas default, which has been deprecated in newer versions of FSL. - 2 = use
${FSLDIR}/bin/eddy(should take ~7 hours to run, for most inputs); - 3 = use
${FSLDIR}/bin/eddy_correct(does not require a metadata file) - alternatively, the user can specify which eddy program to use (e.g.,
eddy_cuda). The binary file specified by the user must be located in${FSLDIR}/bin/(do not include "${FSLDIR}/bin/" in the command, just the name of the binary file).
- 0 = skip eddy correction (not recommended) (this is the same as running
-r: Region of interest (ROI) analysis [default = 1]- 0 = skip ROI analysis (the output
csvfile with ALPS index will NOT be generated) - 1 [default] = ROI analysis done using the provided ROIs drawn on FSL's
JHU-ICBM-FA-1mm.nii.gz:L_SCR.nii.gzLEFT PROJECTION FIBERS (superior corona radiata)R_SCR.nii.gzRIGHT PROJECTION FIBERS (superior corona radiata)L_SLF.nii.gzLEFT ASSOCIATION FIBERS (superior longitudinal fasciculus)R_SLF.nii.gzRIGHT ASSOCIATION FIBERS (superior longitudinal fasciculus)
- alternatively, the user can specify a COMMA-SEPARATED list of 4 custom ROIs (
NIfTIbinary masks), which MUST be in the following order:LEFTPROJECTION FIBERS (superior corona radiata)RIGHTPROJECTION FIBERS (superior corona radiata)LEFTASSOCIATION FIBERS (superior longitudinal fasciculus)RIGHTASSOCIATION FIBERS (superior longitudinal fasciculus)
- 0 = skip ROI analysis (the output
-t: template to use for the ROI analysis [default = 1]. Only used if-ris not equal to 0. The DTI maps will be registered to the template specified by the user.- 0 = performs the analysis in NATIVE space. A list of 4 custom ROIs in NATIVE space can be specified with the
-roption. Alternatively, if-roption is 1 (default), then the default ROIs will be linearly registered from JHU-FA template space into native space. - 1 [default] =
JHU-ICBM-FA-1mm.nii.gz(if no structural MRI data input),MNI_T1_1mm_brain.nii.gz(if structural data input is a T1) orJHU-ICBM-T2-1mm.nii.gz(if structural data input is a T2) in FSLDIR will be used as template. - alternatively, the user can specify a
NIfTIfile to be used as a template. The ROIs must be in the same space of this template. The DTI maps will be registered to this template.
- 0 = performs the analysis in NATIVE space. A list of 4 custom ROIs in NATIVE space can be specified with the
-v: VOLUMETRIC structural MRI data (a T1w or T2w NIfTInii.gzfile) to be used for registration of the FA map to the template-h: weight of the structural MRI data (1=T1-weighted [default], 2=T2-weighted, no PD, no FLAIR)-w: WARP, type of registration (option needed only when the analysis is done in the template space AND a structural MRI data is NOT provided; option -w is ignored when a structural MRI is used (-v is not empty).- 0 [default] = perform linear registration of the reconstructed FA map to the template
- 1 = perform ONLY non-linear registration (warping) of the reconstructed FA map to the template using FSL's suggested default parameters (not recommended).
- 2 = perform linear (flirt) + non-linear registration (fnirt)
-f: Define FSL's function to transform the TENSOR to the template.- 1 [default] = Use
flirt(if -w = 0) orapplywarp(if -w = 1 or 2 or -v is not empty) to transform the TENSOR file to the template space. - 2 = use
vecregto transform the TENSOR file to the template space.
- 1 [default] = Use
-o: name of the output folder. If not specified, the default output folder will be called 'alps' and will be located in the same folder of the (first) input.-s: Option to skip preprocessing and DTI fitting, i.e. performs ONLY ROI analysis [default = 0];- 0 [default] = all the steps are performed;
- 1 = ONLY ROI analysis is performed;
If-s 1, then-oMUST BE DEFINED and MUST CORRESPOND TO THE FOLDER WHEREdti_FA.nii.gzANDdti_tensor.nii.gzARE LOCATED. This option is useful for example when the user wants to perform the ROI analysis in NATIVE space with custom ROIs drawn on the output of the DTI processing steps (dti_FA.nii.gz) (see Example 4). In this case, the user can run thealpsscript twice: the first time skipping the ROI analysis (-r 0option), then draw the ROIs on the dti_FA.nii.gz output, and then re-run thealpsscript with the options-s 1,-r myroi1.nii.gz,myroi2.nii.gz,myroi3.nii.gz,myroi4.nii.gzand-o outputdirectory(where "outputdirectory" is the directory where dti_FA.nii.gz and the other tensor files are located).
If you want to include theidname in the output csv file with the ALPS index, include the-aoption with the ID you want to use (e.g.,-a myID; if-ais a.niior.nii.gzfile, then the file extension will be excluded from the ID name:-a mynifti.nii.gzwill result in IDmynifti).
- The main output is a
csvfile namedalps.csvlocated inalps.statfolder in the output directory. This file includes theid(based on the-ainput), the scanner manufacturer (based on the-minput), and the metrics required to compute the ALPS index, separately for the left and right side:$$ALPS=mean(Dxproj,Dxassoc)/mean(Dyproj,Dzassoc)$$ The last column namedalpsis the average of the ALPS index on the left and right side. - UPDATE 09-11-2024: an additional
csvfile namedfa+md_alps.csvlocated inalps.statfolder in the output directory is generated. This file includes the sameidheader as the main outputalps.csvand the fractional anisotrophy (FA) and mean diffusivity (MD) measured in the same exact ROIs used for the ALPS index, on both sides. The last 2 columns are the average measures of the FA and MD on the left and right side of the projection fibers and the left and right side of the association fibers. - DTI FITTING outputs: these
.nii.gzfiles are the outputs from the FSL commanddtifitand their names start withdti_ - ALPS tensor files:
dxx.nii.gz,dyy.nii.gz, anddzz.nii.gzare the tensor files used for the calculation of the ALPS index. If the analysis is done on a template space, the corresponding files transformed to the template space will be also output. - Preprocessing outputs: for each input dwi, the following files will be possibly output (based on the user-defined
-doption):dwi1.denoised.nii.gz,dwi1.unring.nii.gz,dwi1.denoised.unring.nii.gz, which represents the denoised dwi image, the unringed dwi image, and the denoised+unringed dwi image, respectively. If 2 dwi inputs are provided, the output will be generated for each input. - Eddy current correction outputs: these files' name starts with
eddy_corrected_data. - TOPUP correction outputs:
my_hifi_b0.nii.gz(the new B0 image corrected for susceptibility-induced distortions) andmy_topup_results_fieldcoef.nii.gz(what topup thinks the off-resonance field looks like).
IMPORTANT: If Eddy current correction outputs are not present in the output folder, it means that the DTI fitting has been performed EITHER on preprocessed (denoised and/or unringed) input(s) OR on raw dwi input(s) if preprocessed data are not present in the output folder. If TOPUP correction outputs are not present in the output folder, it means that NO TOPUP correction has been applied (see the log for understanding the reason why).
alps.sh -a my_4D_dwi.nii.gz -b my_bval_file -c my_bvec_file -m my_bids_file.json
This command will preprocess my_4D_dwi.nii.gz (denoising and unringing, i.e. default option -d), perform eddy current correction on the preprocessed data, and compute the ALPS index using the provided default ROIs on FSL template JHU-ICBM-FA-1mm.nii.gz. The output folder will be called with the default name "alps" and will be located in the same folder as the input.
2. ALPS analysis with 2 dwi inputs with opposite PE direction and B0 image as first volume in both inputs.
alps.sh -a dwi_PA.nii.gz -b id_PA.bval -c id_PA.bvec -m id_PA.json -i dwi_AP.nii.gz -j id_AP.bval -k id_AP.bvec -n id_AP.json
This command will preprocess both dwi_PA.nii.gz and dwi_AP.nii.gz (denoising and unringing, i.e. default option -d), perform TOPUP and eddy current correction on the preprocessed data, and compute the ALPS index using the provided default ROIs on FSL template JHU-ICBM-FA-1mm.nii.gz. The output folder will be called with the default name "alps" and will be located in the same folder as the FIRST input.
3. ALPS analysis with 1 dwi input, in native space (-t 0), and customized output folder (-o my_output_folder).
alps.sh -a my_4D_dwi.nii.gz -b my_bval_file -c my_bvec_file -m my_bids_file.json -t 0 -r proj_L.nii.gz,proj_R.nii.gz,assoc_L.nii.gz,assoc_R.nii.gz -o my_output_folder
This command will preprocess my_4D_dwi.nii.gz (denoising and unringing, i.e. default option -d), perform eddy current correction on the preprocessed data, and compute the ALPS index in native space (-t 0) using the ROI files defined by the user, which MUST be in native space. The output folder will be "my_output_folder".
4. ALPS analysis with 1 dwi input in native space (-t 0) after drawing ROIs on the output dti_FA.nii.gz.
This is a 3-step process:
alps.sh -a my_4D_dwi.nii.gz -b my_bval_file -c my_bvec_file -m my_bids_file.json -r0 -o my_output_folder
This command will preprocessmy_4D_dwi.nii.gz(denoising and unringing, i.e. default option-d), perform eddy current correction on the preprocessed data, and output only the DTI fitting files in "my_output_folder".- Draw the ROIs in the generated FA map (native space): myroi1_native.nii.gz, myroi2_native.nii.gz, myroi3_native.nii.gz, myroi4_native.nii.gz
alps.sh -a my_4D_dwi.nii.gz -t 0 -s 1 -o my_output_folder -r myroi1_native.nii.gz,myroi2_native.nii.gz,myroi3_native.nii.gz,myroi4_native.nii.gzThis command will skip all preprocessing steps and the DTI fitting step (-s 1) and will use the DTI fitting output files previously generated in "my_output_folder" to compute the ALPS index in native space (-t 0) using the user-defined ROIs (-r myroi1_native.nii.gz,myroi2_native.nii.gz,myroi3_native.nii.gz,myroi4_native.nii.gz).
The option-a my_4D_dwi.nii.gzis not required in this latest command, but is only needed to add the ID in the final CSV output file with the ALPS index.
alps.sh -a my_4D_dwi.nii.gz -b my_bval_file -c my_bvec_file -m my_bids_file.json -d 0 -r 1 -t 1
This command will perform ONLY eddy current correction on the RAW dwi input data (not denoised nor unringed), and compute the ALPS index using the provided default ROIs on FSL template JHU-ICBM-FA-1mm.nii.gz. The output folder will be called with the default name "alps" and will be located in the same folder as the input.
6. Minimal number of inputs (not recommended if used without the eddy current correction -e 3 option).
alps.sh -a my_4D_dwi.nii.gz -b my_bval_file -c my_bvec_file
This command will preprocess my_4D_dwi.nii.gz (denoising and unringing, i.e. default option -d) and compute the ALPS index using the provided default ROIs on FSL template JHU-ICBM-FA-1mm.nii.gz. Eddy current correction will be applied only if the user specifies the option -e 3 (i.e., using ${FSLDIR}/bin/eddy_correct). If -e 3 is not specified, no eddy current correction will be performed, which is not recommended.