Commit 92d19c0f authored by Shaun Warrington's avatar Shaun Warrington
Browse files

Merge branch 'patch-191119' into 'master'

Patch 191119

See merge request !6
parents e20653fa dfac9802
## XTRACT - a command-line tool for 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
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. MNI152)
The script was written by Saad Jbabdi & Stamatios Sotiropoulos
......@@ -31,16 +31,16 @@ NeuroImage, 76(1), 400-411. DOI: 10.1016/j.neuroimage.2013.03.015
---------------------------------------------------------------------
## Usage:
## Usage:
```
__ _______ ____ _ ____ _____
__ _______ ____ _ ____ _____
\ \/ /_ _| _ \ / \ / ___|_ _|
\ / | | | |_) | / _ \| | | |
/ \ | | | _ < / ___ \ |___ | |
/_/\_\ |_| |_| \_\/_/ \_\____| |_|
Usage:
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]
......@@ -49,7 +49,7 @@ Usage:
-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)
......@@ -59,8 +59,8 @@ Usage:
Optional arguments:
-stdwarp <std2diff> <diff2std> Standard2diff and Diff2standard transforms (Default=bedpostx_dir/xfms/{standard2diff,diff2standard})
-gpu Use GPU version
-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)
......@@ -70,8 +70,8 @@ Usage:
---------------------------------------------------------------------
## Running XTRACT:
XTRACT automatically detects if $SGE_ROOT is set and if so uses FSL_SUB.
For optimal performance, use the GPU version!!!!
XTRACT automatically detects if $SGE_ROOT is set and if so uses FSL_SUB.
For optimal performance, use the GPU version!!!!
---------------------------------------------------------------------
......@@ -80,7 +80,7 @@ Usage:
- 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
When running XTRACT with the '-species' option, a predefined list of tracts is automatically extracted. Currently the following tracts are available:
......@@ -119,12 +119,12 @@ When running XTRACT with the '-species' option, a predefined list of tracts is a
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.
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
- seed.nii.gz : a seed mask
**Optional**:
- stop.nii.gz : a stop mask if required
......@@ -133,7 +133,7 @@ Then create the following NIFTI files (with this exact naming) and copy them int
- 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
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.
......@@ -146,27 +146,33 @@ The output of XTRACT is a folder that contrains tracts in separate folders. We p
```
__ _______ ____ _ ____ _____ _
\ \/ /_ _| _ \ / \ / ___|_ _| __ _(_) _____ _____ _ __
\ \/ /_ _| _ \ / \ / ___|_ _| __ _(_) _____ _____ _ __
\ / | | | |_) | / _ \| | | | \ \ / / |/ _ \ \ /\ / / _ \ '__|
/ \ | | | _ < / ___ \ |___ | | \ V /| | __/\ V V / __/ |
/_/\_\ |_| |_| \_\/_/ \_\____| |_| \_/ |_|\___| \_/\_/ \___|_|
Usage:
xtract_viewer -dir <xtractDir> [options]
Compulsory arguments:
Usage:
xtract_viewer -dir <xtractDir> -species HUMAN [options]
xtract_viewer -dir <xtractDir> -species MACAQUE [options]
xtract_viewer -dir <xtractDir> -brain <PATH> [options]
-dir FOLDER Path to XTRACT output folder
Compulsory arguments:
Optional arguments:
-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
-str STRUCTURE,STRUCTURE,... Structures (comma separated (default = display all that is found in input folder)
Optional arguments:
-thr NUMBER NUMBER The lower and upper thresholds applied to the tracts for viewing
Default = 0.001 0.1
-str STRUCTURE,STRUCTURE,... Structures (comma separated (default = display all that is found in input folder)
-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
-thr NUMBER NUMBER The lower and upper thresholds applied to the tracts for viewing
Default = 0.001 0.1
```
......@@ -16,7 +16,7 @@ datadir=$FSLDIR/etc/xtract_data
Usage() {
cat << EOF
Usage:
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]
......@@ -25,7 +25,7 @@ Usage:
-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)
......@@ -35,8 +35,8 @@ Usage:
Optional arguments:
-stdwarp <std2diff> <diff2std> Standard2diff and Diff2standard transforms (Default=bedpostx_dir/xfms/{standard2diff,diff2standard})
-gpu Use GPU version
-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)
......@@ -50,12 +50,12 @@ Splash (){
cat <<EOF
__ _______ ____ _ ____ _____
__ _______ ____ _ ____ _____
\ \/ /_ _| _ \ / \ / ___|_ _|
\ / | | | |_) | / _ \| | | |
/ \ | | | _ < / ___ \ |___ | |
/_/\_\ |_| |_| \_\/_/ \_\____| |_|
\ / | | | |_) | / _ \| | | |
/ \ | | | _ < / ___ \ |___ | |
/_/\_\ |_| |_| \_\/_/ \_\____| |_|
EOF
}
......@@ -64,7 +64,7 @@ Warning (){
cat <<EOF
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING!!!! MACAQUE TRACTS ARE A WORK IN PROGRESS STILL....
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
EOF
}
......@@ -219,13 +219,13 @@ while read structstring; do
nseed=1
fi
nseed=$(echo "scale=0; 1000 * ${nseed} / 1"|bc)
maskdir=$p/$struct
# DEALING WITH RESAMPLING --
# Pick space to run tractography in (diffusion or standard)
# DEALING WITH RESAMPLING --
# Pick space to run tractography in (diffusion or standard)
if [ "$nat" -eq 1 ];then
echo " -- transforming masks into native space"
echo " -- transforming masks into native space"
mkdir -p $out/masks/$struct
for m in seed stop exclude;do
if [ `$FSLDIR/bin/imtest $maskdir/$m` -eq 1 ];then
......@@ -233,22 +233,22 @@ while read structstring; do
$FSLDIR/bin/fslmaths $out/masks/$struct/$m -thr 0.1 -bin $out/masks/$struct/$m -odt char
fi
eval "${m}=$out/masks/$struct/$m"
done
done
else
for m in seed stop exclude;do
for m in seed stop exclude;do
if [ $res -gt 0 ];then
# Resample at a different resolution
mkdir -p $out/masks/$struct
if [ `$FSLDIR/bin/imtest $maskdir/$m` -eq 1 ];then
$FSLDIR/bin/flirt -in $maskdir/$m -out $out/masks/$struct/$m -applyisoxfm $res -ref $maskdir/$m
$FSLDIR/bin/flirt -in $maskdir/$m -out $out/masks/$struct/$m -applyisoxfm $res -ref $maskdir/$m
$FSLDIR/bin/fslmaths $out/masks/$struct/$m -thr 0.1 -bin $out/masks/$struct/$m -odt char
fi
eval "${m}=$out/masks/$struct/$m"
fi
eval "${m}=$out/masks/$struct/$m"
else
eval "${m}=$maskdir/$m"
fi
done
fi
fi
# Deal with targets (in cases where there may be more than one)
targets=`imglob $maskdir/target*`
......@@ -276,7 +276,7 @@ while read structstring; do
# Get generic options
o=$opts
# Add inclusion/exclusion masks
if [ `$FSLDIR/bin/imtest $stop` -eq 1 ];then
o="$o --stop=$stop"
......@@ -287,7 +287,7 @@ while read structstring; do
# Add seed/target
o1="$o --nsamples=$nseed -x $seed "
if [ "x${targets}" != "x" ];then #Add waypoints if there are any
o1=" $o1 --waypoints=$targetfile "
fi
......@@ -295,8 +295,8 @@ while read structstring; do
# Outputs
o1=" $o1 -o density --dir=$out/tracts/$struct"
# Does the protocol define a second run with inverted seed / target masks?
# Does the protocol define a second run with inverted seed / target masks?
if [ -e $maskdir/invert ]; then #Invert-mode
if [ `$FSLDIR/bin/imtest $maskdir/target.nii.gz` -eq 1 ];then # Check if a target.nii.gz image exists when invert option has been selected.
mkdir -p $out/tracts/$struct/tractsInv
......@@ -311,8 +311,8 @@ while read structstring; do
mergecmd="$FSLDIR/bin/fslmaths $out/tracts/$struct/density -add $out/tracts/$struct/tractsInv/density $out/tracts/$struct/sum_density"
#Add waypoints (create command but don't execute)
addcmd="echo \"scale=5; \`cat $out/tracts/$struct/waytotal\` + \`cat $out/tracts/$struct/tractsInv/waytotal\` \"|bc > $out/tracts/$struct/sum_waytotal"
addcmd="echo \"scale=5; \`cat $out/tracts/$struct/waytotal\` + \`cat $out/tracts/$struct/tractsInv/waytotal\` \"|bc > $out/tracts/$struct/sum_waytotal"
# Waypoint normalisation (create command but don't execute)
normcmd="$FSLDIR/bin/fslmaths $out/tracts/$struct/sum_density -div \`cat $out/tracts/$struct/sum_waytotal\` $out/tracts/$struct/densityNorm"
......@@ -338,7 +338,7 @@ chmod +x $commands
if [ "x$SGE_ROOT" != "x" ]; then # Submit all commands to run in parallel on the cluster
# One job per tract for a CPU cluster, one job for all tracts for a GPU cluster.
if [ $gpu -eq 0 ];then
fsl_sub -q long.q -l $out/logs -N xtract -t $commands
fsl_sub -q long.q -T 2160 -l $out/logs -N xtract -t $commands
else
fsl_sub -q $FSLGECUDAQ -T 300 -l $out/logs -N xtract $commands
fi
......
#!/bin/bash
# Copyright (C) 2019 University of Oxford
......@@ -14,11 +12,20 @@ Usage() {
cat << EOF
Usage:
xtract_viewer -dir <xtractDir> [options]
xtract_viewer -dir <xtractDir> -species HUMAN [options]
xtract_viewer -dir <xtractDir> -species MACAQUE [options]
xtract_viewer -dir <xtractDir> -brain <PATH> [options]
Compulsory arguments:
-dir FOLDER Path to XTRACT output folder
-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
Optional arguments:
......@@ -27,8 +34,6 @@ Usage:
-thr NUMBER NUMBER The lower and upper thresholds applied to the tracts for viewing
Default = 0.001 0.1
-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
}
......@@ -37,12 +42,12 @@ Splash (){
cat <<EOF
__ _______ ____ _ ____ _____ _
\ \/ /_ _| _ \ / \ / ___|_ _| __ _(_) _____ _____ _ __
__ _______ ____ _ ____ _____ _
\ \/ /_ _| _ \ / \ / ___|_ _| __ _(_) _____ _____ _ __
\ / | | | |_) | / _ \| | | | \ \ / / |/ _ \ \ /\ / / _ \ '__|
/ \ | | | _ < / ___ \ |___ | | \ V /| | __/\ V V / __/ |
/_/\_\ |_| |_| \_\/_/ \_\____| |_| \_/ |_|\___| \_/\_/ \___|_|
/ \ | | | _ < / ___ \ |___ | | \ V /| | __/\ V V / __/ |
/_/\_\ |_| |_| \_\/_/ \_\____| |_| \_/ |_|\___| \_/\_/ \___|_|
EOF
}
......@@ -59,11 +64,12 @@ cL="${#cmaps[@]}" # length of array for colourmap loop control
# Set defaults
thr=0.001
uthr=0.1
brain=${FSLDIR}/data/standard/FSL_HCP1065_FA_1mm.nii.gz
str=ALL
spec=""
while [ ! -z "$1" ];do
case "$1" in
-dir) dir=$2;shift;;
-species) spec=$2;shift;;
-str) IFS=', ' read -r -a str <<< "$2";shift;;
-thr) thr=$2;uthr=$3;shift;shift;;
-brain) brain=$2;shift;;
......@@ -81,12 +87,26 @@ elif [ ! -d $dir ];then
echo "Xtract folder $dir 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>"
if [ "$spec" == "" ];then
if [ "$brain" == "" ];then
echo "Must set compulsory argument '-brain' OR specify '-species <SPECIES>'"
errflag=1
elif [ `$FSLDIR/bin/imtest $brain` -eq 0 ];then
echo "Brain overlay file $brain not found"
errflag=1
fi
elif [ $spec == HUMAN ];then
brain=${FSLDIR}/data/standard/FSL_HCP1065_FA_1mm.nii.gz
elif [ $spec == MACAQUE ];then
brain=${FSLDIR}/etc/xtract_data/standard/F99/mri/struct_brain.nii.gz
elif [ ! "$spec" == "HUMAN" ] && [ ! "$spec" == "MACAQUE" ];then
echo "Unrecognised option '$spec'. Must set '-species' using HUMAN or MACAQUE"
errflag=1
fi
if [ `$FSLDIR/bin/imtest $brain` -eq 0 ];then
echo "Brain overlay file $brain not found"
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 [ "$errflag" -eq 1 ];then
......@@ -130,9 +150,9 @@ for tract in "${str[@]}";do
else
# if you find a left tract, then find the corresponding right tract
# and colour in the same way
if [[ $tract == *"_l"* ]];then
if [[ $tract == *"_l"* ]];then
tt=`echo ${tract} | sed s/_l/_r/`
if [[ "${str[@]}" =~ "$tt" ]];then
if [[ "${str[@]}" =~ "$tt" ]];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
......
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