Difference between revisions of "Cross-sectional TBSS"
From CMIC
(Created page with "The nipype script to perform cross-sectional TBSS is called <code>perform_dti_tbss_cross_sectional.py</code> This pipeline is to replicate the work presented in the following...") |
|||
| (8 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
| − | |||
| − | |||
This pipeline is to replicate the work presented in the following paper: | This pipeline is to replicate the work presented in the following paper: | ||
[http://doi.org/10.1371/journal.pone.0045996 Keihaninejad, S., Ryan, N. S., Malone, I. B., Modat, M., Cash, D., Ridgway, G. R., Zhang, H., et al. (2012). The importance of group-wise registration in tract based spatial statistics study of neurodegeneration: a simulation study in Alzheimer's disease. PloS one, 7(11), e45996. doi:10.1371/journal.pone.0045996] | [http://doi.org/10.1371/journal.pone.0045996 Keihaninejad, S., Ryan, N. S., Malone, I. B., Modat, M., Cash, D., Ridgway, G. R., Zhang, H., et al. (2012). The importance of group-wise registration in tract based spatial statistics study of neurodegeneration: a simulation study in Alzheimer's disease. PloS one, 7(11), e45996. doi:10.1371/journal.pone.0045996] | ||
| + | |||
| + | __FORCETOC__ | ||
| + | |||
| + | <h1>How to run the cross-sectional TBSS pipeline</h1> | ||
| + | The nipype script to perform cross-sectional TBSS is called <code>perform_dti_tbss_cross_sectional.py</code>. | ||
| + | To use this script [[Prerequisite DTI-TK | DTI-TK has to be installed]] | ||
The script help returns: | The script help returns: | ||
<pre> | <pre> | ||
usage: perform_dti_tbss_cross_sectional.py [-h] --input_img input_img | usage: perform_dti_tbss_cross_sectional.py [-h] --input_img input_img | ||
| − | [input_img ...] --mat design_mat | + | [input_img ...] [--mat design_mat] |
| − | --con design_con -o output_dir | + | [--con design_con] |
| − | [--output_pre prefix] [-g] | + | [--skeleton_thr thr] |
| + | [-o output_dir] | ||
| + | [--output_pre prefix] | ||
| + | [--no_randomise] [-g] | ||
| − | Cross-section TBSS pipeline. The required input are the tensor images and the | + | Cross-section TBSS pipeline (as described in 10.1371/journal.pone.0045996). |
| − | design matrix and contrast. The input images can be specified using the | + | The required input are the tensor images and the design matrix and contrast. |
| − | --input_img argument. The design matrix (--mat) and contrast (--con) can be | + | The input images can be specified using the --input_img argument. The design |
| − | generated as described on this page: http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM | + | matrix (--mat) and contrast (--con) can be generated as described on this |
| − | with the Glm_gui executable. Note that the file order has to match the design | + | page: http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM with the Glm_gui executable. |
| − | matrix. The user also need to specify an output directory (--output_dir) where | + | Note that the file order has to match the design matrix. The user also need to |
| − | all the result files will be saved. Using the --g argument you can generate | + | specify an output directory (--output_dir) where all the result files will be |
| − | the pipeline graph without running the actual pipeline. | + | saved. Using the --g argument you can generate the pipeline graph without |
| + | running the actual pipeline. | ||
optional arguments: | optional arguments: | ||
| Line 24: | Line 32: | ||
--input_img input_img [input_img ...] | --input_img input_img [input_img ...] | ||
List of Nifti file(s) to include in the analysis | List of Nifti file(s) to include in the analysis | ||
| − | + | --mat design_mat Design matrix file to be used by randomised on the | |
| − | --mat design_mat Design matrix file to be used by randomised | + | skeletonised FA maps. Required to run the statistical |
| − | --con design_con Design contrast file to be used by randomised | + | analysis |
| + | --con design_con Design contrast file to be used by randomised on the | ||
| + | skeletonised FA maps. Required to run the statistical | ||
| + | analysis | ||
| + | --skeleton_thr thr Threshold value to use to binarise the TBSS skeleton | ||
| + | (default is 0.2) | ||
-o output_dir, --output_dir output_dir | -o output_dir, --output_dir output_dir | ||
Output directory where to save the results | Output directory where to save the results | ||
--output_pre prefix Output result prefix (default='tbss_') | --output_pre prefix Output result prefix (default='tbss_') | ||
| + | --no_randomise Do not perform the randomise test on the skeletonised | ||
| + | FA maps (permutation test) | ||
-g, --graph Print a graph describing the node connections and exit | -g, --graph Print a graph describing the node connections and exit | ||
</pre> | </pre> | ||
As an input, the script expects several DTI images, e.g. /folder/DTI_img0.nii.gz, /folder/DTI_img1.nii.gz, ..., /folder/DTI_imgN.nii.gz. The script also expect the design matrix and design contrast file generated as described in [http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM] with the <code>Glm_gui</code> executable. | As an input, the script expects several DTI images, e.g. /folder/DTI_img0.nii.gz, /folder/DTI_img1.nii.gz, ..., /folder/DTI_imgN.nii.gz. The script also expect the design matrix and design contrast file generated as described in [http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM] with the <code>Glm_gui</code> executable. | ||
| + | Note that the order of the input diffusion tensor images has to be identical to the order specified in the design matrix and contrast. | ||
| − | The generated files will be store in the folder specified by the <code>--output_dir</code> option. | + | The generated files will be store in the folder specified by the <code>--output_dir</code> option. By default the output will be written in the current working directory. |
| + | |||
| + | By default, a value of 0.2 is used to binarise the mean FA skeleton and create the skeleton mask required for the statistical analysis. This value can be altered by using the <code>--skeleton_thr</code> argument. | ||
By default, all generated files will have the <code>tbss_</code> prefix. This prefix can be altered using the <code>--output_pre</code> option. | By default, all generated files will have the <code>tbss_</code> prefix. This prefix can be altered using the <code>--output_pre</code> option. | ||
| Line 59: | Line 77: | ||
The output, if the design contrast and matrix are specified, encompass: | The output, if the design contrast and matrix are specified, encompass: | ||
| − | * | + | * <prefix>mean_fa.nii.gz -- Mean FA map generated from the input DTI using a groupwise approach with DTI-TK |
| − | * | + | * <prefix>mean_fa_skeleton.nii.gz -- Skeleton of the mean FA map |
| + | * <prefix>mean_fa_skeleton_mask.nii.gz -- Binary skeleton of the mean FA map | ||
| + | * <prefix>all_fa_skeletonised.nii.gz -- 4D image containing all FA maps masked using the FA skeleton | ||
| + | * <prefix>all_md_skeletonised.nii.gz -- 4D image containing all MD maps masked using the FA skeleton | ||
| + | * <prefix>all_rd_skeletonised.nii.gz -- 4D image containing all RD maps masked using the FA skeleton | ||
| + | * <prefix>all_ad_skeletonised.nii.gz -- 4D image containing all AD maps masked using the FA skeleton | ||
| + | * randomise outputs | ||
| + | |||
If the <code>--no_randomise</code> option is used, the outputs are: | If the <code>--no_randomise</code> option is used, the outputs are: | ||
| − | * | + | * <prefix>mean_fa.nii.gz -- Mean FA map generated from the input DTI using a groupwise approach with DTI-TK |
| − | * here | + | * <prefix>mean_fa_skeleton.nii.gz -- Skeleton of the mean FA map |
| + | * <prefix>mean_fa_skeleton_mask.nii.gz -- Binary skeleton of the mean FA map | ||
| + | * <prefix>all_fa_skeletonised.nii.gz -- 4D image containing all FA maps masked using the FA skeleton | ||
| + | * <prefix>all_md_skeletonised.nii.gz -- 4D image containing all MD maps masked using the FA skeleton | ||
| + | * <prefix>all_rd_skeletonised.nii.gz -- 4D image containing all RD maps masked using the FA skeleton | ||
| + | * <prefix>all_ad_skeletonised.nii.gz -- 4D image containing all AD maps masked using the FA skeleton | ||
| + | |||
| + | Note that for all 4D images, the order of the images is identical to the order specified with the <code>--input_img</code> argument. | ||
| + | |||
| + | In order to run the statistical analysis independently, see [http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Randomise/UserGuide the FSL randomise user guide page]. | ||
| + | |||
| + | |||
| + | <h1>Various advices</h1> | ||
| + | Martina and Kirsi to have a go here. | ||
Latest revision as of 16:35, 25 August 2015
This pipeline is to replicate the work presented in the following paper: Keihaninejad, S., Ryan, N. S., Malone, I. B., Modat, M., Cash, D., Ridgway, G. R., Zhang, H., et al. (2012). The importance of group-wise registration in tract based spatial statistics study of neurodegeneration: a simulation study in Alzheimer's disease. PloS one, 7(11), e45996. doi:10.1371/journal.pone.0045996
How to run the cross-sectional TBSS pipeline
The nipype script to perform cross-sectional TBSS is called perform_dti_tbss_cross_sectional.py.
To use this script DTI-TK has to be installed
The script help returns:
usage: perform_dti_tbss_cross_sectional.py [-h] --input_img input_img
[input_img ...] [--mat design_mat]
[--con design_con]
[--skeleton_thr thr]
[-o output_dir]
[--output_pre prefix]
[--no_randomise] [-g]
Cross-section TBSS pipeline (as described in 10.1371/journal.pone.0045996).
The required input are the tensor images and the design matrix and contrast.
The input images can be specified using the --input_img argument. The design
matrix (--mat) and contrast (--con) can be generated as described on this
page: http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM with the Glm_gui executable.
Note that the file order has to match the design matrix. The user also need to
specify an output directory (--output_dir) where all the result files will be
saved. Using the --g argument you can generate the pipeline graph without
running the actual pipeline.
optional arguments:
-h, --help show this help message and exit
--input_img input_img [input_img ...]
List of Nifti file(s) to include in the analysis
--mat design_mat Design matrix file to be used by randomised on the
skeletonised FA maps. Required to run the statistical
analysis
--con design_con Design contrast file to be used by randomised on the
skeletonised FA maps. Required to run the statistical
analysis
--skeleton_thr thr Threshold value to use to binarise the TBSS skeleton
(default is 0.2)
-o output_dir, --output_dir output_dir
Output directory where to save the results
--output_pre prefix Output result prefix (default='tbss_')
--no_randomise Do not perform the randomise test on the skeletonised
FA maps (permutation test)
-g, --graph Print a graph describing the node connections and exit
As an input, the script expects several DTI images, e.g. /folder/DTI_img0.nii.gz, /folder/DTI_img1.nii.gz, ..., /folder/DTI_imgN.nii.gz. The script also expect the design matrix and design contrast file generated as described in [1] with the Glm_gui executable.
Note that the order of the input diffusion tensor images has to be identical to the order specified in the design matrix and contrast.
The generated files will be store in the folder specified by the --output_dir option. By default the output will be written in the current working directory.
By default, a value of 0.2 is used to binarise the mean FA skeleton and create the skeleton mask required for the statistical analysis. This value can be altered by using the --skeleton_thr argument.
By default, all generated files will have the tbss_ prefix. This prefix can be altered using the --output_pre option.
A typical example application can be:
python perform_dti_tbss_cross_sectional.py \ --input_img /folder/DTI_img0.nii.gz /folder/DTI_img1.nii.gz [...] /folder/DTI_imgN.nii.gz \ --output_dir /folder/path/output_folder \ --output_pre new_prefix_ \ --mat /folder/path/design_matrix.mat \ --con /folder/path/design_contrast.con
Note that if the --no_randomise option is specified the --mat and --con options do not required to be specified. In this case, a typical command can be:
python perform_dti_tbss_cross_sectional.py \ --input_img /folder/DTI_img0.nii.gz /folder/DTI_img1.nii.gz [...] /folder/DTI_imgN.nii.gz \ --output_dir /folder/path/output_folder \ --output_pre new_prefix_ \ --no_randomise
The output, if the design contrast and matrix are specified, encompass:
- <prefix>mean_fa.nii.gz -- Mean FA map generated from the input DTI using a groupwise approach with DTI-TK
- <prefix>mean_fa_skeleton.nii.gz -- Skeleton of the mean FA map
- <prefix>mean_fa_skeleton_mask.nii.gz -- Binary skeleton of the mean FA map
- <prefix>all_fa_skeletonised.nii.gz -- 4D image containing all FA maps masked using the FA skeleton
- <prefix>all_md_skeletonised.nii.gz -- 4D image containing all MD maps masked using the FA skeleton
- <prefix>all_rd_skeletonised.nii.gz -- 4D image containing all RD maps masked using the FA skeleton
- <prefix>all_ad_skeletonised.nii.gz -- 4D image containing all AD maps masked using the FA skeleton
- randomise outputs
If the --no_randomise option is used, the outputs are:
- <prefix>mean_fa.nii.gz -- Mean FA map generated from the input DTI using a groupwise approach with DTI-TK
- <prefix>mean_fa_skeleton.nii.gz -- Skeleton of the mean FA map
- <prefix>mean_fa_skeleton_mask.nii.gz -- Binary skeleton of the mean FA map
- <prefix>all_fa_skeletonised.nii.gz -- 4D image containing all FA maps masked using the FA skeleton
- <prefix>all_md_skeletonised.nii.gz -- 4D image containing all MD maps masked using the FA skeleton
- <prefix>all_rd_skeletonised.nii.gz -- 4D image containing all RD maps masked using the FA skeleton
- <prefix>all_ad_skeletonised.nii.gz -- 4D image containing all AD maps masked using the FA skeleton
Note that for all 4D images, the order of the images is identical to the order specified with the --input_img argument.
In order to run the statistical analysis independently, see the FSL randomise user guide page.
Various advices
Martina and Kirsi to have a go here.
