README.md 12.8 KB
Newer Older
Saad Jbabdi's avatar
Saad Jbabdi committed
1
## XTRACT - a command-line tool for automated tractography
Saad Jbabdi's avatar
Saad Jbabdi committed
2

3
4
XTRACT can be used to automatically extract a set of carefully dissected tracts in humans and macaques (other
species to come). It can also be used to define one's own tractography protocols where all the user needs to do is to
Saad Jbabdi's avatar
Saad Jbabdi committed
5
define a set of masks in standard space (e.g. MNI152)
Saad Jbabdi's avatar
Saad Jbabdi committed
6

7
The script was written by Saad Jbabdi, Stamatios Sotiropoulos & Shaun Warrington
Saad Jbabdi's avatar
Saad Jbabdi committed
8
(based on the autoPtx tool by Marius de Groot - see https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/AutoPtx)
Saad Jbabdi's avatar
Saad Jbabdi committed
9

Saad Jbabdi's avatar
Saad Jbabdi committed
10
11
12
13
14
15
16
The tractography protocols were created by:

Rogier Mars & Stamatios Sotiropoulos

with help from:
Saad Jbabdi, Kathryn Bryant, Shaun Warrington, Marina Charquero-Ballester, Gwenaelle Douaud

Saad Jbabdi's avatar
Saad Jbabdi committed
17
The XTRACT viewer helper script was written by Shaun Warrington
Shaun Warrington's avatar
Shaun Warrington committed
18

Shaun Warrington's avatar
Shaun Warrington committed
19
The XTRACT stats helper script was written by Shaun Warrington
Saad Jbabdi's avatar
Saad Jbabdi committed
20

Saad Jbabdi's avatar
Saad Jbabdi committed
21
---------------------------------------------------------------------
Saad Jbabdi's avatar
Saad Jbabdi committed
22
23

## Citations:
Saad Jbabdi's avatar
Saad Jbabdi committed
24

Saad Jbabdi's avatar
Saad Jbabdi committed
25

Shaun Warrington's avatar
Shaun Warrington committed
26
27
28
Warrington S, Bryant K, Khrapitchev A, Sallet J, Charquero-Ballester M, Douaud G, Jbabdi S*, Mars R*,
Sotiropoulos SN* (2020) XTRACT - Standardised protocols for automated tractography in the human and
macaque brain. NeuroImage. DOI: 10.1016/j.neuroimage.2020.116923
Saad Jbabdi's avatar
Saad Jbabdi committed
29
30
31
32
33

de Groot M; Vernooij MW. Klein S, Ikram MA, Vos FM, Smith SM, Niessen WJ, Andersson JLR (2013)
Improving alignment in Tract-based spatial statistics: Evaluation and optimization of image registration.
NeuroImage, 76(1), 400-411. DOI: 10.1016/j.neuroimage.2013.03.015

Saad Jbabdi's avatar
Saad Jbabdi committed
34
35
36

---------------------------------------------------------------------

37
## Usage:
Saad Jbabdi's avatar
Saad Jbabdi committed
38
```
39
 __  _______ ____      _    ____ _____
Saad Jbabdi's avatar
Saad Jbabdi committed
40
41
42
43
44
 \ \/ /_   _|  _ \    / \  / ___|_   _|
  \  /  | | | |_) |  / _ \| |     | |  
  /  \  | | |  _ <  / ___ \ |___  | |  
 /_/\_\ |_| |_| \_\/_/   \_\____| |_|  

45

46
47
48
 Usage:
     xtract -bpx <bedpostX_dir> -out <outputDir> -species <SPECIES> [options]
     xtract -list
Saad Jbabdi's avatar
Saad Jbabdi committed
49

50
     Compulsory arguments:
Saad Jbabdi's avatar
Saad Jbabdi committed
51

52
53
54
        -bpx <folder>                          Path to bedpostx folder
        -out <folder>                          Path to output folder
        -species <SPECIES>                     One of HUMAN or MACAQUE
Stamatios Sotiropoulos's avatar
Stamatios Sotiropoulos committed
55

56
     Optional arguments:
57
58
59
60
61
62
63
64
65
66
67
68
69
        -list                                  List the tract names used in XTRACT
        -str <file>                            Structures file (format: <tractName> per line OR format: <tractName> [samples=1], 1 means 1000, '#' to skip lines)
        -p <folder>                            Protocols folder (all masks in same standard space) (Default=$FSLDIR/etc/xtract_data/<SPECIES>)
        -stdwarp <std2diff> <diff2std>         Standard2diff and Diff2standard transforms (Default=bedpostx_dir/xfms/{standard2diff,diff2standard})
        -gpu                                   Use GPU version
        -res <mm>                              Output resolution (Default=same as in protocol folders unless '-native' used)
        -ptx_options <options.txt>	           Pass extra probtrackx2 options as a text file to override defaults, e.g. --steplength=0.2 --distthresh=10)

        And EITHER:
        -native                                Run tractography in native (diffusion) space

        OR:
        -ref <refimage> <diff2ref> <ref2diff>  Reference image for running tractography in reference space, Diff2Reference and Reference2Diff transforms
Saad Jbabdi's avatar
Saad Jbabdi committed
70

Saad Jbabdi's avatar
Saad Jbabdi committed
71
```
Saad Jbabdi's avatar
Saad Jbabdi committed
72
73
---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
74
## Running XTRACT:
Shaun Warrington's avatar
Shaun Warrington committed
75
76
77

XTRACT automatically detects if $SGE_ROOT is set and if so uses FSL_SUB. For optimal performance, use the GPU version!!!!

Shaun Warrington's avatar
Shaun Warrington committed
78
**Outputs of XTRACT**
Shaun Warrington's avatar
Shaun Warrington committed
79
80
81
82
83
84

Under <outputDir>:

- "commands.txt" - XTRACT processing commands
- "logs" - directory containing the probtrackx log files
- "tracts" - directory continaing tractography results
Shaun Warrington's avatar
Shaun Warrington committed
85
86
87
  - "<tractName>" - directory per tract, each continaing:
  - "waytotal" - txt file continaing the number of valid streamlines
  - "density.nii.gz" - nifti file containing the fibre probability distribution
Shaun Warrington's avatar
Shaun Warrington committed
88
89
90
91
  - "density_lenths.nii.gz" - nifti file containing the fibre lengths, i.e. each voxel is the
  average streamline length - this is the "-ompl" probtrackx option
  - "densityNorm.nii.gz" - nifti file continaing the waytotal normalised fibre probability distribution
  (the "density.nii.gz" divided by the total number of valid streamlines)
Shaun Warrington's avatar
Shaun Warrington committed
92
93
94
95
96
97
  - If the protocol calls for reverse-seeding:
    - "tractsInv" - directory continaing the above for the seed-target reversed run
    - "sum_waytotal" and "sum_density.nii.gz" - the summed waytotal and fibre probability distribution
  - If the "-native" option is being used:
    - "masks" - directory
    - "<tractName>" - directory per tract continaing the native space protocol masks
Shaun Warrington's avatar
Shaun Warrington committed
98
99
100

The primary output is the "densityNorm.nii.gz" file.

Shaun Warrington's avatar
Shaun Warrington committed
101
**Pre-processing**
Shaun Warrington's avatar
Shaun Warrington committed
102
103
104

Prior to running XTRACT, you must complete the FDT processing pipeline:

Shaun Warrington's avatar
Shaun Warrington committed
105
1. Brain extraction using BET
Shaun Warrington's avatar
Shaun Warrington committed
106
107
2. Susceptibility distortion correction using topup (only if spin-echo fieldmaps have been
  acquired - if you don't have these, skip to step 3)
Shaun Warrington's avatar
Shaun Warrington committed
108
109
110
111
3. Eddy current distortion and motion correction using eddy
4. Fit the crossing fibre model using bedpostx
5. Registration to standard space (MNI152), see the FDT pipeline
6. Your data should now be ready to run XTRACT!
Shaun Warrington's avatar
Shaun Warrington committed
112
113


Saad Jbabdi's avatar
Saad Jbabdi committed
114
115
116

---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
117
## Atlases:
Saad Jbabdi's avatar
Saad Jbabdi committed
118
119
120
121

- For HUMAN, XTRACT uses the MNI152 standard space in $FSLDIR/etc/standard

- For MACAQUE, XTRACT uses the F99 atlas in Caret - see http://brainvis.wustl.edu/wiki/index.php/Caret:Atlases
122

Shaun Warrington's avatar
Shaun Warrington committed
123
124
  We also provide a copy of the F99 atlas in $FSLDIR/etc/xtract_data/standard/F99. This
  includes a helper script for registering your own diffusion/structural data to the F99 altas
Saad Jbabdi's avatar
Saad Jbabdi committed
125

Saad Jbabdi's avatar
Saad Jbabdi committed
126
127
When running XTRACT with the '-species' option, a predefined list of tracts is automatically extracted. Currently the following tracts are available:

128
| **Tract**   | **Abbreviation** | **XTRACT tractName** |
129
| -------- | ------------ | ------------ |
130
131
132
133
134
135
136
137
| Arcuate Fasciculus | AF | af_l   af_r |
| Acoustic Radiation | AR | ar_l   ar_r |
| Anterior Thalamic Radiation | ATR | atr_l   atr_r |
| Cingulum subsection : Dorsal | CBD | cbd_l   cbd_r |
| Cingulum subsection : Peri-genual | CBP | cbp_l   cbp_r |
| Cingulum subsection : Temporal | CBT | cbt_l   cbt_r |
| Corticospinal Tract | CST | cst_l   cst_r |
| Frontal Aslant | FA | fa_l   fa_r |
138
139
| Forceps Major | FMA | fma |
| Forceps Minor | FMI | fmi |
140
141
142
| Fornix | FX | fx_l   fx_r |
| Inferior Longitudinal Fasciculus | ILF | ilf_l   ilf_r |
| Inferior Fronto-Occipital Fasciculus | IFO | ifo_l   ifo_r |
143
| Middle Cerebellar Peduncle | MCP | mcp |
144
| Middle Longitudinal Fasciculus | MdLF | mdlf_l   mdlf_r |
145
| Optic Radiation | OR | or_l or_r |
146
147
148
149
| Superior Thalamic Radiation | STR | str_l   str_r |
| Superior Longitudinal Fasciculus 1 | SLF1 | slf1_l   slf1_r |
| Superior Longitudinal Fasciculus 2 | SLF2 | slf2_l   slf2_r |
| Superior Longitudinal Fasciculus 3 | SLF3 | slf3_l   slf3_r |
150
| Anterior Commissure | AC | ac |
151
152
| Uncinate Fasciculus | UF | uf_l   uf_r |
| Vertical Occipital Fasciculus | VOF | vof_l   vof_r |
153
154
155

You can run a subset of these tracts by providing a structure text file using the format:

156
tractName, per line (default number of seeds taken from default structure file)
157
158
159

OR

160
tractName nsamples, per line
161
162

For an example, see $FSLDIR/etc/xtract_data/Human/structureList
Saad Jbabdi's avatar
Saad Jbabdi committed
163

Saad Jbabdi's avatar
Saad Jbabdi committed
164
165
---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
166
## Adding your own tracts:
Saad Jbabdi's avatar
Saad Jbabdi committed
167
168
169

Suppose you want to create an automated protocol for a tract called 'mytrack'.  

170
First you need to create a folder called 'mytrack' which you can add e.g. in the protocols folder.
Saad Jbabdi's avatar
Saad Jbabdi committed
171

172
Then create the following NIFTI files (with this exact naming) and copy them into 'mytrack':
Saad Jbabdi's avatar
Saad Jbabdi committed
173

Saad Jbabdi's avatar
Saad Jbabdi committed
174
**Compulsory**:
175
- seed.nii.gz : a seed mask
Saad Jbabdi's avatar
Saad Jbabdi committed
176

Saad Jbabdi's avatar
Saad Jbabdi committed
177
**Optional**:
Saad Jbabdi's avatar
Saad Jbabdi committed
178
179
180
181
182
183
- stop.nii.gz    : a stop mask if required
- exclude.nii.gz : an exclusion mask if required
- ONE of the following:
  - target.nii.gz  :  a single target mask  
  - target1.nii.gz, target2.nii.gz, etc. : a number of targets, in which case streamlines will be kept if they cross ALL of them
- invert (empty file to indicate that a seed->target and target->seed run will be added and combined)
184
  if such an option is required a single "target.nii.gz" file is also expected
Saad Jbabdi's avatar
Saad Jbabdi committed
185

Shaun Warrington's avatar
Shaun Warrington committed
186
187
All the masks above should be in standard space (e.g. MNI152 or F99) if you want to run
the same tracking for a collection of subjects.
Saad Jbabdi's avatar
Saad Jbabdi committed
188

Shaun Warrington's avatar
Shaun Warrington committed
189
190
Next, make a structure file using the format <tractName> <nsamples> per line and call XTRACT
using -species <SPECIES> -str <file> -p <folder>, pointing to your new protocols folder 'mytrack'.
Saad Jbabdi's avatar
Saad Jbabdi committed
191

Saad Jbabdi's avatar
Saad Jbabdi committed
192
193
194
195
---------------------------------------------------------------------

## Visualising results with FSLEYES

Shaun Warrington's avatar
Shaun Warrington committed
196
197
198
The output of XTRACT is a folder that contains tracts in separate folders. We provide a
convenient script that can load these tracts (or a subset of the tracts) into FSLEYES using
different colours for the different tracts but matching the left/right colours
Saad Jbabdi's avatar
Saad Jbabdi committed
199
200
201

```
 __  _______ ____      _    ____ _____         _                        
202
 \ \/ /_   _|  _ \    / \  / ___|_   _| __   _(_) _____      _____ _ __
Saad Jbabdi's avatar
Saad Jbabdi committed
203
204
205
206
207
  \  /  | | | |_) |  / _ \| |     | |   \ \ / / |/ _ \ \ /\ / / _ \ '__|
  /  \  | | |  _ <  / ___ \ |___  | |    \ V /| |  __/\ V  V /  __/ |   
 /_/\_\ |_| |_| \_\/_/   \_\____| |_|     \_/ |_|\___| \_/\_/ \___|_|                                                                           


208
209
210
211
 Usage:
     xtract_viewer -dir <xtractDir> -species HUMAN [options]
     xtract_viewer -dir <xtractDir> -species MACAQUE [options]
     xtract_viewer -dir <xtractDir> -brain <PATH> [options]
Saad Jbabdi's avatar
Saad Jbabdi committed
212

213
     Compulsory arguments:
Saad Jbabdi's avatar
Saad Jbabdi committed
214

215
216
217
218
219
220
221
222
        -dir <FOLDER>                     Path to XTRACT output folder

        And EITHER:
        -species <SPECIES>                One of HUMAN or MACAQUE

        OR:
        -brain <PATH>                     The brain image to use for the background overlay - must be in the same space as tracts.
                                          Default is the FSL_HCP065_FA map for HUMAN and F99 T1 brain for MACAQUE
Saad Jbabdi's avatar
Saad Jbabdi committed
223

224
     Optional arguments:
Saad Jbabdi's avatar
Saad Jbabdi committed
225

226
        -str STRUCTURE,STRUCTURE,...      Structures (comma separated (default = display all that is found in input folder)
Saad Jbabdi's avatar
Saad Jbabdi committed
227

228
229
        -thr NUMBER NUMBER                The lower and upper thresholds applied to the tracts for viewing
                                          Default = 0.001 0.1
Saad Jbabdi's avatar
Saad Jbabdi committed
230
231

```
Shaun Warrington's avatar
Shaun Warrington committed
232
233
234
235
236

---------------------------------------------------------------------

## Extracting tract-wise summary statistics

Shaun Warrington's avatar
Shaun Warrington committed
237
238
239
A common usage of the XTRACT output is to summarise tracts in terms of simple summary
statistics, such as their volume and microstructural properties (e.g. mean FA). We provide XTRACT
stats to get such summary statistics in a quick and simple way.
Shaun Warrington's avatar
Shaun Warrington committed
240
241
242

You can use XTRACT stats with any modelled diffusion data, e.g. DTI, bedpostx, DKI.

Shaun Warrington's avatar
Shaun Warrington committed
243
244
245
246
Simply provide; the directory (and basename of files, if any) leading to the diffusion d
ata of interest, the directory containing the XTRACT output, the warp field (or use 'native'
if tracts are already in diffusion space). If tracts are not in diffusion space, you must also
provide a reference image in diffusion space (e.g. FA map).
Shaun Warrington's avatar
Shaun Warrington committed
247
248
249

e.g. call: xtract_stats -d /home/DTI/dti_ -xtract /home/xtract -w /home/warp/standard2diff -r /home/DTI/dti_FA

Shaun Warrington's avatar
Shaun Warrington committed
250
251
The output (a .csv file) by default contains the tract volume (mm3) and the mean, median and
standard deviation of the probability, length, FA and MD for each tract.
Shaun Warrington's avatar
Shaun Warrington committed
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282

```
__  _______ ____      _    ____ _____    _        _
\ \/ /_   _|  _ \    / \  / ___|_   _|__| |_ __ _| |_ ___
 \  /  | | | |_) |  / _ \| |     | |/ __| __/ _  | __/ __|
 /  \  | | |  _ <  / ___ \ |___  | |\__ \ || (_| | |_\__ \\
/_/\_\ |_| |_| \_\/_/   \_\____| |_||___/\__\__ _|\__|___/


Usage:
    xtract_stats -d <dir_basename> -xtract <XTRACT_dir> -w <xtract2diff> [options]

    Compulsory arguments:

       -d <folder_basename>                   Path to microstructure folder and basename of data (e.g. /home/DTI/dti_)
       -xtract <folder>                       Path to XTRACT output folder
       -w <xtract2diff>                       EITHER XTRACT results to diffusion space transform OR 'native' if tracts are already in diffusion space

    Optional arguments:
       -r <reference>                         If not 'native', provide reference image in diffusion space (e.g. /home/DTI/dti_FA)
       -out <path>                            Output filepath (Default <XTRACT_dir>/stats.csv)
       -str <file>                            Structures file (as in XTRACT) (Default is all tracts under <XTRACT_dir>)
       -thr <float>                           Threshold applied to tract probability map (default = 0.001 = 0.1%)

       -meas <list>                           Comma separated list of features to extract (Default = vol,prob,length,FA,MD - assumes DTI folder has been provided)
                                              vol = tract volume, prob = tract probability, length = tract length
                                              Additional metrics must follow file naming conventions. e.g. for dti_L1 use 'L1'

       -keepfiles                             Keep temporary files

```