| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
|
== 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 1. 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, 1. a parameter '''Estimate''' matrix (called '''A''' in the GLM equation), and 1. the '''Contrast''' vector(s) 1. 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:Self: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). recon-all is used to create this data: {{{ recon-all -s <subjid> -qcache }}} The -qcache flag will run numerous mris_preproc and mri_surf2surf processes on your machine, so be prepared for it to run for about an hour. An alternate average surface can be specified by adding {{{-target myaverage}}} to the recon-all command (replacing {{{myaverage}}} with whatever average subject you may have created, noting that the default {{{fsaverage}}} is fine in most instances). === 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. |
See FsTutorial/QdecGroupAnalysis |
- Diff for "Qdec"