Back to list of all tutorials
Back to course page
FslFeat Tutorial Homepage

Preparations

If You're at an Organized Course

If you are taking one of the formally organized courses, everything has been set up for you on the provided laptop. The only thing you will need to do is run the following commands in every new terminal window (aka shell) you open throughout this tutorial. Copy and paste the commands below to get started:

setenv SUBJECTS_DIR $TUTORIAL_DATA/buckner_data/tutorial_subjs
cd $SUBJECTS_DIR/fbert-feat
ln -s $FREESURFER_HOME/subjects/fsaverage
ln -s $FREESURFER_HOME/subjects/bert

To copy: Highlight the command in the box above, right click and select copy (or use keyboard shortcut Ctrl+c), then use the middle button of your mouse to click inside the terminal window (this will paste the command). Press enter to run the command.

These two commands set the SUBJECTS_DIR variable to the directory where the data is stored and then navigates into this directory. You can now skip ahead to the tutorial (below the gray line).

If You're not at an Organized Course

If you are NOT taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the 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. These are the commands that you need to run before getting started:

tcsh
source your_freesurfer_dir/SetUpFreeSurfer.csh
setenv SUBJECTS_DIR $TUTORIAL_DATA/buckner_data/tutorial_subjs
cd $SUBJECTS_DIR/fbert-feat
ln -s $FREESURFER_HOME/subjects/fsaverage
ln -s $FREESURFER_HOME/subjects/bert

Notice the command to open tcsh. If you are already running the tcsh command shell, then the 'tcsh' command is not necessary. If you are not using the tutorial data you should set your SUBJECTS_DIR to the directory in which the recon(s) of the subject(s) you will use for this tutorial are located.

The subjects 'fsaverage' and 'bert' may already exist in the subjects directory, so ignore any warnings that might be issued that say 'File exists'.

1.0 Resampling COPEs to common surface

1.1 Individual Runs for a Subject

In order to perform surface-based group analysis, you need to have all the copes sampled into a common space. This is done with mris_preproc:

mris_preproc --target fsaverage --hemi lh --fwhm 5 \
  --out xrun/lh.cope1.mgh \
  --iv fbert1.feat/stats/cope1.nii.gz fbert1.feat/reg/freesurfer/anat2exf.register.dat \
  --iv fbert2.feat/stats/cope1.nii.gz fbert2.feat/reg/freesurfer/anat2exf.register.dat

In this case, the common space is the left hemisphere of fsaverage. Surface-based smoothing of 5mm FWHM is used. The output lh.cope1.mgh looks like a volume because it is in mgh format, but it is really a surface stored in a volume format (note it's dimensions are 1974 x 1 x 83 = 163842 = number of vertices in fsaverage's surface). It has 2 frames, one for each run.

Note that each volume (cope1.nii.gz) is accompanied by a registration matrix (anat2exf.register.dat). The above example extracts data from each run of the same subject. If you have multiple subjects, you can specify the gfeat/cope1/stats/cope1.nii.gz paired with the anat2std.register.dat matrix.

You can also extract the cope variances (varcopes) in the same way:

mris_preproc --target fsaverage --hemi lh --fwhm 5 \
  --out xrun/lh.varcope1.mgh \
  --iv fbert1.feat/stats/varcope1.nii.gz fbert1.feat/reg/freesurfer/anat2exf.register.dat \
  --iv fbert2.feat/stats/varcope1.nii.gz fbert2.feat/reg/freesurfer/anat2exf.register.dat

1.2 Runs combined in a GFEAT within a Subject

Once the runs are combined in a GFEAT analysis, they are no longer in the native functional space but rather in the standard space. You can still use the surface-based analysis as long as the subjects have not been combined together. To do this, you just need the appropriate registration matrix that takes the data from standard space to the subject's anatomical. This is computed when you run reg-feat2anat. Each run will have this matrix, but they should all be the same. Eg:

mris_preproc --target fsaverage --hemi lh --fwhm 5 \
  --out xsubject/lh.cope1.mgh \
  --iv fbert.gfeat/cope1.feat/stats/cope1.nii.gz fbert1.feat/reg/freesurfer/anat2std.register.dat \
  --iv fnick.gfeat/cope1.feat/stats/cope1.nii.gz fnick1.feat/reg/freesurfer/anat2std.register.dat \
  ...

The cope is specified from the gfeat, but the registration matrix is specified from the feat from the first run of each subject. The output can be used in the surface-based group analysis below.

2.0 Surface-based Group Analysis (Fixed Effects)

Once you have the copes in the common surface space, the (nearly) same as you would with a thickness study. With a functional study, you also have the flexibility to run fixed- and weighted random-effects analysis.

The command below can be used to run a fixed-effects analysis across both runs. Normally, you would probably run a random effects or weight random effects analysis, but since we only have two runs here, we'll use a fixed-effects. The dof=163 is the sum of the dofs from fbert?.feat/stats/dof. The model here is a simple one-sample group mean (OSGM) in which the design matrix is simply a column of 1s. For more elaborate designs, use an FSGD file instead of --osgm.

mri_glmfit --y xrun/lh.cope1.mgh --yffxvar xrun/lh.varcope1.mgh --ffxdof 163 \
           --osgm --glmdir xrun/lh.osgm.ffx --surf fsaverage lh \
           --label $SUBJECTS_DIR/fsaverage/label/lh.cortex.label

This will create a directory called xrun/lh.osgm.ffx:

ls xrun/lh.osgm.ffx
ar1.mgh -- spatial AR1 map
beta.mgh -- regression coefficients (same as PEs)
fwhm.dat -- estimate of spatial FWHM (not valid with 2 data points)
mask.mgh -- binary mask (if used)
mri_glmfit.log -- log file
osgm -- contrast directory
rstd.mgh -- residual standard deviation
rvar.mgh -- residual standard variance
Xg.dat -- design matrix (text)
X.mat -- design matrix (matlab)

The most important results are in the contrast directory:

ls xrun/lh.osgm.ffx/osgm
C.dat - contrast matrix
cnr.mgh - contrast-to-noise ratio
F.mgh - F ratio
gamma.mgh - contrast size (same as COPE)
maxvox.dat - info about the vertex with max F stat
sig.mgh - significance map (-log10(p))

To view the higher-level results, run:

tksurfer fsaverage lh inflated  \
  -overlay xrun/lh.osgm.ffx/osgm/sig.mgh  \
  -fthresh 2 -fmid 3 -fslope 1 -annot aparc.annot

There are several differences between this invocation of tksurfer and the one used during the individual analysis before:

• The subject is fsaverage, not bert
• The input is a sig map, which is -log10(p)

• The thresholds are significance thresholds, not z. So, 2 means p < .01.

3.0 Alternative method to resample COPEs to common surface

This command will resample the copes to the common surface space, but does not concatenate them together as mris_preproc does. Rather, it stores the result in fbert1.feat/reg_surf-lh-fsaverage/stats for the left (reg_surf-rh-fsaverage for right).

feat2surf --feat fbert1.feat --cope-only

4.0 Surface-based Group Analysis (Random Effects)

Usually, you will have many subjects and will want to run a random effects analysis. To do this, stack your subjects into one file (lh.cope1.mgh below) using mris_preproc or mri_concat and run the command below:

mri_glmfit --y lh.cope1.mgh \
           --osgm --glmdir lh.osgm.rfx --surf fsaverage lh \
           --label $SUBJECTS_DIR/fsaverage/label/lh.cortex.label

Back to list of all tutorials
Back to course page
FslFeat Tutorial Homepage