AFQ

From Vista Lab Manual

Contents

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.

Image:TractProfiles.jpg

Download AFQ

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:

  git pull

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:

 git branch

For more information on how branches work see the git help page for remote branches.

AFQ Tutorials

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

4 Here is a complete list of AFQ functions

AFQ Options

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

  edit AFQ_Create

3D Visualization

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.

Image:FibersMovie.gif

AFQ contains a number of tools to visualize data on a mesh of the cortical surface. See the page of AFQ Cortical Meshes for some examples of the tools.

AFQ Pipeline

AFQ_run

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

1. AFQ_WholebrainTractography

Perform whole brain tractography for a subject. All fibers will be tracked from a white matter mask using deterministic tractography (STT)

2. AFQ_SegmentFiberGroups

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.

3. AFQ_removeFiberOutliers

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.

4. AFQ_ComputeTractProperties

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

4. AFQ_ComputeNorms

Compute norms for each tract based on the control group.

5. AFQ_ComparePatientsToNorms

Compare each patient to the norms and identify ones that deviate from the standardized Tract Profiles

6. AFQ_plot

Visualize the results. This contains a variety of functions for plotting either groups or individual subjects.

7. AFQ_RenderFibers

Render a fiber group and Tract Profile in 3-D.

8. AFQ_exportData

Export all the tract profiles as a .csv file that can be read into MS Excel or SPSS

User Notes

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.

Analyzing quantitative MRI data with AFQ

AFQ will generate Tract Profiles of tissue properties for any data type that is saved as a nifti image and coregistered to the DWI data. To add aditional maps to your AFQ analysis you must add paths to the relevant image for each subject. First you have to create an afq structure with a cell array of paths to each subject's dt6.mat directory (sub_dirs) and a binary vector defining patients and controls (sub_group). This is where all the subsequent computations will be saved.

  afq = AFQ_Create( 'sub_dirs', sub_dirs, 'sub_group', sub_group);

Then you can use the AFQ_set command to add additional maps to the structure. You first need to create a cell array of paths to each subjects image.

  for ii = 1:length(sub_dirs), t1Path{ii} = fullfile(sub_dirs{ii}, 't1_map.nii.gz'), end
  afq = AFQ_set(afq, 'images', t1Path);

Now when you run AFQ Tract Profiles for these maps will automatically be computed and added to the AFQ structure:

  afq = AFQ_run(sub_dirs, sub_group, afq);

The values of the tract profiles will be saved based on the name of the image (eg. t1_map). They can be accessed in the afq structure using the AFQ_get command:

  vals = AFQ_get(afq, 'Left Arcuate' , 't1_map')