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.3 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. 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
: 4DNIfTI
file ofdwi
(the first volume should be a B0 image)-b
:bval
file-c
:bvec
file-m
: BIDS sidecarjson
file including the metadata of the inputdwi
(not required, but HIGHLY RECOMMENDED)
If you provide this file, then the script will try to perform eddy correction based on the acquisition parameters reported in thejson
file. 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, and the DTI fitting will be performed on the rawdwi
input or the preprocesseddwi
input (if preprocessing is enabled).
The script has been tested withjson
files generated fromdcm2niix
(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
: 4DNIfTI
file of the seconddwi
input (the first volume must be a B0 image and the PE direction must be opposite to the PE of the firstdwi
dataset in order to be used)-j
:bval
file of the seconddwi
input. If not provided together with the seconddwi
input, the first volume of the seconddwi
input will be assumed to have b-value equal to that of the firstdwi
input.-k
:bvec
file of the seconddwi
input. Not needed.-n
: BIDS sidecarjson
file of the seconddwi
input. If not provided together with the seconddwi
input, the PE direction of the seconddwi
input will be assumed to be opposite to the PE direction of the firstdwi
input.
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 thedwi
input(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.sh
without specifying thejson
file with the-m
option, but using only the inputs-a
,-b
, and-c
); - 1 [default] = use
${FSLDIR}/bin/eddy_openmp
(should take 1-to-2 hours to run, for most inputs); - 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
csv
file 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.gz
LEFT PROJECTION FIBERS (superior corona radiata)R_SCR.nii.gz
RIGHT PROJECTION FIBERS (superior corona radiata)L_SLF.nii.gz
LEFT ASSOCIATION FIBERS (superior longitudinal fasciculus)R_SLF.nii.gz
RIGHT ASSOCIATION FIBERS (superior longitudinal fasciculus)
- alternatively, the user can specify a COMMA-SEPARATED list of 4 custom ROIs (
NIfTI
binary masks), which MUST be in the following order:LEFT
PROJECTION FIBERS (superior corona radiata)RIGHT
PROJECTION FIBERS (superior corona radiata)LEFT
ASSOCIATION FIBERS (superior longitudinal fasciculus)RIGHT
ASSOCIATION FIBERS (superior longitudinal fasciculus)
- 0 = skip ROI analysis (the output
-t
: template to use for the ROI analysis [default = 1]. Only used if-r
is 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
-r
option. Alternatively, if-r
option 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
NIfTI
file 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.gz
file) 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
vecreg
to 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-o
MUST BE DEFINED and MUST CORRESPOND TO THE FOLDER WHEREdti_FA.nii.gz
ANDdti_tensor.nii.gz
ARE 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 thealps
script twice: the first time skipping the ROI analysis (-r 0
option), then draw the ROIs on the dti_FA.nii.gz output, and then re-run thealps
script with the options-s 1
,-r myroi1.nii.gz,myroi2.nii.gz,myroi3.nii.gz,myroi4.nii.gz
and-o outputdirectory
(where "outputdirectory" is the directory where dti_FA.nii.gz and the other tensor files are located).
If you want to include theid
name in the output csv file with the ALPS index, include the-a
option with the ID you want to use (e.g.,-a myID
; if-a
is a.nii
or.nii.gz
file, then the file extension will be excluded from the ID name:-a mynifti.nii.gz
will result in IDmynifti
).
- The main output is a
csv
file namedalps.csv
located inalps.stat
folder in the output directory. This file includes theid
(based on the-a
input), the scanner manufacturer (based on the-m
input), 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 namedalps
is the average of the ALPS index on the left and right side. - DTI FITTING outputs: these
.nii.gz
files are the outputs from the FSL commanddtifit
and their names start withdti_
- ALPS tensor files:
dxx.nii.gz
,dyy.nii.gz
, anddzz.nii.gz
are 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
-d
option):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.gz
This 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.gz
is 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.