Documentation/Nightly/Modules/UKFTractography

Introduction and Acknowledgements

This work is part of the National Alliance for Medical Image Computing (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NA-MIC can be obtained from the NA-MIC website. Author: Yogesh Rathi, Ph.D, Psychiatry Neuroimaging Laboratory, Brigham & Women's Hospital Contact: Ryan Eckbo, <email>reckbo@bwh.harvard.edu</email>

Isomics, Inc. <- Replace this logo with yours   Surgical Planning Laboratory (SPL) <-Replace this logo with yours

Module Description

We present a framework which uses an unscented Kalman filter for performing tractography. At each point on the fiber the most consistent direction is found as a mixture of previous estimates and of the local model.

It is very easy to expand the framework and to implement new fiber representations for it. Currently it is possible to tract fibers using two different 1-, 2-, or 3-tensor methods. Both methods use a mixture of Gaussian tensors. One limits the diffusion ellipsoids to a cylindrical shape (the second and third eigenvalue are assumed to be identical) and the other one uses a full tensor representation.

Authors: Yogesh Rathi (yogesh@bwh.harvard.edu), Stefan Lienhard, Yinpeng Li, Martin Styner, Ipek Oguz, Yundi Shi, Christian Baumgartner (c.f.baumgartner@gmail.com), Ryan Eckbo

Use Cases

• 1-Tensor tractography
• 1-Tensor tractography with free water
• 2-Tensor tractography
• 2-Tensor tractography with free water

Tutorials

N/A

Panels and their use

Input/Output (IO)

--dwiFile <std::string> Input DWI Image

--seedsFile <std::string> Seeds for diffusion. If not specified, full brain tractography will be performed, and the algorithm will start from every voxel in the brain mask where the Generalized Anisotropy is bigger than 0.18

--labels <std::vector<int>> A vector of the ROI labels to be used (default: 1)

--maskFile <std::string> Mask for diffusion tractography

--tracts <std::string> Tracts generated, with first tensor output

--tractsWithSecondTensor <std::string> Tracts generated with second tensor output (if there is one)

Seeding Options

--seedsPerVoxel <int> Number of seeds per voxel (default: 1)

--seedFALimit<double> Seed points whose FA are below this value are excluded (default: 0.15)

Model Options

--numTensor <1|2|3> Number of tensors used (default: 2)

--fullTensorModel Whether to use the full tensor model. Which models all three eigenvalues seperately, as opposed to lambda2=lambda3.

--freeWater Adds a term for free water difusion to the model. If checked, the 1T simple model is forced.

Stopping Criteria

--minFA <double> Abort the tractography when the Fractional Anisotropy is less than this value (default: 0.15)

--minGA <double> Abort the tractography when the Generalized Anisotropy is less than this value (default: 0.1)

Fiber Scalar Fields

--recordFA Whether to store FA. Attaches field 'FA', and 'FA2' for 2-tensor case to fiber.

--recordNMSE Whether to store NMSE. Attaches field 'NMSE' to fiber.

--recordTrace Whether to store Trace. Attaches field 'Trace', and 'Trace2' for 2-tensor case to fiber.

--recordFreeWater Whether to store the fraction of free water. Attaches field 'FreeWater' to fiber.

--recordState Whether to attach the states to the fiber. Will generate field 'state'.

--recordCovariance Whether to store the covariance. Will generate field 'covariance' in fiber.

--recordTensors Recording the tensors enables Slicer to color the fiber bundles by FA, orientation, and so on. The fields will be called 'TensorN', where N is the tensor number.

Advanced Options

--numThreads <int> Number of threads used during compuation. Set to the number of cores on your workstation for optimal speed. If left undefined boost will figure out the number of cores, and hence threads, during runtime.

--normalizedDWIData Whether the DWI input data is already normalized

--weightsOnTensors <std::vector<double>> Weights on different tensors when using multiple tensors. There must be one weight for each tensor, and the weights must sum up to 1. Defaults to equally weighted.

--maxHalfFiberLength <double> The max length limit of the half fibers generated during tractography. Here the fiber is "half" because the tractography goes in only one direction from one seed point at a time (default: 10000)

--Qm <double> Process noise for angles/direction (Will be set during runtime to the optimal value for the chosen model, unless overriden by user).

--Ql <double> Process noise for eigenvalues (Will be set during runtime to the optimal value for the chosen model, unless overriden by user).

--Qw <double> Process noise for free water weights, ignored if no free water estimation (Will be set during runtime to the optimal value for the chosen model, unless overriden by user).

--Rs <double> Measurement noise (Will be set during runtime to the optimal value for the chosen model, unless overriden by user).

--stepLength <double> Step length i.e. size of the step taken in the most consistent direction during each iteration of tractography given in millimeters (Will be set during runtime to the optimal value for the chosen model, unless overriden by user).

--maxBranchingAngle <double> Maximum branching angle, in degrees. When using multiple tensors, a new branch will be created when the tensors' major directions form an angle between (minBranchingAngle, maxBranchingAngle). Branching is supressed when this maxBranchingAngle is set to 0.0

--minBranchingAngle <double> Minimum branching angle, in degrees. When using multiple tensors, a new branch will be created when the tensors' major directions form an angle between (minBranchingAngle, maxBranchingAngle)

Additional Output Options

--noTransformPosition Don't transform Points back from ijk->RAS when writing the output fiber

--branchesOnly Only output branches, ignore the primary tracts

--storeGlyphs Store tensors' main directions as two-point lines in a separate file named glyphs_{tracts}. When using multiple tensors, only the major tensors' main directions are stored

--outputNormalizedDWIData Whether to output the DWI after normalization (i.e. preprocessing)

Tractography unrelated options

--returnparameterfile <std::string> Filename in which to write simple return parameters (int, float, int-vector, etc.) as opposed to bulk return parameters (image, geometry, transform, measurement, table).

--processinformationaddress <std::string> Address of a structure to store process information (progress, abort, etc.). (default: 0)

--xml Produce xml description of command line arguments.

--echo Echo the command line arguments.

--, --ignore_rest Ignores the rest of the labeled arguments following this flag.

--version Displays version information and exits.

-h, --help Displays usage information and exits.

Similar Modules

N/A

References

Reference for 2-tensor tractography:

• http://pnl.bwh.harvard.edu/pub/papers_html/MalcolmIEEETransMed10.html

Reference for 1-tensor and 2-tensor + free-water:

• C. Baumgartner, O. Michailovich, O. Pasternak, S. Bouix, J. Levitt, ME Shenton, C-F Westin, Y. Rathi,

"A unified tractography framework for comparing diffusion models on clinical scans": in Workshop on computational diffusion MRI, 2012.