Commit 3c32f14b authored by Saad Jbabdi's avatar Saad Jbabdi
Browse files

small changes

parent 8a91c6c3
.DS_Store
*~
---------------------------------------------------------------------
## XTRACT is a command-line tool for running automated tractography.
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)
The script was written by Saad Jbabdi & Stamatios Sotiropoulos
(based on the autoPtx tool by Marius de Groot - see https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/AutoPtx)
The tractography protocols were created by:
Rogier Mars & Stamatios Sotiropoulos
with help from:
Saad Jbabdi, Kathryn Bryant, Shaun Warrington, Marina Charquero-Ballester, Gwenaelle Douaud
---------------------------------------------------------------------
## Citations:
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
---------------------------------------------------------------------
## Usage:
```
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)
```
---------------------------------------------------------------------
## Runtime:
XTRACT automatically detects if $SGE_ROOT is set and if so uses FSL_SUB
For optimal performance, use the GPU version!!!!
---------------------------------------------------------------------
Atlases:
- 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
---------------------------------------------------------------------
## Adding your own tracts:
Suppose you want to create an automated protocol for a tract called 'mytrack'.
First you need to create a folder called 'mytrack' which you can add e.g. in the protocols folder.
Then create the following NIFTI files (with this exact naming) and copy them into mytrack:
*Compulsory*:
- seed.nii.gz : a seed mask
*Optional*:
- 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
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.
......@@ -47,6 +47,26 @@ EOF
exit 1
}
Splash (){
cat <<EOF
***************************************************
__ __ _____ ____ _ ____ _____
\ \/ /|_ _|| _ \ / \ / ___||_ _|
\ / | | | |_) | / _ \ | | | |
/ \ | | | _ < / ___ \ | |___ | |
/_/\_\ |_| |_| \_\/_/ \_\ \____| |_|
***************************************************
EOF
}
Splash
[ "$1" = "" ] && Usage
......
#!/bin/bash
# Copyright (C) 2019 University of Oxford
#
# SHCOPYRIGHT
# Script to view output of XTRACT in fsleyes
# Written by Shaun Warrington 07/2019
# Modified by Saad Jbabdi 08/2019
Usage() {
cat << EOF
Usage:
xtract_viewer -dir <xtractDir> -str <structuresFile> [options]
Compulsory arguments:
-dir <folder> Path to Xtract folder
e.g. for subject, /data/subID/Xtract
for atlas, /data/tract_atlases
-str <file> Structures file (can be same as xtract input structures list)
Optional arguments:
-sub Use this flag to view a single subject's data
(look's for densityNorm.nii.gz under <dir>/tracts/)
Default is to view a tract atlas (looks for <structure>.nii.gz under <dir>)
-mip Use this flag to view tracts as mips, window of 5 slices, spline interpolation
-thr <number> <number> The lower and upper thresholds applied to the tracts for viewing
Default for subject = 0.001 0.1, default for atlas = 0.3 1.0
-brain The brain image to use for the background overlay - must be in the same space as tracts.
Default is the FSL_HCP065_FA map
EOF
exit 1
}
echo "---"
echo "----"
echo "-----"
echo "------"
echo "-------"
echo "------- Xtract Viewer"
echo "-------"
echo "------"
echo "-----"
echo "----"
echo "---"
[ "$1" = "" ] && Usage
# Set defaults
sub=0
mip=0
thr=""
brain=""
# the colourmap options
cmaps=(blue red green blue-lightblue pink red-yellow cool yellow copper \
hot hsv coolwarm spring summer winter Oranges)
cL="${#cmaps[@]}" # length of array for colourmap loop control
# Parse command-line arguments
while [ ! -z "$1" ];do
case "$1" in
-dir) dir=$2;shift;;
-str) str=$2;shift;;
-sub) sub=1;;
-thr) thr=$2;uthr=$3;shift;shift;;
-mip) mip=1;;
-brain) brain=$2;shift;;
*) echo "Unknown option '$1'";exit 1;;
esac
shift
done
# Default threshold values and mip opts
if [ "$thr" == "" ];then
if [ "$sub" == "1" ]; then
thr=0.001
uthr=0.1
elif [ "$sub" == "0" ]; then
thr=0.3
uthr=1.0
fi
fi
if [ "$brain" == "" ];then
# the FA atlas
brain=${FSLDIR}/data/standard/FSL_HCP1065_FA_1mm.nii.gz
fi
# Check compulsory arguments
errflag=0
if [ "$dir" == "" ];then
echo "Must set compulsory argument '-dir'"
errflag=1
elif [ ! -d $dir ];then
echo "Xtract folder $dir not found"
errflag=1
fi
if [ "$str" == "" ];then
echo "Must set compulsory argument '-str'"
errflag=1
elif [ ! -f $str ];then
echo "Structure file $str not found"
errflag=1
fi
if [ "$uthr" == "" ];then
echo "You have set a lower threshold but not an upper threshold. Must set '-thr' using <number> <number>"
errflag=1
fi
if [ ! -f $brain ];then
echo "Brain overlay file $brain not found"
errflag=1
fi
if [ "$errflag" -eq 1 ];then
echo ""
echo "Exit without doing anything.."
exit 1
fi
# build struct array - removing any empty/comment lines
# and check for and remove any file extentions
strlist=()
while read structstring; do
struct=`echo $structstring | awk '{print $1}'`
# skip empty lines and lines that start with '#'
if [ "${struct:0:1}" == "#" ];then
foo=0 #do nothing
elif [ ! "$struct" == "" ];then
ss=`echo $struct | sed s/.nii.gz//`
strlist+=("$ss")
fi
done < $str
# start the fsleyes command with basic options
cmd="${FSLDIR}/bin/fsleyes $brain -dr 0 `fslstats $brain -r | awk '{print $2}'`"
opts="-dr $thr $uthr"
# Using mip?
if [ "$mip" == "1" ];then
opts="$opts --overlayType mip --interpolation spline --window 5.0"
fi
# subject or atlas data structure?
if [ "$sub" == "1" ];then
preT="/tracts"
postT="/densityNorm.nii.gz"
else
preT=""
postT=".nii.gz"
fi
# Now loop and check for left/right tracts to colour the same
# checks for _l and matches any _r
# if no _?, then just move on to next line
i=0
for tract in "${strlist[@]}"
do
if [ $i -gt $((cL - 1)) ]; then i=0; fi # control colourmap loop
# check tract exists
if [ ! -f "${dir}/${preT}/${tract}${postT}" ]; then
echo "Couldn't find ${tract} image."
echo "Moving on to the next structure."
echo "Check ${dir}/${preT}/${tract}${postT} and try again"
else
# if you find a left tract, then find the corresponding right tract
# and colour in the same way
if [[ $tract == *"_l"* ]];then
tt=`echo ${tract} | sed s/_l/_r/`
if [ "`grep ${tt} $str`" != "" ];then
# append _l and _r to fsleyes command with viewing options
cmd="$cmd ${dir}/${preT}/${tract}${postT} $opts -cm ${cmaps[i]} -n ${tract} ${dir}/${preT}/${tt}${postT} $opts -cm ${cmaps[i]} -n ${tt}"
else
# else, just add the current tract
cmd="$cmd ${dir}/${preT}/${tract}${postT} $opts -cm ${cmaps[i]} -n ${tract}"
fi
elif [[ $tract == *"_r"* ]] && [[ ! $cmd == *"$tract"* ]] && [[ ! ${strlist[@]} == *"`echo ${tract} | sed s/_r/_l/`"* ]];then
# if tract name has _r and hasn't been found already
cmd="$cmd ${dir}/${preT}/${tract}${postT} $opts -cm ${cmaps[i]} -n ${tract}"
elif [[ $tract != *"_r"* && $tract != *"_l"* ]];then
# if tract name doesn't have _l or _r
cmd="$cmd ${dir}/${preT}/${tract}${postT} $opts -cm ${cmaps[i]} -n ${tract}"
fi
((i++))
fi
done
echo $cmd
echo "Launching FSLeyes..."
bash $cmd &
#echo $cmd
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment