dtiprep:MainPage
From NITRC Wiki
Contents |
Objective
We would like to create an application allowing both individual and group quality control of DWI/DTI data sets in both a GUI and command-line mode. This page describes the related pipeline with its basic components, parameters, as well as directions to its usage.
Getting the Program
Binary releases will be made available from Files
Mac users
The current package is not a full Mac App. The user needs to start the program via a terminal window, executing the binary within the bin/DTIPrep/MacOSX_ folder.
Compilation
For those who have significant software development expertise, consider the instructions for DTIPrep Compilation.
Pipeline overview
- Dicom to NRRD converting
- Image information checking
- Diffusion information checking
- Slice-wise intensity artifact checking
- Interlace-wise venetian blind artifact checking
- Baseline averaging
- Eddy-current and head motion artifact correction
- Motion artifact checking
- DTI computing
DTIProcess lib
Part of all the tools downloaded through the svn repository is the DTIProcess library. A description and help page of the tools from this library can be found here: DTIProcess help. These tools are command line software that work on dti data (tensor estimation, scalar measurement images, tensor field deformation, fiber tracking...)
Preparing the NRRD file
- Convert DICOM file to NRRD file format. A description of the process to extract directions from DICOM files used by this program can be found on the National Alliance for Medical Image Computing (NA-MIC) Wiki.
/opt/NAMICDTI/bin/DicomToNrrdConverter --inputDicomDirectory A468.6/ --outputVolume dti_parta.nhdr
- Review the plain ASCII text file with an .nhdr extension to verify that the RAW file name, b value, and diffusion gradient directions are properly represented. For custom DTI sequences that do not produce compliant DTI DICOM files, you will likely have to insert the proper gradient direction information.
- The NRRD file is now ready to be processed by DTIPrep in either GUI or command line mode.
Concatenating Multiple DTI runs (Optional)
If multiple compatible dti sequences were performed (either the same sequence multiple times, or different set of directions each time), it may be desirable to concatenate the data set and treat it as a single long acquisition for analysis purposes.
The GTRACT software is recommended for this step. Complete documentation can be found here.
/opt/NAMICDTI/bin/gtractConcatDwi --outputVolume dti.nhdr --inputVolume dti_parta.nhdr,dti_partb.nhdr
Using the GUI
- Load the GUI with the following command:
/opt/NAMICDTI/bin/DTIPrep
- Load NRRD file
- Click "NRRD" folder icon at top left hand corner
- Select NRRD file
- DWI image should load into GUI (axial, sagittal, and coronal views are visible)
- Roll mouse scroll wheel forward/backwards over images to increase/decrease their sizes
- Click mouse, hold click and drag mouse forward/backwards over images to darken/brighten window level
- Click mouse, hold click and drag mouse left/right over images to change contrast
- r - bring 3D view back to center
- f - zoom in on 3D view
- w - remove views from 3D view
- s - bring back views in 3D view
- Click on hollow ball icon, 3D view tab, and P or F star: displays vertices of gradient vectors on sphere
- Click 3D view tab and P or F star (unclick hollow ball icon): only displays gradient vectors radiating out from origin
- Click "NRRD" folder icon at top left hand corner
Option 1 -- Define a new data acquisition protocol file
If this is the first time this DTI family of DTI scan types has been loaded into DTIPrep, a new data acquisition protocol file (.xml file containing pipeline checking parameters) must be created
- Click the "Protocol" tab
- Click "Default" button, default protocol parameters and NRRD file information should appear in window with "Parameter" and "Value" as headings. Protocol parameters can be changed here.
NOTE: Descriptions of configurable DTIPrep QC options are listed on DTIPrep Configurations Page.
- Click "Save as" button to save the data acquisition protocol file (file can be named before clicking "Save as" by typing next to "Load" button or after clicking "Save as")
Option 2 -- Compare this data set to a previously defined data acquisition protocol
- If the currently loaded NRRD file has parameters similar to a NRRD file processed by DTIPrep in the past (ex: a protocol file for a 31 gradient direction data series was created and another NRRD file with 31 directions must now be processed by DTIPrep), the previous data acquisition protocol file can be used to help check for similarities between protocols.
- Click "Protocol" tab
- Click "Load" button
- Load data acquisition protocol file from past NRRD file
- Again, protocol parameters can be changed here as well. Clicking "Save&Update" will update the loaded protocol file by saving any changes. Clicking "Save as" provides the option of saving the parameters into a new protocol file.
- Click "Protocol" tab
Validating against data acquisition protocol file
- Click "RunByProtocol" button at the bottom. This will generate 4 files in the same directory as the NRRD input file.
- QCReport: txt file with information about excluded gradients
- New nhrd file: only includes the gradients that have NOT been excluded by DTI Prep
- New raw file: raw file based on new nhrd file
- New xml file: report on how each gradient was treated while running DTIPrep (NOTE: only produced while using GUI mode)
Viewing contents of QCResults xml file
- If you ran DTIPrep in GUI mode and still have the GUI open, click on the QCResults tab to view the DTIPrep's results.
- If you ran DTIPrep in GUI mode and would like to view the output xml file report, do one of the following:
- Click on the yellow icon at the top left corner of the GUI to upload the output xml file report
- Click on the QCResults tab, followed by the Load icon to upload the output xml file report]
Command line usage
Help information can be displayed by
/opt/NAMICDTI/bin/DTIPrep -h
Usage : DTIPrep
Command tags:
-w --DWINrrdFile < DWIFileName >
= DWI file name to convert dicom image series into or to be checked (nhdr)
-p --xmlProtocol < xmlFileName >
= protocol xml file containing all the parameters
[ -d --default ]
= create default protocol xml file
[ -c --check ]
= check by protocol xml file. Default operation.
[ -n --resultNotesFile < NotesFile > ]
= result notes
[ -f --outputFolder < OutputFolder > ]
= output folder name
Running DTIPrep from the command line (validating against a previously created data acquisition protocol file)
/opt/NAMICDTI/bin/DTIPrep --DWINrrdFile < DWIFileName > --xmlProtocol < xmlFileName > --check --outputFolder < OutputFolder >
Running DTIPrep from the command line (generate a new data acquisition protocol file based on input NRRD file)
/opt/NAMICDTI/bin/DTIPrep --DWINrrdFile < DWIFileName > --xmlProtocol < xmlFileName > --default --outputFolder < OutputFolder >
Running DTIPrep from the command line (generate a new data acquisition protocol file from the input NRRD file AND begin validation)
/opt/NAMICDTI/bin/DTIPrep --DWINrrdFile < DWIFileName > --xmlProtocol < xmlFileName > --default --check --outputFolder < OutputFolder >
Please note that the data acquisition protocol file generated from the command line will consist of default settings only. Notes file is a text file containing information about analysis (number of gradients removed, which checking steps passed).
Result files
RAW NRRD parta (Output from DicomToNRRD): dti_parta.raw dti_parta.nhdr RAW NRRD partb (Output from DicomToNRRD): dti_partb.raw dti_partb.nhdr RAW Concatenated file (Output from gtractConcatDwi): dti.raw dti.nhdr The protocol description file for one class of DTI: DTIProtocol.xml The remaining directions that pass QC testing (Output of DTIPrep): dti_QCed.nhdr dti_QCed.raw.gz A report of the removed directions (Output of DTIPrep): dti_QCReport.txt
Simple Analysis Example
Create a Tensor image fromthe QC'ed data:
/opt/NAMICDTI/bin/gtractTensor --inputVolume dti_QCed.nhdr --outputVolume Tensor.nhdr --backgroundSuppressingThreshold 50 --medianFilterSize 1,1,1 --b0Index 0 /opt/NAMICDTI/bin/gtractAnisotropyMap --inputTensorVolume Tensor.nhdr --outputVolume FA.nhdr --anisotropyType FA /opt/NAMICDTI/bin/gtractAnisotropyMap --inputTensorVolume Tensor.nhdr --outputVolume ADC.nhdr --anisotropyType ADC /opt/NAMICDTI/bin/gtractAnisotropyMap --inputTensorVolume Tensor.nhdr --outputVolume AD.nhdr --anisotropyType AD /opt/NAMICDTI/bin/gtractAnisotropyMap --inputTensorVolume Tensor.nhdr --outputVolume RD.nhdr --anisotropyType RD
- An evaluation of GTRACT for Fiber Tracking can be found in the paper at PMID 16631385 Evaluation of the GTRACT diffusion tensor tractography algorithm: a validation and reliability study.
- An alternative DTI processing tool is described on the Slicer3 Tutorials page.
- A set of DTI processing tools from the SCI Institute can be found at DTIProcess
