Commit 86c7e139 authored by Shaun Warrington's avatar Shaun Warrington
Browse files

Merge branch 'species_str' into 'master'

Tract subsets

See merge request !11
parents 8af9e2cf 729eb4f9
...@@ -4,7 +4,7 @@ XTRACT can be used to automatically extract a set of carefully dissected tracts ...@@ -4,7 +4,7 @@ XTRACT can be used to automatically extract a set of carefully dissected tracts
species to come). It can also be used to define one's own tractography protocols where all the user needs to do is to 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) define a set of masks in standard space (e.g. MNI152)
The script was written by Saad Jbabdi & Stamatios Sotiropoulos and slightly edited by Shaun Warrington The script was written by Saad Jbabdi, Stamatios Sotiropoulos & Shaun Warrington
(based on the autoPtx tool by Marius de Groot - see https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/AutoPtx) (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: The tractography protocols were created by:
...@@ -40,32 +40,26 @@ NeuroImage, 76(1), 400-411. DOI: 10.1016/j.neuroimage.2013.03.015 ...@@ -40,32 +40,26 @@ NeuroImage, 76(1), 400-411. DOI: 10.1016/j.neuroimage.2013.03.015
/_/\_\ |_| |_| \_\/_/ \_\____| |_| /_/\_\ |_| |_| \_\/_/ \_\____| |_|
Usage: Usage:
xtract -bpx <bedpostX_dir> -out <outputDir> -str <structuresFile> -p <protocolsFolder> [options] xtract -bpx <bedpostX_dir> -out <outputDir> -species <SPECIES> [options]
xtract -bpx <bedpostX_dir> -out <outputDir> -species HUMAN [options] xtract -list
xtract -bpx <bedpostX_dir> -out <outputDir> -species MACAQUE [options]
Compulsory arguments: Compulsory arguments:
-bpx <folder> Path to bedpostx folder -bpx <folder> Path to bedpostx folder
-out <folder> Path to output 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 -species <SPECIES> One of HUMAN or MACAQUE
Optional arguments: 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}) -stdwarp <std2diff> <diff2std> Standard2diff and Diff2standard transforms (Default=bedpostx_dir/xfms/{standard2diff,diff2standard})
-gpu Use GPU version -gpu Use GPU version
-native Run tractography in native (diffusion) space -native Run tractography in native (diffusion) space
-res <mm> Output resolution (Default=same as in protocol folders unless '-native' used) -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) -ptx_options <options.txt> Pass extra probtrackx2 options as a text file to override defaults, e.g. --steplength=0.2 --distthresh=10)
``` ```
--------------------------------------------------------------------- ---------------------------------------------------------------------
...@@ -85,33 +79,41 @@ Usage: ...@@ -85,33 +79,41 @@ Usage:
When running XTRACT with the '-species' option, a predefined list of tracts is automatically extracted. Currently the following tracts are available: When running XTRACT with the '-species' option, a predefined list of tracts is automatically extracted. Currently the following tracts are available:
| **Tract** | **Abbreviation** | | **Tract** | **Abbreviation** | **XTRACT tractName** |
| --------| ------------ | | -------- | ------------ | ------------ |
| Arcuate Fasciculus | AF | | Arcuate Fasciculus | AF | af_l af_r |
| Acoustic Radiation | AR | | Acoustic Radiation | AR | ar_l ar_r |
| Anterior Thalamic Radiation | ATR | | Anterior Thalamic Radiation | ATR | atr_l atr_r |
| Cingulum subsection : Dorsal | CBD | | Cingulum subsection : Dorsal | CBD | cbd_l cbd_r |
| Cingulum subsection : Peri-genual | CBP | | Cingulum subsection : Peri-genual | CBP | cbp_l cbp_r |
| Cingulum subsection : Temporal | CBT | | Cingulum subsection : Temporal | CBT | cbt_l cbt_r |
| Corticospinal Tract | CST | | Corticospinal Tract | CST | cst_l cst_r |
| Frontal Aslant | FA | | Frontal Aslant | FA | fa_l fa_r |
| Forceps Major | FMA | | Forceps Major | FMA | fma |
| Forceps Minor | FMI | | Forceps Minor | FMI | fmi |
| Fornix | FX | | Fornix | FX | fx_l fx_r |
| Inferior Longitudinal Fasciculus | ILF | | Inferior Longitudinal Fasciculus | ILF | ilf_l ilf_r |
| Inferior Fronto-Occipital Fasciculus | IFO | | Inferior Fronto-Occipital Fasciculus | IFO | ifo_l ifo_r |
| Middle Cerebellar Peduncle | MCP | | Middle Cerebellar Peduncle | MCP | mcp |
| Middle Longitudinal Fasciculus | MdLF | | Middle Longitudinal Fasciculus | MdLF | mdlf_l mdlf_r |
| Optic Radiation | OR | | Optic Radiation | OR | or_l or_r |
| Superior Thalamic Radiation | STR | | Superior Thalamic Radiation | STR | str_l str_r |
| Superior Longitudinal Fasciculus 1 | SLF1 | | Superior Longitudinal Fasciculus 1 | SLF1 | slf1_l slf1_r |
| Superior Longitudinal Fasciculus 2 | SLF2 | | Superior Longitudinal Fasciculus 2 | SLF2 | slf2_l slf2_r |
| Superior Longitudinal Fasciculus 3 | SLF3 | | Superior Longitudinal Fasciculus 3 | SLF3 | slf3_l slf3_r |
| Anterior Commissure | AC | | Anterior Commissure | AC | ac |
| Uncinate Fasciculus | UF | | Uncinate Fasciculus | UF | uf_l uf_r |
| Vertical Occipital Fasciculus | VOF | | 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
--------------------------------------------------------------------- ---------------------------------------------------------------------
...@@ -121,7 +123,7 @@ Suppose you want to create an automated protocol for a tract called 'mytrack'. ...@@ -121,7 +123,7 @@ 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: Then create the following NIFTI files (with this exact naming) and copy them into 'mytrack':
**Compulsory**: **Compulsory**:
- seed.nii.gz : a seed mask - seed.nii.gz : a seed mask
...@@ -137,12 +139,13 @@ Then create the following NIFTI files (with this exact naming) and copy them int ...@@ -137,12 +139,13 @@ Then create the following NIFTI files (with this exact naming) and copy them int
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. 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.
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'.
--------------------------------------------------------------------- ---------------------------------------------------------------------
## Visualising results with FSLEYES ## Visualising results with FSLEYES
The output of XTRACT is a folder that contrains 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 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
``` ```
__ _______ ____ _ ____ _____ _ __ _______ ____ _ ____ _____ _
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
# Written by Saad Jbabdi & Stam Sotiropoulos (based on Marius de Groot autoPtx code) # Written by Saad Jbabdi & Stam Sotiropoulos (based on Marius de Groot autoPtx code)
# Protocols created by Rogier Mars et al. # Protocols created by Rogier Mars et al.
# Location of probtrackx2_gpu binary
ptxbin_gpu=$FSLDIR/bin/probtrackx2_gpu ptxbin_gpu=$FSLDIR/bin/probtrackx2_gpu
# Location of xtract data # Location of xtract data
...@@ -17,24 +17,19 @@ Usage() { ...@@ -17,24 +17,19 @@ Usage() {
cat << EOF cat << EOF
Usage: Usage:
xtract -bpx <bedpostX_dir> -out <outputDir> -str <structuresFile> -p <protocolsFolder> [options] xtract -bpx <bedpostX_dir> -out <outputDir> -species <SPECIES> [options]
xtract -bpx <bedpostX_dir> -out <outputDir> -species HUMAN [options] xtract -list
xtract -bpx <bedpostX_dir> -out <outputDir> -species MACAQUE [options]
Compulsory arguments: Compulsory arguments:
-bpx <folder> Path to bedpostx folder -bpx <folder> Path to bedpostx folder
-out <folder> Path to output 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 -species <SPECIES> One of HUMAN or MACAQUE
Optional arguments: 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}) -stdwarp <std2diff> <diff2std> Standard2diff and Diff2standard transforms (Default=bedpostx_dir/xfms/{standard2diff,diff2standard})
-gpu Use GPU version -gpu Use GPU version
-native Run tractography in native (diffusion) space -native Run tractography in native (diffusion) space
...@@ -60,14 +55,6 @@ EOF ...@@ -60,14 +55,6 @@ EOF
} }
Warning (){
cat <<EOF
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING!!!! MACAQUE TRACTS ARE A WORK IN PROGRESS STILL....
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
EOF
}
Splash Splash
[ "$1" = "" ] && Usage [ "$1" = "" ] && Usage
...@@ -80,11 +67,13 @@ str="" ...@@ -80,11 +67,13 @@ str=""
p="" p=""
std2diff="" std2diff=""
ptx_opts="" ptx_opts=""
stdref="$FSLDIR/data/standard/MNI152_T1_1mm" stdref=""
gpu=0 gpu=0
nat=0 nat=0
spec="" spec=""
res=-1 res=-1
list=0
seedget=0 # if user specifies -str and format is <tractName>, try to get nseeds from default structureList (i.e. if using a subset of XTRACT tracts)
# Parse command-line arguments # Parse command-line arguments
while [ ! -z "$1" ];do while [ ! -z "$1" ];do
...@@ -98,12 +87,33 @@ while [ ! -z "$1" ];do ...@@ -98,12 +87,33 @@ while [ ! -z "$1" ];do
-gpu) gpu=1;; -gpu) gpu=1;;
-native) nat=1;; -native) nat=1;;
-res) res=$2;shift;; -res) res=$2;shift;;
-list) list=1;shift;;
-ptx_options) ptx_opts=`cat $2`;shift;; -ptx_options) ptx_opts=`cat $2`;shift;;
*) echo "Unknown option '$1'";exit 1;; *) echo "Unknown option '$1'";exit 1;;
esac esac
shift shift
done done
# list argument
if [ "$list" -eq 1 ];then
tractNames=""
echo ""
echo "Tract names:"
while read structstring; do
struct=`echo $structstring | awk '{print $1}'`
if [ "${struct:0:1}" == "#" ];then
foo=0
elif [ "$struct" == "" ];then
foo=0
else
tractNames="${tractNames} ${struct},"
fi
done < $datadir/Human/structureList
echo ${tractNames%,}
exit 1
fi
# Default warps # Default warps
if [ "$std2diff" == "" ];then if [ "$std2diff" == "" ];then
std2diff=$bpx/xfms/standard2diff std2diff=$bpx/xfms/standard2diff
...@@ -120,7 +130,6 @@ fi ...@@ -120,7 +130,6 @@ fi
echo SPECIES $spec echo SPECIES $spec
# GPU stuff # GPU stuff
if [ $gpu -eq 0 ];then if [ $gpu -eq 0 ];then
ptxbin=$FSLDIR/bin/probtrackx2 ptxbin=$FSLDIR/bin/probtrackx2
...@@ -129,7 +138,6 @@ else ...@@ -129,7 +138,6 @@ else
ptxbin=${ptxbin_gpu} ptxbin=${ptxbin_gpu}
fi fi
# Check compulsory arguments # Check compulsory arguments
errflag=0 errflag=0
if [ "$bpx" == "" ];then if [ "$bpx" == "" ];then
...@@ -144,32 +152,82 @@ if [ "$out" == "" ];then ...@@ -144,32 +152,82 @@ if [ "$out" == "" ];then
errflag=1 errflag=1
fi fi
# Check which species and protocols to run
if [ "$spec" == "" ];then if [ "$spec" == "" ];then
if [ "$str" == "" ];then echo "Must set compulsory argument '-species'"
echo "Must set compulsory argument '-str'"
errflag=1 errflag=1
elif [ ! -f $str ];then elif [ "$spec" == "HUMAN" ];then
echo "Structure file $str not found" stdref=$FSLDIR/data/standard/MNI152_T1_1mm
strdef=$datadir/Human/structureList
if [ "$p" == "" ];then
p=$datadir/Human
if [ "$str" == "" ];then
str=$p/structureList
fi
elif [ ! "$p" == "" ];then
if [ "$str" == "" ];then
echo "If selecting a protocol folder, must set argument '-str'"
errflag=1 errflag=1
fi fi
fi
elif [ "$spec" == "MACAQUE" ];then
stdref=$datadir/standard/F99/mri/struct_brain
strdef=$datadir/Macaque/structureList
if [ "$p" == "" ];then if [ "$p" == "" ];then
echo "Must set compulsory argument '-p'" p=$datadir/Macaque
errflag=1 if [ "$str" == "" ];then
elif [ ! -d $p ];then str=$p/structureList
echo "Protocol folder $p not found" fi
elif [ ! "$p" == "" ];then
if [ "$str" == "" ];then
echo "If selecting a protocol folder, must set argument '-str'"
errflag=1 errflag=1
fi fi
fi
else else
if [ "$spec" == "HUMAN" ];then
p=$datadir/Human
str=$p/structureList
elif [ "$spec" == "MACAQUE" ];then
p=$datadir/Macaque
str=$p/structureList
Warning
else
echo "Species must be one of HUMAN or MACAQUE" echo "Species must be one of HUMAN or MACAQUE"
errflag=1 errflag=1
fi
# Check that -str and -p exist
if [ ! -d $p ];then
echo "Protocol folder $p not found"
errflag=1
fi
if [ ! -f $str ];then
echo "Structures files $str not found"
errflag=1
fi
# Check -str file format
tchk=()
if [ ! "$str" == "$strdef" ];then
while read structstring; do
struct=`echo $structstring | awk '{print $1}'`
if [ "${struct:0:1}" == "#" ];then
foo=0
elif [ "$struct" == "" ];then
foo=0
else
if [ "`echo $structstring | awk '{print $2}'`" == "" ];then
tchk+=("1") # if empty, then 1 - get nseeds from default -str file
else
tchk+=("0")
fi
fi
done < $str
IFS=$'\n'; tchk=($(sort <<<"${tchk[*]}")); unset IFS
if [ ! "${tchk[0]}" -eq "${tchk[${#tchk[@]}-1]}" ];then
echo ""
echo "-str file format is inconsistent. Format should be either:"
echo "<tractName> per line"
echo "OR"
echo "<tractName> [samples=1] per line"
echo "samples=1, 1 means 1000. Use '#' to skip lines"
errflag=1
elif [ ${tchk[0]} -eq 1 ];then
echo "Using subset of XTRACT protocols and getting 'nsamples' from default structure file."
seedget=1
fi fi
fi fi
...@@ -214,9 +272,16 @@ while read structstring; do ...@@ -214,9 +272,16 @@ while read structstring; do
#echo "autoTrack $struct" #echo "autoTrack $struct"
mkdir -p $out/tracts/$struct mkdir -p $out/tracts/$struct
nseed=`echo $structstring | awk '{print $2}'` # if running a subset of tracts and -str format is <tractName>, check for nseed in str file
if [ "$seedget" -eq 1 ]; then
nseed=`grep -w ${struct} $strdef | awk '{print $2}'`
if [ "$nseed" == "" ];then if [ "$nseed" == "" ];then
nseed=1 echo "Couldn't find number of samples for '$struct'. Exiting now."
exit 1
fi
else
nseed=`echo $structstring | awk '{print $2}'`
if [ "$nseed" == "" ];then nseed=1; fi
fi fi
nseed=$(echo "scale=0; 1000 * ${nseed} / 1"|bc) nseed=$(echo "scale=0; 1000 * ${nseed} / 1"|bc)
......
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