DTI Tutorial 1 - From Scanner to Tensor
Starting out with data analysis often seems like a daunting task, as there are innumerable software packages with sometimes poor documentation. To make this process easier and help you get started with diffusion imaging analyses I put together this tutorial that will introduce you to the most important processing steps and tools. Always keep in mind that there are many ways of processing your data, and the examples used in this tutorial provide just one way of doing things. As you get more versed with the different steps and software you will be able to try different packages and see which you prefer best.
There will be questions in each section to allow you to actively work with data and tools. These question will sometimes ask you to install software or download example data, you can find the example data for this tutorial here. Most of the publicly available (and thus free) software tools used in neuro-imaging will only work in a bash terminal environment (linux or mac). If you are not already, try to become comfortable in a linux environment. An example of linux tutorials can be found online, for example the "UNIX Tutorial for Beginners" contains explanations of basic commands commonly used to navigate the terminal. If you would like some advanced tutorials that go into scripting in bash you can check out this linux tutorial, as scripting in linux will become an important skill when datasets get large. Finally, this DTI tutorial assumes a basic understanding of diffusion MRI, if you would like to catch up on that first, you can go trough these slides that introduce this tutorial. Beyond that you can check out the post on diffusion imaging 101, and start perusing other posts on this website.
In this first tutorial the overall goal is to demonstrate how to convert raw diffusion data files to tensor images. In order to get to tensor images there are a number of intermediate steps that are essential to go through:
1. You will have to move the data off the scanner and convert it to a usable format.
2 & 3. It is important to deal with distortions common to diffusion images, like EPI and eddy currents.
4. Make sure you remove any non-brain tissues.
5. Make the gradient directions file.
6. Fit the tensors.
7. Check the fit of the tensors.
At the end of the document you will find a pdf with the answers to the questions in this tutorial, although try to figure things out yourself as much as possible. If you run into issues going through this tutorial please direct your questions to the diffusion imaging forum, where there will likely be someone able to help you out. Please make sure to describe your question as clearly as possible. Remember to please direct software specific questions to their own respective forums or mail lists.
There will be questions in each section to allow you to actively work with data and tools. These question will sometimes ask you to install software or download example data, you can find the example data for this tutorial here. Most of the publicly available (and thus free) software tools used in neuro-imaging will only work in a bash terminal environment (linux or mac). If you are not already, try to become comfortable in a linux environment. An example of linux tutorials can be found online, for example the "UNIX Tutorial for Beginners" contains explanations of basic commands commonly used to navigate the terminal. If you would like some advanced tutorials that go into scripting in bash you can check out this linux tutorial, as scripting in linux will become an important skill when datasets get large. Finally, this DTI tutorial assumes a basic understanding of diffusion MRI, if you would like to catch up on that first, you can go trough these slides that introduce this tutorial. Beyond that you can check out the post on diffusion imaging 101, and start perusing other posts on this website.
In this first tutorial the overall goal is to demonstrate how to convert raw diffusion data files to tensor images. In order to get to tensor images there are a number of intermediate steps that are essential to go through:
1. You will have to move the data off the scanner and convert it to a usable format.
2 & 3. It is important to deal with distortions common to diffusion images, like EPI and eddy currents.
4. Make sure you remove any non-brain tissues.
5. Make the gradient directions file.
6. Fit the tensors.
7. Check the fit of the tensors.
At the end of the document you will find a pdf with the answers to the questions in this tutorial, although try to figure things out yourself as much as possible. If you run into issues going through this tutorial please direct your questions to the diffusion imaging forum, where there will likely be someone able to help you out. Please make sure to describe your question as clearly as possible. Remember to please direct software specific questions to their own respective forums or mail lists.
1. From scanner to NifTI
What is the best way to get your scanner data to a format that you can actually look at? It depends on your preferences and your scanner. GE and Siemens scanners output DICOM (which stands for Digital Imaging and COmmunications in Medicine) format. While Philips scanners output PAR/REC format. While it is possible to view DICOM or PAR/REC images using specialized software, they are not suitable for processing. Formats that are more commonly used for processing and viewing is the NifTI format. NifTI stands for Neuroimaging informatics Technology Initiative, started by NIH to help streamline the available tools for neuroimaging research. To convert DICOM or PAR/REC images to NifTI you can use software tools like dcm2nii or others.
dcm2nii by MRIcron
Q1: In your document write the command code to how show how you would convert your raw scanner image to NifTI, assume your data is in dicom format, and organized like this:
In order to get an impression of the quality of the data that you got off the scanner it will be important to take a closer look at your data. This will be a recurring activity, as you can only really make sure your data is valid and your analysis steps work by looking at your data. An example of a toolbox that can help you with that was developed by the University of Oxford FMRIB software library (FSL). A good way to get familiar with some of their software tools is to go through the FSL tutorial on their website.
fslview by FSL
One method to investigate the information of your image is to look at the header information. A tool that can help you with that is fslinfo. The image below explains the information that you get when you use fslinfo on a diffusion image. The numbers in blue indicate the image dimensions (256x256x67), in red you see the total number of volumes (49), and in green the voxel dimensions (1x1x2mm). Another good habit is to view your data after it has been collected. This way you can catch any issues that may have occurred during the scan session. More info on why and how to do this can be found here. A commonly used image visualization tool is fslview.
 |
Image information of the sample data
|
http://fsl.fmrib.ox.ac.uk/fsl/fslview/
Q2: Download our example diffusion weighted image (052212_s09_dti.nii) through this link, or use your own data. Open the image in fslview (if you don't know how, look at the fslview documentation, or type fslview in your terminal after installing the software). Scroll through the different volumes. Can you identify how many volumes were acquired without diffusion weighting (b=0)?
Additional online resources:
- A wiki that provides more information on converting diffusion images from the DICOM format- Video on how to use the graphical user interface of dcm2nii
- Additional information from dcm2nii on data repositories and alternatives tools
- Website dedicated to medical imaging formats
- Other dicom converters: mri_convert by freeserver, dimon by afni, dicom2nifti for SPM
- Other data viewers: 3D Slicer: Image Visualization Software, MedINRIA: DTI Analysis and Visualization Software.
2. Distortion correction (eddy)
In the next step we will run an eddy distortion correction. Eddy currents are a natural effect of the changing magnetic field that are commonplace in diffusion scans. If you are interested you can find more background on eddy distortions in our post on distortions corrections. The most common tool to counter eddy currents has been developed by FSL. In addition to correcting eddy currents this tool will correct for simple head motions. It takes each volume from your diffusion image and will apply a rigid registration (using FLIRT under the hood) to align all volumes to the first "reference" volume. It is common practice to set the reference volume to be the first volume that was acquired, thus number 0 (counting starts at 0). All the following volumes will then be registered to that first volume.
eddy_correct by FSL
Q3: Run the command line code for the eddy correction as shown below. What does the output to the terminal look like? Does it take long to run? Why?
eddy_correct 052212_s09_dti.nii 052212_s09_dti_eddy.nii 0(If you'd like to quit before its done; type ctrl-c in your terminal, the output files are available to download: 052212_s09_dti_eddy.ecclog and 052212_s09_dti_eddy.nii)
Additional online resources:
- You can also use the FSL Diffusion Toolbox, which has a graphical user interface- If you acquired two diffusion scans with opposing polarity, you can use FSL's eddy instead
- Distortion correction and preprocessing tutorial from Stanford
3. Distortion correction (EPI)
EPI (aka field or B0-susceptibility) distortions are caused by magnetic field inhomogeneities, and are more obvious to spot then eddy currents. You can find more info on EPI distortions in this blog post. An example of EPI distortions is shown in the image below. FSL has great tutorials and tools that help deal with EPI distortions using a field map that you should acquire in addition to your diffusion scan. The process essentially consists of two steps, first compose the field map from the raw phase and magnitude files (acquired as part of the field map sequence), and second apply the field map to your diffusion image. Field maps can be collected in different ways, you may have to talk to your local MRI-guru to figure out how your data is collected, but fear not -- if you instead collected two diffusion-scans with opposing polarity and no field map, you can use the TOPUP tool to combine both.
FUGUE by FSL
http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FUGUE/Guide?highlight=%28%5CbCategoryFUGUE%5Cb%29
FUGUE by FSL
http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FUGUE/Guide?highlight=%28%5CbCategoryFUGUE%5Cb%29
TOPUP by FSL
 |
| Example of EPI distortions in the frontal lobe of 052212_s09_dti.nii |
Q4: On FSL's FUGUE website find the image that shows a real field map image. Can you get an impression from that image where you would expect most distortion to be localized? Look at the field map from the provided example data (download 052212_s10_fmap.nii here). Does that agree with the distortion that you see in the raw diffusion image (052212_s09_dti.nii)?
Q5: Note in the image above how the diffusion image is altered after the field map was applied (in green) and EPI distortion was corrected. Take a close look at the gif and indicate what brain regions show reductions in stretch distortion.
 |
| Pre and post (green) EPI distortion correction |
Q5: Note in the image above how the diffusion image is altered after the field map was applied (in green) and EPI distortion was corrected. Take a close look at the gif and indicate what brain regions show reductions in stretch distortion.
Additional online resources:
- Distortion correction tutorial for TOPUP from UCDavis
- Distortion correction tutorial by Andy's Brain Blog, with video's
- EPI distortion correction using ExploreDTI
- Distortion correction tutorial by MNI
- Distortion correction tutorial by Andy's Brain Blog, with video's
- EPI distortion correction using ExploreDTI
- Distortion correction tutorial by MNI
4. Stripping the Skull
In this step the objective is to isolate the brain and get rid of unwanted skull and tissue from the scan so that further processing occurs solely on brain tissue. FSLs automated brain extraction tool (bet) is a tool that can assist in that process. It is important to check if the output from the automated masking process was effective, if not, then you can alter the bet extraction options or manually edit the mask. It should be noted that bet is optimized for human brain extraction, and manual extraction if often necessary in other species. The image below shows different examples of brain extraction with bet, in red is an example of an output mask of the brain tissue.
 |
| Brain extraction using FSL's bet. Image courtesy of FSL |
bet by fsl
http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BET
Q6: Investigate the command options in bet using the help function or the online documentation. Explain what executing the below command would entail. How would you alter these options if your output mask is too small? Run a brain extraction on the sample data (e.g. 052212_s09_dti_eddy_fm.nii) using the code below, add options in the command so that it will output a binary mask, and so that it will run multiple iterations for a robust output.
bet 052212_s09_dti_eddy_fm.nii 052212_s09_dti_eddy_fm_strip -f 0.3
Additional online resources:
- BET frequently asked questions
- Other skull stripping tools: 3dSkullStrip by AFNI, SPM, BrainSuite
- Other skull stripping tools: 3dSkullStrip by AFNI, SPM, BrainSuite
5. Gradient directions
The gradient information from the scanner is used in order to calculate the tensors models. More information on the mathematics can be found in our post here. The gradient information is sometimes stored in the header of the images, if it is not, talk to your scan tech to get this information. There are two aspects that have to be taken into account, the b-values and the b-vectors. Diffusion-weighted b-values usually range from 750~1500 s/m^2, and is most frequently set at 1000s/m^2.
“The b-value identifies the measurement’s sensitivity to diffusion and determines the strength and duration of the diffusion gradients.” (Graessner, 2011).Depending on the used b-value (in below example is: 1000s/m^2), and the number of b=0 volumes (in the example: 6) an abbreviated version of the b-value document can look like this:
0,0,0,0,0,0,1000,1000,1000,1000,1000,1000,1000,1000,1000,1000,1000
In contrast the b-vectors consist out of 3 separate vectors (x, y, z) for each gradient direction acquired. A file containing b-vectors might look like this:
 |
| Examples of b-vectors |
The format used for the b-vectors and b-values depends on the final program that you are going to use to calculate the tensors. Since we are going to use Camino software to run the tensor calculation in this tutorial, we will have to convert the b-values and b-vectors to a scheme file format that combines both, using fsl2scheme. The abbreviated scheme file will look the image below, where the first three columns indicate the b-vectors, and the 4th shows the b-values.
 |
| Example scheme file (left), diffusion weighted volumes (right) |
fsl2scheme by Camino (download Camino here)
Q7: Investigate the documentation of fsl2scheme, provide example code of how to convert b-vectors and b-values from an FSL format to a Camino scheme file.
If you ran an eddy correction on you data you will first have to correct your scheme file. This is a necessary step as the rigid registration makes the volumes move, causing the gradient directions to be misaligned. Here are a couple of resources to explain this process further and provide code to run the correction:
1. Blog on rotating bvecs for DTI fitting
2. Publication on why you should do this
3. Github code on how to run this rotationrotate_bvectors.sh by bernardng
https://github.com/bernardng/codeSync/blob/master/dMRIanalysis/preprocess_batch.sh
Combined example code to rotate and produce scheme file:
prefix=052212_s09
sh rotate_bvectors.sh bvecs.txt ${prefix}.bvecs EDDY/
rm -f ${prefix}*.mat
fsl2scheme -bvecfile ${prefix}.bvecs -bvalfile bval.txt > ${prefix}.scheme
Additional online resources:
- Camino website with more details on the scheme file formats and application
- FSL forum with more details and code for b-vector rotation
- FSL forum with more details and code for b-vector rotation
6. Tensor Fitting
In this step we will use Camino to run the tensor calculation. This tool is currently my preferred software for this step as it regularly implements novel mathematical models and scientific developments in diffusion MRI. In order to use this tool, the NifTI format (.nii) images will have to be converted to Camino format (.Bfloat). To do this you can use Camino's tool image2voxel. Once the data is in .Bfloat format you can use Camino to run the tensor model estimation from the diffusion weighted images, using modelfit. Once this is done, you will have to convert the data back to .nii format, using dt2nii. Which will read the header information from a reference NifTI file and copy that to the new tensor NifTI file.
image2voxel by Camino
http://cmic.cs.ucl.ac.uk/camino//index.php?n=Man.Image2voxelmodelfit by Camino
http://cmic.cs.ucl.ac.uk/camino//index.php?n=Man.Modelfit
dt2nii by Camino
http://cmic.cs.ucl.ac.uk/camino//index.php?n=Man.Dt2nii
Example code:
prefix=052212_s09
export CAMINO_HEAP_SIZE=2000
image2voxel -4dimage ${prefix}_dti_eddy_fm.nii > ${prefix}_DWI.Bfloat
modelfit -inputfile ${prefix}_DWI.Bfloat -schemefile ${prefix}.scheme -outputdatatype float > ${prefix}_DTI.Bfloat
dt2nii -inputfile ${prefix}_DTI.Bfloat -inputdatatype float -header ${prefix}_dti_eddy_fm.nii -outputroot ${prefix}_dti_eddy_fm_strip_
Q8: Download the necessary data from our example data. Using the example code shown above try to run the tensor fitting. Note that ${prefix} indicates a variable in bash, which is defined in line 1, if you are unsure how variables work in bash look it up here. Learning how to work with variables now will make it easier to transition to loops in scripts later on. This code will need a couple of minutes to run. Side note; to avoid a java error message (as shown below) we increased the java RAM usage allowed for Camino with the third line in the example script. Solution came from the camino help list.
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
Q9: Imagine that due to unforeseen reasons you collected noisy data, and you would like to run a robust tensor estimation as described by Chang, Jones & Pierpaoli (2005). Investigate the Camino list of available commands. What tool would be able to accommodate your aim?
Additional online resources:
7. Sanity Check
Finally it will be essential to check if your scheme file was applied well, and your tensors were fit correctly. If you have not already go through the tensor fitting quality control post to see why and how. In order to see the tensor fit we will use tools by camino to draw and visualize the main tensor. In principle you should only have to check this for one sample image in your entire dataset.
dteig by Camino
pdview by Camino
Example code:
prefix=052212_s09
dteig -inputmodel dt -inputdatatype float -outputdatatype float < ${prefix}_DTI.Bfloat > ${prefix}_DTI_EIG.Bfloat
pdview -inputdatatype float -inputmodel dteig -inputfile ${prefix}_DTI_EIG.Bfloat -datadims 256 256 67 &
Q10: Run the example code to investigate the tensor fit, compare the results to the examples from the quality control post and the Camino website, were the tensors fit correctly?
Further additional online resources:
- General tutorial on "Diffusion Tensor Imaging Analysis using FSL"
- Overview of other software packages on this blog
- Article on the do's and don'ts of diffusion imaging
- Article that is the hitchhikers guide to diffusion imaging
- Preprocessing tutorial by the Enigma group
- Overview of other software packages on this blog
- Article on the do's and don'ts of diffusion imaging
- Article that is the hitchhikers guide to diffusion imaging
- Preprocessing tutorial by the Enigma group
Answers:
DTI Tutorial 1 Answers
---------------------
Reference this post as: Do Tromp, DTI Tutorial 1 - From Scanner to Tensor, The Winnower 3:e145653.31559 (2016). DOI: 10.15200/winn.145653.31559
---------------------
Reference this post as: Do Tromp, DTI Tutorial 1 - From Scanner to Tensor, The Winnower 3:e145653.31559 (2016). DOI: 10.15200/winn.145653.31559
