fsl_streamlines

What is fsl_streamlines?

FSL implements probabilistic tractography (see probtrackx2 and its wrapper tool xtract). While this approach allows the quantification of uncertainty in the streamlining process, the resulting spatial histograms (e.g. fdt_paths in probtrackx2) are not easy to visualise, and are certainly not as aesthetically pleasing as what you would get from deterministic streamlining (e.g. figure below).

The fsl_streamlines tool can be used to generate streamline tractograms from probtrackx2/xtract outputs. It does so by running deterministic streamlining through a vector field saved by probtrackx2. This vector field represents the average orientation visited in each voxel. The streamlines are saved alongside their associated probabilities so that they can be thresholded during visualisation in FSLeyes.

Info

fsl_streamlines will be included in the next version of FSL (6.0.7.19).

Prior to running fsl_streamlines

The fsl_streamlines tool requires probtrackx2 to be run with the --opathdir option, which generates a fdt_paths_localdir.nii.gz file containing per-voxel average tract orientation:

probtrackx2 --opathdir <remaining arguments>

If you are running xtract, you can pass on this option to probtrackx2 using a text file:

echo "--opathdir" > options.txt
xtract -ptx_options options.txt <remaining arguments>

Running fsl_streamlines

There are three ways in which you can run fsl_streamlines:

• Using probtrackx2 output: the main input is one or more probtrackx2 output folder(s). The fdt_paths and fdt_paths_localdir files are automatically detected.
• Using xtract output : the input is one or more xtract folder(s).
• Using a "vector" file : you can run streamlining directly on one or more 4D vector files (e.g. dti_V1 from dtifit)

The main output of fsl_streamline is one or more streamline files in .trk or .vtk formats. These files contain the coordinates of the vertices of each streamline, alongside vertex-wise scalar information (e.g. streamline probability from probtrackx2).

Viewing the streamlines in FSLeyes

To view the streamlines files in FSLeyes, see the documentation page on Tractograms and on how to view them in 3D.

Usage

Typing fsl_streamlines --help gives the usage:

usage: fsl-streamlines [-h] [-o OUTPUT_PREFIX] [-f {trk,vtk}] [-p PTX2_PREFIX] [-t DENSITY_THRESHOLD] [-min MIN_STEPS]
                       [-max MAX_STEPS] [-s STEP] [-j] [-spv SEEDS_PER_VOXEL] [-ss SUBSAMPLE] [-nj NUM_JOBS]
                       [-i {nn,trilinear,spline}] [--no-density] [-so [SAVE_OVERLAY ...]] [-rs SEED] [-v]
                       input [input ...]

positional arguments:
  input                 XTRACT or PROBTRACKX tract directory/directories, or orientation file

options:
  -h, --help            show this help message and exit
  -o OUTPUT_PREFIX, --output-prefix OUTPUT_PREFIX
                        Output file prefix (default: streamlines)
  -f {trk,vtk}, --output-format {trk,vtk}
                        Output format - one of trk (default) or vtk
  -p PTX2_PREFIX, --ptx2-prefix PTX2_PREFIX
                        File prefix for PROBTRACKX inputs (default: fdt_paths)
  -t DENSITY_THRESHOLD, --density-threshold DENSITY_THRESHOLD
                        Threshold for streamline density (default: 1e-3). If density image is not provided, all voxels within
                        the tract are used as seeds (but --subsample is still applied).
  -min MIN_STEPS, --min-steps MIN_STEPS
                        Minimum number of steps in a streamline (default: no minimum)
  -max MAX_STEPS, --max-steps MAX_STEPS
                        Maximum number of steps in a streamline (default: 300)
  -s STEP, --step STEP  Step size relative to voxel size (default: 0.4)
  -j, --jitter          Randomize seed position within voxel
  -spv SEEDS_PER_VOXEL, --seeds-per-voxel SEEDS_PER_VOXEL
                        If --jitter specified, number of random seeds to use per voxel (default: 1)
  -ss SUBSAMPLE, --subsample SUBSAMPLE
                        Subsample seed voxels, e.g. if 10 consider only every 10th seed voxel (default: 1)
  -nj NUM_JOBS, --num-jobs NUM_JOBS
                        Number of processes to use to parallelise streamlining (default: 1)
  -i {nn,trilinear,spline}, --interp {nn,trilinear,spline}
                        Interpolation method for density values (default: nn)
  --no-density          Do not colour streamlines by density
  -so [SAVE_OVERLAY ...], --save-overlay [SAVE_OVERLAY ...]
                        With --output-format=vtk, also save following volumes in compatible .vti format
  -rs SEED, --seed SEED
                        Seed for random number generator (default: random seed)
  -v, --version         show program's version number and exit