app-tractographyQualityCheck
This app computes a number of statistics about your input tractogram and any (optionally input) associated White Matter Classification (WMC) structure. These statistics can be used to facilitate quality assurance on your tractography and segmentation, or as part of subject/group level quantative analysis for a research project. See the output section for a detailed description of the measures computed.
Authors
- Daniel Bullock (dnbulloc@iu.edu)
Contributors
- Soichi Hayashi (hayashis@iu.edu)
Project Director
- Franco Pestilli (franpest@indiana.edu)
Funding
References
Running the App
Inputs
On Brainlife.io
Visit this site to run this app on the brainlife.io platform. Minimally requires a tractogram. Can also be augmented with a LiFE input and/or a White Matter Classification (WMC) structure object to perform statistical analyes relevant to the LiFE fit and/or segmentation.
Running Locally (on your machine) using singularity & docker
Because this is compiled code which runs on singularity, you can download the repo and run it locally with minimal setup.
Running Locally (on your machine)
Pull the WMA toolkit repo
Ensure that the packages listed under 'adding paths' are avaialble on your local environment.
Run: this function, but take care to ensure that the addpath-genpath statements are relevant to your local setup.
Utilize a config.json setup that is analagous to the one contained within this repo, listed as a sample.
Sample Datasets
Visit brainlife.io and explore the following data sets to find viable classification and tractography inputs:
Output
There are three outputs generated by this application:
a csv output from the quality check app which displays the following traits for each tract:
| Column header | Description |
|---|---|
| TractName | The name of this tract |
| Code Link: NA | |
| StreamlineCount | The number of streamlines in this tract |
| Code Link | |
| volume | The volume occupied by this tract (presented in cubic mm) |
| Code Link | |
| averageStreamlineLength | The mean streamline length of this tract |
| Code Link | |
| streamlineLengthStdev | The standard deviation of streamline lengths for this tract |
| Code Link | |
| averageFullDisplacement | The average distance between streamline endpoints for this tract |
| Code Link | |
| fullDisplacementStdev | The standard deviation of distances between streamline endpoints for this tract |
| Code Link | |
| ExponentialFitA | The (a) parameter when fitting y=a^(b*x) for the whole brain distribution of fiber lengths. Only ever computed for the whole brain tractography (i.e. is empty for all non "whole brain" tracts) |
| Code Link | |
| ExponentialFitB | The (b) parameter when fitting y=a^(b*x) for the whole brain distribution of fiber lengths. Only ever computed for the whole brain tractography (i.e. is empty for all non "whole brain" tracts) |
| Code Link | |
| StreamlineLengthTotal | The sum total of streamline lengths for this tract (i.e. total wiring) |
| Code Link | |
| endpoint1Density* | The density of the endpoint mask associated with the right/superior/anterior-most (whichever is most appropriate for this tract) collection of terminations for this tract. Computes the number of endpoints per occupied (by endpoints from this group) 1mm cubic voxel. |
| Code Link | |
| Endpoint2Density* | The density of the endpoint mask associated with the left/inferior/posterior-most (whichever is most appropriate for this tract) collection of terminations for this tract. Computes the number of endpoints per occupied (by endpoints from this group) 1mm cubic voxel. |
| Code Link | |
| AverageEndpointDistanceFromCentroid1* | The average distance of a streamline endpoint within the right/superior/anterior-most group from the centroid of this group. Computed as the euclidean distance from the average coordinate of this group. Considered to be a measure of streamline endpoint dispersion. |
| Code Link | |
| AverageEndpointDistanceFromCentroid2* | The average distance of a streamline endpoint within the left/inferior/posterior-most group from the centroid of this group. Computed as the euclidean distance from the average coordinate of this group. Considered to be a measure of streamline endpoint dispersion. |
| Code Link | |
| stdevOfEndpointDistanceFromCentroid1* | The standard deviation of the distances of a streamline endpoint within the right/superior/anterior-most group from the centroid of this group. Computed as the euclidean distance from the average coordinate of this group. |
| Code Link | |
| stdevEndpointDistanceFromCentroid2* | The standard deviation of the distances of a streamline endpoint within the left/inferior/posterior-most group from the centroid of this group. Computed as the euclidean distance from the average coordinate of this group. |
| Code Link | |
| MidpointDensity | The density of the midpoint mask associated for this tract. Computes the number of midpoints per occupied (by midpoints) 1mm cubic voxel. |
| Code Link | |
| averageMidpointDistanceFromCentroid | The average distance of a streamline midpoint from the centroid of this group. Computed as the euclidean distance from the average coordinate of this group. |
| Code Link | |
| stDevOfMidpointDistanceFromCentroid | The standard deviation of the distances of a streamline midpoint from the centroid of this group. Computed as the euclidean distance from the average coordinate of this group. |
| Code Link | |
| TotalVolumeProportion | The proportion of the total white matter volume occupied by this tract. Intended to control for variability in brain size. |
| Code Link | |
| TotalCountProportion | The proportion of the total number of streamlines associated with tract. Intended to control for variability in input tractogram size (i.e. whole brain streamline total). |
| Code Link | |
| TotalWiringProportion | The proportion of the total streamline length accounted for by streamlines associated with this tract. |
| Code Link |
*endpoint membership in either the left/inferior/posterior-most (LIP) or right/superior/anterior-most (RAS) group is determined by the following process:
- computing the primary dimension of traversal for a tract (i.e. left-right, inferior-superior, anterior-posterior) by determining which dimension exhibits the greatest displacement for the given tract.
- Once this dimension has been determined, the relevant coordinates (x, y, or z) of the streamline's endpoints are checked to determine determine LIP or RAS membership
An svg image output from the quality check app with the following plots:
| Figure title | X axis quantity | Y axis quantity | Description |
|---|---|---|---|
| "Normalized WBFG & NonZero Weighted Stream Count Comparison" | streamline length (in mm) | whole brain proportion of the streamline count | This plot depicts the proportion of streamlines (out of all those in the whole brain fiber group) that are of a certain length. The dark blue line corresponds to the input whole brain tractogram, while the light blue line corresponds to the line of best fit using an exponential model (y=a^(b*x)). The relevant parameters can be noted in the grey column on the left. |
| "Cumulative proportion of fibers in connectome, by length" | streamline length (in mm) | total proportion of streamlines | This plot depicts the total proportion of streamlines that are equal to or less than the specified length. |
| "Classified Streamline proportion Comparison: WBFG & Surviving" | streamline length (in mm) | total proportion of classified streamlines | Similar to the first plot, but only computes proportions for classified streamlines. Proportion is relative to all classified streamlines. |
| "Log10 of proportion of connectome streamlines in tract" | tract names | log10 of the percentage of the total number of streamlines in whole brain fiber group | For all identified tracts in the input white matter classification (WMC) structure this plot indicates the percentage (scaled in log10) of all streamlines in the whole brain fiber group that are associated with this specific tract.For tracts which have left and right variants, left is plotted in blue and right is plotted in orange. For tracts which do not have left and right variants (i.e. are interhemispheric) the default color is blue. |
| "Proportion of white matter volume occupied by tract" | tract names | Portion of white matter occupied (by percent) | For all identified tracts in the input white matter classification (WMC) structure this plot indicates the percentage of the total white matter volume occupied by each respective tract. For tracts which have left and right variants, left is plotted in blue and right is plotted in orange. For tracts which do not have left and right variants (i.e. are interhemispheric) the default color is blue. |
A tiered, field based .mat structure with the metrics included in the tractmeasures.csv , along with additional metrics. Generated as an output from the quality check app. Below the metrics not included in the tractmeasures.csv are described.
Note: statistics listed immediately below are those within the field contents of results.WBFG and are specific to the associated whole brain fiber group, and are thus computed across all streamlines in the associated** whole brain fiber group**. The exception is the tractStats field, which will be described in a separate table immediately following this one.
| Fieldname (within results.WBFG) | Description |
|---|---|
| avgefficiencyRat(average efficiency ratio) | This quantity is the average efficiency ratio for all streamlines in the entire whole brain fiber group. For a given streamline this is computed by dividing the streamline's displacement (see description in tractmeasures.csv section) by that same streamline's length. Thus this value approaches 1 as a streamline approaches being shaped like a straight line, and approaches 0 as a streamline approaches being shaped like a full circuit. |
| Code Link | |
| stDevefficiencyRat(standard deviation of efficiency ratio) | This quantity is the standard deviation of the efficiency ratio for all streamlines in the entire whole brain fiber group. |
| Code Link | |
| avgAsymRat(average asymmetry ratio) | This quantity is the average asymmetry ratio for all streamlines in the entire whole brain fiber group. In essence, for a given streamline, it is the square of the differences between the efficiency ratios for the respective halves of a streamline. Thus, as a streamline's asymmetry ratio approaches the maximum of 1, it indicates that one half has an efficiency ratio of 0, and resembles a full circuit, while the other half has an efficiency ratio of 1 and resembles a straight line. On the other hand, as a streamline's asymmetry ratio approaches the minimum of 0, the difference between the two halves' efficiency ratios approach 0, and are thus presumed to more closely resemble one another, at least within the domain of wiring efficiency. |
| Code Link | |
| stdDevAsymRat(standard deviation of asymmetry ratio) | This quantity is the standard deviation of the asymmetry ratio for all streamlines in the entire whole brain fiber group. |
| Code Link | |
| volLengthRatio(volume length ratio) | The ratio of the total wiring length for all streamlines in the whole brain fiber group to the total white matter volume of the whole brain fiber group (i.e. in this case, simply the total volume of the white matter) |
| Code Link | |
| lengthCounts | A 1x299 long vector wherein the ith entry corresponds to the number of streamlines such that i≤[streamline length]<i+1 |
| Code Link | |
| LengthProps | A 1x299 long vector wherein the ith entry corresponds to the proportion of the total number of streamlines such that i≤[streamline length]<i+1 |
| Code Link | |
| LengthData | The computed length for each streamline in the whole brain fiber group. |
| Code Link | |
| tractStats | A 1 by N cell structure, wherein each cell entry corresponds to the output of a quantitative analysis for a specific tract. The ith entry in this cell structure corresponds to the tract specified in the ith entry in the classification.names field of the associated classification structure. |
| Code Link |
Note: statistics listed immediately below are those within the field contents of results.WBFG.tractStats{1,i}, where i corresponds the tract specified in the ith entry in the classification.names field of the associated classification structure. The quantifications described below are specific to their associated tract. Omitted from these descriptions are quantifications which have been described either for the tractmeasures.csv data object or the results.WBFG field. In cases where the quantification has previously been described within the context of a measurement of a whole brain fiber group, the quantification is to be understood to represent the same general concept, but to characterize a specific tract in these cases.
| Fieldname (within results.WBFG.tractStats{1,i}) | Description |
|---|---|
| endpointVolume1 | The volume of the endpoint mask associated with the right/superior/anterior-most (whichever is most appropriate for this tract) collection of terminations for this tract. |
| Code Link | |
| endpointVolume2 | The volume of the endpoint mask associated with the left/inferior/posterior-most (whichever is most appropriate for this tract) collection of terminations for this tract. |
| Code Link | |
| avgEndpointCoord1 | The centroid of the endpoints associated with the right/superior/anterior-most end of this tract. Computed as the average coordinate of this group. |
| Code Link | |
| avgEndpointCoord2 | The centroid of the endpoints associated with the left/inferior/posterior-most end of this tract. Computed as the average coordinate of this group. |
| Code Link | |
| midpointVolume | The volume of the endpoint mask associated with the midpoints of streamlines associated with this tract. |
| Code Link | |
| avgMidpointCoord | The centroid of the midpoints of streamlines associated with this tract. Computed as the average coordinate of this group. |
| Code Link | |
| results.WBFG.tractStats{1,i}.endpointVolume1Prop | The proportion of the total white matter volume occupied by this endpoint mask associated with the right/superior/anterior-most (whichever is most appropriate for this tract) collection of terminations for this tract. Intended to control for variability in brain size. |
| Code Link | |
| results.WBFG.tractStats{1,i}.endpointVolume2Prop | The proportion of the total white matter volume occupied by this endpoint mask associated with the left/inferior/posterior-most (whichever is most appropriate for this tract) collection of terminations for this tract. Intended to control for variability in brain size. |
| Code Link | |
| results.WBFG.tractStats{1,i}.midpointVolumeProp | The proportion of the total white matter volume occupied by this endpoint mask associated with the midpoints of streamlines associated with this tract. Intended to control for variability in brain size. |
| Code Link |
Product.json
Currently not implimented
Dependencies
This App only requires singularity, and in order to load the tck, a verson of vistasoft.
(Click here to learn more about installing singularity)
Release Notes
1.3
Updated the neuro/tractmeasure output column name to use "structureID" instead of "TractName" to adheare to neuro/tractmeasure datatype specification