[FSL] [TitleIndex] [WordIndex] 

Contents

  1. Introduction
  2. User Guide

    Contents

    1. Processing pipeline
    2. Eddy Current Correction
    3. Registration within FDT
    4. DTIFIT
    5. BEDPOSTX
    6. PROBTRACKX - probabilistic tracking with crossing fibres
      1. Overview
      2. Seed specification
        1. Single voxel
        2. Single mask
        3. Multiple masks
      3. Including targets for tractography - rationale
        1. Waypoint masks
        2. Exclusion mask
        3. Termination mask
        4. Classification targets
      4. Options Tab
    7. Using surfaces
      1. Switching conventions
      2. Projecting data onto the surface
      3. Using FreeSurfer surfaces
        1. FreeSurfer Registration
        2. Label files
    8. Utilities
      1. proj_thresh
      2. find_the_biggest
      3. vecreg - Registration of vector images
      4. qboot - Estimation of fibre orientations using q-ball ODFs and residual bootstrap
    9. Fslview
      1. Displaying DWI images in fslview
  3. FAQ

Processing pipeline

To call the FDT GUI, either run Fdt (Fdt_gui on a Mac), or run fsl and press the FDT button.

A typical processing pipeline (and approximate time required for each stage, based on an Intel 2.66GHz processor, and a 60-direction whole brain dataset of dimensions 128x128x70, at 2 mm isotropic resolution) would consist of:

  1. Any study or scanner-specific pre-processing (e.g., conversion from DICOM to NIFTI, removal of images affected by large artifacts). This would be done manually by the user.
  2. Eddy current correction using FDT (around half a minute per volume).

  3. Brain extraction using BET.

  4. dtifit - Fitting of diffusion tensors on corrected data using dtifit within FDT to check data quality (~1 minute)
  5. bedpostx - Fitting of the probabilistic diffusion model on corrected data (~15 hours, or less if parallelised)
  6. registration - (3-6 minutes)
  7. probtrackx - Probabilistic tractography run on the output of bedpostx (execution time depends very much on what the user wishes to do. Generating a connectivity distribution from a single voxel of interest takes about 1 second)

  8. Further post-processing of probtrackx outputs can be carried out if required using the command-line utilities

Eddy Current Correction

Eddy currents in the gradient coils induce (approximate) stretches and shears in the diffusion weighted images. These distortions are different for different gradient directions. Eddy Current Correction corrects for these distortions, and for simple head motion, using affine registration to a reference volume.

In the FDT GUI, use the top left drop down menu to select Eddy current correction.

Command line utility 

 eddy_correct <4dinput> <4doutput> <reference_no>

Registration within FDT

If tractography results are to be stored in any space other than diffusion space then registration must be run.

Registration within FDT uses FLIRT, but there is also an option for using FNIRT nonlinear registration to standard space. When using the GUI, registration can only be applied after bedpostx has been run. Typically, registration will be run between three spaces:

Note that the structural (T1-weighted) image must have had BET applied. The nodif_brain image should be the brain extracted version of the nodif image that is stored in the bedpostX directory. Create this image using fslroi then bet on the data if it does not already exist. (it is important that the user checks the quality of bet results on these images and adjust the settings in bet where appropriate).

Transformation matrices, and their inverses, will be derived from diffusion to structural space and from structural to standard space. Relevant matrices will be concatenated to produce transformation matrices between diffusion and standard space. The resulting matrices are stored within the xfms subdirectory of the bedpostX directory and named as follows:

By default, transformation matrices between diffusion and structural space are derived using 6 degrees of freedom, the correlation ratio cost function and normal search; transformation matrices between structural and standard space are derived using 12 degrees of freedom, the correlation ratio cost function and normal search. These parameters may be adjusted if required using the drop down menus in the registration panel.

In the GUI, it is possible to use nonlinear FNIRT registration between structural and standard space. In this case, the user needs to provide a non-brain-extracted structural image, as this will make FNIRT more accurate.

Note that diffusion images will typically have geometric distortions due to the effect of field inhomogeneities that are not affecting the structural image. Therefore, an affine FLIRT registration to structural space may not be accurate enough. We recommend that the user corrects for these distortions either using fieldmap acquisitions or using the TOPUP tool. This must be done in the pre-processing and prior to registration.

DTIFIT

DTIFIT fits a diffusion tensor model at each voxel. You would typically run dtifit on data that has been pre-processed and eddy current corrected. Note that dtifit is not necessary in order to use the probabilistic tractography (which depends on the output of BEDPOSTX, not DTIFIT).

In the FDT GUI, use the top left drop down menu to select DTIFIT.

Input: You can specify an input directory containing all the required files with standardized filenames, or alternatively you can specify input files manually by turning on the specify input files manually switch. If an input directory is specified then all files must be named as shown in parentheses below. If input files are specified manually they can have any filename. Required files are:

The format is

x_1 x_2 x_3 ... x_n
y_1 y_2 y_3 ... y_n
z_1 z_2 z_3 ... z_n

Vectors are normalised to unit length within the dtifit code. For volumes in which there was no diffusion weighting, the entry should still be present, although the direction of the vector does not matter!

The format is

b_1 b_2 b_3 ... b_n

Advanced options In addition to the required input above, the user can choose to apply a weighted least-squares regression instead of the default standard linear regression. The user can also choose to save the tensor elements and/or the sum of squared error. This last output can be useful for detecting artefacts.

Outputs of dtifit

optional output

fdt_lines_subs.gif

fdt_rgb_subs.gif

fdt_l1.gif

fdt_fa.gif

V1 Lines

V1 RGB

L1

FA

command line utility 

dtifit

Compulsory arguments (You MUST set one or more of):
        -k,--data       dti data file
        -o,--out        Output basename
        -m,--mask       Bet binary mask file
        -r,--bvecs      b vectors file
        -b,--bvals      b values file

Optional arguments (You may optionally specify one or more of):
        -V,--verbose    switch on diagnostic messages
        -h,--help       display this message
        --cni           Input confound regressors
        --sse           Output sum of squared errors
        -w,--wls        Fit the tensor with weighted least squares
        --littlebit     Only process small area of brain
        --save_tensor   Save the elements of the tensor
        -z,--zmin       min z
        -Z,--zmax       max z
        -y,--ymin       min y
        -Y,--ymax       max y
        -x,--xmin       min x
        -X,--xmax       max x

BEDPOSTX

fdt_bedpostx2.gif BEDPOSTX stands for Bayesian Estimation of Diffusion Parameters Obtained using Sampling Techniques. The X stands for modelling Crossing Fibres. bedpostx runs Markov Chain Monte Carlo sampling to build up distributions on diffusion parameters at each voxel. It creates all the files necessary for running probabilistic tractography. For an overview of the modelling carried out within bedpostx see this technical report.

bedpostx allows to model crossing fibres within each voxel of the brain. Crucially, bedpostx allows to automatically determine the number of crossing fibres per voxel. For details on the model used in this case, see Behrens et al, NeuroImage 2007.

bedpostx takes about 15 hours to run but will automatically batch if run on an SGE-capable system.

Note that bedpostx is a wrapper script for a command-line tool called xfibres.

In the FDT GUI, use the top left drop down menu to select BEDPOSTX.

Input directory: Use the browse button to select an input directory. That directory must contain the following files:

The format is

x_1 x_2 x_3 ... x_n
y_1 y_2 y_3 ... y_n
z_1 z_2 z_3 ... z_n

Vectors are normalised to unit length within the bedpostx code. For volumes in which there was no diffusion weighting, the entry should still be present, although the direction of the vector does not matter!

The format is

b_1 b_2 b_3 ... b_n

The order of bvals must match the order of data.

Tip: Run bedpostx_datacheck in command line to check if your input directory contains the correct files required for bedpostx.

Outputs of BEDPOSTX

bedpostx creates a new directory at the same level as the input directory called <indir>.bedpostX which contains all the files you need for probabilistic tractography. Highlights are (<i> indicates the i-th fibre. It ranges from 1 to the maximum number of fibres set in the advanced options.):

Advanced Options

You may change some options before running bedpostx, depending on the questions you want to ask or the quality of your diffusion data. The default values of these parameters are the ones used in the corresponding paper (Behrens et al, NeuroImage 2007).

Additionally, the following alternative models are available in the advanced options:

Command line utility 

Usage: bedpostx <subject directory> [options]

 expects to find bvals and bvecs in subject directory
 expects to find data and nodif_brain_mask in subject directory

 options (old syntax)

  -n (number of fibres per voxel, default 2)
  -w (ARD weight, more weight means less secondary fibres per voxel, default 1)
  -b (burnin period, default 1000)
  -j (number of jumps, default 1250)
  -s (sample every, default 25)
  -model (1 for monoexponential, 2 for multiexponential, default 1)

 ALTERNATIVELY: you can pass on xfibres options directly to bedpostx
  For example:  bedpostx <subject directory> --noard --cnonlinear
  Type 'xfibres --help' for a list of available options 
  Default options will be bedpostx default (see above), and not xfibres default.

 Note: Use EITHER old OR new syntax.

PROBTRACKX - probabilistic tracking with crossing fibres

For details about probabilistic tractography as implemented in FDT, see this technical report, and for details about crossing fibre modelling in FDT, see Behrens et al, NeuroImage 2007.

After bedpostx has been applied it is possible to run tractography analyses using probtrackx. Briefly, probtrackx repetitively samples from the distributions of voxel-wise principal 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 histogram of the posterior distribution on the streamline location or the connectivity distribution.

The following explains how to run probtrackx using the GUI. The command-line options (which are slightly more flexible than the GUI) can be obtained from a terminal window by running: 

probtrackx2 --help

Note that the GUI only runs the new version (probtrackx2). Users of the old version (probtrackx) can only run it from the command line.

PROBTRACKX GUI has two main sections:

Seed Space

Optional Targets

PROBTRACKX requires the specification of a bedpostX directory. This directory must contain all the following images:

As explained below, results from probtrackx can be binned in any available space -e.g., diffusion space, structural space or standard space. Note, however, that tractography itself ALWAYS takes place in diffusion space - it is simply the results of probtrackx that are stored in the required space. If probtrackx results are to be stored in a space other than diffusion space then you will need transformations from this space back into the space of the diffusion data.

You can use the FDT registration tab to create the required transformations, which will all be stored in the xfms subdirectory of the bedpostX directory. Probtrackx can take either linear (FLIRT) or nonlinear (FNIRT) transformations. In the latter case, both forward (diffusion to seed space) and backward (seed space to diffusion) transformations are needed.

For example, for analyses in structural space:

Overview

PROBTRACKX involves generating connectivity distributions from user-specified seed voxels or surface vertices (or both). The output will be a single image in the space of the specified seed like this. All brain voxels will have a value (though many of these will be zero) representing the connectivity value between that voxel and the seed voxel (i.e., the number of samples that pass through that voxel). Note that when connectivity distributions are generated from multiple seed points within a region of interest then the time required for the analysis to run will be approximately the number of seed points multiplied by the time taken to generate a distribution from a single point. probtrackx also allows to specify targets for the tractography. These can either be inclusion/exclusion masks, or targets for seed classification based on connectivity.

Seed specification

A common feature for all seed specification modes is the ability to provide the seed in another space than the diffusion space. If seed space is not diffusion, then check the corresponding button. Set the transformation matrix from seed space to diffusion space (or both forward and backward warpfields if using nonlinear registration). Note that, in all cases, the smaller the voxel size in your seed space image, the lower the resulting connectivity values will be to these voxels (This is intuitive - the smaller a voxel is, the less chance that the true streamline will pass through it). This highlights the problem with binning a continuous distribution into meaningless discrete bins. In order for the probability values to be truly meaningful, the discrete bins chosen should be anatomically meaningful, as is the case when using classification targets.

Seed can be specified either as a Single Voxel, a Single mask, or Multiple masks (see below for more details). When using masks, these can either be volume files or surface files (see below for supported surface formats). Check the surface button if one or all of the masks are surfaces. When using surfaces, the user must set the surface coordinate convention and provide a surface reference volume.

Streamlines are seeded from all non-zero voxels of the seed files, or all vertices of the surface files. In the case where the surface files contain numerical values associated with vertices, tractography is seeded from all non-zero vertices, unless all the numerical values are zero, in which case the whole surface is considered as an ROI.

Single voxel

Generates a connectivity distribution from a single, user-specified voxel.

GUI Options:

Seed reference image Use the browse button to locate a reference image (e.g., subject1.bedpostX/struct.nii.gz if seed space is structral space).

Seeds: Enter the x,y,z co-ordinates of a single seed voxel. Use the buttons to the right to specify whether the coordinates are given in voxels or millimetres.

Single mask

Generates a connectivity distribution from a user-specified region of interest.

GUI Options: Seed image/surface: Use the browse button to locate the seed image/surface. Probabilistic tractography will be run from every point (voxel or vertex) with a value different than 0 in this mask. If a surface is used as an input, and if all vertices have zero scalar value, then all vertices of the surface will be seeded.

The output directory will contain:

Multiple masks

Generates a connectivity distribution between a group of seed masks. This option repeatedly samples tracts from every seed mask in a list, and retains only those tracts that pass through at least one of the other seed masks. The output is the sum of the connectivity distributions from each of the seed masks.

GUI Options:

Masks list: Use the add button to locate each seed mask. Seed masks should all be in the same space (e.g., diffusion, structural or standard space). Seed masks can be either image volumes or surfaces or both. When all masks are loaded you can press the save list button to save the list of masks as a text file. If you already have a text file list of required seed masks (including their path) then you can load it with the load list button.

The output directory will contain:

Including targets for tractography - rationale

probtrackx allows you to include target masks for any tractography experiment. These masks can be image volumes and/or surfaces. When using surfaces, these should all be using the same convention (i.e. FreeSurfer/Caret/FIRST/voxel - see below).

Very Important: Every target mask must be in the same space as the seed masks (or the reference image in the case of a single voxel mode).

Targets can be waypoint masks (a.k.a. inclusion masks), for selecting only tracts passing through particular points in the brain; exclusion masks, for excluding tracts passing through parts of the brain; termination masks, for forcing tracts to stop whenever they reach a certain area; or classification target masks for connectivity-based seed classification. All these targets are optional.

Waypoint masks

Use inclusion masks in the tractography. If more than one mask is set, then by default probtrackx will perform an AND operation. I.e. tracts that do not pass through ALL these masks will be discarded from the calculation of the connectivity distribution. You can set this to an OR using the Waypoint option drop down menu under the Options tab. In this case, streamlines are only retained if they intersect at least one of the waypoint masks.

Use the add and remove buttons to make a list of waypoint masks.

Exclusion mask

If an exclusion mask is to be used then check the box and use the browse button to locate the mask file. Pathways will be discarded if they enter the exclusion mask. For example, an exclusion mask of the midline will remove pathways that cross into the other hemisphere.

Termination mask

If a termination mask is to be used then check the box and use the browse button to locate the mask file. Pathways will be terminated as soon as they enter the termination mask. The difference between an exclusion and a termination mask is that in the latter case, the tract is stopped at the target mask, but included in the calculation of the connectivity distribution, while in the former case, the tract is completely discarded. (Note that paths are always terminated when they reach the brain surface as defined by nodif_brain_mask)

Classification targets

quantitative targets When using classification targets, probtrackx will quantify connectivity values between a seed mask and any number of user-specified target masks. This option is only active when the seed mask is a single mask. In the example on the right, seed voxels in the thalamus are classified according to the probability of connection to different cortical target masks.

Use the add button to locate each target mask. Targets must be in the same space as the seed mask. When all targets are loaded you can press the save list button to save the list of targets as a text file. If you already have a text file list of required targets (including their path) then you can load it with the load list button. The output directory will contain a single volume for each target mask, named seeds_to_{target} where {target} is replaced by the file name of the relevant target mask. In these output images, the value of each voxel within the seed mask is the number of samples seeded from that voxel reaching the relevant target mask. The value of all voxels outside the seed mask will be zero. Note that the files seeds_to_{target} will have the same format (either volumes or surfaces) as the seed mask.

quantitative targets

There are command line utilities that can be run on these outputs:

Options Tab

Before running probtrackx, the user is able to change the setting of certain parameters by clicking the options tab.

Basic Options:

Advanced options:

Waypoint options (only used if waypoint masks are set in the main tab):

Matrix Options The following set of options can be used to store a connectivity matrix between (1) all seed points and all other seed points, or (2) all seed points and all points in a target mask, or (3) all pairs of points in a target mask (or a pair of target masks). All masks used here MUST BE IN SEED SPACE. These options can be used separately or in conjunction.

Matrix1 and Matrix2 store the number of samples (potentially modulated by distance when distance correction is used) between the rows (seed points) and the columns of the matrix.

Matrix3 stores the number of sample streamlines (potentially modulated by distance when distance correction is used) between each pair of points in a pair of target masks. In this case, when a streamline is sent from each seed point in both directions, if the streamline hits the two target masks at two locations along either sides of the streamline, the corresponding row and column of matrix3 is filled.

Note on the ouput format: matrix1,2,3 are stored as 3 column ASCII coding of sparse matrices. These files can be loaded into matlab using e.g.: 

    x=load('fdt_matrix1.dot');
    M=spconvert(x);

MatrixOptions.png

Summary of Matrix Options output

Typical uses of Matrix options:

Example use of Matrix2 for clustering:

A typical use of Matrix2 is blind (i.e. hypothesis-free) classification. Say you have run probtrackx with a seed roi (e.g. thalamus) and the --omatrix2 option by setting the Matrix2 target mask to a whole brain mask (typically this mask would be lower resolution than the seed mask). The resulting Matrix2 can be used in Matlab to perform 'kmeans' classification. Below is an example Matlab code to do this (this example is only valid if the seed mask is a NIFTI volume, not a surface): 

   % Load Matrix2
   x=load('fdt_matrix2.dot');
   M=full(spconvert(x));
   % Calculate cross-correlation 
   CC  = 1+corrcoef(M');
   % Do kmeans with k clusters
   idx = kmeans(CC,k);   % k is the number of clusters
   % Load coordinate information to save results
   addpath([getenv('FSLDIR') '/etc/matlab']);
   [mask,~,scales] = read_avw('fdt_paths');
   mask = 0*mask;
   coord = load('coords_for_fdt_matrix2')+1;
   ind   = sub2ind(size(mask),coord(:,1),coord(:,2),coord(:,3));
   [~,~,j] = unique(idx);
   mask(ind) = j;
   save_avw(mask,'clusters','i',scales);
   !fslcpgeom fdt_paths clusters

Using surfaces

It is possible to use surface files in probtrackx. The preferred format is GIFTI.

Surface files typically describe vertex coordinates in mm. Annoyingly, different softwares use different conventions to transform mm to voxel coordinates. Probtrackx can deal with the following conventions: FreeSurfer, Caret, FIRST and voxel. The latter convention simply means that mm and voxel coordinates are the same.

Switching conventions

When using surfaces in probtrackx, all surfaces MUST use the same convention. However, we provide a command-line tool (surf2surf) to transform between different conventions. This tool can also be used to convert between different surface file formats. 

surf2surf - conversions between surface formats and/or conventions

Usage: 
Usage: surf2surf -i <inputSurface> -o <outputSurface> [options]

Compulsory arguments (You MUST set one or more of):
        -i,--surfin     input surface
        -o,--surfout    output surface

Optional arguments (You may optionally specify one or more of):
        --convin        input convention [default=caret] - only used if output convention is different
        --convout       output convention [default=same as input]
        --volin         input ref volume - Must set this if changing conventions
        --volout        output ref volume [default=same as input]
        --xfm           in-to-out ascii matrix or out-to-in warpfield [default=identity]
        --outputtype    output type: ASCII, VTK, GIFTI_ASCII, GIFTI_BIN, GIFTI_BIN_GZ (default)

Projecting data onto the surface

It is often useful to project 3D data onto the cortical surface. We provide the following command-line tool (surf_proj) to do exactly that: 

Usage: surf_proj [options]

Compulsory arguments (You MUST set one or more of):
        --data  data to project onto surface
        --surf  surface file
        --out   output file

Optional arguments (You may optionally specify one or more of):
        --meshref       surface volume ref (default=same as data)
        --xfm   data2surf transform (default=Identity)
        --meshspace     meshspace (default='caret')
        --step  average over step (mm - default=1)
        --direction     if>0 goes towards brain (default=0 ie both directions)
        --operation     what to do with values: 'mean' (default), 'max', 'median', 'last'
        --surfout       output surface file, not ascii matrix (valid only for scalars)

Using FreeSurfer surfaces

Using FreeSurfer with probtrackx requires a few specific steps that we describe below:

FreeSurfer Registration

FreeSurfer operates in a conformed space, which is different from the original structural image space that it has received as an input. When tracking from FreeSurfer surfaces, it is necessary to provide a transformation between conformed space and diffusion space. Below are a few steps that show how to achieve this.

We assume that you have ran dtifit on your diffusion data with an FA map called dti_FA.nii.gz (we recommend using an FA map to register to T1 structural images), and also that you have a file called struct.nii.gz that you have used as an input to FreeSurfer recon_all program.

We will carry on a few steps that aim at calculating the following transformations: fa<->struct<->freesurfer. Then we will concatenate these transformations to get fa<->freesurfer.

Let us start with struct<->freesufer (assuming john is the subject's name): 

tkregister2 --mov $SUBJECTS_DIR/john/mri/orig.mgz --targ $SUBJECTS_DIR/john/mri/rawavg.mgz --regheader --reg junk --fslregout freesurfer2struct.mat --noedit 
convert_xfm -omat struct2freesurfer.mat -inverse freesurfer2struct.mat

Now transforming FA to struct: 

flirt -in dti_FA -ref struct_brain -omat fa2struct.mat 
convert_xfm -omat struct2fa.mat -inverse fa2struct.mat

The final stage is to concatenate these transformations: 

convert_xfm -omat fa2freesurfer.mat -concat struct2freesurfer.mat fa2struct.mat 
convert_xfm -omat freesurfer2fa.mat -inverse fa2freesurfer.mat

Label files

Label files from FreeSurfer are useful as cortical ROIs for tractography. In order to use a label file (or collection of labels) in probtrackx, you must first transform it (them) into a surface file, using the label2surf command.

For instance, say you want to create a surface ROI for Brodmann areas 44 and 45. You must first decide which surface to use (pial, white) and which hemisphere (lh or rh). Say you want BA44/45 on the lh.white surface, then you must first transform the relevant surface file into an FSL-compatible format (ASCII or VTK or GIFTI), then use label2surf to transform the label files into a surface file. Below, the first command is a FreeSurfer command: 

mris_convert lh.white lh.white.gii
echo lh.BA44.label lh.BA45.label > listOfAreas.txt
label2surf -s lh.white.gii -o lh.BA44.gii -l listOfAreas.txt

The full set of arguments for label2surf is shown below: 

label2surf 
         Transforms a group of labels into a surface

Usage: 
label2surf -s <surface> -o <outputsurface> -l <labels>

Compulsory arguments (You MUST set one or more of):
        -s,--surf       input surface
        -o,--out        output surface
        -l,--labels     ascii list of label files

Optional arguments (You may optionally specify one or more of):
        -v,--verbose    switch on diagnostic messages
        -h,--help       display this message

Utilities

proj_thresh

proj_thresh is a command line utility that provides an alternative way of expressing connection probability in connectivity-based segmentation. It is run on the output of probtrackx when classification targets are used.

The output of Connectivity-based seed classification is a single volume for each target mask, named seeds_to_{target} where {target} is replaced by the file name of the relevant target mask. In these output images, the value of each voxel within the seed mask is the number of samples seeded from that voxel reaching the target mask. proj_thresh is run as follows: 

proj_thresh <list of volumes/surfaces> threshold

Where the list of volumes is the outputs of Connectivity-based seed classification (i.e., files named seeds_to_target1 etc etc) and threshold is expressed as a number of samples For each voxel in the seeds mask that has a value above threshold for at least one target mask, proj_thresh calculates the number of samples reaching each target mask as a proportion of the total number of samples reaching any target mask. The output of proj_thresh is a single volume for each target mask.

find_the_biggest

find_the_biggest is a command line utility that performs hard segmentation of a seed region on the basis of outputs of probtrackx when classification targets are being used.

The output of Connectivity-based seed classification is a single volume for each target mask, named seeds_to_{target} where {target} is replaced by the file name of the relevant target mask. In these output images, the value of each voxel within the seed mask is the number of samples seeded from that voxel reaching the target mask. find_the_biggest classifies seed voxels according to the target mask with which they show the highest probability of connection. It is run as follows: 

find_the_biggest <list of volumes/surfaces> <output>

Where the list of volumes is the outputs of Connectivity-based seed classification (i.e., files named seeds_to_target1 etc etc).

The example below uses probtrackx and find_the_biggest to perform hard segmentation of the thalamus on the basis of its connections to cortex.

quantitative targets

vecreg - Registration of vector images

vector registration After running dtifit or bedpostx, it is often useful to register vector data to another space. For example, one might want to represent V1 for different subjects in standard space. vecreg is a command line tool that allows to perform such registration.

Vector images cannot be registered by simply applying a transformation (as calculated by, say, FLIRT) to every voxel's coordinates. The corresponding vectors have to be reoriented accordingly (see D. Alexander 2001, IEEE-TMI 20:1131-39). vecreg performs this operation for you. The image on the right shows the effect of applying vecreg (right) to the V1 image on the left, compared to simply applying voxelwise transformation (e.g. using applyxfm4D) to the vectors (centre).

Important: vecreg does not calculate a transformation, but simply applies a given transformation to the input vector field. vecreg can apply a linear transformation calculated with FLIRT, or a non-linear transformation calculated by FNIRT.

types of input that may be used for vecreg from DTIFIT: V1,V2,V3,tensor from BEDPOSTX: dyads1, dyads2, etc.

Command line options 

vecreg -i <input4D> -o <output4D> -r <refvol> [-t <transform>]


Compulsory arguments (You MUST set one or more of):
        -i,--input      filename for input vector or tensor field
        -o,--output     filename for output registered vector or tensor field
        -r,--ref        filename for reference (target) volume

Optional arguments (You may optionally specify one or more of):
        -v,--verbose    switch on diagnostic messages
        -h,--help       display this message
        -t,--affine     filename for affine transformation matrix
        -w,--warpfield  filename for 4D warp field for nonlinear registration
        --rotmat        filename for secondary affine matrix 
                        if set, this will be used for the rotation of the vector/tensor field 
        --rotwarp       filename for secondary warp field 
                        if set, this will be used for the rotation of the vector/tensor field 
        --interp        interpolation method : nearestneighbour, trilinear (default), sinc or spline
        -m,--mask       brain mask in input space
        --refmask       brain mask in output space (useful for speed up of nonlinear reg)

qboot - Estimation of fibre orientations using q-ball ODFs and residual bootstrap

qboot

qboot is a command line tool that allows estimation of diffusion ODFs and fibre orientations from them. Its output can be used as an input for probtrackX in order to perform probabilistic tractography.

ODF estimation is performed using a real spherical harmonics basis. Fibre orientations are estimated as the local maxima of the ODFs. Both deterministic and probabilistic estimation can be performed. For the latter, residual bootstrap is performed to infer on the ODF shape and obtain a distribution of fibre orientations. For more details on the implementation see Sotiropoulos2011 (S.N. Sotiropoulos, I. Aganj, S. Jbabdi, G. Sapiro, C. Lenglet and T.E. Behrens, "Inference on Constant Solid Angle Orientation Distribution Functions from Diffusion-Weighted MRI", p.609, Quebec, Canada, OHBM, 2011).

qboot allows reconstruction of q-ball ODFs (Tuch DS, MRM 2004), CSA ODFs (Aganj I et al, MRM, 2010) and variants of them, obtained via Laplacian sharpening and Laplace-Beltrami regularization (Descoteaux et al, MRM, 2007). Both spherical harmonic coefficients of the reconstructed ODFs and fibre orientation estimates may be returned as output. A real spherical harmonic basis is employed (Aganj I et al, MRM, 2010).

Input files for qboot : Similar to dtifit and bedpostx, qboot needs a 4D data file, a binary mask_file, a bvecs and a bvals file.

Command-line options 

qboot -k data_file -m nodif_brain_mask -r bvecs -b bvals

Compulsory arguments (You MUST set one or more of):
        -k,--data       Data file
        -m,--mask       Mask file
        -r,--bvecs      b vectors file
        -b,--bvals      b values file

Optional arguments (You may optionally specify one or more of):
        --ld,--logdir   Output directory (default is logdir)
        --forcedir      Use the actual directory name given - i.e. don't add + to make a new directory
        --q             File provided with multi-shell data. Indicates the number of directions for each shell
        --model         Which model to use. 1=Tuch's ODFs, 2=CSA ODFs (default), 3=multi-shell CSA ODFs
        --lmax          Maximum spherical harmonic order employed (must be even, default=4)
        --npeaks        Maximum number of ODF peaks to be detected (default 2)
        --thr           Minimum threshold for a local maxima to be considered an ODF peak.
                        Expressed as a fraction of the maximum ODF value (default 0.4)
        --ns,--nsamples Number of bootstrap samples (default is 50)
        --lambda        Laplace-Beltrami regularization parameter (default is 0)
        --delta         Signal attenuation regularization parameter for model=2 (default is 0.01)
        --alpha         Laplacian sharpening parameter for model=1 (default is 0, should be smaller than 1)
        --seed          Seed for pseudo-random number generator
        --gfa           Compute a generalised FA, using the mean ODF in each voxel
        --savecoeff     Save the ODF coefficients instead of the peaks. 
        --savemeancoeff Save the mean ODF coefficients across all samples
        -V,--verbose    Switch on diagnostic messages

Possible Outputs of qboot

Running qboot on a cluster

Similar to bedpostX qboot can be parallelised if run on an SGE-capable system. The qboot_parallel script can be employed for this purpose.

Multi-shell data assumptions

The current implementation of qboot can estimate multi-shell ODFs, assuming the following for the data:

It is assumed that all data from each shell are grouped together and shells are one after the other in data, bvecs and bvals. So, if for example 3 directions are available for 3 shells these should appear as: dir1_shell1, dir2_shell1, dir3_shell1, dir1_shell2,dir2_shell2, dir3_shell2, dir1_shell3,dir2_shell3, dir3_shell3.

Fslview

FDT vectors

Displaying DWI images in fslview

Outputs of bedpostx or dtifit can be conveniently displayed in fslview. If you open an image of diffusion vectors (e.g., dtifit_V1 output of dtifit or dyads<i> output of bedpostx) then it is possible to display these vectors using RGB coding (where the colours red,green and blue represent diffusion in the x,y,z axes respectively) or using lines where a line at each voxel represents the principle diffusion direction at that voxel.

It is also possible to display multiple lines per voxel. Each line will be displayed in a different colour. In the example above, the red lines represent the main fibre orientation, and the blue lines represent the secondary fibre orientations (thresholded at an f-value of 0.05), as calculated by bedpostx.

If you only want to visualise fibres within voxels where multiple fibres are supported (e.g. above a certain threshold for the corresponding mean_f<i>samples), then you first have to create a vector file where the voxels below a certain f-threshold are zeroed. You may use the two following command for that: 

maskdyads dyads<i> mean_f<i>samples 0.05

For more details see the relevant fslview tutorial.

CategoryFDT

2014-07-08 15:33