Difference between revisions of "Documentation/Nightly/Modules/UKFTractography"
Line 8:  Line 8:  
{{documentation/{{documentation/version}}/moduleintroductionstart{{documentation/modulename}}}}  {{documentation/{{documentation/version}}/moduleintroductionstart{{documentation/modulename}}}}  
{{documentation/{{documentation/version}}/moduleintroductionrow}}  {{documentation/{{documentation/version}}/moduleintroductionrow}}  
+  
+  {{documentation/{{documentation/version}}/moduleacknowledgements}}  
+  
This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NAMIC can be obtained from the [http://www.namic.org/ NAMIC website].<br>  This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NAMIC can be obtained from the [http://www.namic.org/ NAMIC website].<br>  
Author: Yogesh Rathi, Ph.D, Psychiatry Neuroimaging Laboratory, Brigham & Women's Hospital<br>  Author: Yogesh Rathi, Ph.D, Psychiatry Neuroimaging Laboratory, Brigham & Women's Hospital<br> 
Revision as of 17:47, 5 August 2016
Home < Documentation < Nightly < Modules < UKFTractography
For the stable Slicer documentation, visit the 4.10 page. 
Introduction and Acknowledgements
Contact: Ryan Eckbo, <email>reckbo@bwh.harvard.edu</email>  

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 3tensor 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, Lauren O'Donnell, Jessica Lee
Use Cases
 1Tensor tractography
 1Tensor tractography with free water
 2Tensor tractography
 2Tensor tractography with free water
 Neurite orientation dispersion and density imaging (NODDI)
Tutorials
 UKF Tractography tutorial: https://www.slicer.org/slicerWiki/index.php/Documentation/4.5/Training#UKF
Panels and their use
Input/Output (IO)
dwiFile <std::string> Input diffusion weighted (DWI) volume
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. These are the voxel values where tractography should be seeded. (default: 1)
maskFile <std::string> Brain mask for diffusion tractography. Tracking will only be performed inside this mask.
tracts <std::string> Output fiber tracts generated with one tensor.
Tractography Options
seedsPerVoxel <int> Tractography parameter used in all models: number of seeds per voxel. Each seed generates a fiber, thus using more seeds generates more fibers. In general use 1 or 2 seeds, and for a more thorough result use 5 or 10 (depending on your machine this may take up to 2 days to run). Default: 1. Range: 050. (default: 1)
seedFALimit<double> Tractography parameter used in all models. Seed points whose fractional anisotropy (FA) are below this value are excluded. Default: 0.18. Range: 01.
minFA <double> Tractography parameter used in tensor model. Tractography will stop when the fractional anisotropy (FA) of the tensor being tracked is less than this value. Note: make sure to also decrease the GA to track through lower anisotropy areas. This parameter is used only in tensor models. Default: 0.15. Range: 01.
minGA <double> Tractography parameter used in all models. Tractography will stop when the generalized anisotropy (GA) is less than this value. GA is a normalized variance of the input signals (so it does not depend on any model). Note: to extend tracking through low anisotropy areas, this parameter is often more effective than the minFA. This parameter is used by both tensor and NODDI models. Default: 0.1. Range: 01.
numThreads <int> Tractography parameter used in all models. Number of threads used during computation. Set to the number of cores on your workstation for optimal speed. If left undefined, the number of cores detected will be used.
numTensor <123> Number of tensors (tensor model) or orientations (NODDI model) used. (default: 2)
stepLength <double> Tractography parameter used in all models. Step size when conducting tractography (in mm). Default: 0.3. Range: 0.11.
Qm <double> Rate of change of tensor direction/orientation. UKF data fitting parameter for tensor or NODDI model: Process noise for angles/direction. Defaults: Noddi0.001; Single tensor0.005; other0.001. Suggested Range: 0.00001  0.25. Default of 0.0 indicates the program will assign value based on other model parameters.
recordLength <double> Tractography parameter used in all models. Step size between points saved along fibers. Default: 0.9. Range: 0.14.
maxHalfFiberLength <double> Tractography parameter used in all models. The max length limit of the half fibers generated during tractography. A fiber is "half" when the tractography goes in only one direction from one seed point at a time. Default: 250 mm. Range: 1500 mm.
recordNMSE Record output from data fitting: Store normalized mean square error (NMSE) along fibers.
Tensor Model
freeWater Adds a term for free water diffusion to the model. The free water model is a tensor with all 3 eigenvalues equal to the diffusivity of free water (0.003). To output the free water fraction, make sure to use the "save free water" parameter.
recordFA Record output from tensor model: Save fractional anisotropy (FA) of the tensor(s). Attaches field 'FA' or 'FA1' and 'FA2' for 2tensor case to fiber.
recordTrace Record output from tensor model: Save the trace of the tensor(s). Attaches field 'Trace' or 'Trace1' and 'Trace2' for 2tensor case to fiber.
recordFreeWater Record output from tensor plus free water model: Save the fraction of free water. Attaches field 'FreeWater' to fiber.
recordTensors Record output from tensor model: Save the tensors that were computed during tractography (if using tensor model). The fields will be called 'TensorN', where N is the tensor number. Recording the tensors enables Slicer to color the fiber bundles by FA, orientation, and so on. Recording the tensors also enables quantitative analyses.
Ql <double> UKF data fitting parameter for tensor model: rate of change of eigenvalues. Defaults: 1 tensor300 ; 2 tensor50 ; 3 tensor100. Suggested Range: 11000. Default of 0.0 indicates the program will assign value based on other model parameters.
Qw <double> UKF data fitting parameter for tensor plus free water model: Process noise for free water weights, ignored if no free water estimation. Defaults: 1 tensor0.0025; 2 tensor0.0015. Suggested Range: 0.000010.25. Default of 0.0 indicates the program will assign value based on other model parameters.
NODDI Model:
noddi Use neurite orientation dispersion and density imaging (NODDI) model instead of tensor model.
recordVic Save NODDI volume fraction of intracellular compartment along fibers.
recordKappa Save NODDI concentration parameter that measures the extent of orientation dispersion.
recordViso Save NODDI volume traction of CSF compartment along fibers.
Qkappa <double> UKF data fitting parameter for NODDI model: Rate of change of kappa value. Higher kappa values indicate more fiber dispersion. Default: 0.01.
Qvic <double> UKF data fitting parameter for NODDI model: Rate of change of volume fraction of intracellular component. Default: 0.004
Signal Parameters (Expert Only)
Rs <double> Expected noise in signal. This is used by the UKF method to decide how much to trust the data. This should be increased for very noisy data or reduced for high quality data. Defaults: single tensor/orientation0.01; other0.02. Suggested Range: 0.0010.25. Default of 0.0 indicates the program will assign value based on other model parameters.
Debug/Develop Only
sigmaSignal <double> igma for Gaussian kernel used to interpolate the signal at subvoxel locations. Default: 0.0
recordState Store the states along the fiber. Will generate field 'state'. The state is the model for UKF. In the case of the two tensor model, it is a tenparameter vector.
recordCovariance Store the covariance matrix along the fiber. Will generate field 'covariance' in fiber. This is the covariance from the unscented Kalman filter.
fullTensorModel Use the full tensor model instead of the default model. The default model has both smaller eigenvalues equal, whereas the full model allows 3 different eigenvalues.
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. Default: 0.0. Range: 090.
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). Default: 0. Range: 090.
tractsWithSecondTensor <double> Tracts generated, with second tensor output (if there is one)
storeGlyphs Store tensors' main directions as twopoint lines in a separate file named glyphs_{tracts}. When using multiple tensors, only the major tensors' main directions are stored
Tractography Command Line Options
returnparameterfile <std::string> Filename in which to write simple return parameters (int, float, intvector, 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 2tensor tractography:
Reference for 1tensor and 2tensor + freewater:
 C. Baumgartner, O. Michailovich, O. Pasternak, S. Bouix, J. Levitt, ME Shenton, CF Westin, Y. Rathi,
"A unified tractography framework for comparing diffusion models on clinical scans": in Workshop on computational diffusion MRI, 2012.
Information for Developers
Section under construction. 