TORTOISE v130 Manual June 29 2012

1. Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
1.1 TORTOISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 DIFF_CALC Main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1.1 DIFF_CALC Software Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1.1.1 1. Introduction to DIFF_CALC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1.1.2 2. DIFF_CALC Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.1.1.3 3. Usage of DIFF_CALC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.2 DIFF_PREP Main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.1.2.1 DIFF_PREP pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
1.1.2.2 Software Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
1.1.2.2.1 1. Introduction to DIFF_PREP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
1.1.2.2.2 2. Software Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1.1.2.2.3 3. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
1.1.2.3 Transformation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
1.1.3 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
1.1.3.1 Change Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
1.1.4 Quick Start Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
1.1.4.1 data import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
1.1.4.2 diff_calc loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
1.1.4.3 image registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
1.1.4.3.1 diff_calc fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
1.1.4.4 running tortoise modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
1.1.4.5 system setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
1.1.5 Version Update Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
2. Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
2.1 var_gui . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Home
Welcome to the Pediatric Neuroimaging Diffusion Tensor MRI Center Website
In this website you will find information about our diffusion MRI software package TORTOISE, as well as the DTI activities related to The NIH MRI
Study of Normal Brain Development for which we serve as the diffusion processing center. More information about this study is available at
www.NIH-PediatricMRI.org
TORTOISE
Tolerably Obsessive Registration and Tensor Optimization Indolent Software Ensemble
The current release is TORTOISE V1.3.0, available on the download page
Click here for version update information.
To get started with TORTOISE: Quick Start Guide
*See note at bottom of the page
Why TORTOISE? Our software is not for rabbit type people; if you need to process diffusion data at the scanner console you do not want to use
our software.
Why obsessive? We have realized that DTI is a wonderful quantitative technique which is unfortunately susceptible to all sorts of artifacts and
confounds. We spent a lot of time trying to obtain reliable DTI measurements, which has made ourselves and our software a little obsessive. Why
indolent? Our emphasis has been on developing conceptually rigorous routines more than optimizing the speed and user-friendliness of the
software.
TORTOISE was presented at the ISMRM meeting in Stockholm, Sweden in 2010. Please reference the following abstract if you use
TORTOISE in your work.
C. Pierpaoli, L. Walker, M. O. Irfanoglu, A. Barnett, P. Basser, L-C. Chang, C. Koay, S. Pajevic, G. Rohde, J. Sarlls, and M. Wu, 2010,
TORTOISE: an integrated software package for processing of diffusion MRI data, ISMRM 18th annual meeting, Stockholm, Sweden,
#1597 (pdf)
The TORTOISE software package is for processing diffusion MRI data, and it contains two main modules, DIFF_PREP and DIFF_CALC.
DIFF_PREP - software for image resampling, motion, eddy current distortion and susceptibility induced EPI distortion corrections, and for
re-orientation of data to a common space
DIFF_CALC - software for tensor fitting, error analysis, color map visualization and ROI analysis
In addition, TORTOISE contains additional Utilities, such as a tool for the analysis of multi-center phantom data.
Some common questions and answers about our software packages are listed in the FAQ.
If you are interested in contributing to these wiki pages, please contact us in order to create an account for you.
*This picture is adapted from an image we downloaded from the web. We would like to give credit to the original author(s) who we have been
unable to identify. Please contact us at tortoisedti@gmail.com if you know the origins of this picture.
For internal NIH collaborators only
DIFF_CALC Main
If you use our software in your research, the algorithms listed below have been published elsewhere. Downloadable pdf copies of the articles are
available by clicking the download links. Please cite the appropriate references in your work. A general reference for TORTOISE is shown below.
1
DIFF_CALC is a software package for the estimation of the diffusion tensor in each voxel and for the computation of tensor-derived quantities.
Functions include:
Automated 2,14 and manual (ROI based) image noise estimation

Tensor computation approaches including weighted and unweighted linear, non-linear, 3 and robust fitting including RESTORE 5 and
informed RESTORE 14
Future support of dual compartment, 6 and Newton constrained fitting 7
Proper weighting in the tensor fitting to account for changes in the statistical properties of the image due to interpolation from image
registration 8,9
Goodness of fit analysis with display of the residuals of the fitting
Tensor derived quantities in analyze and nifti formats including Trace(D), eignevalues, eigenvectors, fractional anisotropy, relative
anisotropy, volume ratio, 10 lattice index, 11 directionally encoded color (DEC) maps, 12 Westin's measures, 13 skewness, 1 linefield
representation of principal eigenvector, etc.
ROI analysis including orthogonal viewer for 3D Volume of Interest (VOI) analysis
Export modules for diffusion weighted images and/or diffusion tensor to: FSL, Camino, TrackVis, Slicer, DTI-TK, NRRD, VTK, DTI Studio
For access to the Software Guide click here

For a list of the outputs of the tensor fitting click here
For frequently asked questions, please visit our FAQ
References
1. C. Pierpaoli, L. Walker, M. O. Irfanoglu, A. Barnett, P. Basser, L-C. Chang, C. Koay, S. Pajevic, G. Rohde, J. Sarlls, and M. Wu, 2010,
#1597 pdf
2. Koay CG, zarslan E and Basser PJ. A signal transformational framework for breaking the noise floor and its applications in MRI. J Magn
Reson 2009; 197: 108-119. pdf
3. Basser, P.J., Mattiello, J., and LeBihan, D. (1994) Estimation of the effective self-diffusion tensor from the NMR spin echo. J Magn Reson
B 103:247-254 pdf
4. Mangin JF, Poupon C, Clark C, Le Bihan D, Bloch I. (2002) Distortion correction and robust tensor estimation for MR diffusion imaging.
Med Image Anal. 6(3):191-8. abstract
5. Chang, L.C., Jones, D.K., and Pierpaoli, C. (2005) RESTORE: Robust estimation of tensors by outlier rejection. Magn Reson Med.
53:1088-1095 pdf
6. Kim, S., et al. (2005) Dependence on diffusion time of apparent diffusion tensor of ex vivo calf tongue and heart. 13th Annual ISMRM,
Miami Beach, Florida, USA #1285
7. Koay, C.G., Chang, L-C., Carew, J.D., Pierpaoli, C., and Basser, P.J. (2006) A unifying theoretical and algorithmic framework for least
squares methods of estimation in diffusion tensor imaging. J Magn Reson. 182:115-125 pdf
8. Rohde, G.K., Barnett, A.S., Basser, P.J., and Pierpaoli, C. (2005) Estimating intensity variance due to noise in registered images:
Applications to diffusion tensor MRI. Neuroimage 26:673-684 pdf
9. Irfanoglu, M. O., Walker, L., Machiraju, R., Pierpaoli, C. (2011). Accounting for changes in signal variance in diffusion weighted images
following interpolation for motion and distortion correction. ISMRM 19th Annual Meeting and Exhibition, Montreal, Canada.
10. Basser, P.J. and Pierpaoli, C. (1996) Microstructural and physiological features of tissues elucidated by quantitative-diffusion-tensor MRI.
J Magn Reson B. 111:209-219 pdf
11. Pierpaoli, C. and Basser, P.J. (1996) Toward a quantitative assessment of diffusion anisotropy. Magn Reson Med. 36:893-906 pdf
12. Pajevic, S. and Pierpaoli, C. (1999) Color schemes to represent the orientation of anisotropic tissues from diffusion tensor data:
12.
application to white matter fiber tract mapping in the human brain. Magn Reson Med. 42:526-540 pdf
13. Peled S, Gudbjartsson H, Westin CF, Kikinis R, Jolesz FA. (1998) Magnetic resonance imaging shows orientation and asymmetry of
white matter fiber tracts. Brain Res. 5;780(1):27-33 abstract
14. Chang, L.C., Walker, L., Pierpaoli, C., (2012) Informed RESTORE: A Method for Robust Estimation of Diffusion Tensor from Low
Redundancy Datasets in the Presence of Physiological Noise Artifacts. MRM. In Press
DIFF_CALC Software Guide

Collapse all
Expand all Collapse all
1. Introduction to DIFF_CALC
Welcome to the DIFF_CALC software guide. In this document, details about the properties and usage of the software will be described.
Diffusion Tensor Imaging (DTI) is a Magnetic Resonance Imaging (MRI) modality, which allows in-vivo extraction of brain neural pathways. DTI
requires a scan with at least 6 diffusion weighted volumes obtained with non-colinear diffusion gradient directions in addition to at least one
diffusion-free T2W image (b0 image).
The purpose of this software is to enable users to perform accurate tensor estimation, and create tensor derived metric maps. This software also
includes basic visualization tools, ROI utilities and the capability to export the tensor and/or raw data to other software packages.
The recommended procedure for DTI processing would be to first correct for eddy distortions, motion and susceptibility induced EPI ditortions
using DIFF_PREP, then to estimate your tensor with DIFF_CALC.
< Up >
1.1 Organization
This guide is organized as follows:
In the Introduction a brief overview of the software is given including system requirements and software installation.
In Software Overview we briefly describe the functionality of the software.
In Usage instructions on how to use the software are given.
< Up >
1.2 About
DIFF_CALC has been developed at the Section on Tissue Biophysics and Biomimetics (STBB), part of the Eunice Kennedy Shriver National
Institute of Child Health and Human Development (NICHD) at the National Institutes of Health (NIH) by the NIH Pediatric Neuroimaging Diffusion
Tensor MRI group.
Special thanks to the members and contributors to the software:
Dr. Peter Basser

Dr. Lin-Ching Chang
Michael Curry
David Hughes
Dr. M. Okan Irfanoglu
Dr. Cheng Guan Koay
Stuart McMurray
Dr. Sinisa Pajevic
Dr. Carlo Pierpaoli
Lindsay Walker
Please email Dr. Chang: changl at mail dot nih dot gov or Dr. Pierpaoli: cp1a at mail dot nih dot gov for any bug reports, questions or suggestions.
< Up >
1.3 Installation
In this section, the installation procedure for DIFF_CALC will be described.
This software requires either a full IDL license or can be run using the precompiled IDL virtual machine (VM) distributed with the TORTOISE
download.
< Up >
1.3.1 System Requirements
The software currently supports the Linux platform and intel based Mac systems. Windows support is expected in a future release.
Please note: all flavors of Linux 32 bit edition and Linux 64 bit edition should be supported. However, due to the vast number of flavors, we were
unable to test them all. If you run into any errors, please contact us, and let us know the error you received, as well as the linux edition and flavor
you are running. Parts of this code has been tested on CentOS 5.2, 5.3, 5.4 and 5.5, REHL 4, Ubuntu, Fedora 7, and Fedora 9.
Some errors have been reported using Mac OS X Lion. We are working to correct these problems.
< Up >
1.3.2 Software Installation
The installation of the software is very straightforward.
1. download and save the distribution tar file.

2. Untar the file to a convenient installation directory of your choosing.
3. The software is now ready to use! The installation directory contains the two modules, DIFF_PREP and DIFF_CALC, as well as a
folder for Utilities. DIFF_CALC is run from the diffcalc_main directory which you will find in /installation
directory/DIFF_CALC/diffcalc_main. Usage is described in detail in the Usage chapter.
4. OPTIONAL: download and install the IDL virtual machine. More details are provided here, and also at the itt website.
5. OPTIONAL: inside the DIFF_CALC directory is a folder named "DIFF_CALC_WORK". Copy this directory to the user's home directory.
This is used for storing settings files and for writing of temporary files. If this directory does not exist, it will be created the first time you
run DIFF_CALC.
6. OPTIONAL: inside DIFF_CALC_WORK, open configfile_simple.xml in a text editor and edit the settings according to your needs. The
software will run with the default settings; however it may be advantageous to optimize you configuration file. The configuration file is
described in more detail in the 3.1 Configuration File section.
< Up >
1.3.3 Running DIFF_CALC
We highly recommend the use of the IDL VM as it is platform independent, and should therefore encounter fewer problems than running with an
IDL license
Linux and Max OS X can either run the IDL VM from command line or from the IDL VM file selection menu.
With precompiled IDL Virtual Machine (VM)
navigate to the install directory/DIFF_CALC/diffcalc_main

type calcvm
Click anywhere in the IDL VM window to dismiss the splash screen and display the file selection menu
With IDL Virtual Machine (VM)
Note: we recommend using the above option with the precompiled IDL VM due to some errors reported by users. If you run into any errors using
the following run commands, please try the precompiled option.
Command Line Linux:
Enter the following command in a shell: idl -vm=<path><filename>.sav. For example:
idl -vm=/home/TORTOISE/DIFF_CALC/diffcalc_main/diffcalc.sav
Note that if you first navigate to the diffcalc_main directory, it is necessary only to type:
idl -vm=diffcalc.sav
Click anywhere in the IDL VM window to dismiss the splash screen and display the file selection menu.
Command Line Mac:
Enter the following command in a shell: idl -vm=<path><filename>.sav. For example:
idl -vm -32=/home/TORTOISE/DIFF_CALC/diffcalc_main/diffcalc.sav

Note that if you first navigate to the diffcalc_main directory, it is necessary only to type:
idl -vm -32=diffcalc.sav
File Selection Menu:
Enter the following command in a shell:
idl -vm {-32 if using Mac}
The IDL VM window is displayed
Locate and select the .sav file, and click Open
With Full IDL license (Linux or Mac OS X)
Go to the diffcalc_main directory inside the DIFF_CALC install directory in a shell

Type "idl" in the command prompt.
On the IDL command prompt type:
IDL> diffcalc
< Up >
1.3.4 IDL VM
OPTIONAL: How to Download and Install the IDL VM
The IDL Virtual Machine (VM) is designed to provide IDL users with a simple, no-cost method for distributing IDL applications. It runs on all IDL
supported platforms, and does not require a license to run. TORTOISE has a precompiled version of the IDL VM included in the download,
and it is not necessary to download and install the VM separately.
1. Visit the ITT website http://www.ittvis.com/

Click on the Downloads -> Product Dwonload
2. Select the IDL Virtual Machine option
3. ITT requires you to register for an account to download the virtual machine. Follow their instructions to create an account.
4. Log In with your ITT username and password. Download the appropriate version for your operating system. TORTOISE is compatible
with the most up to date version as of January 2012, version 8.1.
5. Follow the instruction provided by the installer to complete your installation of the IDL virtual machine.
DIFF_CALC is a stand-alone IDL application that can be run on any Linux or intel based Mac OS X computer containing the IDL VM or a licensed
copy of IDL.
When a .sav file is executed in the IDL VM the current working directory will be the directory that contains the .sav file
< Up >
2. DIFF_CALC Overview
Under Construction
< Up >
3. Usage of DIFF_CALC
DIFF_CALC is a software package for the estimation of the diffusion tensor and for the calculation of tensor derived quantities. It also has the
ability to perform region of interest (ROI) analysis, and to export data to a number of software packages.
The various functions of DIFF_CALC will be described in this section of the Software Guide.
< Up >
3.1 Configuration File

The first time you run DIFF_CALC, it will create a working directory with a default configuration file. This file tells the software where your initial
working directory is located, and where to write a log file.
There is also a sample configuration file provided with the software called configfile_simple.xml. You can download the sample xml file by right
clicking on the link and selecting save link as.
The configfile_simple.xml file contains the following lines:






<writelog>2</writelog>

<logname>~/DIFF_CALC_WORK/log.txt</logname>


<curdir>~</curdir>

<analyze_image_type>NIFTI</analyze_image_type>
More advanced settings can be set, and are described in the following section.
< Up >
3.1.1 Optimize Configfile

How to optimize your Configfile
The default configfile as shown in section 3.1 Configuration file contains only the minimum tags required for proper functioning of DIFF_CALC. Do
not remove any of the default tags, or the program may give you errors. However, there are a number of other tags that can be copied and pasted
into your configfile in order to set some default settings to suit your needs. Some extra descriptions for the tags which are not self-explanatory is
included below. Please copy and paste the tags and comments that you desire exactly as they appear below. Do not include the extra
descriptions, only the comments surrounded by .
Usage Options:
The default working directory is set as your home directory. However, if you have a location where your data is stored, you may wish to set your
curdir appropriately. See the example below:


<curdir>/home_directory/my_data_directory</curdir>
Tensor Fitting Options:
The default tensor fitting option is weighted linear fitting. The user can set their desired fitting algorithm with this tag:


<diff_par_a>1</diff_par_a>
To set robust fitting default options use the following. The software's default is non-robust.


<robust_par_a>0</robust_par_a>
A histogram of the residuals for each slice is displayed by default during the tensor fitting. Use this tag if you would like to turn off this histogram.
Note that the residuals can clearly show if there are any problems with your data, and so can be very helpful.

<residue_par_a>0</residue_par_a>
For the non-linear tensor fitting method, a cumulative histogram of the residuals is displayed by default. Use this if you do not want to display the
residuals. See the above discussions for reasons to display the histogram. In a few cases, with very very large data sets (256 x 256 x 150 x 120
directions for example) IDL may run out of memory. If this happens, set the value of this tag to 0.


<residual_stat_flag>1</residual_stat_flag>
This option will allow you to save the cumulative histogram. Please heed the warning included in the tag description. Having this tag set to 1 has
caused IDL to run out of memory, as it can be a very large array. The default for this tag is don't save.



<save_global_residual_array_flag>0</save_global_residual_array_flag>
Occasionally, DWI data can contain zero values. This is problematic for the tensor estimation. There are 3 ways that TORTOISE can handle this
situation using the following flag. If the user sets the flag to 1, then any voxel which contains a zero value in any of the DWI images will be
masked out, and no tensor fitting will be performed on that voxel location. If the user sets the flag to 0, then zero value voxels will be removed
from the tensor fitting, and the fit will be based on all remaining voxels. If the user sets the flag to 2 (this is the default option) then the zero point is
replaced using a median filter of the surrounding tissue. Warning: if the flag is set to 0, and there are a large number of 0 values in your DWI
dataset, then it is possible that too many points will be removed, and the tensor fitting will fail with an error message will report a "singular matrix".
If this happens, please change the flag to 1 or 2 so that zero value points will either be masked out or replaced by the median filtering.


<mask_zero_point>2</mask_zero_point>
Other Options:
When masking the data, one can choose either to use bet2 1 or a simple threshold. Default is to use bet2.


<mask_par_a=1>1</mask_par_a=1>
Saving Options:



<mask_save_data>1</mask_save_data>
References
1. S.M. Smith, Fast robust automated brain extraction, HBM 17(3):143-155, Nov. 2002 abstract
< Up >
3.2 Main Software GUI
We HIGHLY RECOMMEND that you re-start DIFF_CALC every time you want to load a new dataset. While every effort
has been made to zero variables when loading a new file, it is safer to quit and re-start to ensure that you do not run
into problems with the software.
Once DIFF_CALC has been installed, it is very simple to run, as described in the installation section of this guide. Simply navigate to the
diffcalc_main directory in your install directory, and start IDL from that location. Then, type diffcalc and the main GUI will start up (see picture
below), or alternatively, type calcvm for use with the precompiled IDL VM. Note that if you have multiple configuration files, then a window will pop
up asking you to select the appropriate configuration file. Once you have selected the file, the main GUI will appear.
Each button will be described in the following sections, starting with load listfile, and working down the right hand column, then continuing with
process tensor and continuing down the left hand column.
When you first start the software, there are only 3 buttons that are available.
load listfile - load raw or processed data via the listfile

quit
About TORTOISE - contains information about the software creators, and the license agreement
The first step is to load a dataset via the listfile. This will be described in the next section. Once data has been loaded, more buttons will become
available.
The larger buttons will execute the command you wish to run (for example: load listfile). Beside each large button is an Options button (labeled
opt) with a few options for each button. These will be described in detail in the following sections.
< Up >
3.2.01 Load Listfile
Load listfile is the first step in using DIFF_CALC. Data must be in listfile format in order to be read by our software. This can be accomplished
using the Import routines of DIFF_PREP.
When you click on Load listfile, it will give a dialogue, as shown in the figure:
The full path to the data can be typed in the text box at the top. Or, the user can navigate to the desired directory using the list on the left
(Directories). Select the appropriate list file from the list on the right (Files). Double click on the list file, or select it and hit "OK".
If the list file does not contain information about the image endianism, than the following dialogue will appear:
If you do not know the endianism of your images select "Statistical Test". If you do know, select either "Big Endian" or "Little Endian" as
appropriate. Then click Done.
If the data was loaded properly, the status report window will show a few message, ending with either "Loaded bmatrix" or "curdir=...". A few more
buttons will now be sensitized, as in the figure below.
< Up >
3.2.02 Display Images
The next recommended step is to display the raw images. This will provide you an opportunity to visually inspect all images for artifacts, or other
problems. It also allows you to review whether the number of slices and volumes is correct, and that the Import routines properly sorted your
image volumes.
On the top right of the GUI, you should now see that the "display raw images" and "estimate signal SD" buttons are available. Click on "display
raw images". You will see a new window pop up (as in the figure below).
The controls on the right hand side function as follows:
Magnification - controls the size of the displayed image on your screen. Default is 4.
gamma - controls the gamma correction. It can be used to adjust the contrast of the images as viewed on your screen.
max ceiling - adjusts the maximum intensity value displayed.
SLICES - this allows you to view all slices of a single brain volume (i.e. a single b0 or DWI volume).
B_VALUES - this allows you to view a single slice from all brain volumes (i.e. slice #37 for all b0 and DWI volumes).
If you use the B_VALUES slider to select a particular volume, then click back on SLICES, it will let you view all slices from that
new volume.
INSPECT ENTIRE SET - This function allows you to view either all slices from one volume or one slice from all volumes on a single
screen. More details on this in the next section.
DONE - click this when you are done viewing the images. It is always advisable to use the "Done" buttons, and not to close the widgets
with the 'x' at the top right of the window. Using the 'x' to close can cause problems with the software.
Labels 'X', 'Y', and 'Value' - If you move your mouse cursor over the image, it will display the coordinate and the intensity value at that
voxel location.
DELETE VOLUME - This allows the user to delete extremely bad brain volumes which may be affected by artifacts such as spike noise,
or within-volume motion. Use this function with caution! The number of images used in your experiment can affect the value of
your tensor derived metrics1,2. If you find yourself removing more than a few volumes from your data, reconsider if the data is worth
keeping, and if you want to include it in a group analysis, as it may affect your statistics. More details on this function are provided here.
< Up >
References
1. Farrell JA, Landman BA, Jones CK, Smith SA, Prince JL, van Zijl PC, Mori S (2007) Effects of signal-to-noise ratio on the accuracy and
reproducibility of diffusion tensor imaging-derived fractional anisotropy, mean diffusivity, and principal eigenvector measurements at 1.5
T. J Magn Reson Imaging. 26(3):756-67. abstract
2. Tannazi, F., et al, (2011) Bias in Diffusion Tensor-Derived Quantities Depend on The Number of DWIs Composing The DT-MRI Dataset,
19th Annual ISMRM, Montreal, Quebec, Canada.
3.2.02.01 Inspect Entire Set
When you click on Inspect Entire Set, a new window will open up that will fill your display. By default, it will show all of the slices of your first
volume of your data set. In the figure below, this is the 1st non-diffusion weighted image.
By clicking on the Slices button, you can display a single slice from each of your volumes as in the figure below. Note that in the sample shown,
the 1st, 8th, 15th, and 22nd images are non-diffusion weighted (b0) volumes, while the rest of the images are diffusion weighted images (DWIs). If
your monitor is too small, then some of the volumes may not be visible on your screen (in the figure the last few images are cut off because of this
issue). Change the magnification factor to an appropriate value for your monitor. The smallest magnification factor is "0.5" which means that if
your native images are largely zero-filled at the scanner, then you may not be able to visualize all of your images in this manner.
The menu on the right hand side of the window has the following options:
Magnification - This controls the size of the images on your display. A quirk of this software is that if you adjust the magnification factor it
will default back to the "bvalues" display. Click on "slices" to go to that mode after magnifying.
gamma - controls the gamma correction. It can be used to adjust the contrast of the images as viewed on your screen.
max ceiling - adjusts the maximum value displayed.
SLICES - this allows you to view the same slice from each of your b0 and DWI images (see the second figure above).
B_VALUES - this is the default setting for this function. It displays all slices of a single brain volume (i.e. a single b0 or DWI volume) (see
the 1st figure above).
DONE - exits from the multiple image display function.
< Up >
3.2.02.02 Delete Volume
The Delete Volume control allows you to remove a single volume from your DWI dataset. This is only recommended under the following
circumstances: 1) You have severe artifacts in your data that post-processing cannot repair, such as motion within your DWI volume resulting in
major signal dropouts, or an interleaved type of motion artifact, and 2) Your data has adequate over-sampling that removing volumes does not
ill-define your tensor matrix (i.e. if you only acquire 6 directions without any replicates, you cannot remove any volumes). Under this circumstance,
it may be advisable to remove DWIs containing artifacts. However, we recommend extreme caution in removing data, as the number of images
in your dataset can affect the value of measures such as fractional anisotropy 1,2. If you feel you must remove a large number of volumes for your
data to be usable, consider carefully it's inclusion in statistical analyses.
The Delete Volume button is available in the Display Raw Image function of DIFF_CALC.
NOTE: No physical data is ever removed from your system with this function! We simply write out a new .path file
which does not contain paths to the un-wanted files.
When you click on Delete Volume, it removes whichever volume you are currently viewing (i.e. the b-value #). After you click that button, if you
scan through the different b-values of your data, you should see 1 less volume than before.
When you click "Done" a new .list, .path and .bmtxt file are written out with the naming convention my_original_filename_DR.list, where _DR is
added to indicate "data removed".
If you want to remove multiple volumes, be aware of the following items:
1. After clicking "delete volume", the display refreshes. If you had a total of 42 volumes, and you removed volume #3, if you look now, there
will still be a volume #3, but your top volume number is #41. In other words, all your volumes are re-numbered to be consecutive starting
at volume #1. Thus, if you wish to remove multiple volumes, be aware that the volume numbers may have changed since you originally
assessed your data.
2. If you click "delete volume" then click "done" you will get a new listfile name _DR.list. If you then open the _DR.list file and decide to
remove another volume by following the same procedure, you will get a new list file called _DR_DR.list. To avoid this, determine which
volumes you wish to delete, and click on "delete volume" for each selected volume, then click "done". This will create a single new
_DR.list file with only the final desired images.
3. IMPORTANT you will now need to run your DIFF_PREP processing on the _DR.list file! If you continue to use the
my_original_filename.list then you will still be using data containing the un-wanted volumes.
4. If you notice AFTER running DIFF_PREP that you want to remove volumes, load the _DMC.list file, and follow these rules:
a. If I need to remove the first b0 image, I need to re-run DIFF_PREP because the registration makes use of the first b0 volume as
a target for eddy and motion correction
b. If I need to remove any volume OTHER than the first b0 volume, I need to run (or re-run) the tensor fitting in DIFF_CALC to
create a tensor that does not include the un-wanted volumes. I DO NOT need to re-run DIFF_PREP pre-processing on this data.
5.
5. We want to re-iterate that if you find that you are removing large numbers of volumes, you may want to reconsider if it is worthwhile
including this dataset in your analysis. Also, if you remove selected volumes from your data, please report this in all publications, so
people are aware of the potential bias in FA values due to inconsistent numbers of images across your subjects 1.
< Up >
References
1. Farrell JA, Landman BA, Jones CK, Smith SA, Prince JL, van Zijl PC, Mori S (2007) Effects of signal-to-noise ratio on the accuracy and
reproducibility of diffusion tensor imaging-derived fractional anisotropy, mean diffusivity, and principal eigenvector measurements at 1.5
T. J Magn Reson Imaging. 26(3):756-67. abstract
2. Tannazi, F., et al, (2011) Bias in Diffusion Tensor-Derived Quantities Depend on The Number of DWIs Composing The DT-MRI Dataset,
19th Annual ISMRM, Montreal, Quebec, Canada.
3.2.03 Estimate signal SD
Some of the routines in DIFF_CALC require a measure of the noise in your images. This is either measured in the background of the b0 image, or
automatically from the goodness of fit of your data. There are 4 options, which can be selected using the opt button to the right of the estimate
signal SD button. The four options are as shown below:
New! More accurate automated noise estimation methods
The default option is an automatic estimation of the noise. The software masks an area of the brain that is known to be essentially free of
physiological noise, in the white matter regions toward the top of the brain, based on the outlier probability maps found in Walker, et al 1. Tensor
fitting is performed on only these voxels in order to assess the goodness of the fit. A second option uses the GMM robust fitting to get a better
estimate in the presence of artifactual data points. The user can input the fraction of outliers they wish to allow. Default value is 0.05 (i.e. 5%). A
noise estimate is derived from each of these methods based on the formulation from Chang, et al 2.
The automatic noise estimation is strongly recommended when the user wishes to perform RESTORE robust tensor fitting, as a
reasonable estimate of the noise is required for proper performance of this algorithm.
The user can also choose to manually draw an noise ROI. When you click the estimate signal SD button, a window will pop up that is similar to
the display raw images window. Select a slice toward the top or bottom of the brain, where there is a significant amount of noise, which is
generally free of artifacts. Click on the DRAW NOISE ROI button, then in the image, use the left mouse button to draw, and the right mouse
button to close the ROI. An example is shown here:
As shown in this example, it is useful to adjust the gamma and max ceiling so that the background of the image is more visible. Additionally, the
ROI is best placed in a region free of ghosting or other artifacts. If your images are reconstructed with parallel imaging techniques, make sure that
you define your noise ROI in a region containing noise, not all zero values.
The final option is user input. In this case, the user is required to fill in a value for the noise. This can be measured any way the user deems
appropriate. Note that if a value for noise exists in the .list file for your data, that value will be entered automatically, as shown in the example
below. Simply replace the default value with the noise value you desire.
Once a noise value has been entered the mask raw images button should become available in the main GUI.
< Up >
References
1. Walker, L., Chang, L.-C., Koay, C. G., Sharma, N., Cohen, L., Verma, R., Pierpaoli, C. (2011). Effects of physiological noise in population
analysis of diffusion tensor MRI data. Neuroimage 54(2): 1168-1177.
Redundancy Datasets in the Presence of Physiological Noise Artifacts. MRM. In Press
3.2.04 mask raw images
The software requires a brain mask for tensor fitting. This helps decrease the processing time, by not calculating nonsense tensor values in the
background of the image. The opt button to the right of the mask raw images button contains several options, as seen below.
The two types of masking are threshold based, and brain extraction using bet2 1 which are selected via the radio buttons at the bottom of the
options window. The default is brain extraction.
Additional options are as follows:

Threshold based on N times noise_mean. N: - determines the level of masking. A higher value here will create a bigger mask, and results
in a smaller brain image.
Volume number used for masking: - the default value here is 0. This refers to the volume which will be used for masking. Generally, one
wants to use a b0 volume for masking. If your first volume (volume 0) is NOT a b0 volume, change this value appropriately.
Erosion factor for masking: - this value indicates the number of voxels removed from the edge of the mask. Default is 1.
f bet value: - as per the FSL documentation, a smaller value will result in a larger brain. Default value is 0.4
g bet value: - as per the FSL documentation, a negative value results in a smaller brain at the bottom and larger brain at the top. A
positive value will result in the opposite. Default value is 0.0.
Click done when finished selecting your options.
When the options are set as you desire, click on the mask raw images button. When it is complete, the display mask button should be sensitized.
Click this button to review your mask. Red voxels are masked out, blue voxels will be included in tensor computations.
If the mask is not adequate, simply click done, then adjust your mask raw images settings as described above, and click mask raw images again.
Review the mask to make sure you are satisfied with the new settings. Click done.
The next step in a standard processing of your data would be to set the appropriate tensor fitting options, and start the tensor fitting. This will be
described in the tensor fitting section of this software guide.
< Up >
References
1. Smith, S.M, Fast robust automated brain extraction, Human Brain Mapping, 17(3):143-155, 2002 abstract.
3.2.05 quit
Use this button to safely exit the software. It is recommended to always use the Done and quit buttons throughout the software for proper
functionality.
Note, it is also highly recommended to quit the software when loading in a new dataset. This will assure that all variables will be properly re-set
before processing new data.
< Up >
3.2.06 About TORTOISE
Clicking this button will provide you with the license agreement for the software.
< Up >
3.2.07 process tensor
This button is used to start the tensor estimation. There are a number of options available to the user, as seen in the opt button to the right of the
process tensor button. More options will be available with future releases of the software.
The first options allow you to choose the tensor fitting algorithm. There are three options 1:
tensor linear
tensor nonlinear
tensor linear unweighted
The default value is linear because it is the fastest algorithm, however, the use of the non-linear algorithm is highly recommended as it provides a
more accurate estimate of the tensor.
Robust estimation options are either RESTORE 2 or informed RESTORE (iRESTORE), 3 and are only available with the tensor nonlinear option.
Default is "off". We recommend using the automated noise estimation option when using RESTORE or iRESTORE robust tensor fitting.
RESTORE and iRESTORE have additional user defined options. See the following pages for details.
The Residue display selections allows the user to display a histogram of the residuals of the tensor fitting. This can help to indicate to the user if
there is a problem with the fitting. Default value is do not display residuals. The final two options allow the user to adjust the display of the
histogram by choosing whether or not to sort the residuals.
When the appropriate options have been selected, click done, then click the process tensor button. This will fit the tensor, calculate the
eigenvalues and eigenvectors, and then derive all the tensor derived metrics. This will create a new .list, .bmtxt and .path file for your data, with
_L0 appended to the name for linear fit, _N1 for non-linear fit, _LU for unweighted linear fit, _R1 for RESTORE robust fit, and _iR1 for informed
RESTORE robust fit. It will also create a directory with the same name appended with _SAVE. This SAVE directory contains the tensor derived
metric images in either analyze or nifti format, depending on the setting in your configuration file.
References
1. Basser, P.J., Mattiello, J., and LeBihan, D. (1994) Estimation of the effective self-diffusion tensor from the NMR spin echo. J Magn Reson
B 103:247-254 pdf
2. Chang, L.C., Jones, D.K., and Pierpaoli, C. (2005) RESTORE: Robust estimation of tensors by outlier rejection. Magn Reson Med.
53:1088-1095 pdf
Redundancy Datasets in the Presence of Physiological Noise Artifacts. MRM. In Press abstract
< Up >
3.2.07.01 RESTORE Options
When you select RESTORE, you are able to set additional options using the RESTORE Options button.
The RESTORE options menu, as shown below, is populated with reasonable default values. For description of each parameter, click on the "help"
button, and a message will be displayed in the Parameter details box at the bottom. These parameters are briefly described below the figure.
Threshold value of reduced chi-square - RESTORE is only run if the data fails to reach a "quality" threshold, which can be user define.
This threshold, based on the chi-square goodness of fit measure, is automatically computed for your data based on the formula provided
in the "help". However, if the user wishes to be more or less stringent, the value can be set manually here.
Threshold value of confidence interval - By default, RESTORE rejects data points that lie 3 standard deviations away from the mean
of the expected distribution of datapoints.
Maximum number of iterations - The maximum number of iterations allowed for RESTORE to converge.
Do no check the b0 images - Default value = do not check. The non-diffusion weighted (b0) images generally show different variance
properties than the diffusion weighted images. As such, RESTORE is not optimized to identify outliers in the b0 images. We recommend
leaving this at the default value. All voxels of all b0 images will be included in the tensor fitting.
B-value threshold - The b-value of each volume is determined from the b-matrix. Due to imaging gradients, rotations of the b-matrix from
motion correction, or acquisition of non-zero low b-value images, means that the b-value of the b0 image may not be exactly 0. The user
can input a minimum value below which images are not considered for outlier detection. Default value is 100.
Check the remaining directions after outlier identifications - this is a newer feature of RESTORE that checks that the b-matrix is not
ill-defined after removal of data points (i.e. ensures that enough data remains in all diffusion encoding directions). Default value is "on",
and we recommend that this check be performed.
Redundancy coefficient - Determines the minimum amount of data required in each encoding direction. More details of this coefficient
can be found in Chang, et al. 1
Write log file to record parameters used in robust fitting - a log file can be written to keep track of parameters used.
< Up >
3.2.07.02 iRESTORE Options
When iRESTORE is selected, the user is able to set additional parameters using the iRESTORE Options menu.
Click the help button for additional details of each parameter. The parameters are briefly described below the figure.
Threshold value of reduced chi-square - iRESTORE is only run if the data fails to reach a "quality" threshold, which can be user define.
This threshold, based on the chi-square goodness of fit measure, is automatically computed for your data based on the formula provided
in the "help". However, if the user wishes to be more or less stringent, the value can be set manually here.
Threshold value of confidence interval - By default, iRESTORE rejects data points based on the size of the residuals. This value
determines if the point is considered outside the acceptable range.
Maximum nmber of bias -
Do no check the b0 images - Default value = do not check. The non-diffusion weighted (b0) images generally show different variance
properties than the diffusion weighted images. As such, RESTORE is not optimized to identify outliers in the b0 images. We recommend
leaving this at the default value. All voxels of all b0 images will be included in the tensor fitting.
B-value threshold - The b-value of each volume is determined from the b-matrix. Due to imaging gradients, rotations of the b-matrix from
motion correction, or acquisition of non-zero low b-value images, means that the b-value of the b0 image may not be exactly 0. The user
can input a minimum value below which images are not considered for outlier detection. Default value is 100.
Check the remaining directions after outlier identifications - this is a newer feature of RESTORE that checks that the b-matrix is not
ill-defined after removal of data points (i.e. ensures that enough data remains in all diffusion encoding directions). Default value is "on",
and we recommend that this check be performed.
Redundancy coefficient - Determines the minimum amount of data required in each encoding direction. More details of this coefficient
can be found in Chang, et al. 1
Write log file to record parameters used in robust fitting - a log file can be written to keep track of parameters used.
< Up >
3.2.08 compute eigenvalues
By clicking on process tensor, the software will automatically compute the eigenvalues and eigenvectors. Negative eigenvalues can be handled in
several ways. By default, negative eigenvalues accepted. Other options are as shown below:
If the user desires one of the non-default options, it is necessary to select the desired option, click done, then click the compute eigenvalues
button. When the computations are complete, click the derive variables button to re-calculate all tensor derived quantities. It will also be necessary
to click the save session button once all computations are complete in order to save the newly calculated values.
< Up >
3.2.09 triplanar
The triplanar viewer allows the user to view axial, sagittal and coronal views simultaneously. It also provides ROI drawing tools which can be used
on any of the image orientations.
First, to set the magnification factor, use the opt button beside triplanar. The default value is 4, and is generally acceptable for most human brain
data:
Two windows will appear when you click the triplanar button, a viewer and an image type menu.
Image Type Menu
Image Types
These images are explained in detail in the section describing the axial only roi utilities
Amplitude: a calculated reference (S0) image, calculated from the intercept of the tensor fitting.
Trace: the trace of the diffusion tensor. Mean diffusivity (MD) = 1/3(TRACE)
Dxx, Dyy, Dzz: diagonal tensor elements
Dxy, Dxz, Dyz: off-diagonal tensor elements
Eigenv1, Eigenv2, Eigenv3: the eigenvalues
Structural: The image used as target for registration (if it exists)
Skewness_opt1:
Skewness_opt2:
VolRatio: volume ratio
Relative: relative anisotropy
Fractional: fractional anisotropy
Lattice: lattice index
Color_Egv: a color coded eigenvalue image
DEC Map: directionally encoded color maps
Westin Linear: Westin linear measure
Westin Planar: Westin planar measure
Westin Spherical: Westin spherical measure
The menu on the left hand side of the viewer provides display and ROI drawing options. ROI options are discussed in the next section. Display
options are noted with red boxes below.
Crosshairs: when turned on, the cross hairs will be placed where the mouse cursor is clicked in the image. It is placed on all 3
orientations, and is useful for identification of anatomical structures in all 3 orientation views.
The color options are identical to the color options for the roi utilities.
Use the Done button to exit the triplanar viewer.
If you have non-isotropic voxels then the aspect ratio of the re-sliced orientations will be incorrect. This may occur if, for
example, your slice thickness is greater than your in-plane resoultion. This will not affect the values computed from regions of
interest.
< Up >
3.2.09.1 Define ROI
Regions of interest can be defined on any of the three orientation views of the triplanar viewer. In addition, multiple ROIs can be drawn and saved
as a single region of interest, allowing for ROI definition that more closely matches a volume of interest.
Proceedure for ROI definition
1. Select the image type you would like to use for drawing your regions, and navigated to the desired slice of the brain for drawing
2. Click on Define ROI, and a new menu will pop up with 3 options: UNDO, SAVE and DISCARD (figure on right)
3. Hold down the left mouse button to draw continuously, or click with the left button to place points. Use the right button to close the ROI.
4. Once you have closed the ROI, you can go to another view and/or another slice (using the sliders to the right of each view respectively),
or do one of the following:
Use UNDO if you wish to re-draw this ROI
Use SAVE to save this single ROI as your region (proceed to step #6 after clicking SAVE)
Use DISCARD if you wish to abandon ROI drawing
5. Continue defining ROIs until you are happy with your region/volume of interest the do one of the following:
Use SAVE to save your multiple ROIs as a single volume of interest
Use DISCARD if you wish to delete all ROIs drawn in this volume of interest
While UNDO and DISCARD appear to have similar behaviour, when drawing multiple ROIs, UNDO will only remove the most
recently drawn region, while DISCARD will delete all
6. When you click on SAVE, you will be asked to provide a name for your region
7.
7. Type in the name of your ROI and hit the ENTER key on your keyboard. This should add your ROI to the list of regions. For example,
we've named a sample region 'cc'
8. Click on the "Clear" button to clear the current region from the display and from the memory. To display that region again, double click on
its name in the list
9. To define additional regions, follow steps 1-8. It is very important that you use the Clear button before defining additional ROIs.
Any new regions drawn without clearing out the last region will be appended to the previous region!
Extracting Values from ROIs

After all desired regions have been defined as described above, simple click on Extract values to create a text file with the voxel values contained
in your ROIs. This will bring up a new menu that looks like:
In the above figure, we have defined 3 ROIs: cc, test1 and test2. By default, all ROIs defined are selected. If you wish to only extract
values for specific regions, deselect the ones you do not wish to keep by click on the radio buttons to their left.
Values from all image types shown can be exported. Some common ones, such as Trace and Fractional Anisotropy (FA) are selected by
default.
Once values are selected as desired, click EXPORT. This will write a text file to your _proc directory.
If you load the same dataset again, the triplanar viewer will locate previously drawn ROIs and automatically load them into the list. New
ROIs can be defined at any time, and will simply be added to the list.
Additional important information
The text file contains comma separated values. The value for each voxel within your ROI is reported. This text file can be easily imported
into most spreadsheet and subsequently statiscal analysis software packages for computation of summary statistics.
All ROIs are saved as binary nifti image files, with voxels inside the ROI=1 and outside=0. These can be loaded in any software which
reads nifti images. For instance, these can potentially be used for defining seed points for tractography in software pacakges such as
FSL and TrackVis.
The nifti files and the list of regions are stored in a directory called "ROIs" which is created inside your data set's _proc directory.
If you wish to permanently remove any ROIs, simply double click on them in the list, and then click on Delete Selected ROI.
< Up >
3.2.10 roi utilities
The roi utilities area allows the user to view all of the derived metric maps, as well as the tensor elements. It also contains roi drawing and
statistics output. When you first click on ROI utilities, you will see a window open on the right hand of your screen, and 2 menus open on the left
hand of your screen. The right window will likely be black. Use the slider on the ROI FUNCTION menu to scroll through the image slices. See
figure below:
The default image displayed in the image window is the Amplitude image. The other available maps are as shown in the Image Type menu:
AMPLITUDE: a calculated reference (S0) image, calculated from the intercept of the tensor fitting.
TRACE: the trace of the diffusion tensor. Mean diffusivity (MD) = 1/3(TRACE)
Dxx, Dyy, Dzz: diagonal tensor elements
Dxy, Dxz, Dyz: off-diagonal tensor elements
EIGENV1, EIGENV2, EIGENV3: the eigenvalues
SKEWNESS: the degree of oblateness or prolateness of the diffusion ellipsoid in each
voxel based on the skewness of the eigenvalues
((MeanMedian)/Mean)
COLOR_EGV: a color coded eigenvalue image
VolRatio: volume ratio
Relative: relative anisotropy
Fractional: fractional anisotropy
Lattice: lattice index
LINEFIELD: vector field of the first eigenvector
DEC MAP: directionally encoded color maps
CHI SQUARE: a voxel-wise map of a measure of the goodness of fit
ITERATIONS: a map of the number of iterations needed for the non-linear tensor fitting to converge
STRUCTURAL 1: structural image used as target for registration in DIFF_PREP (if it exists)
OUTLIER MAP: for robust fitting only, the percentage of outlier data points removed before fitting
(points removed/
(total points-degrees of freedom))
W_LINEAR: Westin linear measure
W_SPEHRICAL: Westin spherical measure
W_PLANAR: Westin planar measure
Tensor elements and eigenvalues are reported in 10 -6 mm 2 /s, or m 2 /s
Naming convention of saved files
_AM: Amplitude image

_CS: Chi-squared map
_DT: 4D file containing the 6 tensor elements
_EG: Eigenvectors
_EV: Eigenvalues
_FA: Fractional anisotropy
_LI: Lattice index
_ME: mask eroded (by erosion factor)
_MF: flow artifact mask - shows bad points which are masked automatically
_M0: mask original - if the user selects an alternate mask, this image contains the original mask
_MP: mask plain - mask before erosion factor is applied
_MS: mask - either ME or MP depending on what the user sets. Default is ME
_RA: Relative anisotropy
_TR: Trace
_VR: Volume ratio
_WL: Westin linear
_WP: Westin planar
_WS: Westin spherical
The ROI FUNCTION menu contains a number of options, as shown in the figure and described below:
IMAGE TYPE MENU: If you close the Image Type menu, this button will open a new Image Type menu
EDIT OPTIONS: Contains options for the linefield and magnification of the displayed images.
EDIT COLOR OPTIONS: Contains options for the display of the DEC maps.
FILTER ROI OPTIONS: Allows the user to filter the ROIs for removal of unwanted regions, such as CSF.
DRAW NEW ROI: Select the map on which you would like to draw the ROI (such as FA). Click this button to draw an ROI on your image.
Then use the left click to draw, and right click to complete the ROI. Statistics of the selected maps will be output to the status report
window. To save the ROI for display on other maps, or to output statistics, see the following options.
ADD ROI TO LIST: To save your ROI for display on other maps, or statistics output, click this button. You will see a small window. Enter
a name for your ROI. For example, genu as shown below.
SHOW ROIs: To display your ROI, click this button. You will see a list of all ROIs that have been added. Click on the entry and it will
display on the active map. If you click the show all roi button, it will display all of the ROIs sequentially in the order displayed in the list.
LIST ROIs: If you click this button, it will list all of the "added" ROIs in the status report window.
PROPAGATE TO SLICES: This function allows you to copy your ROI to another slice of your image. Simply select the ROI you would
like to copy, then click on either "select slice to propagate" which will copy the ROI to the selected slice and add it to the ROI list, or
"propagate to all slices" which will copy the ROI to all the slices of your image.
SORT by NAME: this sorts your "added" ROIs by name.
SORT by SLICE: this sorts your "added" ROIs by slice number.
DELETE ROI: use this to remove ROIs from your list.
REPORT POINT: this will give you the coordinates of a single point in your image, simply by clicking on the desires location with the left
mouse button.
GET STATISTICS:This will save the statistics (from the selected maps) to a text file. It will create a directory in your procbase with
_STAT appended to the end of the listfile name. In that directory, you will find two .DAT files containing the selected values at every voxel
in your ROI.
SAVE ROI: to save all "added" ROIs, click this button, then enter a name for your set of ROIs (with no extension).
RESTORE OLD ROI: If you have previously saved an ROI file, you can reload it using this function. Simply navigate to the location of
your save .roi file, and click restore.
DONE: click this when you are done looking at your maps and drawing ROIs.
< Up >
3.2.10.1 edit options
The EDIT OPTIONS button of the ROI FUNCTION menu contains a number of options listed below:
LineF length: controls the length of the lines in the linefield image
LineF Rebin Factor: controls the density of the lines in the linefield image
smoothing: allows the user to smooth the images for the purposes of the magnification. Options are described in the readme button.
magnification factor: determines the size of the image to be displayed on the screen. note that once you adjust the magnification factor,
you will need to hit "done" on all menus to get back to just the main software GUI, and then click the roi utilities button in order to resize
the images appropriately.
show statistics option: This is a button which provides an additional menu. Use this menu to determine the quantities which are desired
in the ROI statistics output.
readme: contains information about the smoothing and linefield options
done: click this button when you are done editing the roi options.
< Up >
3.2.10.2 edit color options
The options in this menu control the appearance of the directionally encoded color (DEC) maps by allowing the user to optimize the display of the
DEC maps for a specific screen. These are heuristically determined parameters, as described in Pajevic and Pierpaoli 1. Ideally, you should
adjust the values below so that the visual perception of the color circle has a uniform distribution of the colors. An example is shown below.
lattice max: the DEC maps are displayed filtered by the Lattice Index. This value determines the maximum lattice index used to filter the
images. If you set this to a lower value, you will saturate high values but also help bring out low anisotropy features.
lattice min: minimum lattice index value for filtering of DEC maps.
adjust exp: this affects only have the images are viewed on your monitor. The default value is set to a generally good value, but you may
wish to adjust this for better visualization, depending on your monitor.
gamma cor.: similar to adjust exp, this controls the gamma correction for your monitor.
Stevens beta, pB, pG, pC, and pS: are all heuristic parameters as proposed in the Pajevic and Pierpaoli Color Schemes paper 1.
truncate, multiply: multiply is the default option. This will weight the DEC map by the lattice index. If you select truncate, the DEC map
will no longer be weight, but will be of uniform intensity. This can be used if the user would like to view only a specific range of anisotropy
values. Set the lattice max = max of your range of interest and lattice min = min of your range of interest, and then select the truncate
radio button, and reload the DEC map.
Radio buttons that control the type of color map, as defined Pajevic and Pierpaoli 1. Select the map you wish to view, then click DONE.
To display the new color map, click on the DEC button of the Image Type menu in order to refresh the displayed image.
Absol Heur: Absolute value
CylSymm Heur: Cylindrical symmetry
NoSymm Heur: No symmetry
Circle buttons: these buttons display the color circle of the selected color map type at different resolutions (512, 256, or 128).
DONE: click this when you are done setting color settings.
Example: Three different gamma correction values with the absolute value DEC map. On our screens, a gamma value of 0.8 shows very dark,
with poor angular distribution of the colors; a large amount of blue and green colors are visible, with less red and yellow. On the other end, a
gamma value of 2.0 shows faint colors, with more red and yellow visible, with less blue and green. A gamma value of 1.4 for our screens (and the
default value for the program) shows the best range of colors.
< Up >
References
1. Pajevic, S. and Pierpaoli, C. (1999) Color schemes to represent the orientation of anisotropic tissues from diffusion tensor data:
application to white matter fiber tract mapping in the human brain. Magn Reson Med. 42:526-540 pdf
3.2.10.3 filter roi options
To enable filtering, click the button with ---- beside ENABLE FILTERING. It should then say *ON*. You can filter by setting a range of desired
TRACE values, or a range of desired LATTICE INDEX values (ranging from 0 - 1). You can also apply a CSF filter. If you define an ROI near or
across a region with values outside your defined range(s), the outside values will not be included. Click Done when you are finished.
< Up >
3.2.11 export images
The export images menu allows the user to export data to other software packages. This is recommended, for example, if the user would like to
use DIFF_PREP to correct for image artifacts, and then perform tractography with FSL. All of these options should create a new directory in your
proc directory, containing the appropriate new files.
RAW FSL-LIKE SORTED: Creates a 4D analyze file containing all of the diffusion weighted images, with b0 images first, followed by
DWIs. It also creates bvecs and bvals with b0 entries first. text files as required by FSL. If you have created a mask with the mask raw
images button, then it should also output a mask image. This output can also easily be input into Camino
RAW FSL_LIKE UNSORTED: The same as above, but it leaves the images in the original order.
RAW INVERT SLICE ORDER: TORTOISE expects data to be acquired in the standard IS (inferior to superior, or bottom to top) order. If
your data was acquired SI (i.e. top to bottom), you can select this option to change the order of the slices within your raw data.
PROCESSED FOR TRACKVIS: Outputs the tensor quantities for input into Trackvis for fiber tractography.
NRRD TENSOR: Outputs the tensor image in NRRD format for use with Slicer
DTITK TENSOR: Outputs the tensor image for input into DTI-TK for tensor registration.
VTK TENSOR: Outputs the tensor image in VTK tensor format, for use in Slicer.
FA and VEC for DTI Studio: Outputs the FA map and eigenvectors for performing tractography in DTI Studio
DONE: Click this when you are finished exporting your data.
The following section gives details on how to export to FSL.
< Up >
3.2.11.1 Export to FSL

Export Data in FSL-like format
1. Start up DIFF_CALC according to the software guide

2. Click on load listfile, and navigate to your list file (if you have run the registration software, this will be the one ending in _DMC.list)
3. a window may pop up asking about Endianism, select "statistical test" and click Done (unless you know what the endianism is, then you
can specify big or little and click done).
4. Click on the "export images" button on the left hand side of the GUI that has become active. For FSL: Select the "RAW FSL-LIKE
UNSORTED". This may take a few minutes to finish, depending on how big your data is. It will create a bvecs, bvals and a 4D analyze file
(.img/.hdr). The following message will be displayed when it is finished: "Raw images exported. 4Ddata UNSORTED bvecs, Flipped X".
Similarly, for Camino: Select either the "RAW FSL-LIKE SORTED" or the "RAW FSL-LIKE UNSORTED" option depending on your
desired scheme file version.
5. You're done. Just click the "quit" button in the GUI to close the software. There will now be a new directory inside your proc directory
ending in _FSL_RAW_UNSORTED (or _FSL_RAW_SORTED). If you go into that directory, you will see the files you need for running
FSL or importing into Camino.
NOTES:
The statement "Flipped X" reflects a simple difference in coordinate system between our software and FSL and Camino.
If you need a mask image, use the mask raw images option of DIFF_CALC before selecting export images. The mask that is created
here will be output to the same _FSL_RAW_UNSORTED directory.
< Up >
3.2.12 save session
The save session button allows you to save your data if you have made any changes while the data was loaded. This includes options that are
listed in the opt button to the right of the save session button, as shown below.
SAVE SESSION OPTIONS controls the way in which the data is saved:
without saving: allows you to run tensor fitting without saving the images. This may be useful for testing purposes, as it will
complete faster without having to save. Select this option BEFORE hitting the process tensor button for tensor estimation.
save using default names: This is the default option. It will use the name of the listfile as provided to the software, and will
automatically append either _L0, _N1, _R1, _iR1, or _LU depending on the tensor fitting option chosen.
save using user defined names: this allows the user to define a different name for the processed data. Once the process
tensor button has been clicked, a window will pop up asking the user to provide a name. Provide a name without extension, as
shown in the figure below.
Processed Output Endianism largely exists for legacy reasons, as most systems are currently little endian. However, the following
options exist:
Machine endianism: is the default value, and will auto detect if your machine is big or little endian and use that endianism for
output images.
BIG endian, LITTLE endian: you can manually set your endianism to BIG or LITTLE as desired for output images.
readme: contains instructions on the save session options.
done: click this button when you are done setting your saving options.
< Up >
3.2.13 restore session
Once you have estimated your tensor, it will write out a new .list, .path and .bmtxt files with _L0, _N1, _LU, _R1, or _iR1 appended to the file
name, indicating that tensor estimation has been performed on that data. If you would like to re-load your tensor and tensor derived metric
images, simply load the new listfile, then click the restore session button. This will load all of the previously derived maps into DIFF_CALC without
having to re-estimate the tensor.
< Up >
3.2.14 sensitize the buttons
The sensitize the buttons button at the bottom left of the main software gui generally only works if the user has a full licensed version of IDL. If the
buttons become desensitized due to an error in the software, click this button to re-sensitize the buttons. It is advisable that once the buttons are
re-sensitized, the user selects the quit button, and restarts the software, to avoid any problems that may remain.
< Up
DIFF_PREP Main
DIFF_PREP is software programmed in IDL meant for pre-processing of diffusion weighted images. It includes:
Image import and computation of B-matrix from gradient tables

Motion and eddy current distortion correction with B-matrix reorientation 2
B0 susceptibility induced EPI distortion correction 3
Reorientation of the DWIs into a target space with B-matrix reorientation 3
Provided below are links for a software guide including a detailed user's manual, and a short guide on recommended steps after pre-processing is
complete.
If you use our software in your research, the algorithms listed above have been published elsewhere. Downloadable pdf copies of the articles are
available by clicking the pdf links. Please cite the appropriate references in your work. A general reference for TORTOISE is shown below 1.
To access the Software Guide click here
DIFF PREP Flow Chart
Description of the transformation matrices
Registration is done. What do I do now?
Internal NIH collaborators only
References
1. C. Pierpaoli, L. Walker, M. O. Irfanoglu, A. Barnett, P. Basser, L-C. Chang, C. Koay, S. Pajevic, G. Rohde, J. Sarlls, and M. Wu, 2010,
#1597 pdf
2. Rohde, G.K., Barnett, A.S., Basser, P.J., Marenco, S., and Pierpaoli, C. (2004) Comprehensive approach for correction of motion and
distortion in diffusion-weighted MRI. Magn Reson Med. 51:103-114 pdf
3. Wu, M., Chang, L.-C., Walker, L., Lemaitre, H., Barnett, A.S., Marenco, S., and Pierpaoli, C. (2008) Comparison of EPI Distortion
Correction Methods in Diffusion Tensor MRI Using a Novel Framework. MICCAI 2008, Part II, LNCS 5242, pp. 321-329 pdf
DIFF_PREP pipeline
Notes about the following pipeline document

The "registration to standard space" of the T2 structural image is not performed automatically by TORTOISE. Instead, it is something we
recommend users of TORTOISE do outside of our software, as the desired standard space may be different depending on the user's specific
dataset.
Recommendations and Requirements for standard space registration of T2 structural images:
The T2 structural image must remain anatomically faithful - meaning no affine or non-linear warping steps should be performed. This
is vital for proper performance of the EPI distortion correction step, which uses image registration to match a non diffusion weighted (b0)
image to this T2 structural image to correct for EPI distortions.
We recommend putting your T2 image into an ACPC alignment, including a midsagital alignment. This assures consistency between
datasets, aligns the data so that the color encoding looks as expected, and also provides a good initial consistent orientation from which
to perform further processing steps, such as tensor based registration. Many software packages have an ACPC alignment option. We
generally use mipav.
Software Guide
Collapse all
Expand all Collapse all
1. Introduction to DIFF_PREP
Welcome to the DIFF_PREP software guide. In this document, details about the properties and usage of the software will be described.
Diffusion Tensor Imaging (DTI) is a Magnetic Resonance Imaging (MRI) modality, which allows in-vivo extraction of brain neural pathways. DTI
requires a scan with at least 6 diffusion weighted volumes obtained with non-colinear diffusion gradient directions in addition to at least one
diffusion-free T2W image (b0 image). Because of the patient/subject motion during the scan, the same voxels in different volumes do not
generally correspond to exactly the same anatomical brain locations. Additionally, the common MR protocol used in DTI imaging, the Echo Planar
Imaging protocol (EPI), introduces additional artifacts into the images.
The purpose of this software is to correct for all types of distortions induced during the DTI scan, including: motion distortions, eddy current
distortions and B0 susceptibility induced EPI distortions. This will enable users to accomplish a correct tensor estimation and better fiber tracking.
< Up >
1.1 Welcome
Welcome to the software guide for the DIFF_PREP module of TORTOISE. This software has been developed along with the DIFF_CALC module
to fulfill most of the needs of users wishing to process DTI data.
The standard procedure for processing would be to correct and register your data using DIFF_PREP and then calculate the tensor and tensor
derived quantities using DIFF_CALC.
< Up >
1.1.1 Document Organization
This guide is organized as follows:
In the Introduction, a brief overview of the software is given, system requirements to run the software are explained, and the preliminary steps for
software installation are described.
In Software Overview, we describe the functionalities of the software; i.e. a complete list and explanations of what you can do with it.
In Usage, the instructions on how to use the software are given first. Because DIFF_PREP is a registration software, it may require many
settings to be tuned for specific cases. Even though the DIFF_PREP software is automated at its best, it will not perform well with some data.
Additionally, the user might want to perform some operations and avoid some others during registration. The sections Registration Settings and
Optimization Settings go over the parameters to handle these cases. The last section of this chapter describes the properties and usage of some
extra programs that are very helpful when used along with DIFF_PREP.
< Up >
1.1.2 About
DIFF_PREP has been developed at the Section on Tissue Biophysics and Biomimetics (STBB), part of the Eunice Kennedy Shriver National
Institute of Child Health and Human Development (NICHD) at the National Institutes of Health (NIH) by the NIH Pediatric Neuroimaging Diffusion
Tensor MRI group.
Special thanks to the members and contributors to the software:
Dr. Peter Basser

Dr. Alan Barnett
Dr. Lin-Ching Chang
M. Okan Irfanoglu
Dr. Carlo Pierpaoli
Dr. Gustavo Rohde
Lindsay Walker
Minjie Wu
Please email tortoisedti@gmail.com for any bug reports, questions or suggestions.
< Up >
1.2 Installation
In this section, the installation procedure for DIFF_PREP will be described.

This software requires either a full IDL license or can be run using the pre-compiled IDL virtual machine (VM) supplied with the TORTOISE
download.
< Up >
1.2.1 System Requirements
The software currently supports the Linux platform and intel based Mac. Windows support is expected in a future release.
For faster processing, the IDL code calls external C/C++ functions. These functions need to be compiled for the specific platform the user is
running in order for the software to work properly. Here is the list of specific platforms:
Linux 32 bit edition: This platform is fully supported. It even includes Java run time libraries for an advanced algorithm to compute
background noise. This platform is the only platform that has JRE support. Note that Java functions will not work with the virtual machine.
Linux 64 bit edition: This platform is fully supported.
Mac OSX: Intel based systems are fully supported.
Note that due to the vast number of Linux flavors we were unable to test them all. If you run into any errors, please contact us, and let us know the
error you received, as well as the linux edition and flavor you are running. This code has so far been tested on CentOS 5.2, CentOS 5.3, REHL 4,
Ubuntu, Fedora 7, and Fedora 9.
< Up >
1.2.2 Software Installation
The installation of the software is very straightforward.
1. download and save the distribution tar file.

2. Untar the file to a convenient installation directory of your choosing. The software is run from the installation directory, using one of
prepvm, diffprep_gui.sav or diffprep.sav which you should now see in your installation directory. Usage is described in detail in the Usage
chapter.
3. OPTIONAL: create a directory named "DIFF_PREP_WORK" in the current user's home directory. This is required for storing settings files
and for writing of temporary files. If you do not create this it will be created for you by the software.
Instructions for running the software are in the Usage section.
< Up >
2. Software Overview
A flow chart for the software is available at DIFF_PREP pipeline.
Section 2 of the software guide is UNDER CONSTRUCTION
< Up >
2.1 Overall Algorithm
UNDER CONSTRUCTION
< Up >
2.2 Motion Distortion Correction
UNDER CONSTRUCTION
< Up >
2.3 Eddy Current Distortion Correction

UNDER CONSTRUCTION
< Up >
2.4 EPI Distortion Correction
UNDER CONSTRUCTION
< Up >
2.5 Other features
UNDER CONSTRUCTION
< Up >
2.5.1 Image resampling
UNDER CONSTRUCTION
< Up >
2.5.2 Automatic Noise Computation
UNDER CONSTRUCTION
< Up >
2.5.3 Image cropping
UNDER CONSTRUCTION
< Up >
2.5.4 Brain masking
UNDER CONSTRUCTION
< Up >
3. Usage
In this chapter the details for software usage will be given.
In the section Running the Software, instructions to run the program with its default settings will be given. In the sections Registration Settings
and Optimization Settings customizing the settings for the user's specific needs will be explained.
< Up >
3.1 Running the Software

To run the software:
With the precompiled IDL Virtual Machine (VM)

Go to the install directory/diffprep_main
Type prepvm
Click on the IDL splash screen to start the software
With IDL Full licensed version

Go to the install directory/diffprep_main
Type "idl" in the command prompt. This assumes that the path to the executable "idl" exists in your "PATH" environment
variable. Otherwise, give the full path to "idl".
On the IDL command prompt type one of the two commands:
For command line:
IDL> diffprep, 'FULL PATH TO DATA DESCRIPTION FILE'
OR for GUI version:
IDL> diffprep_gui
With locally installed IDL virtual machine (VM) - Note: a few users have reported problems running the software in this manner. We have
not yet identified the issue. Please use the precompiled version of the IDL VM (see above) if you run into problems.
Start the IDL VM from your local install of IDL
select diffprep_gui.sav
The main software is a user friendly GUI "diffprep_gui.sav" where you can use a GUI to create the data description file and run the software. This
can be used with the IDL VM, the precompiled VM or with the full IDL license.
The command line version of the software is called "diffprep.sav". This procedure takes one parameter - a string containing the full path of an
".xml" file that contains the descriptions of the data that needs to be processed, called the data description file. This file needs to be created
manually for use in the command line version, and will be described in the following sections. This is only an option using a full IDL license.
< Up >
3.1.1 Data Format
The DWI format expected by the software consists of a couple of different files:
1. Listfile: Listfiles are similar to header files in other formats and describe geometric and pyhsical properties of the data. It also contains
links to the path files and b-matrix files.
2. Path files: The format used by the software expects the files of the data to contain 2D slice images , not 3D volumes or 4D sets of
volumes as in other formats. The path file contains the relative paths to every single slice file (with respect to the directory containing the
list file - referred to as the Procbase).
3. Bmatrix files: This file defines the B-matrix used in diffusion tensor fitting computations. It is a text file containing 6 columns and as many
rows as the number of gradients used in the scan.
DIFF_PREP contains import tools for Phillips Par/Rec, GE Dicom, Siemens Dicom, Siemens Mosaic Dicom, and FSL style 4D nifti images. See
the Import section of this user manual.
DIFF_PREP registration software uses an additional "structural image" file in addition to the DWI data. As explained in the Software Overview
chapter, this ANALYZE or NIFTI format file, is a high resolution anatomical MR image used to describe the coordinate frame for the registered
images as well as to compute BO susceptibility induced EPI distortion deformations. The recommended image is a high resolution T2W image
with fat saturation, as it has been found to produce the best results for B0 susceptibility induce EPI distortion correction.
< Up >
3.1.2 Data description file
To run the program, the user needs an additional file describing the data, called the data description file. This XML file contains all the necessary
information about the data to run the software. A sample data description file is displayed on the next page.
For manual creation of the data description file for use with the command line version of DIFF_PREP, the user needs to replace the values in
between the tags with the information based on their data. The mandatory tags in the file are:
PROCBASE: This tag defines the full path to the main folder which contains the listfile, the path file and the Bmatrix file. Most
intermediate and final output files of the software are going to be placed in this folder.
example:
<PROCBASE>/home/main_data_folder/specific_data_folder/</PROCBASE>
The user should replace the path in between <PROCBASE></PROCBASE> to the correct path.
list_root_filename: This tag defines the name of the listfile to be used. Please note that it is just the filename and not the full path and that
it is assumed that this file exists in the PROCBASE folder.
example:
<list_root_filename>sample.list</list_root_filename>
STRUCTURAL_FILENAME: This tag defines the full path to the structural image file. The file should be in analyze or nifti format and the
path should point to the ".nii" or ".img" (not the ".hdr" file). Note that this is an optional image to provide. If none is provided, the 1st b0
image in your DTI dataset will be extracted and used as a target. In this case, the user should set the 'Correction for B0 distortion with
BSplines' to off, as a non-epi image is required for this correction.
example:
<STRUCTURAL_FILENAME>/home/main_data_folder/specific_data_folder/structural.img</STRUCTURAL_FILENAME>
registration_filename: This tag defines the name of the registration settings file. The details of this file will be explained in Section
Registration Settings. Please again note that this is not the full path but just the filename and this file must be located in the
DIFF_PREP_WORK directory in the user's home directory, with the extension .dmc. If that is not the case, the program will display an
error message.
is_brain_data: The software behaves differently if the data to be used is brain data or phantom data. This tag indicates the type of the
data. It can be "yes/no". Note that if your images do not have roughly whole brain coverage, it is necessary to select "no". By default, this
is set to yes (the radio button of the GUI is automatically selected when you first load the software).
example:
<is_brain_data>yes</is_brain_data>
The following tags are optional:
TEMPLATE_FILENAME: This tag defines the full path to the template image to be used in the registration. If it is provided, the value in
this tag will be used. Otherwise, a template image will be automatically created from the b0 image in the DTI data set. The automatic b0
template creation is the recommended procedure.
REORIENTATION_FILENAME: This tag defines the full path to an optional template for final reorientation. This can be used if a different
target than STRUCTURAL_FILENAME is desired for the final reorientation of the data. An example of a target could be the ICBM atlases
, or other atlas type images.
upsample_name: Currently, this is referred to in the software as "anonymize name". If a name is specified here, a copy of the original
data will be made with the specified name, and all processing will be performed with the new name. This is intended as a means of
anonymizing data. This functionality used to be associated with the upsampling procedure, but has been replaced with an independent
re-naming function (as of V1.0.1).
example:
<upsample_name>subject_57_up</upsample_name>
The following tags are needed ONLY WHEN the "automatic_B0_noise" setting is turned off in the registration settings file. Otherwise, they are not
needed. The default value is 0.0 as a place holder only. If "automatic_B0_noise" is set to off, please supply appropriate values.
B0_noise_mean: This tag defines the mean intensity value of the background in the b0 image.
example:
<B0_noise_mean>0.0</B0_noise_mean>
B0_noise_stdev: This tag defines the standard deviation of the noise in the background of the b0 image.
example:
<B0_noise_stdev>0.0</B0_noise_stdev>
structural_noise_mean: This tag defines the mean of the noise in the background of the structural image.
structural_noise_stdev: This tag defines the standard deviation of the noise in the background of the structural image.
< Up >
3.1.2.1 Sample Data Description File




<PROCBASE>/home/username/main_data_folder/specific_data_folder/</PROCBASE>


<STRUCTURAL_FILENAME>/home/username/main_data_folder/specific_data_folder/structural_image.img</STRUCTURAL_FILENAME><!-
Path to the template filename. OPTIONAL.. If not provided, the software will look for -->






<is_brain_data>yes</is_brain_data>


<registration_filename>sample_registration_settings.dmc</registration_filename>



<! -- <upsample_name>upsampled_</upsample_name>


<B0_noise_mean>0.0</B0_noise_mean>


<B0_noise_stdev>0.0</B0_noise_stdev>


<structural_noise_mean>0.0</structural_noise_mean>


<structural_noise_stdev>0.0</structural_noise_stdev>
< Up >
3.1.3 from Command Line

It is easiest to run the software from the GUI, which will automatically create your data description file, however, if you require command line
usage, the following will describe the steps.
Copy the text from the previous page and use it as a template to manually create your own data description file. Simply fill in the required
information (Procbase, structural file, list file and registration settings file) and save it to a convenient location, generally within your procbase.
Once the data properties file is created and all the registration settings are as desired (Registration Settings) the program can simply be run from
the IDL command line by typing (assuming that the name of the data properties file is sample.xml):
IDL> diffprep, '/home/username/main_data_folder/specific_data_folder/sample.xml'
If everything is done right the program should start spitting out information in the command prompt and status report window.
< Up >
3.1.4 with GUI
Another option to run the software is to automatically create the data properties file with a GUI. When the user runs either diffprep_gui or prepvm,
a graphical user interface to create the data description file will be displayed (the large blue numbers only appear in this graphic as an aid to this
description):
The GUI has 2 sides; one for data import and one for data processing. The appropriate side is selected using the radio buttons marked by the
blue number 1 in the figure above. "IMPORT data" options are described in the next section, "Process imported data" options are described here.
When the user selects the "Process imported data" radio button, all the buttons and text boxes on the right hand side of the window will be
enabled and everything on the left hand side will be disabled.
The Process imported data side has 2 main areas. The user can use the "Select data properties file" option (marked by number 2) if he/she has
an existing data description file for the data. Otherwise the user should use section 4 to enter the necessary information in the corresponding
fields. Note that the section 5 represents optional parameters that may also be entered at this time.
The user can choose to enter the full path to the data description file on the textbox labeled with 2 or can press the button on the right to browse
for the file. When the correct path is displayed in the textbox, pressing "Apply" at the bottom of the window will cause DIFF_PREP to run with the
existing data description file.
If the user does not have a data description file already created for the data, information will need to be entered in section 4. The user now can
enter the required information about the data in the textboxes or can browse for the paths by pressing the corresponding buttons. The textboxes
labeled with 4 are for recommended information (all but the structural image are MANDATORY) and the ones labeled with 5 are optional. These
fields are described in detail in the data description file section of this user manual.
When entering the name of the registration settings file in area 4, the user can choose to either enter an existing file name, or create a new
registration settings file using a GUI, shown below. The registration settings file is described in detail in the registration settings section of this
guide. Important: please note that the default name for the settings file is registration_settings1.dmc. The user should enter a new name which is
meaningful to them for future use/reference. For example, tumor_patient_grp.dmc or control_group.dmc, etc.
After the desired settings are selected, hit apply, and a new registration settings file will be created in your DIFF_PREP_WORK directory. If a file
already exists with the selected name, you will be prompted to overwrite the file, or cancel and enter a unique name for the settings file. This will
then put you back in the main diffprep GUI.
After all information is entered in the main GUI, when the user presses the "Apply" button, a new data description file is created in the
PROCBASE folder with the name "list_file_name.xml" and DIFF_PREP is run with this newly created file. If the user wishes to process the same
data again at a later time, he can use the "Select data properties file" section and use this data description file and will not need to re-enter the
information.
< Up >
3.1.4.1 Import Tools
Data must be imported to a format which our software can read. This is a very simple format consisting of three text files: a header file (.list), a file
of pointers to the raw data (.path) and a b-matrix file (.bmtxt). These are described in more detail in the Data format section of the DIFF_PREP
Software Guide. These files are created in a parallel directory to your data directory with the same name with _proc appended to it. For example:
if your data is in my_data/, the importing routine will create my_data_proc/.
This process generally takes only a few minutes. Where possible, telling the software the number of slices in your data greatly reduces the import
processing time.
When the DIFF_PREP gui is first loaded, it defaults to the IMPORT data side (area 2 in the figure below).
First, use the drop down menu to select your input image type. The options are currently Philips PAR/REC, Philips DICOM, GE DICOM,
SIEMENS DICOM, SIEMENS MOSAIC DICOM, FSL 4D NIFTI and Bruker, as shown in the figure below. Each of the options will be described
separately.
Philips PAR/REC
Enter the full path to the PAR file into the textbox, or use the button on the right of the box to browse for your PAR file. If your data is acquired
such that the image reference frame and the gradient reference frame are not the same, turn on the option "Rotate gradients based on slice
orientation?". This should be used in cases where the data was acquired with over plus.
For software versions 4.1 and greater, the gradients are specified in the PAR file. However, for earlier software versions you will need to supply a
text file which contains 3 space or tab separated columns in the order of x y z with a row for each DWI volume acquired. If your data also contains
a calculated trace weighted image (done by the scanner) please include an additional line of 0.0 0.0 0.0 to the bottom row of your gradient text
file.
The user is given the option to swap the gradients. The gradient table is expecting the entries to be in the order or READ PHASE SLICE. If these
are swapped, for instance if the phase encoding direction of axial images is changed to Left/Right instead of the standard Anterior/Posterior, this
may be necessary. This should be a rare occurence.
Click the import button. This will create the proc directory parallel to your data directory. Inside there will now be a .list, .path and .bmtxt file as
described above. It will also populate the List file field of the process side of the DIFF_PREP GUI.
Philips DICOM
Enter the full path to the dicom image directory into the textbox, or use the button on the right of the box to browse. If your data is acquired such
that the image reference frame and the gradient reference frame are not the same, turn on the option "Rotate gradients based on slice
orientation?". This should be used in cases where the data was acquired with over plus.
Note: your DTI data must be in a single directory containing ONLY the DTI data (sub-directories for separate DTI series is okay, but all files in the
same parent directory will be included in the import). Please separate your DTI series from other series (such as anatomical T1 or T2 images)
before using the importing process. .
The user is given two optional fields. First, the user scan specify the number of slices in a single brain volume. This should only be necessary in
cases where this information is not available in the DICOM header, usually due to anonymization proceedures. Second, the user can swap the
gradients. The gradient table is expecting the entries to be in the order or READ PHASE SLICE. If these are swapped, for instance if the phase
encoding direction of axial images is changed to Left/Right instead of the standard Anterior/Posterior, this may be necessary. This should be a
rare occurence.
GE DICOM / SIEMENS DICOM

Select the correct manufacturer and data type for your data with the pull down menu. Usage for both dicom types is the same, as specified below,
with a few minor differences.
Enter the full path to the dicom image directory (or use the button to browse for your data directory). Note: your DTI data must be in a single
directory containing ONLY the DTI data. Please separate your DTI series from other series (such as anatomical T1 or T2 images) before using
the importing process. .
The gradient file is a text file where the first line contains only the number of volumes in your data, and the subsequent lines contain three
columns in the order of x y z, with one line per volume in your data. Note: If you have multiple b-values the gradient vectors must be scaled to the
b-value. More details are provided in the Quick Start Guide.
Optional information to provide the software are:
1. Number of slices - the number of slices in a volume is not required but will speed up the import process if it is provided.
2. b-value - this is the maximum b-value of your data. If not provided, the software will find the b-value from the DICOM header. However,
due to changes in the DICOM header over time, it is sometimes possible that the software will be unable to locate this value, or will locate
an incorrect. If the software cannot locate a value, an error message will appear in the status report window. Due to the possibility of
inconsistencies in the dicom header files, we highly recommend that the user provide the maximum b-value. If not, please check that your
b-matrix is correct. Occasionally we have seen a bmatrix of all zeros due to a zero b-value being identified in the dicom header
3. Flip slice order? - The tensor reference frame in DIFF_CALC assumes your data is acquired in the standard bottom-to-top (IS) fashion. If
your data is acquired top-to-bottom (SI) please select this option in order to have correct directional information in your fitted tensor.
4. Rotate Gradients? - SIEMENS ONLY - Siemens always applies diffusion gradients with respect to the magnet coordinate frame. This
means that if images are acquired obliquely (i.e. the user rotates the field of view on the scanner console), this rotation is not taken into
account in the gradient table provided to the scanner. Rotate Gradients is turned on by default, as it is harmless if your data is acquired in
axial orientation, and necessary if your data are acquired obliquely. NOTE: the b-matrix which is computed and stored in the DICOM
header for Siemens does take this rotation into account. However, TORTOISE requires a gradient table as input, so the b-matrix from the
DICOM header is not used at this time.
5. Flip X, Flip Y, Flip Z - If the directions of your gradient file are inconsistent with the reference from of our software, it may be necessary to
use these buttons. Note: In our experience, the convention from Siemens is different than our convention, and requires the use of the Flip
5.
Y option, therefore, for both Siemens dicom and Siemens Mosaic dicom files this is the default used.
6. Swap XY, Swap XZ, Swap YZ - The gradient table is expecting the entries to be in the order or READ PHASE SLICE. If these are
swapped, for instance if the phase encoding direction of axial images is changed to Left/Right instead of the standard Anterior/Posterior,
this may be necessary. This should be a rare occurence.
SIEMENS MOSAIC DICOM
Using the Siemens Mosaic Dicom import tool is identical to the GE and SIEMENS DICOM formats as described above. However, there are a few
differences internally to the code of which the user should be aware.
This data format contains all of the slices for one DTI volume in a single 2D mosaic view. Therefore, to be read by our data, we must cut apart the
images into standard slice-by-slice data. This new data is saved as floating point slices in a new directory. Thus, the naming convention becomes:
original data: my_data/, raw floating point data: my_data_slices/, imported data: my_data_proc/.
Additionally, this process can take up to 5-10 minutes, depending on your computer and on the size of your data set.
In TORTOISE V1.3.0, Rotate Gradients? is by default turned on. The user does not currently have the option to turn it off. This option SHOULD
be used at all times, but if the user requires it to be turned off, they should contact us at tortoisedti@gmail.com for a slightly different version of the
software.
FSL 4D NIFTI
For 4D nifti data, the software is expecting the data structure and naming convention of FSL. Mainly there needs to be a 4D NIFTI data file
containing all of your diffusion and non-diffusion (b0) weighted images, as well as a corresponding bvectors and bvalues files, named exactly
bvecs and bvals. This can be created using the dcm2nii tool available through MRICron.
Due to inconsitencies in the way nifti files are created by different software packages, the user is given the option to either use or not use the
transformation matrix in the nifti header. This is controlled with the Reslice NII? option. By default it is turned on, and in most cases this is
desirable. However, if you view your raw DWI images in DIFF_CALC and find that they are oriented in an unusual, or un-desirable way, please
re-import your data with Reslice NII turned off.
An additional option is to Swap XY, Swap XZ, or Swap YZ. The gradient table is expecting the entries to be in the order or READ PHASE SLICE.
If these are swapped, for instance if the phase encoding direction of axial images is changed to Left/Right instead of the standard
Anterior/Posterior, this may be necessary. This should be a rare occurence.
Bruker Data Format

This import routine should be considered Beta, as we have had limited access to Bruker data for testing. Please contact us at
tortoisedti@gmail.com if you encounter difficulties. This will help us to make this routine more robust.
Enter the full path to the bruker raw data directory (or use the button to browse for your data directory). All diffusion data contained within this
directory will be included in the importing. If you have multiple DTI acquisitions which you do not want to be combined, or which have different
acquisition parameters, they should be separated into different data directories.
The users is given the option to Swap XY, Swap XZ, or Swap YZ. The coordinate system of Burker data is complex, and while all efforts are made
to correctly interpret the gradient information, we give the user the option to swap gradient directions in the case that the import is not correct.
< Up >
3.2 Registration settings
DIFF_PREP is a powerful and very flexible registration based motion and distortion correction software. Its flexibility comes from the options
available in the "registration settings" file. The settings in this file let the user customize the behavior of the program according to his needs and to
the user's data.
A sample registration settings file presented in the following pages. The settings displayed are tuned to be applicable to most cases. Therefore,
you might not need to change any settings for most data. However, we strongly recommend the user to analyze the properties of the data, i.e. the
presence of big rotations from the axial plane, noise levels, etc..., and customize the settings accordingly. The following pages describe each
setting individually.
As explained in the Software Installation section, all the registration settings files should be stored in a folder called DIFF_PREP_WORK in the
current user's home directory, with a .dmc extension.
< Up >
3.2.09 Automatic kappa
<automatic_kappa></automatic_kappa>
on
off
During the automatic noise computation process the images are smoothed using Perona-Malik anisotropic diffusion filtering. As previously
explained, this algorithm requires a parameter "kappa" to automatically smooth homogeneous regions and strengthen edges.
This parameter, "automatic_B0_kappa", determines the kappa parameter in that process. If it is set to on, the program automatically determines a
suitable kappa. This is the default value and is highly recommended.
If this is set to any other value, that value will be used for the "kappa" parameter. Reasonable values for this parameter are completely dependent
on your data, and are generally determined using trial and error. A good starting value is ~40. If your images come out looking too smoothed
(such that the center of mass of the image is not preserved) than use a lower number. If the images are not smoothed at all, then user a higher
number. Note: that we highly recommend using the default value for this tag.
< Up >
3.2.08 Automatic noise computation
<automatic_noise_computation></automatic_noise_computation>
on
off
The inherent noise in the DW images is an important property that can drive the registration into local minima. Therefore, the mean and the
standard deviation of the noise in both the b0 image and the structural image have to be known by the program.
DIFF_PREP extracts the brain and pads noise into the blank regions resulting from the transformations applied to the original image.
This setting is to tell the program to compute the noise information from the images automatically and use those values instead of the ones in the
data properties file.
Because the sole purpose of this noise computation is to pad the non-brain regions, it is more important to extract the structural noise information
just outside the brain (which might occur due to parallel imaging) instead of the white noise from the background. Therefore, the algorithm first
finds the brain and then samples pixels from a "halo" just outside of the brain and computes the noise information based on these pixels.
Note: If this setting is turned on, the noise values in the data description file will NOT be used. If the tag is set to off, the noise values in
the data properties file will be used so they must be entered correctly. These values can be roughly approximated by drawing an ROI in the
background of your images, in an area free of ghosting and other artifacts, and measuring the mean and standard deviation within your ROI,
using the image processing software of your choice.
< Up >
3.2.23 BSpline grid size
<BS_EPI_parameters></BS_EPI_parameters>
This value determines the grid size of the bspline registration. The border size is set by default to a value of '3'. The final grid size is then
(BS_EPI_parameters value)+3. The exact value to choose for this tag is not straight forward and will likely take some experimentation based on
your specific data. However, values between 5 and 10 are generally best for this application.
This tag will only take effect if <bspline_EPI_correction> is 'on'.
< Up >
3.2.22 Correction for B0 distortion with BSplines
<bspline_EPI_correction></bspline_EPI_correction>
on
off
Perform bspline image registration based B0 susceptibility induced EPI distortion correction. Options are 'on' or 'off'. The default is 'on'.
< Up >
3.2.21 Working FOV

<cropped_FOV></cropped_FOV>
200,240,190
One can prescibe the field of view (FOV) for the template image. Values are in mm, in the order x,y,z.
The default is set to a reasonable value for whole brain DTI as an example, however, we recommend to set this value such that it leaves a
reasonable amount of empty space around your image.
This FOV is entirely meant for internal workings of the software. This was erroneously reported before as representing the FOV of the final output
images. However, in reality, the final output FOV is the same as the FOV of the structural target image provided in the data description file.
< Up >
3.2.03 DWI-B0 registration (2)
<DWI_B0_registration></DWI_B0_registration>
on
off
This tag is intended for testing purposes only! It is HIGHLY RECOMMENDED to leave this at the default value of 'on'
This tag allows the user to choose not to run the eddy distortion and motion correction algorithm (step 2). If the user wishes to run a quick test of
the code, than they can set this to the 'off' option. However, for any real data analysis, this should be set to 'on', which is the default value.
< Up >
3.2.02 DWI-B0 registration (1)
For this page and subsequent pages describing the registration settings file options the first bulleted item indicates the name of the settings tag,
the next indented bulleted items indicate the possible options. The option in blue is the default setting.
<effect></effect>
rigid
motion_distortion
The first operation that the program performs is the motion correction and eddy current distortion correction. This tag in the registration settings
file determines which type of correction is performed.
If "rigid" is chosen, only rigid body transformations are considered therefore only motion artifacts are corrected.
If "motion_distortion" is chosen, both rigid body transformations and eddy current related distortion transformations are considered and corrected.
In most cases, the "motion_distortion" option is the better one and is set as the default option.
< Up >
3.2.06 Gaussian variance
<gaussian_variance></gaussian_variance>
0.3333
This option is only active if the "smoothing" option is turned on AND the "smoothing_algorithm" is set to "gaussian". It is a floating point value.
The height and width of the Gaussian kernel depends on this variance by the formula:
width= 2* ceil( 3*gaussian_variance) +1
Therefore, with the default value, the height and width of the kernel would be 3.
< Up >
3.2.12 DWI final voxelsize (mm)
<img_resample_res></img_resample_res>
1.5,1.5,1.5
Once all the processing is done, the corrected diffusion weighted images are saved with a specified resolution, defined by this setting. This
describes the voxel resolution that the user wants for the final DWI output in [mm].
Three floating point entries separated with commas should be given for this setting.
WARNING: the smaller the voxel size the more disk space this will take. With this tag set to 1,1,1 we have experienced some memory problems
with IDL. A reasonable value to use for this tag is a slightly higher resolution than your original images. The default value of 1.5,1.5,1.5 was
chosen based on data acquired with 2mm isotropic voxels. If your data is, for example, 3mm isotropic, it may suffice to set this tag to 2,2,2 or
even 2.5,2.5,2.5.
< Up >
3.2.15 Initial global search
<initial_global_search></initial_global_search>
on
off
In some cases, the structural image and the diffusion weighted images may have very different translation and rotation. In these cases, the
steepest-descent based optimization scheme employed in the registration framework may fail and get stuck at a local minima.
When this setting is turned on, an initial rigid-body search is performed with an evolutionary genetic algorithm optimizer. The individuals used in
the population for the genetic algorithm cover a wide range of translations and rotations in between -PI/4 to +PI/4.
The default setting is off because in most cases the structural and b0 images will have similar transformations but if the registration fails because
of big rotations, it is suggested to turn this setting on.
< Up >
3.2.15 ITK Structural registration
<ITK_structural_registration></ITK_structural_registration>
on
off
If this setting is set to 'off' the registration pipeline in DIFF_PREP will be used. If it is 'on', an external ITK library program will be called to perform
this registration.
The optimization procedure built into DIFF_PREP is adjusted to better handle small rotations or small transformation differences in between the
structural and template images (beginning of step 2). If the registration step in between the structural and the template images does not converge
or if that registration does not conform with user's expectations, the user has the option to use the ITK (Insight Toolkit) library to perform this
registration.
Because the ITK registration is optimized to converge in most of the cases, the default setting for this option is 'on'. However, the registration of
structural to template image will take slightly longer, and so the user is given the option to use the faster built in option.
ITK registration pipeline used is:
Initialization of translation with centre of mass of the two images.

Multi-scale registration of 3 resolution levels.
Mattes mutual information metric (number of bins is set 1.5 times the number of bins in the registration settings file).
Trilinear interpolation
3D Rigid Versor transform (to handle large rotations)
Versor Gradient Descent optimizer (to handle non-linear nature of the versor transform space).
< Up >
3.2.07 Kappa
<kappa></kappa>
35
This option is only active if the "smoothing" option is turned on AND the "smoothing_algorithm" is set to anything but "gaussian" (PM, area, or
rician). It is a floating point value.
This parameter, in a way, defines the strenth of the image gradient to be improved. Gradient values below this parameter will be smoothed and
gradient values above it will be strengthened.
The value "35" is chosen based on standard DWI signal values up to 2000. If the user's scaling is different than this parameter should be scaled
accordingly.
< Up >
3.2.33 keep_deformation_field
This tag is NO LONGER SUPPORTED. The deformation field is now required to be saved
< Up >
3.2.32 Keep step4 output
<keep_step4_output></keep_step4_output>
on
off
Step 4 outputs include a large number of files used in the bspline deformation field calculation. It is generally unecessary to save these files.
However, the user is given the option to save them if desired. 'on'=save the files, 'off'=don't save the files.
Default value is 'off'.
< Up >
3.2.14 Mask with bet2
<mask_fsl></mask_fsl>
on
off
The software can determine a bounding box around the brain based on an FSL masking procedure. This is a step intended to optimize the mutual
information algorithm, by reducing the amount of non-brain space in the image. This not only speeds up the processing, but can also improve the
results of the mutual information based registration algorithm.
However, in a few small cases, such as when there is significant head motion during image acquisition, this can result in an image space which is
too restrictive for the images.
In most cases, the default option of "on" is recommended.
< Up >
3.2.11 NBINS
<nbins></nbins>
48
The metric in the registration framework used by the software is the mutual information metric. Mutual information is based on the probability
distributions of the values in both fixed and moving images and these distributions are discretely computed as histograms. The number of bins in
the histograms is defined by the number "nbins".
Increasing this parameter will increase the number of bins used in histogram computations. Generally, the number of bins depends on the range
of values and size of the images but the default value of 48 should work for most cases.
< Up >
3.2.27 Output endianism
<output_endianism></output_endianism>
big
little
Set the endianism of the output data files. Default is 'big' for legacy reasons. Either option is valid, and in general, most MRI image processing
suites should be able to read both big and little endian files.
< Up >
3.2.01 Sample registration settings file






<effect>motion_distortion</effect>





<DWI_B0_registration>on</DWI_B0_registration>





<smoothing>off</smoothing>





<smoothing_algorithm>PM</smoothing_algorithm>



<gaussian_variance>0.33330000</gaussian_variance>



<kappa>35.000000</kappa>





<automatic_noise_computation>on</automatic_noise_computation>





<automatic_kappa>on</automatic_kappa>


<verbose>6</verbose>


<nbins>48</nbins>


<img_resample_res>1.5000000,1.5000000,1.5000000</img_resample_res>


<structural_output_res>1.5000000,1.5000000,1.5000000</structural_output_res>





<mask_fsl>on</mask_fsl>






<ITK_structural_registration>on</ITK_structural_registration>





<initial_global_search>off</initial_global_search>








<upsampling>all</upsampling>


<upsampling_factor>2.0000000</upsampling_factor>






<upsampling_method>bicubic</upsampling_method>







<scale_signal_factor>1</scale_signal_factor>


<cropped_FOV>200.00000,240.00000,190.00000</cropped_FOV_x>



<bspline_EPI_correction>on</bspline_EPI_correction>




<BS_EPI_parameters>5</BS_EPI_parameters>




<eddy_correction_for_B0_to_structural>on</eddy_correction_for_B0_to_structural>





<eddy_correction_for_B0>on</eddy_correction_for_B0>



<image_format>NIFTI</image_format>



<output_endianism>big</output_endianism>


<write_interpolated_variance>off</write_interpolated_variance>


<compute_corr_matrix>off</compute_corr_matrix>




<start_at_step>0</start_at_step>




<stop_at_step>5</stop_at_step>




<keep_step4_output>off</keep_step4_output>




<keep_intermediate_data>on</keep_intermediate_data>
< Up >
3.2.34 save_template
This tag is NO LONGER SUPPORTED. The template image is required to be saved
< Up >
3.2.20 Scale signal factor
<scale_signal_factor></scale_signal_factor>
Use this tag to scale the diffusion weighted image (including b0) intensity. Regular MRI and DTI signal intensities are on the order of 10^3 and this
software works best in this range. If the data in consideration has a different range, this scale factor can be used to scale the signal intensities by
a constant during the upsampling. Will take effect if <upsampling> is 'all' or 'slice_only'. Integer values are expected, with a default value of '1' for
no scaling.
< Up >
3.2.04 Smoothing
<smoothing></smoothing>
on
off
This option enables or disables smoothing of the DWI and structural images prior to registration. Please note that the smoothed images are only
used to compute the transformations from moving to fixed image. After the transformations are computed, the original images are used to create
the registered images.
The default option is "off", as this has not been tested widely. Use at your own discretion.
< Up >
3.2.05 Smoothing algorithm
<smoothing_algorithm></smoothing_algorithm>
gaussian
PM
area
rician
This setting is ONLY active when the "smoothing" setting is turned on. Otherwise, it does not have any effect on the algorithm.
If the "smoothing" option is turned on, the user is able to choose from a couple of options.
1. Gaussian: When this option is chosen, all images are smoothed with a Gaussian kernel. Please note that this option will blur edges and
might destroy some image structures.
2. PM: Perona-Malik Anisotropic gradient based filtering (edge favoring). This smoothing algorithm smoothes the image on regions where
the image gradient is low (non-edge regions) and enhances the regions with high gradients (edge regions). 1
3. area: Perona-Malik Anisotropic gradient based filtering (area favoring). This algorithm is similar to PM but it favors homogeneous
regions instead of edges.
4. rician: Anisotropic filtering with Rician noise bias corrector. THIS OPTION IS NOT TESTED YET and MAY CAUSE THE PROGRAM
TO CRASH.
References
1. P. Perona, J. Malik, Scale-space and edge detection using anisotropic diffusion, (1990) PAMI 12(7), pp. 629-639. abstract
< Up >
3.2.30 Start Stop steps (1)
<start_at_step></start_at_step>
0
3
4
5
This is generally used only if a part of the pipeline needs to be repeated - for example if the bspline registration does not conform to the user's
desired result, it can be repeated without running the eddy distortion and motion correction step, which can save the user a large amount of time.
For a complete description of the processing pipeline steps, please see the FAQ.
The default value is to start at the first step (step 0) for a complete run through of the code.
< Up >
3.2.31 Start Stop steps (2)
<stop_at_step></stop_at_step>
2
3
4
5
Similar to <start_at_step>, this tag allows the user to stop the code running at a desired step. For a complete description of the processing
pipeline steps, see the FAQ.
Default value is to stop after the final step (step 5), in order to complete a full run through the code.
< Up >
3.2.13 Structural final voxelsize (mm)
<structural_output_res></structural_output_res>
1.5,1.5,1.5
This setting is very similar to img_resample_res but it resamples the registered structural analyze image into the desired resolution. It is generally
advantagious to have this set to the same value as img_resample_res.
< Up >
3.2.17 Initial Upsampling
<upsampling></upsampling>
off
all
slice_only
b0_crop
The users are given the option to upsample the DW images, including B0, by a desired factor before starting the registration process. The default
value is all, which will upsample the images as well as perform some other critical operations, as described below.
Note that upsampling is only performed internally before registration in order to improve the quality of the registration results. Only a single
interpolation step is performed on the raw data, using a combination of all transformations calculated in the software. See the pipeline diagram for
more details.
If you are working with data smaller than 256x256, we highly recommend the use of upsampling in this software.
However, if your data is 256x256 or higher we recommend not upsampling due to disk space and memory limitations.
In this case, use the b0_crop option
Description of each option:
off: No upsampling is done and the template image is not created. If this option is chosen, the user needs to define the full path to the
template file in the data description file.
all: The default value. The images are upsampled in all directions (x,y,z). For example an image of size (128x128x100) will be upsampled
to (256x256x200) if the upsampling factor is 2. Please also note that a NEW dataset is created with the new resolution, including the
listfile, B-matrix and path files.
slice_only: The images are upsampled only in slice direction (z). For example an image of size (128x128x100) will be upsampled to
(128x128x200) with upsampling factor 2. Like in the previous case, a new data set is created if this option is chosen.
b0_crop: No upsampling is performed but the B0 image is automatically extracted from the DWI set, and then cropped to fit the desired
FOV and saved as an ANALYZE or NIFTI image to be used as the template image. This is the recommended setting for high resolution
data, and for data that has been zero filled at the scanner.
< Up >
3.2.18 Upsampling factor
<upsampling_factor></upsampling_factor>
1
2
This value determines the degree of upsampling. Default, and recommended value is '2'. If your raw data is 128x128x50 than the resulting
upsampled data will be 256x256x100. If the value is set to '1', there is no change to the data. The upsampling factor is not required to be an
integer value.
If you wish to rename your data (for example to anonymize your data), you can easily do so by providing an anonymized name
in the data description file to something like 'subject_1'. This was formerly associated with the upsampling algorithm, but has
since been made an independent feature. See the data description file section for more information.
< Up >
3.2.19 Upsampling method
<upsampling_method></upsampling_method>
nearest
linear
bicubic
The upsampling method tag determines which algorithm to use for upsampling. Where 'nearest' refers to nearest neighbor, and 'bicubic' is the
default option. This tag will only take effect if <upsampling> is set to 'all' or 'slice_only'.
The method chosen here is also the interpolation method used for the final transformation of the raw images into the final images.
< Up >
3.2.10 Verbose
<verbose></verbose>
6
The verbose level determines how much information is output to the screen. If the setting is 0, almost no information will be output to the user.
With increasing values, more and more information about each step of the registration will be displayed to the user. Default value is 6.
< Up >
3.2.24 write_extra_files
No longer supported! This is now a mandatory field that has been hard coded to 'on'
< Up >
3.2.35 write_fsl_output
NOT SUPPORTED
< Up >
3.2.25 Affine correction for subsequent B0s
<eddy_correction_for_B0></eddy_correction_for_B0>
on
off
This tag allows the user to choose to run a higher order correction algorithm (similar to the eddy and motion distortion correction step) on the B0
images. Normally, the non-diffusion weighted images should only require rigid registration to the first B0 volume. However, in multi-series data B0
images can have differences in scale and/or shear. This tag is by default turned on in order to correct for differences across these B0 volumes.
< Up >
3.2.26 Image format
<image_format></image_format>
ANALYZE
NIFTI
This tag allows the user to choose the input and output format of all images, including the computed maps, such as FA, LI, etc, as well as all
temporary files, and input target images.
Note: if you select NIFTI, all written files will be in nifti format (.nii), however, input images can be in either nifti or analyze (.img/.hdr) format. If you
select ANALYZE all input images must be in analyze (.img/.hdr) format.
Default value is NIFTI.
< Up >
3.2.28 Write noise variance
<write_interpolated_variance></write_interpolated_variance>
on
off
This allows for the writing of noise variance images. The noise variance images provide voxelwise varying noise values for use in the DIFF_CALC
tensor fitting routines. Default value is on,and we HIGHLY RECOMMEND the use of this function. In versions previous to V1.1.2, the default value
is set to "off". Now and in all future releases this will be set to "on".
Note: this options is disabled for Mac OS
< Up >
3.2.29 Compute noise correlation
<compute_corr_matrix></computer_corr_matrix>
on
off
This is only active if <write_interpolated_variance> is set to on. Default value is set to off, as this function has had mixed results. The interpolated
noise variance is still written out, using a heuristically determined noise correlation matrix. See Irfanoglu, M. O., L. Walker, Machiraju, R., and
Pierpaoli, C. (2011). Accounting for changes in signal variance in diffusion weighted images following interpolation for motion and distortion
correction. ISMRM 19th Annual Meeting and Exhibition, Montreal, Canada for more details.
Note: this options is disabled for Mac OS
< Up >
3.2.36 Keep intermediate data
<keep_intermediate_files></keep_intermediate_files>
on
off
This option is intended to help reduce the disk space taken up by extra data. If set to off, all intermediate files will be deleted. This includes
upsampled raw data, and eddy and motion corrected intermediate images. The user will be left with only the final output images (_DMC) and the
original raw data. The deleting of extra files occurs at the very end of the algorithm. Therefore, if something happens to interrupt the software
before it is complete, these files will not be deleted.
The default setting is on which will keep all files. While this takes up more disk space, it allows for more flexibility in the software. If this tag is set
to off then the user cannot restart the software in the middle with the start_at_step tags, as these tags assume certain files exist that will be
deleted by the software.
< Up >
3.3 Optimization Settings
UNDER CONSTRUCTION
< Up
Transformation Files
Description of the transformation files in TORTOISE (v1.0.5)
After running the full diffprep pipeline there should be two transformation files: ..._rpd.transformations and ..._DMC.transformations. The rpd
transformation file contains information about the transformations for the eddy distortion correction and the motion correction. The DMC
transformation file contains information about the final rigid reorientation to the structural target image.
Things to know
Number of rows in the transformation file = number of volumes in your dataset

A volume is defined as the set of images making up the whole brain for a single b0 or DWI measurement
The 1st b0 (i.e. first row if your first volume is a b0 image) is treated slightly differently than the rest of the volumes.
First row: b0 -> structural: If rigid only, this will be 6 parameters, the rest of the columns will be either 0 or 1. If eddy distortion
correction, there will be values for all columns, as described below.
All subsequent rows: DWI (or subsequent b0) -> first b0: the transformation for each row is applied to its volume, followed by the
transformation from the first row.
rpd.transformations
1st set of three columns represents the rigid portion of the transformation (in millimeters)
Column #1 > x (for axial data = RL)
Column #2 > y (for axial data = AP)
Column #3 > z (for axial data = IS)
2nd set of three columns represents the rotational (Euler angles) component of the transformation (in radians)
Column #4 > x
Column #5 > y
Column #6 > z
where
And overall rotation R= Rx Ry Rz
3rd set of three columns represents the weights of the linear affine component of the transformation (shears) (unitless)
Example: if no eddy correction is applied, and you have a horizontal phase encode direction, these values would be x=1, y,z=0
Column #7 > x
Column #8 > y
Column #9 > z
4th set of three columns represents the non-linear component of the transformation (1/millimeters)
Column #10 > xy
Column #11 > xz
Column #12 > yz
The final 2 columns represent the quadratic terms of the eddy distortion correction (1/millimeters)
Column #13 > x2 - y2
Column #14 > 2z2 - x2 - y2
For details on the eddy distortion correction applied, please see; G.K. Rohde, A.S. Barnet, P.J. Basser, S. Marenco, C. Pierpaoli, Comprehensive
approach for motion and distortion correction in diffusion weighted MRI. Magnetic Resonance in Medicine, vol. 51, pp. 103-114, 2004.
DMC.transformations
This file shows the rigid transformation of registering the 1st b0 image to the structural target image, and as such, there are values only in the first
6 columns of the first row. For coding reasons, there will be the number '1' in the 7th or 8th column depending on the phase encode direction, the
7th for a horizontal PE or the 8th for a vertical PE.
All subsequent lines will contain zeros, as the transformation for the 1st b0 volume is applied to all subsequent lines as described above, and the
rigid transformation is calculated from the registration of the 1st b0 volume to the structural target image.
Source Code
If you have access to the source code, the following are relevant files;
apply_trans_dwi.pro
apply_trans_t2.pro
cst_eval_mecc3d.pro
get_epi_coords_from_transformations.pro
FAQ
1. I would like to contribute information to these wiki pages. How can I edit the wiki?
a. If you are interested in contributing to these wiki pages, please contact us at tortoisedti@gmail.com in order to create an account for you.
2. I get the following error message (or something similar) in DIFF_PREP. What does this mean?
% HISTOGRAM: Illegal binsize or max/min.

% Execution halted at: OTSU
a. This occurs when the automatic noise computation algorithm encounters an image (usually the structural target image) which has a zero
background value, or an unexpected range of values. There are 3 possible solutions to this problem.
If this is done on purpose, such as you decide to use a masked structural target (not recommended!), you will need to enter a reasonable
noise value using the optional settings in DIFF_PREP for the background noise padding that is performed in the code.
If you have manipulated your structural target image (such as ACPC re-orientation and skull attenuation) and this has resulted in zero
values in the background, you will need to make sure that your structural image is being stored as floating point values. When the image
stores either integer or short values, when they become small they get rounded to zero and cause this problem. Click here for instructions
on how to change your image's data type to floating point using mipav.
If your DWI data has an usual scaling factor applied, for example, you DWI images range in intensity from only 0 - 1, then this may occur.
Use the "scale signal factor" setting in the registration settings file to scale your DWI images to a reasonable range.
3. I tried to run DIFF_PREP starting at step 5 and stopping at step 5 (i.e. run step 5 only) and it gave a "No such file or directory" error
message regarding file ....list_step4/...
a. Some files from step 4 are deleted at the end in order to save disk space. These files are required for step 5 to run correctly. You will need to
run this starting at step 4 and stopping at step 5. This should only add a couple of minutes to the processing time.
4. I get an error message in the Import side of DIFF_PREP containing the words "GET_DIRECTION". What is wrong?
a. Likely the number of gradient directions acquired and the number of lines in your gradient file are not consistent. Please check that your
gradient file is correct.
5. What is the output naming convention of the software?
a. The naming convention is simple. Your original listfile will be named based on the data directory put into the Import routine. For example, if your
directory is subject_1_data, then your list file will be subject_1_data.list. The output names reflect the following things.
i) subject_1_data_up.list: _up reflects the fact that you have selected the upsampling option in the registration settings file. This listfile contains
data that is upsampled according to your settings.
ii) subject_1_data_up_rpd.list: _up (see 1 above), _rpd means that the data has been run through the motion and eddy current distortion
correction steps. In this example, the data has first been upsampled, then corrected.
iii) subject_1_data_DMC.list: _DMC is the final results of the registration code.
6. I do not have files with _up, or _up_rpd in my procbase. Where are they?
a. If you do not have the above files, but you do have _DMC files, then check the registration settings file that you used. If "keep intermediate
files" is set to off, then it will delete the _up and _up_rpd files after completing the registration procedures.
7. I tried to run the Import routine, but nothing happened. What is wrong?
a. Please check that you have write permissions in the directory where the data directory resides. The import routine is trying to write a parallel
directory to your data directory, and probably cannot save.
8. I get the following error in DIFF_PREP/DIFF_CALC. What does that mean?
% Program caused arithmetic error: Floating underflow

% Program caused arithmetic error: Floating illegal operand
a. This is normal and can happen in both DIFF_PREP and DIFF_CALC. It is a preference of IDL to keep these statments in. It will not affect the
results or functionality of the software in any way.
9. I get the following error (or something similar). What does that mean?
<ObjHeapVar167174>
STRUCT = -> IDLJAVAOBJECT$CGK_SNIE Array[1]
a. This is a known issue with part of the code written in java. It does not interfere with the normal functionality of the software or the results of your
registration in any way.
10. What interpolation method should I use for upsampling the data?
a. The bicubic interpolation method is both visually more appealing and theoretically a better method. This is being more thoroughly investigated.
11. What are the various start/stop steps in the registration settings file?
a. Start at 0: do everything starting from the beginning

Start at 3: assumes that motion and eddy correction are done, and starts with the b-spline computation
Start at 4: assumes same as above, and that the b-spline deformation has been calculated, and starts with applying that to the DWIs
Start at 5: assumes all steps have been computed for corrections, and starts only with the final reorientation to the structural space.
Stop at step 2: will do ONLY motion and eddy corrections

Stop at step 3: will also calculate the b-spline deformation without applying it to the DWIs
Stop at step 4: will do all of the above and also apply the b-spline deformation to the DWIs
Stop at step 5: do everything
Comment:
the Start at/Stop at settings are only intended as a tool in the case that something goes wrong. For example: your computer crashes during the
b-spline correction and you do not want to have to repeat the motion and eddy distortion corrections.
For flexibility such as "don't do the b-spline" or "don't do the motion and eddy" use the "Perform" options in the registration settings file
12. What is step 1?
a. For legacy reasons, there is currently no step 1. What was originally known as step 1 has been integrated into step 0.
13. What is the difference between diffprep.sav and diffprep_gui.sav?
a. diffprep_gui.sav is the main program for DIFF_PREP. diffprep.sav is a command line only version which can only be run with a full idl license. If
you are using the VM, you must use diffprep_gui.sav, or prepvm which is pre-packaged with the IDL VM.
14. The software crashed, and now it doesn't function normally, what do I do?
a. If the software ever crashes, it is STRONGLY ADVISED that you quit DIFF_PREP or DIFF_CALC, and begin again with a fresh copy. This will
assure that all variables and other information that may be stored in the cache are properly removed.
15. I get a permissions error to do with IDL which says something like:
/install_dir/TORTOISE_V1.0.3/DIFF_PREP/diffprep_main/../../idl71/bin/bin.linux.x86/idl: error while loading shared libraries:
/install_dir/TORTOISE_V1.0.3/DIFF_PREP/diffprep_main/../../idl71/bin/bin.linux.x86/libidl.so.7.1: cannot restore segment prot after reloc:
Permission denied
a. This is a permissions issue with SELinux. To get around this you have to change the system settings to permissive or by changing the security
settings on the idl shared object library files
Do this as root in the directory where these files are:
chcon -t texrel_shlib_t *.so
Thanks to Daniel Glen for this fix
16. I get an error about widgets that says something like:

% WIDGET_CONTROL: Invalid widget identifier: 4.
% Execution halted at: TOSTATUSWINDOW
% CONVERT_INPUT_IMAGES_TO_LISTFILE
% DIFFPREP_GUI_EVENT
% XMANAGER_EVLOOP_STANDARD
% XMANAGER
% DIFFPREP_GUI
% IDLRTMAIN
% $MAIN$
a. IDL needs to keep track of the different widget windows that are opened when running the software. If you close any of the widgets using the
"X" at the top corner of any of the windows, it may produce this error. Please always use the "quit" or "done" buttons in the different windows in
order to close them properly.
17. What quantities are calculated during the tensor fitting?
a. See the page on the roi utilities for DIFF_CALC
18. Siemens Mosaic import cuts my images into the wrong number of slices, resulting in partial brain only in each axial slice.
a. This is specifically caused by the software not being able to read the correct FOV, and is most likely to occur in datasets where zero filling was
applied at the scanner. Normally, this information is provided in a private dicom field (0051,100B). If that tag is missing, the software will not be
able to import your data properly. In TORTOISE V1.1.1, a user has discovered that even when that private tag is present, mosaic data is not
being properly imported into TORTOISE. We have identified this as a problem with IDL V8.0 and are working to correct the problem.
19. FSL 4D NIFTI import option in DIFF_PREP gives me an error message "NIFTI file folder does not contain a bvecs file as outputted by
FSL" but there is a bvec file in the data directory. What is the problem?
a. The FSL 4D NIFTI import option requires that the bvalues and bvectors files be named exactly as they would be for running FSL from the
command line. Check that these files are named exactly "bvecs" and "bvals". The dcm2nii from MRICron may output these files as
your_file_name.bvecs and your_file_name.bvals. These files need to be renamed to bvecs and bvals for import to TORTOISE.
20. I get the following error message. How do I fix this?
/TORTOISE_linux_withIDL_V1.1.1/DIFF_PREP/diffprep_main/../../idl80/bin/bin.linux.x86/idl: error while loading shared libraries:

/TORTOISE_linux_withIDL_V1.1.1/DIFF_PREP/diffprep_main/../../idl80/bin/bin.linux.x86/libidl.so.8.0: cannot restore segment prot after
reloc: Permission denied
a. Follow the instructions from this link

http://www.appistry.com/community/forums/content/cannot-restore-segment-prot-after-reloc-permission-denied.
Thanks to user M.S. for this fix.
21. There are "holes" in my tensor/FA maps. Why? What can I do to remove them?
a. This depends on whether the holes are in your TENSOR or in just the ANISTROPY maps. See the 2 solutions below.
Holes in the TENSOR, which results in holes in all tensor derive metric maps such as FA, TR, etc.
If there is a single "zero" value in any one of your DWI's, the software default used to be to mask out that point entirely. Two additional options
exist, one which is to exclude only the zero data points from the fitting, or the second (which should now be set as the default option) is to use a
median neighborhood filtering to fill the zero points. This can be set in your configuration file, which lives in a directory called DIFF_CALC_WORK,
and resides in your home directory (i.e. /user/home/DIFF_CALC_WORK/default_configfile.xml). Simply copy and paste the following lines into
your configuration file, save the configuration file, and open a new instance of DIFF_CALC so that the variables are set appropriately to the new
configuration file.


<mask_zero_point>2</mask_zero_point>
Holes only in the FRACTIONAL ANISOTROPY or other ANISOTROPY maps
We apply masking that is intended to identify voxels with artifactual anisotropy due to flow artifacts, which are known to occur in the CSF and can
result in artifactual FA values. The flow artifact masking we do does not actually create "holes" in the tensor data, but sets the diffusivity to that of
CSF (i.e. free water at 37 degrees) which has an ideal anisotropy value of zero. Thus, if you look at the Trace (TR) map for instance, you should
not see any holes. However, you may see some zero values in the anisotropy maps. If you take a look at the _MF mask image in your _SAVE
directory, it will show you the points where this flow artifact masking is applied.
We realize that having zero values in the anisotropy maps can be problematic for certain things, such as the erosion of masks in FSL's pipeline.
For a future release of our software, we intend to implement a slight im-balance in the diffusivity that is set for those artifactual data points so that
instead of a zero value, there will now be extremely low values in the anisotropy maps, which should prevent some unwanted behaviour in other
software packages.
If you require to remove these zero values from your anistoropy maps before the next software release, we recommend using an image
processing software package such as MIPAV to replace the zero voxel values with a very low value (something like 0.00001) to prevent excessive
erosion of images during masking, or other issues that may arise due to zero values in your anisotropy images.
Thanks to user S.Z. for bringing these issues to our attention
Change Data Type

If you suspect that your (analyze format) image is being saved with either "short" or "integer" data type, you can check this using mipav, and also
use mipav to change it to float.
1) Open your image in mipav.
2) Go to Utilities -> Conversion tools -> Convert type
3) The list on the left hand side of the convert type window will show you what your current data type is (in the above figure it is set to short).
Select float, then click "OK". This will create a new image.
4) Remember to save your new image!
Quick Start Guide

The following pages describe the normal flow of data processing with TORTOISE. First time users should start with section 1. If the software is
already installed, please start with section 2. The final section shows a brief tutorial with the sample data provided.
1. Initial System Setup

2. Starting DIFF_PREP and DIFF_CALC
3. Data import
4. Loading, viewing and inital QC
5. Image Registration and QC
6. Tensor fitting post registration
7. Tutorial
For more information about DIFF_PREP and DIFF_CALC, visit their respective software guides.
DIFF_PREP Software Guide

DIFF_CALC Software Guide
data import
We have modules for importing Philips PAR/REC, GE DICOM, SIEMENS DICOM, SIEMENS MOSAIC DICOM and FSL 4D
NIFTI as part of DIFF_PREP. Please see the Data Importing page of the software guide for detailed instructions on importing
your data.
Data must be imported to a format which our software can read. This is a very simple format consisting of three text files: a header file (.list), a file
of pointers to the raw data (.path) and a b-matrix file (.bmtxt). These are described in more detail in the data format section of the Software Guide
for DIFF_PREP.
The most important step in importing your data is having or creating a correct gradient file. This should be a plain text file with tab or space
separated values (note: this file must be saved as plain text and not as rich text format). The first line must contain the number of volumes in your
DTI data set, and all subsequent lines contain 3 columns with the 3 gradient vector values in the order x y z. There must be 1 row of values for
each volume of your DTI data set. If you use multiple b-values in your acquisition, the gradient vectors must be scaled down according to the
b-value as described in Mattiello, et al 1. The sample gradient file below contains 6 directions plus 1 b0, repeated 4 times at b = 1000s/mm 2, and
2 times at b = 500s/mm 2 for a total of 42 volumes. The b500 volumes were acquired in the middle, with 2 b1000 sets before and after.
42
0.00000 0.00000 0.00000
0.707107 0.00000 0.707107
-0.707107 0.00000 0.707107
0.00000 0.707107 0.707107
0.00000 0.707107 -0.707107
0.707107 0.707107 0.00000
-0.707107 0.707107 0.00000
0.00000 0.00000 0.00000
0.707107 0.00000 0.707107
-0.707107 0.00000 0.707107
0.00000 0.707107 0.707107
0.00000 0.707107 -0.707107
0.707107 0.707107 0.00000
-0.707107 0.707107 0.00000
0.00000 0.00000 0.00000
0.500000 0.00000 0.500000
-0.500000 0.00000 0.500000
0.00000 0.500000 0.500000
0.00000 0.500000 -0.500000
0.500000 0.500000 0.00000
-0.500000 0.500000 0.00000
0.00000 0.00000 0.00000
0.500000 0.00000 0.500000
-0.500000 0.00000 0.500000
0.00000 0.500000 0.500000
0.00000 0.500000 -0.500000
0.500000 0.500000 0.00000
-0.500000 0.500000 0.00000
0.00000 0.00000 0.00000
0.707107 0.00000 0.707107
-0.707107 0.00000 0.707107
0.00000 0.707107 0.707107
0.00000 0.707107 -0.707107
0.707107 0.707107 0.00000
-0.707107 0.707107 0.00000
0.00000 0.00000 0.00000
0.707107 0.00000 0.707107
-0.707107 0.00000 0.707107
0.00000 0.707107 0.707107
0.00000 0.707107 -0.707107
0.707107 0.707107 0.00000
-0.707107 0.707107 0.00000
If you find that the bmatrix is incorrect for your data (see Loading, viewing and inital QC), then try to use the "Flip" radio buttons in the import
module to adjust your gradient file appropriately.
If you have data in another format other than those listed above, you can manually create your .list, .path and .bmtxt files, according to the
descriptions in the above listed pages. Supported raw data formats are: integer, float, and dicom.
We hope to include support for raw DWI data in analyze format and Philips dicom in a future release.
< Up >
References
1. Mattiello, J., Basser, P.J., and LeBihan, D. (1997) The b matrix in diffusion tensor echo-planer imaging. Magn Reson Med. 37:292-300.
pdf
diff_calc loading
After importing the data, it is possible to immediately use DIFF_PREP for image registration and artifact correction. However, it is advisable,
particularly if you are new to this software, to load your data into DIFF_CALC and inspect the raw data, then perform a simple linear tensor fitting
to make sure that the b-matrix is correct.
1. Start DIFF_CALC follwing the instructions.

2. Click on load images and select your listfile.
3. To inspect the raw data, click on display raw images and use the SLICES and B_VALUES sliders to look through the volumes and slices
of your data. This is shown in detail in Display Raw Images
4. To do a quick linear tensor fit
first click on estimate signal SD to estimate the image noise by either drawing an ROI in the background, or specifying an a priori
value
then click on mask raw images to calculate a brain mask
then select the "opt" button to the right of the process tensor button and select the linear fitting option
5. When the fit is complete, click on roi utilities, and inspect the linefield and the DEC maps in order to assure you have a correct b-matrix.
The figures below show correct and incorrect linefield and DEC maps for one dataset.
The following figure shows some images of a tensor fit with the y-gradient flipped incorrectly. From left to right 1) absolute value DEC map. It
looks reasonable. 2) The Linefield image - note the vertical tensor direction in the splenium of the corpus callosum. This indicates there is a
problem with the gradient file provided. 3) The no symmetry DEC map on a lower slice in the brain - note the pink and orange colors in the internal
capsule. This is incorrect.
The following figure shows the same slices as the previous figure, but with the y gradient flipped. Note the continuous left-right tensor directions in
the corpus callosum on the linefield image, and the correct green and blue colors in the internal capsule.
Please click on the linked pages to get more details about the above steps.
< Up >
image registration
The DIFF_CALC module of TORTOISE is intended for image distortion correction, using image registration techniques. The details on using this
software are outlined in the DIFF_PREP Software Guide.
To run the software, start the software as described in the Starting DIFF_PREP and DIFF_CALC section. This will open a GUI which has two
panels. The panel on the left is used for importing the data. The panel on the right contains both required and optional fields for running the image
distortion correction routines. The most important field will be the registration settings file. This is a pseudo xml file (with extension .dmc) which
contains all of the various settings for running the software. The user can have multiple registration settings files. All of these will be stored in the
DIFF_PREP_WORK directory.
Details for running the software and the registration seettings file are described in the links below:
running DIFF_PREP: Running DIFF_PREP with GUI

registration settings files: 3.2 Registration settings
Post Registration QC check
It is important to check the quality of the eddy and motion correction and the susceptibility induced EPI distortion correction .
Eddy and Motion Correction QC
load the _DMC.list file in DIFF_CALC

click on display raw images
select a slice in the middle of the brain, where you can see some major white matter structures.
click on B_VALUES and scroll through all measurements for the same slice. Make sure the brain appears stationary in your
screen. There should be no apparent motion of the brain in the FOV, and no stretching effects due to eddy distortions.
click on SLICES and go to a slice high in the brain. Click on B_VALUES and scroll through all measurements for that slice, again,
looking for apparent motion and distortion in the images. At the top of the brain it is often easier to see the effects of eddy
distortion.
click on SLICES and go to a slice low in the brain where the brain stem is visible. Click on B_VALUES and scroll through all
measurements for this slice. At this level, it is often easier to see residual motion.
The following 2 movies show an uncorrected dataset with some motion and eddy distortion visible in the left-right direction (due to the
phase encoding direction being LR). The second is the same dataset corrected. Note that the motion and eddy distortions are no longer
present. The apparent size difference of the two images is due to the resampling of the final output data to 1.5mm isotropic from the
original 1x1x2mm resolution.
These movies require Quicktime. If you have trouble viewing them, please install Quicktime, or download the AVI files below to view locally
Uncorrected DWIs
Corrected DWIs
Download Files
AVI Format
uncorrected_DWIs.avi
corrected_DWIs.avi
Quicktime Movie Format
uncorrected_DWIs.mov
corrected_DWIs.mov
B0 susceptibility induced EPI distortion QC
The BSpline algorithm has some inherent instability, and can sometimes be affected by bright signal in the soft tissue, or other factors. For this
reason, we STRONGLY RECOMMEND that the following QC steps are taken to check that no unwanted warping has occurred in the brain.
With your favorite image viewing and ROI drawing software (we generally use mipav), load the following 3 images
_rpdtemplate.nii -> this is the original distorted b0 image located in the _proc directory.
_rpdstructural.nii -> this is the T2 structural target image provided by the user, which has been co-registered into the native
space of the DWI images, and so should be in the same space as _rpdtemplate.nii. It is also located in the _proc directory.
template.nii -> this is the b0 image after correction, located in _deformation_field directory inside the _proc directory.
This figure shows some of the possible instabilities in the brain stem area. Likely, soft tissue was the driving force in the registration at this
location, resulting in a stretch of the brain stem. If this occurs, you can re-run the software and adjust the bspline grid size. The bad correction
here was achieved with a bspline grid size of 7, and the good correction was achieved with a bspline grid size of 10.
Sometimes the differences are not quite as obvious as in the above figure. So it is a good idea to draw some ROIs on both the whole brain, and
several brain structures, such as the corpus callosum and the brain stem, to double check that the correction is good. To do this, define the ROIs
on the structural target image (_rpdstructural.nii) and then copy them to _rpdtemplate.nii and template.nii. The ROIs should match well on
template.nii and _rpdstructural.nii. You may be amazed at the amount of correction visible in the genu of the corpus callosum!
As in the above figure, it is also useful to rotate your images to the sagittal or coronal planes to view the correction. Another good correction is
shown below in the sagittal plane, showing a whole brain ROI defined on the T2 structural image, and copied to the b0 before and after correction
images.
< Up >
diff_calc fit
After registration, you will have some new files in your proc directory. The final results is contained in the _DMC.list file. Load the _DMC.list file
into DIFF_CALC, and follow the same directions as for the quick linear fit, but change the settings to use nonlinear tensor fitting.
To do a nonlinear tensor fit

first load your list file (after standard registration with DIFF_PREP, this will be called _DMC.list), and inspect the registered
images.
then click on estimate signal SD to estimate the image noise
then click on mask raw images to calculate a brain mask
(optional) click on display mask to inspect the mask. If necessary, use the "opt" button beside the mask raw images button to
adjust the masking parameters to create a better mask.
then select the "opt" button to the right of the process tensor button and select the nonlinear fitting option
click on process tensor
When the fit is complete, click on roi utilities to view the tensor derived metric maps. The tensor fitting can be checked for QC again by
looking at the DEC no symmetry map and the linefield. However, if this was performed on the raw data, then it is unecessary at this time.
< Up >
running tortoise modules

There are 3 options for running the software. Starting from inside the TORTOISE distribution directory, do the following:
With distributed IDL VM
For DIFF_CALC:
Go to DIFF_CALC/diffcalc_main
Type calcvm
For DIFF_PREP:
Go to DIFF_PREP/diffprep_main
Type prepvm
With IDL VM installed separately (We highly recommend using the above option, as this method has resulted in some
errors reported by users).
For DIFF_CALC:
Type idl -vm

Select diffcalc
For DIFF_PREP:
Type idl -vm

Select diffprep_gui
With IDL license
For DIFF_CALC:
Type idl
Type diffcalc
For DIFF_PREP:
Type idl
Type diffprep_gui for GUI version
Command line version exists, and is described in the from Command Line section
An important note: if you are running the software on a Mac, be sure to use the 32 bit IDL VM. This can be done from
the command line by typing idl -vm -32
If you get the message "command not found", try running ./calcvm or ./prepvm to start the IDL VM versions of the
software
Additional details for DIFF_PREP and DIFF_CALC can be found at the following links.
DIFF_PREP installation instructions: 1.2 Installation
DIFF_CALC installation instructions: 1.3 Installation
< Up >
system setup
The current release of TORTOISE requires linux or intel based Mac OSX. It runs with either an IDL license, or the IDL Virtual Machine (VM). The
IDL VM is distributed with the software, so you do not need to install the IDL VM at this time.
If you need to, or wish to install IDL including the IDL VM, it can be downloaded from the ITT website http://www.ittvis.com/. Detailed instructions
on installation of the IDL VM can be found here: 1.3.4 IDL VM.
Download and untar the TORTOISE distribution tarball found on the TORTOISE DOWNLOAD page to any convenient location which does not
contain spaces in the path. In the TORTOISE directory you will see 3 folders: DIFF_CALC, DIFF_PREP, and IDL71 as well as a readme and the
license agreement. These contain the 2 TORTOISE modules and the pre-packed IDL VM respectively. A separate download is available
containing sample data. No further installation steps are necessary!
When you first run DIFF_CALC and DIFF_PREP new folders will be created called DIFF_CALC_WORK and DIFF_PREP_WORK respectively, in
your computer's home director. These directories are used for storing configuration and settings files, as well as for writing out log files and
temporary files.
Running the software is described on the next page.
< Up >
Version Update Notes

Updates to TORTOISE Version 1.3.0
Phantom Analysis - a new utility included in TORTOISE
This utility is for analysis of multi-center diffusion tensor phantom data, as described in Walker, L., et. al., A framework for the analysis of phantom
data in multicenter diffusion tensor imaging studies. Human Brain Mapping 2012 (Epub ahead of print).
The user provides a list of co-registered tensor derived metrics (i.e. FA, TR, etc), and the utility computes 1) the difference of each input image
from the median of all images, and 2) the inter- and intra-site variance, variability and ICCs.
Updates to DIFF_PREP:
1. Bruker import improved. Problems with repeats and averages fixed.

2. A bug in PAR/REC import fixed, and routine made more robust.
3. In Siemens Mosaic import, the user can now input the number of images in a single row of the mosaic. Occasionally, the needed
information to automatically chop up the mosaic into individual axial slices fails. Providing this input will correct this problem.
4. Jacobian modulation for EPI correction and noise estimation is no longer being applied. This modulation is still being applied for Eddy
current distortion correction.
5. Additional new import options include:
Flip slice order TORTOISE assumes a frame of reference in which datasets are acquired inferior to superior (i.e. first slice is
closer to the cerebellum, while last slice is closer to the top of the skull). If data is acquired in the superior-to-inferior slice order,
this option should be used. Note: this was previously available, but contained a few bugs that have been fixed.
Reslice NII for FSL nifti import by default, TORTOISE uses transformation information contained in the nifti header. If, after
import, the user finds that their data is not oriented as desired, this option can be turned off.
Swap gradients - the user is given the option to swap x and y, x and z, or y and z gradients (i.e. swapping the columns of the
gradient table). TORTOISE assumes that the gradient vectors are in the order of read, phase, slice. This may not be correct if,
for example, a left-right phase encoding is used for axial DTI acquisitions. In that case, the x and y gradients (read and phase)
may need to be swapped.
6.
6. We now support Philips DICOM format.
7. Similar to the Reslice NII for nifti import, there is a Reslice NII option for the structural image. If the nifti header contains a transformation
that the user DOES NOT wish to apply, then this option should be turned off. Due to reference frame conventions, this will often result in
the structural image being flipped in the Anterior Posterior (AP) direction. See number 8 below on fixing this.
8. If the user finds that their structural image is being flipping in the AP direction, then the option to flip AP is now available to the user.
IMPORTANT NOTE: If the user needs to play around with the Reslice NII and flip AP options, we HIGHLY RECOMMEND that
the user double checks that there has not been any un-wanted flipping in the Left-Right direction. This can be done by visually
comparing a non-diffusion weighted (b0) image and your structural target image for mirror symmetry. Take a look particularly at
the ventricles, which are often asymmetric between hemispheres. If you have already run your data through diffprep, then this
can be compared using _b0_orig_crop.nii and _rpd_structural.nii, which should both be in your _proc directory. If your
structural target is flipped Left/Right compared to the b0 image, then you should use image software, such as Mipav, to flip your
structural target image Left/Right to match the diffusion data.
9. Optimized parameters for using DIFF_PREP for distortion corrections on rat brain are available. Contact us for more details if you are
working with rats, or other small sized animals/objects.
Updates to DIFF_CALC:
1. Fixes to issues which caused the software to crash with Mac OS X Lion (10.7).
2. Updates to the GUI of the tensor fitting options menu.
3. Automatic noise estimation using robust methods now provides the option to enter the fraction of datapoints that the user would like to be
considered as outliers. Default value is 0.05 (i.e. 5%), which is conservative. With 30 directions, 10% gives reasonable results, in our
experience.
Please report any issues, errors, etc, to tortoisedti@gmail.com. If you encounter difficulties in importing your raw data, please let us
know, as we are continuing to improve those routines.
A few important fixes were implemented in this version. This version should REPLACE version 1.2.1, which is no longer available for download
from www.tortoisedti.org.
1. Structural images provided in NIFTI format were sometimes being flipped in the AP direction. This bug has been fixed.
2. Bruker import was having problems with importing 3D sequences. This has been corrected.
1. The triplanar viewer ROI functions in the coronal and sagittal planes now functions normally.
2. Export for TrackVis images were previously displayed flipped in the AP direction, due to an issue with the way TrackVis reads NIFTI
images. We have now accounted for this flipping in our output for TrackVis. Be aware that if TrackVis changes their convention, then
output from TORTOISE may be flipped again in the future.
3. GMM based automatic noise estimation is now accessible in the Estimate Signal SD opt button. This is the most robust automatic noise
estimation, and is recommended.
The updates in this version are mainly small bug fixes. A few things of note:
1. In version 1.2 of the software, Siemens import automatically rotated the bmatrix to account for oblique acquisitions. Due to user demand,
this is now an option. The default is on. A radio button is provided to turn this option off.
1. The triplanar viewer still has some problems with ROI drawing in the sagital view. ROIs are supported only in the axial and coronal
planes.
2. There are now options for running iRESTORE. See the iRESTORE ISMRM abstract for more details. In general, iRESTORE should be
used ONLY when all artifacts in the data result in signal dropouts, such as cardiac pulsation. It is intended to be used in low redundancy
(less than 30 DWI volume) datasets, which have dropout type artifacts.
TORTOISE_V1.2
LINUX and MAC compatible.
The main update to version 1.2 is that this version is once again Mac compatible. The issue was due to the way Mac OS handled files in memory.
All issues related to the Mac OS should now be resolved.
1.
1. Due to reported problems from many users in importing data, the following import routines have been updated to be more generalized:
Siemens DICOM, Siemens Mosaic DICOM, GE DICOM, Philips PAR/REC
2. An import routine has been added for Bruker data. This function should be considered a beta release. Please report any problems you
may encounter with this routine.
3. For oblique acquisitions, the gradient table is now automatically rotated for all Siemens data (standard or mosaic).
4. The optional reorientation file code has been re-written to address some bugs with noise padding, and now the code outputs a file called
_REORIENTATION.nii if a reorientation file has been specified.
1. A bug in export to nrrd format has been fixed

2. The tri-planar viewer has been updated to i) fix some bugs in saving the ROIs, ii) it is now possible to display the structural image, and iii)
ROI drawing can now be done on all 3 planes, while before it was only supported in the axial plane.
3. The function "inspect entire set" within display raw images now allows for a magnification factor of 0.5 to enable large FOV images to be
viewable on smaller monitors.
4. A new automatic noise estimation routine has been included, which uses GMM for robust estimation. In the case where there is at least
one bad volume in your DWI dataset, then the automatic method previously implemented may provide a biased noise estimate. This new
method should be used in these cases.
TORTOISE_linux_V1.1.2
The main reason for this update is to correct a bug introduced in IDL version 8.0 which interfered with the Siemens Mosaic Dicom import function
in DIFF_PREP. In datasets with zero filling (i.e. upsampled by the scanner), the FOV was sometimes read incorrectly, resulting in incorrect slicing
of the mosaic. This was tracked down to a problem in reading the private tag (0051, 100B) by IDL. This was corrected in IDL version 8.1 released
in April, 2011.
A minor change to TORTOISE version 1.1.2 is related to the new voxel-wise noise estimation released in version 1.1.0. (This was an option that
by default is set to off, but can be turned on by using the option "Write noise variance" in DIFF_PREP). This was initially released in version 1.0.3
as a beta function. This function continues to undergo testing, and is still considered under development. The current changes include:
If write noise variance was turned on, it is possible that the automatic noise estimation in DIFF_CALC may produce incorrect results. In
particular, this can impact negatively on RESTORE robust tensor estimation. In version 1.1.2, this behavior has been corrected.
The implementation in version 1.1.1 uses a jacobian correction to the noise variance map. The implementation in the new version 1.1.2
does not use this jacobian correction. This correction is still under active investigation.
Recommendations: if you used the "write noise variance" option in version 1.1.1 and if you did use, or want to use RESTORE robust estimation,
please re-run the tensor fitting using DIFF_CALC in version 1.1.2. Otherwise, no action needs to be taken.
If you are unsure whether you used the write noise variance option, look in your _proc directory. If you see the file _DMC_noise.path and the
directory _DMC_noise_info, then this option is turned on, and you need to follow the above recommendation. You can also check your registration
settings file to see if that option is set to "on".
If you would prefer to not use the noise variance maps that you computed, either move or delete the _noise.path and _noise_info file and directory
from your _proc directory, and re-run any tensor fitting previously performed. The software will function properly without these files.
Minor fixes
1. Fix to Siemens import (regular and mosaic): previously, an incorrect bmatrix was calculated if sequence contained b0 images as the first
volume, the middle volume AND the final volume. In this limited case, the bmatrix would only contain the value zero.
2. Fix to Siemens import (mosaic only): previously, if the maximum b-value was supplied for Siemens mosaic import, then occasionally the
DWI images would not be sorted properly, resulting in a single brain volume having its slices in an apparent random order.
UPDATE Feb. 4, 2011: A user has discovered a bug in V1.1.1 in which Siemens Moasic datasets which have zero filling applied at the scanner
are not being properly imported into TORTOISE. We have identified this as a problem with IDL V8.0 and are working to correct the problem.
Only a few small bugs have been fixed between version 1.1.0 and version 1.1.1 as listed below:
A bug in the compiled ITK library for the EPI correction was fixed. The bug was causing DIFF_PREP to crash when it reached the EPI
correction step, with the message "segmentation fault".
The user-input noise value (in DIFF_CALC Estimate Signal SD) was non-functional. This has been corrected.
Excess print statements in the tri-planar viewer have been removed.
And more details about updates to V1.0.5
Many updates occurred after TORTOISE version 1.0.4. These are described briefly below, with the version of update indicated for each. Updates
are categorized by the specific module.
Affecting both modules:

Release version 1.1.0 is intended for use with LINUX ONLY. We are having some troubles with the Mac platform which we are working to resolve.
A MAC ONLY version will be released when we are able to resolve these issues. It is possible that some segmentation fault or bus errors will
occur using version 1.0.5 with a Mac.
Additionally, we were made aware that newer flavours of linux were having difficulties with files compiled with older versions of IDL and linux. We
are repackaging the software with IDL version 8.0 and compiled using CentOS 5.5. We are releasing two versions of TORTOISE 1.1.0, mainly
one packaged with IDL 8.0 (which is a very large file for download) and a stripped down version which is appropriate for people with IDL
pre-installed with a license, or willing to download and install the IDL VM from the itt website.
Please report any bugs in running the software to tortoisedti@gmail.com.
DIFF_CALC
1. A bug in the export to FSL command was fixed. The bug occurred when the 1st image of your dataset was not a b0 image. (1.1.0)
2. A triplanar viewer was added, with 3D ROI drawing capabilities. This has not been documented on the website yet, but is somewhat
intuitive. Documentation will be posted as it is available. (1.1.0)
3. A delete volume function was added in order to help remove data that is badly affected by artifacts. We highly recommend using this
function with caution. Removal of volumes changes your experimental design, which can result in an ill conditioning of the tensor. (1.0.5)
4. A function called Inspect Entire Set has been added. This allows the user to inspect either all b0 images of a particular slice, or all slices
of a particular volume on one screen. (1.0.5)
5. Additional masking options have now been included. (1.0.5)
6. An updated version of bet is now being used. This requires that the FLSOUTPUTTYPE environment variable to be set to NIFTI or
NIFTI_GZ, as bet no longer supports writing ANALYZE format images. (1.1.0)
7. The tensor derived quantity skewness has been added as an output of the tensor fitting. This is calculated according to the definition in
the following ISMRM abstract: C. Pierpaoli, L. Walker, M. O. Irfanoglu, A. Barnett, P. Basser, L-C. Chang, C. Koay, S. Pajevic, G.
Rohde, J. Sarlls, and M. Wu, 2010, TORTOISE: an integrated software package for processing of diffusion MRI data, ISMRM 18th
annual meeting, Stockholm, Sweden, #1597 (1.1.0)
8. Voxel-wise noise (as calculated in DIFF_PREP, see item number 7 below) is now used for all non-linear tensor estimation routines. The
noise correlation matrix contains values between 0 and 1, and is then scaled by the noise value entered by the user with the Estimate
Signal SD function in DIFF_CALC (see item number 9). (1.1.0)
9. Estimate signal SD now has an automated option. Instead of the user manually defining an ROI in the background, the software creates
an informed mask based on knowledge of systematic physiological noise artifacts. Tensor fitting is performed within this informed mask
only, and the noise is estimated from the fitting, as described in the appendices of Walker L, Chang LC, Koay CG, Sharma N, Cohen L,
Verma R, Pierpaoli C.Effects of physiological noise in population analysis of diffusion tensor MRI data. Neuroimage. 2011 Jan
15;54(2):1168-77. This noise estimation is the default option. (1.1.0)
10. RESTORE robust tensor estimation is now an option Chang, L.C., Jones, D.K., and Pierpaoli, C. (2005) RESTORE: Robust
estimation of tensors by outlier rejection. Magn Reson Med. 53:1088-1095. We HIGHLY recommend using the automated noise
estimation when fitting with RESTORE (item 9 above), as the noise assessment must be reasonable for a good result with this routine.
(1.1.0)
DIFF_PREP
1. Importing of 4D analyze and 4D nifti files to our format is now supported. This requires the FSL bvecs and bvals files for creation of the
bmatrix. (1.1.0)
2. The Siemens mosaic dicom import function has been re-written, as we have had many reports of problems with this feature in the past.
Additionally, there was a bug with importing mosaic files that had zero filling applied at the scanner. This bug has been fixed. (1.1.0)
3. The ParRec import function has been improved. Previously, the user could only import a single ParRec file at a time. The software can
now import multiple ParRec files at once, only in the case that a single acquisition is spanned over multiple ParRec files (i.e. this cannot
be used to combine different acquisition together). In this case, all ParRec files must exist in a single directory. The software will detect
which ParRec files contain DTI data, and combine them all into a single .list, .path and .bmtxt file, and also performs intensity correction
for gain differences between ParRec files. (1.1.0)
4. The initial registration performed between the b0 and structural target image in DIFF_PREP utilizes the ITK library. Previously, if there
was an ITK error the software would either quit unexpectedly (with no error messages if using the IDL VM), or continue despite the
problem with ITK. In the updated version, ITK errors are now captured while using the IDL VM, and if an error occurs, the software will
default back to using the non-ITK based registration algorithm available in DIFF_PREP. (1.1.0)
5. A new higher order distortion correction for b0 images has been added to DIFF_PREP. This applies an affine plus quadratic term
registration (similar to the eddy and motion correction algorithm) to register the first b0 image to the structural target image. This is
intended to correct large distortions due to bad shims. This is by default turned "on" however, it can be turned off in your registration
settings file in the GUI by changing the setting "B0 to structural Eddy distortion correction" or in your settings file proper, by setting the
following tag: <eddy_correction_for_B0_to_structural></eddy_correction_for_B0_to_structural>. In addition, this correction is by default
applied to subsequent b0 images, but can also be turned off in your registration settings file in the GUI by changing the setting "affine
correction for subsequent B0s" to off, or in your settings file proper by setting the following tag: <eddy_correction_for_B0></
eddy_correction_for_B0> . Note: in our experience, if you are using a T1 as your target image for registration, it is often a good idea to
turn these 2 options off, as the bright skull of that modality tends to drive the registration and creates unwanted additional
distortions.(1.0.5)
6. A bug related to field of view (FOV) has been fixed. In previous versions of the software, if the FOV was extremely close to the tissue
being imaged, then DIFF_PREP could remove up to 2 voxels from the edge of each image. This resulted in, for example, the top of the
brain or the cerebellum being cut off by DIFF_PREP even when full brain coverage was achieved at the scanner. (1.0.5)
7. A voxel-wise noise estimation has been introduced for the correction of a bias in the variance of the signals due to noise in the images
which is introduced by interpolation as described in Rohde, G.K., Barnett, A.S., Basser, P.J., and Pierpaoli, C. (2005) Estimating
intensity variance due to noise in registered images: Applications to diffusion tensor MRI. Neuroimage 26:673-684. This was
introduced in TORTOISE version 1.0.3 as a beta function. Based on testing, we have found a solution that works for most data. This is
set by using the "write noise variance" setting in the registration settings GUI, or by the tag <write_interpolated_variance></
write_interpolated_variance>. The default value is off for this function. However, if the user intends to perform statistical operations on the
tensor derived quantities (i.e. TBSS style analysis), then we strongly recommend turning this option on. (1.1.0)
TORTOISE_V1.0.5
Note: the "About TORTOISE" button reports that this is version 1.0.4. This is a typo. We apologize for any confusion.
fixed a bug in the export for FSL routine in DIFF_CALC
added new masking options for DIFF_CALC
added the ability to remove a single brain volume in DIFF_CALC. This is intended for removal of data badly affected by artifacts.
However, we recommend caution in removing volumes from your data, as the effects of volume removal have not been systematically
tested, and may be different for different acquisitions.
A new correction has been added to DIFF_PREP. This applies an affine plus quadratic term registration (the same as the eddy and
motion correction algorithm uses) to the first b0 image, registering it to your structural image. This is intended to correct large distortions
due to bad shims. This is by default turned "on" however, it can be turned off in your registration settings file in the GUI by changing the
setting "B0 to structural Eddy distortion correction" or in your settings file proper, by setting the following tag:
<eddy_correction_for_B0_to_structural></eddy_correction_for_B0_to_structural>
A bug related to FOV in DIFF_PREP has been fixed: in previous versions of the software, if the FOV was extremely close to the tissue
being imaged, then DIFF_PREP could remove up to 2 voxels from the edge of each image.
there were occasional problems related to a small piece of java code used in the software for voxel-wise noise estimation. This can now
be avoided by setting <compute_corr_matrix>off</compute_corr_matrix>.
TORTOISE_V1.0.1
fixed a bug with the FSLOUTPUTTYPE environment variable. Now the software works completely independent of the FSL settings if the
user has a separate installation of FSL
fixed a bug with reading data. Previously if the DIFF_CALC settings file was set to ANALYZE, and the data was NIFTI, restore session
would crash
fixed the weighting factor for the linear fitting in DIFF_CALC
included an option in DIFF_PREP for anonymizing data
TORTOISE_V1
The initial release of Tortoise.
Utilities
TORTOISE now includes DTI related utilities. In release version 1.3.0, the first utilitiy is included, which is for the analysis of variance in phantom
DTI data. We expect to include additional utilities in future releases.
Software Guides for Utilities:

Phantom variance analysis
var_gui
The Phantom Analysis utility implements the two-step analysis framework for multi-center DTI studies as described in our recent publication in
Human Brain Mapping. 1
Two-step analysis framework

Step 1: Voxel-wise median image is computed from all input images. Difference images are computed for each timepoint from the median image.
Step 2: assessment of overall variance, similar to the definition of the traditional ANOVA, compute the intrasite (i.e., within site) and the intersite
(i.e., between sites) variances. In addition, we compute the variability (i.e. standard deviation) maps, and ICC coefficients.
Preparing your phantom data for analysis:
1. Pre-process your data using DIFF_PREP, including correction for motion, eddy current distortion and EPI distortion.
Use a common target image for the corrections, a good choice might be a T2W image from the 1st timepoint of the phantom.
Using a common target is important, as this analysis is performed on a voxel-wise basis, and assumes that the input
images are decently co-registered.
2. Compute the tensor and tensor derived metrics using DIFF_CALC.
3. Create a text file listing the full path to all site and all time point images. An example text file with appropriate format is shown below.
The analysis should be run, at a minimum, on fractional anisotropy (FA) and trace of the diffusion tensor (TR). It can be run on
any tensor derived metric. Interpretation of the results may be difficult for metrics that include negative numbers, such as
skewness, and should be used with caution on this type of metric.
To run the software:

First, navigate to TORTOISE_V1.3.0/Utilities/Phantom_Analysis, then do one of the following options:
1. double click on varvm

2. type varvm (or ./varvm) at the command line
3. If IDL VM is installed: type idl -vm=var_gui.sav at the command line
4. If IDL full version is installed: start IDL, then type var_gui at the IDL command prompt
Click on the splash screen, and a GUI will pop up that looks like:
Using the software:

1. Use the browse button (at right) to input your data file. The data file is a text file that lists the number of timepoints at each site on
consecutive lines, followed by the full path to each image file in the same order.
Example: Two sites, Site 1 has 4 timepoints, and Site 2 has 3 timepoints.
4
3
/data/site1_timepoint1_proc/site1_timepoint1_N1_SAVE/site1_timepoint1_FA.nii
Make sure there are no blank lines at the end of the text file, or the software may crash
2. Use the browse button (at right) to provide your desired output directory.
3. Click COMPUTE
Outputs of the software:

In the provided output directory, there will now be a subdirectory called outlier_analysis, and 7 nifti images.
1. outlier_analysis folder contains the difference from median image for each input image.
example: diff_site1_timepoint1_FA.nii, diff_site1_timepoint2_FA.nii, etc.
2. icc_inter.nii - between sites ICC
3. icc_intra.nii - within sites ICC
4. intersite_variability.nii - between sites variability
5. intersite_variance.nii - between sites variance
6. intrasite_variability.nii - within sites variability
7. intrasite_variance.nii - within sites variance
8. mean_img.nii - mean image computed from all input images
Formulas for the various quantities are defined in Walker, et. al. 1
References
1. Walker, L., Curry, M., Nayak, A., Lange, N., Pierpaoli, C., and the Brain Development Cooperative Group, A Framework for the Analysis
of Phantom Data in Multicenter Diffusion Tensor Imaging Studies, Human Brain Mapping, 2012, PMID:22461391 (early view)

TORTOISE v130 Manual June 29 2012

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

TORTOISE v130 Manual June 29 2012

Hochgeladen von

Copyright:

Verfügbare Formate

1. Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The current release is TORTOISE V1.3.0, available on the download page

Click here for version update information.

To get started with TORTOISE: Quick Start Guide

*See note at bottom of the page

For internal NIH collaborators only

Automated 2,14 and manual (ROI based) image noise estimation

For access to the Software Guide click here

For frequently asked questions, please visit our FAQ

DIFF_CALC Software Guide

This guide is organized as follows:

In Software Overview we briefly describe the functionality of the software.

In Usage instructions on how to use the software are given.

Special thanks to the members and contributors to the software:

Dr. Peter Basser

In this section, the installation procedure for DIFF_CALC will be described.

1.3.1 System Requirements

1.3.2 Software Installation

The installation of the software is very straightforward.

1. download and save the distribution tar file.

1.3.3 Running DIFF_CALC

With precompiled IDL Virtual Machine (VM)

navigate to the install directory/DIFF_CALC/diffcalc_main

With IDL Virtual Machine (VM)

Command Line Linux:

Enter the following command in a shell: idl -vm=<path><filename>.sav. For example:

Command Line Mac:

Enter the following command in a shell: idl -vm=<path><filename>.sav. For example:

idl -vm -32=/home/TORTOISE/DIFF_CALC/diffcalc_main/diffcalc.sav

idl -vm -32=diffcalc.sav

File Selection Menu:

Enter the following command in a shell:

idl -vm {-32 if using Mac}

The IDL VM window is displayed

With Full IDL license (Linux or Mac OS X)

Go to the diffcalc_main directory inside the DIFF_CALC install directory in a shell

1. Visit the ITT website http://www.ittvis.com/

3.1 Configuration File

The configfile_simple.xml file contains the following lines:

3.1.1 Optimize Configfile

Tensor Fitting Options:

3.2 Main Software GUI

load listfile - load raw or processed data via the listfile

3.2.01 Load Listfile

3.2.02 Display Images

3.2.02.01 Inspect Entire Set

3.2.02.02 Delete Volume

If you want to remove multiple volumes, be aware of the following items:

3.2.03 Estimate signal SD

New! More accurate automated noise estimation methods

3.2.04 mask raw images

Additional options are as follows:

Click done when finished selecting your options.

3.2.06 About TORTOISE

3.2.07 process tensor

3.2.07.01 RESTORE Options

3.2.07.02 iRESTORE Options

3.2.08 compute eigenvalues

3.2.09.1 Define ROI