dtiprep:DTIPrepQCConfigurations

From NITRC Wiki

Contents 1 Recommendations on modifying protocol parameters 2 Protocol Settings 2.1 Pipeline Settings 2.2 Image Information Check 2.3 Diffusion Information Check 2.4 Slice-wise Checking 2.5 Interlace-wise Checking 2.6 Baseline Averaging 2.7 Eddy-current and head motion artifacts correcting 2.8 Gradient-wise Checking 2.9 DTI Computing

Recommendations on modifying protocol parameters

• Use the GUI to create new data acquisition protocol files for ease in parameter adjustment.
• Set QC_badGradientPercentageTolerance high if the percentage of bad gradients is not known. This will prevent parameters that are too stringent from terminating the pipeline prematurely.
• If only quality control checking is desired, set "IMAGE_bCheck" and "DIFFUSION_bCheck" both to "No." DTIPrep will then only proceed through slice-wise intensity artifact checking, interlace-wise venetian blind artifact checking, baseline averaging, and eddy-current and head motion artifact correction.
• Increasing/decreasing parameters such as "SLICE_correlationDeviationThresholdbaseline" and "SLICE_correlationDeviationThresholdgradient" will decrease/increase the number of diffusion gradients excluded.
• DIFFUSION_bQuitOnCheckFailure must be set to "No" if DIFFUSION_bUseDiffusionProtocol is set to "Yes" for the pipeline to continue past "Diffusion information check" on the newly created "_DiffusionReplaced.nhdr" file.

Protocol Settings

Pipeline Settings

 QC_QCOutputDirectory                // string     
 QC_QCedDWIFileNameSuffix            // string
 QC_reportFileNameSuffix             // string
 QC_badGradientPercentageTolerance

QC_QCOutputDirectory: Default setting is the directory that contains the input NRRD file.

QC_QCedDWIFileNameSuffix (default setting is "_QCed.nhdr"): Results in "your_nrrd_file_name_QCed.your_file_extension"

QC_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

QC_badGradientPercentageTolerance (default setting is "0.2000"): Percentage of gradients that need to be excluded to trigger the message "Too many bad gradients!" and termination of the pipeline.

QC_reportType (default setting is "0"): 3 format options for the QCReport

• 0: Does not display correlation values generated in Slicewise-Check
• 1: Displays correlation values generated in the Slicewise-Check in slice x gradient matrix format
• 2: Displays correlation values generated in the Slicewise-Check in gradient x slice matrix format. This version is easily parsable because each line of the QCReport is named based on the checking step that created it.

Image Information Check

 IMAGE_bCheck                      // Yes|No
 IMAGE_type
 IMAGE_space
 IMAGE_directions
 IMAGE_dimension
 IMAGE_size
 IMAGE_spacing
 IMAGE_origin
 IMAGE_bCrop
 IMAGE_croppedDWIFileNameSuffix    // string
 IMAGE_reportFileNameSuffix        // string
 IMAGE_reportFileMode              // 0: new   1: append

IMAGE_bCheck (default setting is "Yes"): Compares IMAGE_space (e.g. LPS), IMAGE_directions, IMAGE_size (pixel, pixel, slices per gradient volume), IMAGE_spacing (dimensions of voxels in mm), and IMAGE_origin from data acquisition protocol file (xml) to values in NRRD header file. Results are reported in the terminal and your_NRRD_file_name_QCReport.txt.

IMAGE_bCrop (default setting is "Yes"): When a mismatch in the number of slices per gradient in the NRRD file and data acquisition protocol file occurs, the input NRRD file's number of slices per gradient is changed to that in the protocol. If the number of slices per gradient in the NRRD file is less than that in the data acquisition protocol file, a "padded" NRRD file is created (number of slices per volume is increased). The new padded NRRD file then proceeds through the DTIPrep pipeline. Currently, DTIPrep unexpectedly quits when the number of slices per gradient in the NRRD file is greater than that in the protocol instead of creating a "cropped" NRRD file to process through the pipeline. This bug will be fixed soon.

IMAGE_croppedDWIFileNameSuffix (default setting is "_CroppedDWI.nhdr"): Suffix for new NRRD file created by IMAGE_bCrop. Results in "your_NRRD_file_name_CroppedDWI.nhdr." If this is left blank, neither a padded or cropped NRRD file will be created.

QC_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

IMAGE_reportFileMode (default setting is "1")

• 0: Creates a new QCReport text file containing information only from Image Information Check
• 1: Appends information from Image Information Check to the "your_nrrd_file_name_QCReport.txt" from the previous step.

IMAGE_bQuitOnCheckSpacingFailure (default setting is "Yes"): Terminates pipeline during IMAGE_bCheck when mismatches are found in the IMAGE_spacing (voxel size and/or indices) settings between the protocol and NRRD file of interest

IMAGE_bQuitOnCheckSizeFailure (default setting is "No"): Terminates pipeline during IMAGE_bCheck when a mismatch is found in the IMAGE_size (pixel, pixel, slices per gradient volume) setting between the protocol and NRRD file of interest

Diffusion Information Check

 DIFFUSION_bCheck                              // Yes|No
 DIFFUSION_measurementFrame                    // 3x3 matrix
 DIFFUSION_DWMRI_bValue                        // double
 DIFFUSION_DWMRI_gradient_????                 // diffusion gradient vector
 DIFFUSION_bUseDiffusionProtocol               // Yes|No
 DIFFUSION_diffusionReplacedDWIFileNameSuffix  // string
 DIFFUSION_reportFileNameSuffix                // string
 DIFFUSION_reportFileMode                      // 0: new   1: append

DIFFUSION_bCheck (default setting is "Yes"): Compares b value and diffusion gradient vector information in the NRRD file to that in the data acquisition protocol file. If mismatches are found between the protocol parameters and NRRD files, a series of tolerance tests are executed. The first tolerance test checks for colinearity of diffusion gradient vectors when vector +/- signs do not match. The second tolerance test allows an angle difference < 1 OR 179 < angle < 180 degrees between gradient vectors in the NRRD file and their counterparts in the data acquisition protocol file.

DIFFUSION_bUseDiffusionProtocol (default setting is "Yes"): In the event of a mismatch in diffusion gradient vector information between the NRRD and data acquisition protocol files, DTIPrep will create a new NRRD file that contains the same information as the NRRD file except for the diffusion gradient vector information. The diffusion gradient vector information in the new NRRD file will be from the data acquisition protocol file. This new NRRD file will now proceed through the DTIPrep pipeline.

DIFFUSION_diffusionReplacedDWIFileNameSuffix (default setting is "_DiffusionReplaced.nhdr"): Suffix for new NRRD file created by DIFFUSION_bUseDiffusionProtocol. Results in "your_NRRD_file_name_DiffusionReplaced.nhdr." If this is left blank, a new NRRD file with replaced gradient information will not be created.

DIFFUSION_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

DIFFUSION_reportFileMode (default setting is "1")

• 0: Creates a new QCReport text file containing information only from Diffusion Information Check
• 1: Appends information from "Image information check" to the "your_nrrd_file_name_QCReport.txt" from the previous step.

DIFFUSION_bQuitOnCheckFailure (default setting is "Yes"): Terminates pipeline after the "Diffusion information check" step when any mismatches are found between the diffusion gradients in the data acquisition protocol and NRRD file OR when mismatched diffusion gradients do not pass DIFFUSION_bCheck tolerance tests.

Please note: DIFFUSION_bQuitOnCheckFailure must be set to "No" if DIFFUSION_bUseDiffusionProtocol is set to "Yes" for the pipeline to continue past "Diffusion information check" on the newly created "_DiffusionReplaced.nhdr" file.

Slice-wise Checking

 SLICE_bCheck                                 // Yes|No
 SLICE_checkTimes;
 SLICE_headSkipSlicePercentage;
 SLICE_tailSkipSlicePercentage;
 SLICE_correlationDeviationThresholdbaseline;
 SLICE_correlationDeviationThresholdgradient;
 SLICE_outputDWIFileNameSuffix;
 SLICE_reportFileNameSuffix                    // string
 SLICE_reportFileMode                          // 0: new   1: append

SLICE_bCheck (default setting is "Yes"): Detects intensity artifacts amongst slices and designates a gradient for removal if it contains slice(s) that do not correlate well with their neighboring slices.

Each slice is compared to the previous slice to calculate slice-to-slice correlation values. For example, if a scan has 31 gradients with 50 slices per gradient, there should be 31 correlation values for each of the 49 slice-to-slice comparisons. The 31 correlation values for each slice are then compared across gradients to determine whether or not they make up a normal/Gaussian distribution. If correlation values lie outside of the number of standard deviations set by the user, the corresponding slices/gradients are excluded. Correlation values, a list of gradients removed from thischecking step, and histograms describing the remaining gradients are outputted to the QCReport.

SLICE_bSubregionalCheck (default setting is "No"): Slice-wise Checking can be done on five sub-regions (numbered 0 through 4) in addition to whole-brain slices. The purpose of checking within sub-regions is to add sensitivity to vibration artifact detection. The sub-regions are based on voxel indices (i, j, k). For example, in a scan collected in the standard DICOM LPS coordinate system, sub-region 0 starts with i=0 and j=0, while sub-region 3 starts with i=imax/2 and j=imax/2. Correlation values, a list of gradients removed from this checking step, and histograms describing the remaining gradients are outputted to the QCReport.

SLICE_subregionalCheckRelaxationFactor (default setting is "1.1000"): When SLICE_bSubregionalCheck is set to "Yes," the number of standard deviations set in SLICE_correlationDeviationThresholdbaseline and SLICE_correlationDeviationThresholdgradient are multiplied by SLICE_subregionalCheckRelaxationFactor. This allows less stringent exclusion of gradients within Slice-wise Checking when SLICE_bSubregionalCheck is activated.

SLICE_checkTimes (default setting is "0"): Number of times the mean and standard deviation are computed based on remaining data points. If set to 0, the mean and standard deviation are computed until no outliers exist within data points.

SLICE_headSkipSlicePercentage (default setting is "0.1000"): Fraction of slices not analyzed for removal since they represent the most superior portion of each volume.

SLICE_tailSkipSlicePercentage (default setting is "0.1000"): Fraction of slices not analyzed for removal since they represent the most inferior portion of each volume.

SLICE_correlationDeviationThresholdbaseline (default setting is "3.0000"): Sigma or the number of standard deviations allowed for slice-to-slice correlations for baseline gradients.

SLICE_correlationDeviationThresholdgradient (default setting is "3.5000"): Sigma or the number of standard deviations allowed for slice-to-slice correlations for non-baseline gradients.

SLICE_outputDWIFileNameSuffix (default setting is blank): Suffix used when creating an output NRRD file of remaining gradients after Slice-wise Checking. No output file after Slice-wise Checking is produced if left blank.

SLICE_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

SLICE_reportFileMode (default setting is "1")

• 0: Creates a new QCReport text file containing information only from Slice-wise Checking
• 1: Appends information from Slice-wise Checking to the "your_nrrd_file_name_QCReport.txt" from the previous step.

SLICE_excludedDWINrrdFileNameSuffix (default setting is blank): Creates a NRRD file containing diffusion gradients excluded from Slice-wise Checking when provided with a file name suffix

SLICE_bQuitOnCheckFailure (default setting is "Yes"): Terminates pipeline if Slice-wise Checking has done one of the following

• Reduced the number of remaining gradients to less than 6
• Eliminated all baseline gradients
• Removed a number of gradients greater than the fraction allowed, which is specified by QC_badGradientPercentageTolerance

Interlace-wise Checking

 INTERLACE_bCheck                            // Yes|No
 INTERLACE_badGradientPercentageTolerance;
 INTERLACE_correlationThresholdBaseline;
 INTERLACE_correlationThresholdGradient;
 INTERLACE_correlationDeviationBaseline;
 INTERLACE_correlationDeviationGradient;
 INTERLACE_translationThreshold;
 INTERLACE_rotationThreshold;
 INTERLACE_outputDWIFileNameSuffix;
 INTERLACE_reportFileNameSuffix                // string
 INTERLACE_reportFileMode                      // 0: new   1: append

INTERLACE_bCheck (default setting is "Yes"): Detects venetian blind artifacts.

Interlace-wise Checking separates each gradient into two volumes (odd and even lines of acquisition). Correlation values are computed between the two volumes and plotted. If a correlation value lies outside of the number of standard deviations set by the user, the corresponding gradient is excluded. Rotation and translation information for each gradient, a list of gradients removed from this checking step, and histograms describing the remaining gradients are outputted to the QCReport.

INTERLACE_badGradientPercentageTolerance (default setting is "0.2000"): Percentage of gradients that need to be excluded to trigger the message "Too many bad gradients!"

INTERLACE_correlationThresholdBaseline (determined upon setting default protocol parameters in GUI): Lower limit of correlation plot for baseline gradients.

INTERLACE_correlationThresholdGradient (determined upon setting default protocol parameters in GUI): Lower limit of correlation plot for non-baseline gradients.

INTERLACE_correlationDeviationBaseline (default setting is "2.5000"): Sigma or the number of standard deviations allowed for half-volume-to-half-volume correlation values for baseline gradients.

INTERLACE_correlationDeviationGradient (default setting is "3.0000"): Sigma or the number of standard deviations allowed for half-volume-to-half-volume correlation values for non-baseline gradients.

INTERLACE_translationThreshold (default setting is "2.0000"): Assesses transformation between half-volumes for each gradient. Units are in mm.

INTERLACE_rotationThreshold (default setting is "0.5000"): Assesses transformation between half-volumes for each gradient. Units are in degrees.

INTERLACE_outputDWIFileNameSuffix (default setting is blank): Suffix used when creating an output NRRD file of remaining gradients after Interlace-wise Checking. No output file after Interlace-wise Checking is produced if left blank.

INTERLACE_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

INTERLACE_reportFileMode (default setting is "1")

• 0: Creates a new QCReport text file containing information only from Interlace-wise Checking
• 1: Appends information from Interlace-wise Checking to the "your_nrrd_file_name_QCReport.txt" from the previous step.

INTERLACE_excludedDWINrrdFileNameSuffix (default setting is blank): Creates a NRRD file containing diffusion gradients excluded from Interlace-wise Checking when provided with a file name suffix

INTERLACE_bQuitOnCheckFailure (default setting is "Yes"): Terminates pipeline if Interlace-wise Checking has done one of the following

• Reduced the number of remaining gradients to less than 6
• Eliminated all baseline gradients
• Removed a number of gradients greater than the fraction allowed, which is specified by QC_badGradientPercentageTolerance

Baseline Averaging

 BASELINE_bAverage                             // Yes|No
 BASELINE_averageMethod;
 BASELINE_stopThreshold;
 BASELINE_outputDWIFileNameSuffix;
 BASELINE_reportFileNameSuffix                 // string
 BASELINE_reportFileMode                       // 0: new   1: append

BASELINE_bAverage (default setting is "Yes"): The default setting is an iterative process that first averages b0 gradients then registers each b0 gradient to the averaged b0 gradient. This is repeated until the averaged b0 image exhibits little change. Histograms describing the remaining gradients are outputted to the QCReport.

BASELINE_stopThreshold (default setting is "0.0200"): Amount of change allowed in the averaged b0 image between iterations

BASELINE_averageMethod (default setting is "1")

• 0: Directly averages b0 gradients.
• 1: Baseline optimized or the process described above (mutual information metric).
• 2: Gradient optimized where baseline gradients are mapped to non-baseline gradients.
• 3: Multi-image registration.

BASELINE_outputDWIFileNameSuffix (default setting is blank): Suffix used when creating an output NRRD file of remaining gradients after Baseline Averaging. No output file after Baseline Averaging is produced if left blank.

BASELINE_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

BASELINE_reportFileMode (default setting is "1")

• 0: Creates a new QCReport text file containing information only from Baseline Averaging
• 1: Appends information from Baseline Averaging to the "your_nrrd_file_name_QCReport.txt" from the previous step.

Eddy-current and head motion artifacts correcting

Here you can choose to use either of the two eddy-current and motion correction tools from Univ. Iowa and Univ. Utah. They are all open sourced and you can get the full versions of these tools via the following links:

• U. IOWA GTRACT.

 svn checkout https://www.nitrc.org/svn/vmagnotta  

• U. UTAH

 https://gforge.sci.utah.edu/gf/project/dwi-processing/

Limited experimentation indicates that the U. Iowa methods are more robust for a wide variety of DTI data sets.

Gradient-wise Checking

 GRADIENT_bCheck                           // Yes|No
 GRADIENT_badGradientPercentageTolerance;
 GRADIENT_translationThrehshold;
 GRADIENT_rotationThreshold;
 GRADIENT_outputDWIFileNameSuffix;
 GRADIENT_reportFileNameSuffix                 // string
 GRADIENT_reportFileMode                       // 0: new   1: append

GRADIENT_bCheck (default setting is "Yes"): Detects remaining motion artifacts across gradients that were not detected by the earlier intra-gradient checks. Rotation and translation information for each gradient, a list of gradients removed from this checking step, and histograms describing the remaining transformed gradients are outputted to the QCReport.

GRADIENT_translationThreshold (default setting is "2.0000"): Assesses transformation between each gradient. Units are in mm.

GRADIENT_rotationThreshold (default setting is "0.5000"): Assesses transformation between each gradient. Units are in degrees.

GRADIENT_outputDWIFileNameSuffix (default setting is blank): Suffix used when creating an output NRRD file of remaining gradients after Gradient-wise Checking. No output file after Gradient-wise Checking is produced if left blank.

GRADIENT_reportFileNameSuffix (default setting is "_QCed.txt"): Results in "your_nrrd_file_name_QCReport.txt"

GRADIENT_reportFileMode (default setting is "1")

• 0: Creates a new QCReport text file containing information only from Gradient-wise Checking
• 1: Appends information from Gradient-wise Checking to the "your_nrrd_file_name_QCReport.txt" from the previous step.

GRADIENT_excludedDWINrrdFileNameSuffix (default setting is blank): Creates a NRRD file containing diffusion gradients excluded from Gradient-wise Checking when provided with a file name suffix

GRADIENT_bQuitOnCheckFailure (default setting is "Yes"): Terminates pipeline if Gradient-wise Checking has done one of the following

• Reduced the number of remaining gradients to less than 6
• Eliminated all baseline gradients
• Removed a number of gradients greater than the fraction allowed, which is specified by QC_badGradientPercentageTolerance

DTI Computing

NOTE: This is intended to do a basic first level analysis on the QC'ed dti data. It is currently not fully functional, and is a work in progress. Please ignore these options 2009-02-24.

 DTI_bCompute                           // Yes|No
 DTI_dtiestimCommand                    // string
 DTI_dtiprocessCommand                  // string
 DTI_method                             // string
 DTI_baselineThreshold                  // to exclude the nonbrain tissue     
 DTI_maskFileName                       // string
 DTI_tensor                             // string
 DTI_baseline                           // string
 DTI_idwi                               // string
 DTI_fa                                 // string
 DTI_md                                 // string
 DTI_colorfa                            // string
 DTI_frobeniusnorm                      // string
 DTI_reportFileNameSuffix               // string
 DTI_reportFileMode                     // 0: new   1: append