From Vista Lab Manual
Automated fiber quantification (AFQ)
AFQ is designed to automatically identify major fiber tracts and quantify tissue properties along their trajectories. The result is a "Tract Profile" of MRI parameters that can be used to study white matter tissue properties in healthy brains or quantify abnormalities in diseased brains. In the future we hope to be able to automatically identify abnormalities in an individual and quantify that individual's risk for various functional consequences. AFQ is based on the main mrDiffusion software package but hopefully at some point will be written as a standalone routine. The main contributors to this project are Jason Yeatman, Bob Dougherty and Brian Wandell, however many others have contributed along the way. The software is described in:
Yeatman JD, Dougherty RF, Myall NJ, Wandell BA, Feldman HM (2012) Tract Profiles of White Matter Properties: Automating Fiber-Tract Quantification. PLoS ONE 7(11): e49790. doi:10.1371/journal.pone.0049790
The main steps in the AFQ analysis pipeline are briefly described below and each one is linked to a detailed description of the function. AFQ requires that the data be preprocessed in mrDiffusion with dtiInit to create a dt6.mat file (or processed in another software program and imported into mrDiffusion format). A detailed guide to all the AFQ functions can be found here along with an example of how to analyze a dataset with AFQ. AFQ_run is the main routine that will analyze a group of subjects. The example that is described in the help for AFQ_run will analyze an example data set that is provided with AFQ. Inputs into AFQ_run are a cell array of paths to subject's DTI data and if there are two groups of subjects a vector of 0s and 1s identifying subjects as patients (1) or controls (0). If two groups are provided AFQ_run will output plots of the normal range of the desired diffusion measurement (FA, RD etc.) along each of 20 major fiber tracts. Each subject that is outside this normal range on a given tract will be flagged and plotted with respect to the controls. It will also automatically perform group comparisons for each Tract Profile and plot out the results. If only one group of subjects is provided then the segmented fiber groups and Tract Profiles will be returned.
To run AFQ you must download AFQ, vistasoft, and spm (spm5 or spm8 works) and add them to your MATLAB search path. There are several options for downloading the software off of Jason's github site. v0.1 is the current stable release.
Another (highly recommended) option is to clone AFQ using git. Git can easily be installed on macs or windows and is already installed on most linux machines.The benefit to using git is that you can track changes to the AFQ software and make sure you are working with the most up to date version. To get AFQ with git open your terminal window, then type:
git clone https://github.com/jyeatman/AFQ.git
This will download the current version of the repository. To switch to the most recent stable release (v0.1), change into the AFQ directory and use the checkout command:
git checkout v0.1
Each time there is a new stable release I will tag it in the repository. To list all the tags use the tag command
git tag -l
To update the AFQ software, change into the AFQ directory and type:
I'm am constantly adding more function to improve the AFQ software. I do not necessarily commit these changes to master branch on github because I do not want to change functionality for current users. I use a separate development branch (called "devo") for ongoing software development and maintain the "master" branch as a stable release. You can switch from: the "master" branch and the "devo" branch by typing
git checkout --track origin/devo
This command will tell git to switch over to the "devo" branch so whenever you update the software with git pull, git will pull any changes that I have made to the development branch. You can now switch back and forth between the branches by typing either:
git checkout master git checkout devo
And you can check which branch you are running by typing:
For more information on how branches work see the git help page for remote branches.
I am working on writing a set of matlab tutorials demonstrating the different features of AFQ. They will be posted as they are written.
1. To run the full AFQ pipeline on one or 2 groups of subjects see help AFQ_run
2. For an example of how to track, segment, clean, analyze and visualize fiber groups in an individual subject see AFQ_example
3 Statistical tests can be rendered on a fiber groups Tract Profile. For an example of how to do an independent samples T-test and visualize the T statistics along the Tract Profiles see AFQ_example_GroupComparison
There are a number of options that can be changed in AFQ (however the defaults are most likely fine). All the options for running AFQ are saved in the afq structure that is created with AFQ_Create. To change any of the options define the parameter to be changed and the value that it should be changed to using AFQ_Create. All the parameters are described in AFQ_Create. In a matlab command window type
AFQ contains a number of functions for rendering meshses of fiber tracts and cortical surfaces. The below video was created using the code in the CortexAndFibersMovie.m tutorial which is included in the AFQ software release.
Run the full AFQ analysis pipeline on a group of subjects. The following sections describe the AFQ pipeline. An example of how to use AFQ can be found here
Perform whole brain tractography for a subject. All fibers will be tracked from a white matter mask using deterministic tractography (STT)
This function will segment a whole brain fiber group into the 20 fascicles that are defined in the Wakana et al. (2007) white matter atlas. Candidate fibers for each fascicle are defined with an automated 2 ROI approach. Then fiber tracts are refined by comparing each fiber within the fascicle to a probabilistic fiber tract atlas.
This function will clean stray fibers that deviate substantially from the core of a fiber group. It does this by representing a fiber group as a 3-D gaussian and removing fibers that deviate substantially from the fiber group center.
Define the core of the tract and calculate diffusion measurements along the trajectory of the fiber group weighting each fibers contribution to the measurement based on its distance from the tract core
Compute norms for each tract based on the control group.
Compare each patient to the norms and identify ones that deviate from the standardized Tract Profiles
Visualize the results. This contains a variety of functions for plotting either groups or individual subjects.
Render a fiber group and Tract Profile in 3-D.
Export all the tract profiles as a .csv file that can be read into MS Excel or SPSS
Discussion ongoing in the AFQ Google Group
1. Function for coregistering Tract Profiles is in development but has not been fully tested yet
2. Making Tract Profiles for the full tract is not yet recommended. To do this Tract Profiles need to be coregistered across subjects and some subjects tracts must be flipped to make sure that their start and endpoints are consistent. This will be implemented soon.
3. Tract volume calculations are currently being done based on the covariance matrix at each point. This method is noisy and will be improved in subsequent releases.