Difference between revisions of "Cross-sectional TBSS"

From CMIC
Jump to: navigation, search
 
(One intermediate revision by one other user not shown)
Line 5: Line 5:
  
 
<h1>How to run the cross-sectional TBSS pipeline</h1>
 
<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>
+
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:
Line 83: Line 84:
 
* <prefix>all_rd_skeletonised.nii.gz -- 4D image containing all RD 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
 
* <prefix>all_ad_skeletonised.nii.gz -- 4D image containing all AD maps masked using the FA skeleton
* TBSS outputs
+
* randomise outputs
  
  

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.