[wiki:FsTutorial top] | [wiki:FsTutorial previous] | [wiki:FsTutorial/Visualization next]

PAGE UNDER CONSTRUCTION! DO NOT USE THIS FOR GROUP ANALYSIS!

Please continue to use our old [wiki:FsTutorial/GroupAnalysis tutorial] while we develop this!

FreeSurfer Tutorial: Group Analysis with QDEC

*To follow this exercise exactly be sure you've downloaded the [wiki:FsTutorial/Data tutorial data set] before you begin. If you choose not to download the data set you can follow these instructions on your own data, but you will have to substitute your own specific paths and subject names.

In this tutorial, you will learn how to perform statistical analysis of group surface-based data, including:BR

Assuming that all surface reconstruction has been completed for all subjects in the study, FreeSurfer's mri_glmfit command can be used to perform inter-subject/group averaging and inference on the cortical surface. Mri_glmfit models the data as a linear combination of effects related to variables of interest, confounds and errors, and permits statistical inferences to be made about effects of interest in relation to error variance. It also allows for certain permutation testing and other means for correcting for mutliple comparisons. For group analysis, this technique fits a general linear model (GLM) at each surface vertex to explain the data from all subjects in the study. In this section, a brief overview of linear modeling is presented and mri_glmfit is described for estimating a linear model and testing hypotheses. The modeling overview can be skipped if this material is already familiar. Other software packages have similar types of programs (e.g., FSL's GFEAT).

1.0 Preparing for Group Analysis

For group analysis, you can create an average subject from all the participants in the study. This average will be used as the target subject upon which the results of your group analysis can be output and viewed. To create this average, use make_average_subject. One has already been created for the later exercise, so there is no need to execute this sample command: 

make_average_subject --subjects <subj1> <subj2> ...

The default behavior of this script is to create a subject in the $SUBJECTS_DIR named 'average' using each subjects talairach.xfm transform. This behavior can be modified on the command line. You can specify --out your_named_average to change the name of the average subject and --xform talairach.lta (or talairach.m3z) to specify the use of one of the other transforms.

The average subject is created using the processed volumes and surfaces from the set of subjects you specify following the --subjects flag. The make_average_subject command executes both the make_average_volume and make_average_surface subscripts for you.

The distributed example of an average subject can be found in $FREESURFER_HOME/subjects/buckner_data/tutorial_subjs/group_analysis_tutorial called fsaverage

This average subject was created using the volumes and surfaces of subjects in:

$FREESURFER_HOME/subjects/buckner_data/group_study

(Note: the data in the group_study directory is not required to complete the tutorial. However, [wiki:FsTutorial/Data it is available for download] if you wish to pursue your own group analysis.)

https://surfer.nmr.mgh.harvard.edu/fswiki/make_5faverage_5fsubject

Introduction

Qdec is a single-binary application included in the Freesurfer distribution. QDEC is an acronym for Query, Design, Estimate, Contrast. It is intended to aid researchers perform inter-subject / group averaging and inference on the morphometry data (cortical surface and volume) produced by the Freesurfer processing stream. Prior to usage of qdec, all subcortical segmentation and surface reconstructions for all subjects in a study must be complete. The 'recon-all' script performs that work, and is not the subject of this document.

The qdec binary is a GUI front-end to a 'statistics engine' (the mri_glmfit binary, included in Freesurfer, currently fills this role) intended to:

  1. select the subjects meeting the criteria under study
  2. generate the necessary input to the stats engine, which, for mri_glmfit, includes:

    1. a Design matrix (called X in the GLM equation) containing the explanatory variables,

    2. a parameter Estimate matrix (called A in the GLM equation), and

    3. the Contrast vector(s)

  3. generate and optionally display the output data and/or images

Without the aid of the qdec tool, a researcher has to manually perform the stats analysis, which, when using the mri_glmfit utility, requires manual creation of an 'FSDG' file which specifies the X and A matrices for the group of subjects under study, and manually specifying the contrast vector(s) for the hypothesis to test. This can be quite tedious, and greatly slows down the "Test for an effect of factor X" research task. This is, in fact, the procedure described in the [wiki:FsTutorial/GroupAnalysis 'Group Analysis' tutorial].

Setup

recon-all

Prior to using the qdec application, your group subject data must be processed by the standard Freesurfer processing stream, via the recon-all script. [http://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial A freesurfer tutorial is available.] This processing stream supplies the surfaces and morphometry data on each subject.

pre-smoothed fsaverage surfaces

Qdec is happiest if there exists for each subject pre-computed smoothing data for the fsaverage target surface for each measure (thickness, sulc and curv). There are two options to create this data, via recon-all, or, if the cluster machine 'seychelles' is available to you (at the NMR Center), the script run_mris_preproc.

The recon-all incantation is: 

recon-all -s <subjid> -qcache

The -qcache flag will run numerous back-to-back mris_preproc processes on your machine, so be prepared for it to run for about an hour.

If the cluster machine is available to you, then: 

  ssh seychelles
    $ cd $SUBJECTS_DIR
    $ source /usr/local/freesurfer/nmr-dev-env
    $ run_mris_preproc qdec.table.dat

The qdec.table.dat is a text file associated with your group of subjects, described next (you will need this file independent of the mris_preproc step).

qdec.table.dat

The primary input to qdec is a text file, named qdec.table.dat, containing the subject IDs, and discrete and continuous factors, in table format. Here is an example file: 

fsid            gender  age diagnosis   Left-Cerebral-White-Matter
011121_vc8048   Female  70  Demented    202291
021121_62313-2  Female  71  Demented    210188
010607_vc7017   Female  73  Nondemented 170653
021121_vc10557  Male    75  Demented    142029
020718_62545    Male    76  Demented    186087
020322_vc8817   Male    77  Nondemented 149810

For each discrete factor, there must exist a file named <factor>.levels which lists all possible levels. For example, accompanying the example qdec.table.dat file must be a file named 'gender.levels' containing these lines: 

Female
Male

and there must be a file named 'diagnosis.levels' containing these lines: 

Demented
Nondemented

Of course you may have different discrete factor names and levels (or even no discrete factors, in which case all column data is assumed to be continous factors).

fsaverage

For display purposes, you will need to have an average subject included in this subject group. Freesurfer's fsaverage will do fine: 

cd $SUBJECTS_DIR
ln -s $FREESURFER_HOME/subjects/fsaverage

Usage

SUBJECTS_DIR and FREESURFER_HOME

First, set your SUBJECTS_DIR environment variable to point at your group subjects directory: 

setenv SUBJECTS_DIR /space/boing/users/me/subjects/my_big_study

Or, there is a sample data set you can use to learn: 

setenv SUBJECTS_DIR /autofs/space/sake_025/users/nicks/subjects/qdec3

Then, setup the 'dev' Freesurfer environment, which contains qdec: 

source /usr/local/freesurfer/nmr-dev-env

Startup

Now start qdec: 

qdec &

The first thing you will need to do is to load your qdec.table.dat file. Click File -> Load Data Table and traverse to your subjects directory and select your qdec.table.dat file that you created. When you click Open, it should load your file, the contents scrolling-by in the terminal window. If the data is loaded correctly, you should see in the terminal window a summary, like this example: 

Number of subjects:   295
Number of factors:    201 (2 discrete, 199 continuous)
Number of classes:    4
Number of regressors: 800

Your discrete and continous factors should appear in the Design tab of the qdec application.

Analysis

Select up to four factors in the Design tab to regress against. For the example data, you could select 'gender', 'diagnosis' and 'age'. Leaving the 'Smoothness', 'Measure' and 'Hemisphere' at their defaults (10mm, thickness, and lh), clicking the 'Analyze' button will begin the stats processing, executing the mri_glmfit executable. Upon clicking 'Analyze', the terminal will display the output of this processing. Also, progress information is shown in the bottom bar of the qdec application.

Display

Once the analysis is complete (taking up to several minutes for a large subject set), the fsaverage inflated surface will appear in the display window. Now click on the 'Display' tab. You will see displayed in the form of questions a summary of the various analyses that were completed. Click on one of these questions to load those results. Here is an example display:

attachment:qdec.jpg

Notice the green cross-hairs. You can display a plot of the data for a particular vertex by right-clicking on a point while holding-down the Ctrl key. Here is an example plot that corresponds to the shown selected vertex:

attachment:fsgdplot.jpg

Notice that thickness correlates with age at this vertex (thinning occurs).

To rotate the display, hold-down the left mouse button while moving. It takes quite a bit of practice to learn how to move the display. Holding-down the middle button while moving the mouse will move the display. Holding-down the right mouse button while moving will zoom the display.