README.md 5.11 KB
Newer Older
Saad Jbabdi's avatar
Saad Jbabdi committed
1

Saad Jbabdi's avatar
Saad Jbabdi committed
2

Saad Jbabdi's avatar
Saad Jbabdi committed
3
## XTRACT is a command-line tool for running automated tractography
Saad Jbabdi's avatar
Saad Jbabdi committed
4
5
6
7

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 
define a set of masks in standard space (e.g. MNI)
Saad Jbabdi's avatar
Saad Jbabdi committed
8

Saad Jbabdi's avatar
Saad Jbabdi committed
9
The script was written by Saad Jbabdi & Stamatios Sotiropoulos
Saad Jbabdi's avatar
Saad Jbabdi committed
10
(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
11

Saad Jbabdi's avatar
Saad Jbabdi committed
12
13
14
15
16
17
18
19
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
20
---------------------------------------------------------------------
Saad Jbabdi's avatar
Saad Jbabdi committed
21
22

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

Saad Jbabdi's avatar
Saad Jbabdi committed
24
25
26
27
28
29
30
31

Warrington S, Bryant K, Charquero-Ballester M, Douaud G, Jbabdi S*, Mars R*, Sotiropoulos SN* (in prep.)
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
32
33
34

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

Saad Jbabdi's avatar
Saad Jbabdi committed
35
36
## Usage: 
```
Saad Jbabdi's avatar
Saad Jbabdi committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
    xtract -bpx <bedpostX_dir> -out <outputDir> -str <structuresFile> -p <protocolsFolder> [options]
    xtract -bpx <bedpostX_dir> -out <outputDir> -species HUMAN [options]
    xtract -bpx <bedpostX_dir> -out <outputDir> -species MACAQUE [options]

    Compulsory arguments:

       -bpx <folder>                     Path to bedpostx folder
       -out <folder>                     Path to output folder
       
       And EITHER:
       -str <file>                       Structures file (format: <tractName> [samples=1], 1 means 1000, '#' to skip lines)
       -p   <folder>                     Protocols folder (all masks in same standard space)

       Or:
       -species <SPECIES>                One of HUMAN or MACAQUE

    Optional arguments:

       -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)
Saad Jbabdi's avatar
Saad Jbabdi committed
59
```
Saad Jbabdi's avatar
Saad Jbabdi committed
60
61
---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
62
## Running XTRACT:
Saad Jbabdi's avatar
Saad Jbabdi committed
63
64
65
66
67
  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
68
## Atlases:
Saad Jbabdi's avatar
Saad Jbabdi committed
69
70
71
72
73
74
75

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

Saad Jbabdi's avatar
Saad Jbabdi committed
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
When running XTRACT with the '-species' option, a predefined list of tracts is automatically extracted. Currently the following tracts are available:

| **Tract**   | **Abbreviation** |
| --------| ------------ |
| Arcuate Fasciculus | AF |
| Acoustic Radiation | AR |
| Anterior Thalamic Radiation | ATR |
| Cingulum subsection : Dorsal | CBD |
| Cingulum subsection : Parahippocampal | CBP |
| Cingulum subsection : Temporal | CBT |
| Corticospinal Tract | CST |
| Frontal Aslant | FA |
| Forceps Major | FMA |
| Forceps Minor | FMI |
| Fornix | FX |
| Inferior Longitudinal Fasciculus | ILF |
| Inferior Fronto-Occipital Fasciculus | IFO |
| Middle Cerebellar Peduncle | MCP |
| Middle Longitudinal Fasciculuc | MdLF |
| Optic Radiation | OR |
| Superior Thalamic Radiation | STR |
| Superior Longitudinal Fasciculus 1 | SLF1 |
| Superior Longitudinal Fasciculus 2 | SLF2 |
| Superior Longitudinal Fasciculus 3 | SLF3 |
| Anterior Commissure | AC |
| Uncinate Fasciculus | UF |



Saad Jbabdi's avatar
Saad Jbabdi committed
106
107
---------------------------------------------------------------------

Saad Jbabdi's avatar
Saad Jbabdi committed
108
## Adding your own tracts:
Saad Jbabdi's avatar
Saad Jbabdi committed
109
110
111

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

Saad Jbabdi's avatar
Saad Jbabdi committed
112
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
113

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

Saad Jbabdi's avatar
Saad Jbabdi committed
116
**Compulsory**:
Saad Jbabdi's avatar
Saad Jbabdi committed
117
- seed.nii.gz : a seed mask 
Saad Jbabdi's avatar
Saad Jbabdi committed
118

Saad Jbabdi's avatar
Saad Jbabdi committed
119
**Optional**:
Saad Jbabdi's avatar
Saad Jbabdi committed
120
121
122
123
124
125
126
127
- 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)
  if such an option is required a single "target.nii.gz" file is also expected 

Saad Jbabdi's avatar
Saad Jbabdi committed
128
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
129
130