Home
AFQ automatically identifies the core of major fiber tracts and quantifies the tissue properties in the voxels near the tract cores. The analysis produces a set of "Tract Profiles" that measure the tissue property at sample positions from the start to the end of the tract core. There is one profile for each tract and tissue property combination. The tract profiles have been used to characterize white matter properties in healthy brains or quantify abnormalities in diseased brains. Through the use of neuroinformatics tools, we can automatically identify abnormalities in the profiles of an individual.
AFQ 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
See the discussion AFQ Google Group for more information and find help from other users.
Return to the vistasoft wiki pages.
At present, AFQ uses functions from mrDiffusion, a component of vistasoft. We plan to implement AFQ in a docker container that can be invokved as a standalone routine. The AFQ pipeline is briefly described below. The main steps in the pipeline are 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). AFQ_run is the main routine to analyze group data. This function runs the full automated pipeline and is extensively documented. The example in help AFQ_run analyzes a data set that is included in the repository. For single subject analysis, see AFQ_example.m.
Inputs into AFQ_run are a cell array of paths to subject's DTI data and, if there are two groups of subjects, a binary 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 spm5 or spm8 and add them to your MATLAB search path, preferably by creating a startup.m file. There are several options for downloading the software off of the Yeatman Lab github site. v1.2 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 releases. 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/yeatmanlab/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 we 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
We are constantly adding more function to improve the AFQ software: For more information on how branches work see the git help page for remote branches.
There are a number of tutorials that give examples of different uses of AFQ. We invite users to submit their tutorials!
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.m
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.m
4. There are many functions within AFQ that are not described here but contain extensive documentation within the help of the function: See AFQ functions here and visualization tools here
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
AFQ contains a number of functions for rendering meshses of fiber tracts and cortical surfaces. The below video was created using the code in CortexAndFibersMovie.m tutorial which is included in the AFQ software release.
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.
1. AFQ_WholebrainTractography
Perform whole brain tractography for a subject. All fibers will be tracked from a white matter mask using deterministic tractography (STT), but other algorithms (e.g., CSD through mrtrix) are also supported
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
5. AFQ_ComputeNorms
Compute norms for each tract based on the control group.
6. AFQ_ComparePatientsToNorms
Compare each patient to the norms and identify ones that deviate from the standardized Tract Profiles
7. AFQ_plot
Visualize the results. This contains a variety of functions for plotting either groups or individual subjects.
8. AFQ_RenderFibers
Render a fiber group and Tract Profile in 3-D.
9. AFQ_exportData
Export all the tract profiles as a .csv file that can be read into MS Excel or SPSS
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')
The default in AFQ is to use tensor based deterministic tractograpy. While this is approach sufficient for many applications, there are other instances where a more complicated diffusion model (e.g., CSD) or tractography algorithm (e.g., probabilistic) is desirable. Many of us like to work with mrtrix, and now vistasoft includes a set of tools to interface with mrtrix through MATLAB. mrtrix_init can be used to fit the CSD model and mrtrix_track can be used to estimate a whole-brain connectome with the algorithms included in mrtrix.
If you use mrtrix to track a whole-brain connectome for each subject, rename the file properly ('WholeBrainFG') and place it in each subject's fibers directory, then AFQ will automatically use these fibers. You can also point AFQ to wholebrain fiber groups with another name by editing the paths within the afq structure (afq.files.fibers.wholebrain).
Also see here for importing fibers already tracked in mrTrix.
Recent revisions of AFQ allow you to use mrtrix by setting one parameter in the AFQ structure:
AFQ_Create(...,'computeCSD', 1)
With computeCSD=1 AFQ will automatically use mrtrix to fit the model and will use mrtrix for tractography.
Subject characteristics, such as age, gender, clinical condition and behavioral scores, should be stored within the metadata field of the afq structure. For example, if you ran AFQ on four subjects who were 10, 12, 13 and 15 years of age, 2 males and 2 females:
afq.metadata.age = [10, 12, 13, 15];
afq.metadata.gender = {'Male', 'Male', 'Female', 'Female'};
The order of the scores in afq.metadata should match the order of the subjects. For example afq.sub_dirs{1} should correspond to a 10 year old male in the above example. If metadata is entered in this way, there are a number of useful functions for data analysis
By convention, we ac-pc align each subjects T1 anatomy and align the dMRI data to this ac-pc aligned anatomical image. This makes is so that the qto_xyz transform in the dMRI nifit transforms the data to millimeter coordinates centered around the anterior commissure. At the very least, this transform should roughly center the image. This is important for later steps that use this transform for various alignments The coordinates of all the fiber groups and core fibers in AFQ are in native x,y,z space. There are many ways to do this. One way is to use mrAnatAverageAcpcNifti to ac-pc align the T1 anatomy and then use dtiInit to process the dMRI data which will then be automatically aligned to the T1.
This coordinate space is defined by the field in the dt6 xformToAcpc which takes image indices from the dti data and transforms them to millimeter coordinates. This field is equivalent to the qto_xyz field in the dti nifit image. Thus fiber coordinates can be negative and they can be non-integer. They can be non-integer because millimeter coordinates can be sampled at sub-milimeter resolution as is common in tractography algorithms for which the step size is a parameter that can be set. One implication of this is that the euclidean distance between points on two different fiber groups, or between a fiber node and the fiber core, can be calculated with units of millimeters.