DRTAMAS is a tensor based registration software released under the TORTOISE processing package.This module of processing is mainly used to perform tensor based registration or template creation, using diffusion tensors (DTs) created with the TORTOISE processing pipeline. While running any of these commands from the bin folder, it is advised that you copy all the DTs that will be used in the registration, the text file to be used, and any reference template, into a separate folder. This keeps the template creation or any DRTAMAS generated results separate from rest of the data processing.
This page will focus on the main commands that are used in the template creation and registration of tensors. Other commands, than the ones mentioned here, are used internally as part of these main commands.
15.1. DTIREG
DTIREG command should be used if you want to register one diffusion tensor to another.
15.2. DTI CREATE TEMPLATE
DTICreateTemplate command performs the template creation, from the list of (DTs) provided in the text file. The syntax to run the command is as follows:
If you would like to create a group template from the all the diffusion tensors in your study or specific group, this command will generate the average tensor. The final average tensor that comes out of this process is named as average_template_diffeo_6.nii In the process, the tensors that were used in the creation of this template, will also be warped to the final template and will be in the same folder with the subject name.diffeo.nii
It is important therefore to make sure the individual images have unique names, before you begin processing.
Note: The quality of the template is as good as the input images provided. So, please make sure the prior steps listed in this documentation have been performed.
15.3. DTI batch register to target
When using this command, please copy the text file to be used and the target DT into a separate folder.
EXAMPLES:
1) Creation of a population template
Requirements: tortoise generated DT files, a text file containing the full path of all DT files that will go in the creation of the template i.e DT.txt
We will create a specific folder, called population template. This folder mainly contains the DT.txt file and will contain all the resulting outputs from template creation. If for example, you want to create a template out of three subjects, with three DT.nii files i.e subj1_DT.nii, subj2_DT.nii, subj3_DT.nii, then the DT.txt file will have contents as follows:
/folder1/subj1_DT.nii
/folder2/subj2_DT.nii
/folder3/subj3_DT.nii
*Note: please make sure you save the text file in a folder where you would like the output of template creation to be generated. In this case it will be in the folder 'population_template'.
dtireg_create_template command will be run as follows:
dtireg_create_template -s= ~/population_template/DT.txt -n=1 -c=1 -r=1
In this example command, we are using one CPU with n=1, constraining the deformation c=1, and the resulting output resolution of the final template will be 1mm, r=1. You may also provide an initial rigid template and/or the final output folder.
15.4. outputs of create template or DTIREG
Here is an example folder of outputs generated for dti_create template. This folder consists of the .txt file with the original DTs “control_list.txt”.
The command runs by first picking the rigid template “rigid_template_0.nii”, representative of the group. Then the command runs to iteratively output affine files and the diffeo files. The final template DT is the “average_template_diffeo_6.nii”. As you can also see, there are additional files output for each DT file that went into the creation of the template.
Aff.txt= is the text file comprising of the affine transformation applied to each DT file to morph into the final template that is generated. aff.nii = the native files warped to the template space, after the application of the aff.txt file. diffeo.nii = the native DT transformed to the final template space. Note: final template here is the average_template_diffeo_6.nii that is generated as a result of template creation.
With DIFFCALC now migrated completed to command line, scalar quantities such as FA, Trace etc can be derived from the final average template DT file created or the warped *diffeo.nii file corresponding to each DT file in the folder. The syntax to derive these scalar quantities in DIFFCALC will be the same as using DT.nii file except in this case either *diffeo.nii or average_template_diffeo_6.nii will be provided.
2) Registering subjects in a population to a pre-existing template or template created from dtireg_create_template
If you have a template (ex: control or population) TORTOISE average tensor, you can batch register your individual subject tensors to the average using the command:
dtireg_batch_register_to_target
This command takes a list of individual DT's and registers them to the target DT provided. The requirements for this task are:
a) a text file with list of full path to subject DT's. The organization of the text file you provide to create the template.
b) a template DT file to which you want all the subjects registered
*pro tip: highly recommend creating a separate folder and copying the template DT file and the saving the text file with the list of DT's, that you want to register to the template. In this case the new folder that we will create will be: individual_registration_to_template
With (a) and (b) you can run the command as follows:
dtireg_batch_register_to_target -t=/individual_registration_to_template/average_template_DT.nii -s=/individual_registration_to_template/DT.txt -n=1 -z=1
15.5. Combine Transformations
* The steps noted under this sections mainly applies to generating combined deformation files from the outputs generated for dtireg_create_template.
** Please note: The dtireg_batch_register_to_target will output combined transformations (a.k.a _aff_diffeo_MINV.nii) files and you will not need to do the steps explained below.
Here you will combine the files ending in “aff.txt” (scalar transformation) and “deffield_MINV.nii” (higher order transformation) to create the combined transformation. The transformation file gives information of deformation field generated, from warping the individual DT to the final template space. Please remember that diffeo.nii file output is the warped native DT into the final average template space.
You have three types of combine transformations command, each with same type of output but provisions for customizing the naming convention and image parameters.
If you use combineTransformations: The output file will be a generic name, with combineddeformation.nii as the output. If you have multiple subjects in a directly, these will be overwritten. This command can only be used if you have one set of deformation fields you want to combine in a folder.
If you have multiple subjects and correspoding transformations to be combined, please use CombineTransformationsWithOputputName command. This will give you flexibility to name the output file with specific subject names.
If you would like to output the transformations files with the imaging parameters similar to a reference DT, please use the command: CombineTransformationsWithReferenceImage. This will ensure the origin information from the reference image is translated to the transformation file being created.
15.6. Apply transformations to scalar
The transformation file created in the combined transformation for each subject, can be applied to the native, non warped scalar map from the corresponding subject to bring it into the final template space. This is especially useful if you like to warp each subject’s anatomical map into the final template space.
15.7. Apply transformations to tensor
The transformation file created in the combined transformation for each subject, can be applied to the native, non warped tensor map from the corresponding subject to bring it into the final template space. This maybe advantageous in scenarios where you have created an alternate tensor map such as with dual compartment fitting in TORTOISE and would like to warp those tensors into final template space.
15.8. Apply transformations to 4d image
You may apply the transformations to any 4d image file to bring it into final template space.
Note: Please cite the following paper if you use this tool: DR-TAMAS: Diffeomorphic Registration for Tensor Accurate Alignment of Anatomical Structures, M. Okan Irfanoglu, Amritha Nayak, Jeffrey Jenkins,Elizabeth B.Hutchinson,Neda Sadeghi,Cibu P.Thomas,Carlo Pierpaoli,NeuroImage,Volume 132, 15 May 2016, Pages 439-454