Interoperability Tools in DTI-TK
Overview
There are many excellent DTI tools including AFNI, CAMINO, DTI Studio, FSL to name a few, that provide important functions in most users' existing DTI analysis pipeline, such as tensor reconstruction. However, none of these programs currently output their DTI volumes in a common data format. An important contribution of DTI-TK is in providing necessary tools for users to
- convert the DTI volumes output from these popular packages into an open standard -- the NIfTI tensor format
- convert the NIfTI tensor format back to the DTI volumes in the native formats of these packages.
This makes it possible for users that have existing pipelines using any of these popular packages to take advantage of DTI-TK. Here, we describe the details of the tools that enable DTI-TK to work seamlessly with other DTI packages.
WARNING!!!: When converting to/from another DTI program, one additional step to check is the physical unit of diffusivity. Please refer to the page dedicated to this topic. Be aware that these programs may change their formats unannounced. To be confident in the correctness of the conversion, it is highly advisable to visually inspect one subject in your dataset using the tensor glyph tool (for more information visit the visualization section).
Interoperability with CAMINO
Some programs can output individual tensor component images, and CAMINO offers this option. In this case, these component images, if stored in analyze or NIfTI format and appropriately named, can be converted to NifTI tensor format. The component images should be named as ${prefix}{xx, yx, yy, zx, zy, zz}.hdr (lower triangular) or ${prefix}{xx, xy, xz, yy, yz, zz}.hdr (upper triangular). The following command will combine these images into a single NIfTI tensor image, for lower triangular named files:
ImageToTensorVolume ${prefix} hdr tensor.nii.gz
or for upper triangular named files:
ImageToTensorVolume ${prefix} hdr tensor.nii.gz 1
For example, if the tensor component images are Dxx.hdr, Dyx.hdr, Dyy.hdr, Dzx.hdr, Dzy.hdr Dzz.hdr, then the command would be
ImageToTensorVolume D hdr tensor.nii.gz
NEXT: Check the diffusivity units and visualize your DTs.
Interoperability with FSL
DTI-TK is an official FSL plugin. It implements a two-way interoperability support that enables the existing FSL users to continue to enjoy the powerful tract-based spatial statistic (TBSS) framework while taking advantage of the state-of-the-art tensor-based DTI registration provided by DTI-TK.
FSL is one of the programs that represent DTI volumes in terms of the corresponding eigensystem, i.e., the eigenvalues and the eigenvectors. We've developed tools that convert from and to such format. However, be aware that storing tensors in terms of their eigensystem doubles the storage footprint when compared to the format used in DTI-TK.
To convert the FSL format to the DTI-TK format, use TVFromEigenSystem, e.g.
TVFromEigenSystem -basename tensor -type FSL
The input eigenvalue and eigenvector volumes are expected to use the FSL naming convention. The example above works for the files named as tensor_L{1,2,3}.nii.gz and tensor_V{1,2,3}.nii.gz. If your files are xyz_L{1,2,3}.nii.gz and xyz_V{1,2,3}.nii.gz, the basename will be xyz instead.
By default, you do not need to provide an output file name. The program will create the appropriate file name from the basename. In our example, the output will be tensor.nii.gz. However, if you prefer to provide your own output file name, you can choose to do so. In this case, the command should read
TVFromEigenSystem -basename tensor -type FSL -out preferredfilename.nii.gz
In practice, we recommend the users to use fsl_to_dtitk, a script that takes a FSL-generated DTI eigensystem volumes (non-brain tissue already removed) and converts them into fully DTI-TK compatible DTI volumes, i.e., both in the correct format and correctly preprocessed.
Using the above example, the command should read
To convert back to the FSL format, use TVEigenSystem, e.g.
TVEigenSystem -in tensor.nii.gz -type FSL
The output from this program will be tensor_L{1,2,3}.nii.gz, the eigenvalues, and tensor_V{1,2,3}.nii.gz, the eigenvectors, following precisely the FSL naming convention.
WARNING: FSL also has an option that allows for a DTI volume to be saved on disk in matrix form similar to but NOT the same as the NIfTI tensor format. It stores the six independent matrix components using the "upper triangular" order rather than the "lower triangular" order specified in NIfTI standard! (See Section about CAMINO above for definition of upper and lower triangular) So DO NOT use this option if you want to use its output with DTI-TK!
Interoperability with AFNI
In AFNI, the program for creating DTI volumes from Diffusion-Weighted MR images, 3dDWItoDT, can output the DTI volume both in the NIfTI and multivolume Analyze format. The outputs in both cases are fully compatible with DTI-TK.
NEXT: Check the diffusivity units and visualize your DTs.
Interoperability with DTI Studio
This popular DTI tool pioneered the fiber tractography known as FACT. For tractography, DTI Studio takes two inputs: a FA image in the ani format and the corresponding principal diffusion direction image in the vec format. Here we describe the program in DTI-TK, TVToDTIStudio, that supports the conversion of the NIfTI tensor format to the inputs required for tractography in DTI Studio. It takes a NIfTI tensor image as input and output the corresponding ani and vec files.
TVToDTIStudio -in tensor.nii.gz
The outputs are simply tensor.ani, the FA map, and tensor.vec, the principal diffusion direction map. The volume information, including dimension and FOV, can be determined by the command VolumeInfo.
Volume Info of tensor.nii.gz
size: 112x112x60, voxel size: 2x2x2, origin: [0, 0, 0]
In this case, the image width is the x dimension, 112, the image height is the y dimension, 112, and the number of slices is 60. The Field-of-View is then 224x224 (x dimension multiplies x voxel size and y dimension multiplies y voxel size), and the thickness is 2, the z voxel size.
NEXT: Check the diffusivity units and visualize your DTs.
This excellent tractography visualization and selection/segmentation tools supports the two formats used in DTI-TK.
