README.md 8.04 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
Saad Jbabdi's avatar
Saad Jbabdi committed
18

Saad Jbabdi's avatar
Saad Jbabdi committed
19
---------------------------------------------------------------------
Saad Jbabdi's avatar
Saad Jbabdi committed
20
21

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

Saad Jbabdi's avatar
Saad Jbabdi committed
23

Shaun Warrington's avatar
Shaun Warrington committed
24
Warrington S, Bryant K, Charquero-Ballester M, Douaud G, Jbabdi S*, Mars R*, Sotiropoulos SN* (Submitted)
Saad Jbabdi's avatar
Saad Jbabdi committed
25
26
27
28
29
30
Standardised protocols for automated tractography and connectivity blueprints in the human and macaque brain.

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
31
32
33

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

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

42

43
44
45
 Usage:
     xtract -bpx <bedpostX_dir> -out <outputDir> -species <SPECIES> [options]
     xtract -list
Saad Jbabdi's avatar
Saad Jbabdi committed
46

47
     Compulsory arguments:
Saad Jbabdi's avatar
Saad Jbabdi committed
48

49
50
51
        -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
52

53
54
55
56
57
58
59
60
61
     Optional arguments:
        -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
        -native                           Run tractography in native (diffusion) space
        -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)
Saad Jbabdi's avatar
Saad Jbabdi committed
62

Saad Jbabdi's avatar
Saad Jbabdi committed
63
```
Saad Jbabdi's avatar
Saad Jbabdi committed
64
65
---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
66
## Running XTRACT:
67
68
  XTRACT automatically detects if $SGE_ROOT is set and if so uses FSL_SUB.
  For optimal performance, use the GPU version!!!!
Saad Jbabdi's avatar
Saad Jbabdi committed
69
70
71

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

Saad Jbabdi's avatar
Saad Jbabdi committed
72
## Atlases:
Saad Jbabdi's avatar
Saad Jbabdi committed
73
74
75
76

- 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
77

Saad Jbabdi's avatar
Saad Jbabdi committed
78
  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
79

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

82
| **Tract**   | **Abbreviation** | **XTRACT tractName** |
83
| -------- | ------------ | ------------ |
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
| 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 |
| Forceps Major | FMA | fma |
| Forceps Minor | FMI | fmi |
| Fornix | FX | fx_l fx_r |
| Inferior Longitudinal Fasciculus | ILF | ilf_l ilf_r |
| Inferior Fronto-Occipital Fasciculus | IFO | ifo_l ifo_r |
| Middle Cerebellar Peduncle | MCP | mcp |
| Middle Longitudinal Fasciculus | MdLF | mdlf_l mdlf_r |
| Optic Radiation | OR | or_l or_r |
| 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 |
| Anterior Commissure | AC | ac |
| Uncinate Fasciculus | UF | uf_l uf_r |
| Vertical Occipital Fasciculus | VOF | vof_l vof_r |

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

<tractName> per line (default number of seeds taken from default structure file)

OR

<tractName> <nsamples> per line

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

Saad Jbabdi's avatar
Saad Jbabdi committed
118
119
---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
120
## Adding your own tracts:
Saad Jbabdi's avatar
Saad Jbabdi committed
121
122
123

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

124
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
125

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

Saad Jbabdi's avatar
Saad Jbabdi committed
128
**Compulsory**:
129
- seed.nii.gz : a seed mask
Saad Jbabdi's avatar
Saad Jbabdi committed
130

Saad Jbabdi's avatar
Saad Jbabdi committed
131
**Optional**:
Saad Jbabdi's avatar
Saad Jbabdi committed
132
133
134
135
136
137
- 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)
138
  if such an option is required a single "target.nii.gz" file is also expected
Saad Jbabdi's avatar
Saad Jbabdi committed
139

Saad Jbabdi's avatar
Saad Jbabdi committed
140
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
141

142
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
143

Saad Jbabdi's avatar
Saad Jbabdi committed
144
145
146
147
---------------------------------------------------------------------

## Visualising results with FSLEYES

148
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
149
150
151

```
 __  _______ ____      _    ____ _____         _                        
152
 \ \/ /_   _|  _ \    / \  / ___|_   _| __   _(_) _____      _____ _ __
Saad Jbabdi's avatar
Saad Jbabdi committed
153
154
155
156
157
  \  /  | | | |_) |  / _ \| |     | |   \ \ / / |/ _ \ \ /\ / / _ \ '__|
  /  \  | | |  _ <  / ___ \ |___  | |    \ V /| |  __/\ V  V /  __/ |   
 /_/\_\ |_| |_| \_\/_/   \_\____| |_|     \_/ |_|\___| \_/\_/ \___|_|                                                                           


158
159
160
161
 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
162

163
     Compulsory arguments:
Saad Jbabdi's avatar
Saad Jbabdi committed
164

165
166
167
168
169
170
171
172
        -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
173

174
     Optional arguments:
Saad Jbabdi's avatar
Saad Jbabdi committed
175

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

178
179
        -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
180
181

```