PROBTRACKX - probabilistic tracking with crossing fibres


For details about probabilistic tractography as implemented by FDT, look here. Briefly, FDT repetitively samples from the distributions on voxel-wise diffusion directions, each time computing a streamline through these local samples to generate a probabilistic streamline or a sample from the distribution on the location of the true streamline. By taking many such samples FDT is able to build up the posterior distribution on the streamline location or the connectivity distribution. The major difference with Probtrack is that the local samples have a more complex distribution. They can model different diffusion directions, allowing to track finer pathways and resolve crossing fibres in regions with complex fibre architecture.

After BedpostX has been applied it is possible to run tractography analyses using probtrackx.


Using probtrackx in command line

Probtrackx requires a set of mandatory arguments. The optional arguments allow further specifications.

 

Below is a command for probtrackx with all possible arguments. The bold faced arguments are mandatory. Click on each argument to have a precise description.

 

probtrackx       -s <basename>             -m <mask>      -x <seed>

--mode=<chosenMode>          

--opd   --pd=<n>

--os2t   --targetmasks=<filename>

--omatrix2       --lrmask=<filename>

-o <outputfile>

--mask2=<filename>

--waypoints=<filename>

--seedref=<filename>   --xfm=<transformation>

--dir=<directory>         --forcedir

--rubbish=<filename> 

--nsamples=<n> --cthr=<n> --steplength=<n> --loopcheck --usef --randfib --modeuler --rseed

--verbose --help

 

 

Below you can find a few typical command lines.

 

 

 

The output of probtrackx can be analysed further with:

 

 


Mandatory arguments

There are three compulsory arguments in probtrackx. Basically, the algorithm needs to know the local orientation distributions (output of bedpostX), the brain mask (in order not to draw pathways outside it) and a seed region for the probabilistic tractography.

 

·  -s <basename >

 

<basename> is the prefix of the file containing the orientation distribution given by bedpostX, which in general are of the form (in the case of two fibres per voxel):

 

merged_th1samples

merged_th2samples

merged_ph1samples

merged_ph2samples

merged_f1samples

merged_f2samples

 

If the path to the directory where these files are stored is <pathdir>, then the basename is <pathdir>_merged.

 

·  -m <mask>                                       

 

Binary brain mask that can be computed with bet. This mask MUST BE IN THE DIFFUSION SPACE (i.e. same as the diffusion data). Usually, it is computed from the nodif image, and is named nodif_brain_mask.

 

·  -x <seed>                                                                                   

 

Region of the brain which serves as a seed for the tractography.

When using the simple mode, <seed> is a textfile with the coordinates of the seed voxels stored as follows :

 

x_1      y_1      z_1

x_2      y_2      z_2

               

x_n      y_n      z_n

 

When using seedmask mode, <seed> is a 3D image with non-zero values inside the seed voxels.

 

In both cases (text file or image file), you can use either the diffusion space, or another space (e.g. structural, standard spaces), provided the –seedref and –xfm options.

 


Optional arguments

*** Choose your mode ***

 

·  --mode=<chosenMode>

 

You can run probtrackx in two different modes:

 

simple                          : In case the seed is a textfile with voxel coordinates.

seedmask (default)       : In case the seed is a 3D image file.

 

The voxel coordinates as well as the seedmask can be in a different space than the diffusion space (e.g. high resolution structural space or standard space), provided the transformation that goes from this space to the diffusion space (see the options --seedref and --xfm).

 

*** Choose your outputs ***

 

·  --opd

 

This option allows to output the pathway distribution in <outputfile>.

 

·  --pd=<n>

 

<n> is either 1 (default value) or 2.

 

n=1      : the pathway distribution is the total number of pathways that cross each voxel of the brain mask.

n=2      : the pathway distribution is the mean length of the pathways that cross each voxel (to correct for the effect of the distance to the seed mask).

 

·   --os2t

 

This option allows to output the probability that each individual voxel in the seed mask is connected to each of the target masks (provided a target mask list).

The output are of the form:

 

seed_to_target1

seed_to_target2

seed_to_targetn

 

Each of these files is a volume with non-zero values only within the seed mask.

The value in each voxel of seed_to_target1 within the seed mask is the number of tracts seeded from this voxel that arrived at target1.

Running find_the_biggest on these outputs gives a segmentation of the seed mask into parts connected to the different targets.

 

·   --targetmasks=<filename>

 

<filename> is either a 3D file with one target mask, or a text file containing a list of target masks (with the full path) as following:

 

<full_path_dir>/target1

<full_path_dir>/target2

<full_path_dir>/targetn

 

·   ---omatrix2

 

This option allows to ouput a filename, called fdt_matrix2, which is a NxP matrix, where N is the number of voxels in the seed mask, and P is the number of voxels in the rest of the brain mask.

The values stored in this matrix represent the probability that each voxel in the seed mask is connected with each voxel of the rest of the brain. This value depends on the choice of the option --pd.

This matrix is useful for seed classification based on connectivity profile with the spectral reordering tool : ccops.

For computational and storage reasons, we recommend to use a low resolution brain mask, (e.g. 5x5x5 mm^3).

 

·   --lrmask=<filename>

 

<filename> is a low resolution brain mask used along with the --omatrix2 option

To create a low resolution mask, take a whole brain mask (e.g. using bet), of the same image as the one on which the seeds have been drawn, and subsample it with the command:

 

flirt –i seed_brain_mask –ref seed_brain_mask –applyisoxfm 5 –o lowresmask

 

avwmaths lowresmask –thr 0.5 –bin lowresmask

 

 

·   -o <outputfile>

 

This is the pathway probability distribution. By default, this file is called fdt_paths.

The pathway distribution is in the same space as the seed mask.

 

·   --mask2=<filename>

 

Add this option if you want to draw all the pathways that go from the seed mask to a second region (drawn in mask2), and all the pathways that go from this second region to the seed region.

 

mask2 must be in the same space as the seed mask.

 

·   --waypoints=<filename>

 

Add this option if you want to track only the pathways that happen to cross a (or a set of) region(s) in the brain.

<filename> is either a 3D file with a region mask, or a text file with a list of 3D region masks along with their full path as follows:

 

<full_path_dir>/waypoints_1

<full_path_dir>/waypoints_2

<full_path_dir>/waypoints_n

 

The waypoint masks must all be in the same space as the seed mask

 

*** For registration ***

 

When the seed mask is not in the diffusion space (i.e. ROIs were drawn on the structural image, or in the standard space, coming from FMRI group activation or some template), you must provide probtrackx with a reference image and a transformation.

 

·   --seedref=<filename>

 

<filename> is the name of an image in the same space as the seed mask.

 

For example, struct_brain (if the seed space is the structural space), or standard (if the seed space is the standard space).

 

·   ---xfm=<transformation>

 

<transformation> is a text file containing the transformation matrix (as computed by flirt) from the seed space to the diffusion space.

 

For example :

 

str2diff.mat if the seed space is the structural image.

std2diff.mat if the seed space is the standard space.

 

*** Miscellaneous arguments ***

 

·   --verbose=<n>

 

<n> varies from 0 (very few ouput comments) to 2 (a lot of comments) during the execution of probtrackx.

 

·   --help

 

This prints out the help message providing a short description of the different options.

 

·   --dir=<directory>

 

Name of the directory which will contain all the outputs (fdt_paths, fdt_matrix2, seed_to_targets etc.)

 

·   --forcedir

 

Overwrites the ouput directory if there is already one having the same name. By default, probtrackx will add “+” to an already existing one.

 

·   --rubbish=<filename>

 

Use this option if you want to exclude from the pathway distribution all those pathways that go into a given region. <filename> is a 3D mask of this region. This option is somehow opposite to waypoints. Note that if a pathway goes into this region, only the part that is inside the region will be removed, the rest of the pathway is kept as a part of the distribution.

 

 

*** Expert mode parameters ***

 

·   --nsamples=<n>

 

Number of sample pathways drawn per voxel of the seed mask. The default value is 5000.

 

·   --cthr=<n>

 

Threshold value for the cosine of the angle between two successive steps during the tractography. The default value is 0.2 (corresponding to an angle of 78 degrees).

 

·   --nsteps=<n>

 

Maximum number of steps (default=2000). Using a step length of 0.5mm, this corresponds to a distance of 1m.

 

·   --steplength=<n>

 

Length of each step during the tractography. The default value is 0.5 voxels (of the seed space).  You may want to change this value depending on the voxel size, or if the tractography is performed on different sized brain (e.g. infants or animals).

 

·   --loopcheck

 

This option removes the tracts that make a loop, which can happen as the tractography is probabilistic. It slows down a bit the computations.

 

·   --usef

 

Use this option if you want the fractional anisotropic volumes (stored in merged_fsamples) to influence the tractography. The tracts stop if the anisotropy is lower than a random variable between 0 (low anisotropy) and 1 (high anisotropy).

 

·   --randfib

 

Select randomly the different fibre directions when starting the tractography at one seed voxel. By default, the tractography start from the leading direction (the one with highest fractional volume inside the seed voxel).

 

 

·   --modeuler

 

Use modified Euler integration instead of standard Euler. This is more accurate, but slightly slower.

 

·   --rseed

 

Random variable generator. By default, the value of this variable is fixed, which means that when repeating an experiment with the same data, one gets EXACTELY the same results.

 


Command line examples

·      I want to see all the tracts that go from my seed  to the rest of the brain

 

A typical command when one wants to draw all the pathways (in terms of probability distribution) that run from the seed mask is:

 

probtrackx –s <subject>.bedpostX/merged –m <subject>.bedpostX/nodif_brain_mask –x seed_mask --opd --pd=1 --dir=<subject>.probtrackx

 

Below is the result with a seed in the internal capsule.

 

·      I want to see only the tracts that go from an ROI to another (set of) ROIs

 

Sometimes, one is only interested in the pathways that connect one region to one or several others. For example, one can have the internal capsule as a seed mask, and ask for the pathways that go to M1 in the hand area and the face area, as well as to the cerebral peduncle. Here is a typical command using the waypoints option:

 

probtrackx –s <subject>.bedpostX/merged –m <subject>.bedpostX/nodif_brain_mask –x seed_mask --waypoints=<listOfWaypoints> --opd --pd=1 --dir=<subject>.probtrackx

 

Below is the result. Note that the resulting pathways are a subgroup of the pathways drawn in the first example, which include only those that reach the waypoints.

 

·      I want to use the high resolution structural image (or the standard space image) to draw my ROIs

 

Sometime, one needs to draw the seed mask in a high resolution image (for example, to finely delineate some structure), or on a standard space image (e.g. to use group activations as a common seed mask for a group of subjects). Here is a typical command using the structural as a seed space.

 

Note that the resulting pathways are also in the seed space, but all the computations are done in the diffusion space.

 

probtrackx –s <subject>.bedpostX/merged –m <subject>.bedpostX/nodif_brain_mask –x seed_mask --seedref=struct --xfm=<subject>.bedpostX/xfms/str2diff.mat --opd --pd=1 --dir=<subject>.probtrackx

 

·      I want to segment an ROI depending on its connections with another set of ROIs

 

One can use probtrackx to know which part of the seed mask is more probably connected to each target region within a list. For example, which part of the internal capsule is connected to the hand area, and which part is connected to the face area ?

A typical command for doing that is:

 

 

probtrackx –s <subject>.bedpostX/merged –m <subject>.bedpostX/nodif_brain_mask –x seed_mask  --os2t --targetmasks=<listOfTargets> --dir=<subject>.probtrackx

 

 

·      I want to segment an ROI into different parts having different connections with the rest of the brain

 

As for the SMA/preSMA study, one can ask whether the seed region is composed of two ore more parts having different connections with the rest of the brain, i.e. participating in different structural networks. Probtrackx allows one to output a matrix composed of the values of the connections between each voxel in the seed mask with the rest of the brain (taken at a low resolution for computational reason).

Once this matrix calculated, one can une a spectral reordering command (ccops) to see whether there are two or more clusters within the seed mask. Here is a typical command:

 

probtrackx –s <subject>.bedpostX/merged –m <subject>.bedpostX/nodif_brain_mask –s seed_mask  --omatrix2 --dir=<subject>.probtrackx --lrmask=lowres_mask