A simple tract segmentation technique.
At a minimum, you'll need an up-to-date installation of MRtrix3.
Tractfinder also uses FSL's flirt
to perform MNI registration. If you already have an (affine) registration transform for your data, then this step can be skipped.
Otherwise, an up-to-date installation of FSL is required.
The script bin/tractfinder
is written as an external module against the MRtrix3 python library.
To install tractfinder, first clone this repository:
$ git clone https://github.com/fionaEyoung/tractfinder.git
Next, link the tractfinder repository with your MRtrix3 installation. See MRtrix's guide on external modules for more information.
You will need the path to the MRtrix3 build
script, relative to your tractfinder directory.
Note
The following instructions assume an MRtrix3 build
file exists, which is automatically true for installations of MRtrix3 that have been built from source. See the end of this section if you downloaded MRtrix3 as a pre-compiled package.
Assuming your mrtrix3
and tractfinder
directories are in the same location, option 1 is to create a symbolic link:
cd tractfinder
ln -s ../mrtrix3/build
alternatively, using a text file:
cd tractfinder
echo ../mrtrix3/build > build
If you downloaded MRtrix3 directly as a pre-compiled package from the website, rather than building from source, then you will need to create a dummy build
file:
- Locate your MRtrix3 installation. This will likely be in
/usr/local/mrtrix
for a Unix system. - Create an empty file called
build
in this location. The contents of the file is irrelevant! You made need admin privilages to create the file, i.e.:
sudo touch /usr/local/mrtrix/build
- Follow the linking instructions above, replacing the relevant path with that of the file you just created, e.g.:
cd tractfinder
echo /usr/local/mrtrix/build > build
You can always invoke the tractfinder script as <path/to>/tractfinder/bin/tractfinder
. In order to enable invoking the command using tractfinder
alone, add it's bin
directory to your path (replace <path/to>
with the appropriate location, e.g. ~
if you have installed tractfinder in your home directory):
export PATH=$PATH:<path/to>/tractfinder/bin
To use tractfinder, you'll need at least one tract orientation atlas! Atlases for the corticospinal tract, arcuate fasciculus, optic radiation and inferior fronto-occipital fasciculus are available here: https://zenodo.org/records/10149873 You can also make your own atlases pretty easily! All you need is a dataset of streamlines, curated to your satisfaction, for at least 15 training subjects. Steps for creating custom atlases will be added soon.
Tractfinder operates on white matter fibre orientation distribution (FOD) obtained using constrained spherical deconvolution. Multi-shell, multi-tissue CSD is recommended where possible.
There are two basic modes of using tractfinder. You can either specify pairs of atlas and corresponding output images, each corresponding to a single tract to be mapped, or a directory containing atlases and an output directory (which doesn't have to already exist). In the latter case, any valid SH image in atlas directory will be mapped to the input image and the result will be stored in the output directory with a name matching the corresponding atlas, plus a suffix.
Tractfinder involves alignment of an atlas in template space with the target image.
To this end, you must either provide an affine transformation (in MRtrix3 format) using the -transform
option or a pair of structural images (in template and subject space respectively) using the -struct
option.
Note
the second argument provided to -struct
is assumed to be co-registered with the corresponding diffusion space (i.e. the input FOD image).
Map a single tract, represented in the atlas file CST_left.mif
to the FOD image wm_fod.mif
. Affine transform from template space to subject space is provided in t_mni_2_subject.txt
tractfinder wm_fod.mif CST_left.mif CST_left_tractmap.nii.gz -transform t_mni_2_subject.txt
As above, but registration has not been pre-computed. In this case, supply a structural image "T1w.nii.gz
" in subject space (i.e., already aligned with wm_fod.mif
)
tractfinder wm_fod.mif CST_left.mif CST_left_tractmap.nii.gz -struct MNI152.nii.gz T1w.nii.gz
To map multiple tracts, you can supply each atlas and output file individually:
tractfinder wm_fod.mif CST_left.mif CST_left_tractmap.nii.gz AF_right.mif AF_right_tractmap.nii.gz -transform t_mni_2_subject.txt
Or specify a folder containing all atlases, and an output path to store the results:
tractfinder wm_fod.mif tract_atlases tractfinder_output -transform t_mni_2_subject.txt
Assuming the following contents for tract_atlases
tract_atlases/
|-- CST_left.mif
|-- CST_right.mif
|-- AF_right.mif
the result will be
tractfinder_output/
|-- CST_left_tractmap.mif
|-- CST_right_tractmap.mif
|-- AF_right_tractmap.mif
(Note: the _tractmap
is the default suffix. It can be changed using the -suffix
option.)
The tumour deformation functionality is currently under development, and may not be stable.
To use it, checkout the development (dev
) branch:
cd tractfinder
git checkout dev
Full user guide here.
The basic pipeline is also outlined in the script tractfinder.sh
. Edit the path variables within appropriately and run as sh tractfinder.sh
.
You can also inspect the file and run the corresponding commands directly from the command line (there are only 5 steps at most).