FreeSurfer

Freesurfer is a surface-based fMRI processing and analysis package written for the Unix environment (including Mac OS X, which is based on Unix). The neuroanatomical organization of the brain has the grey matter on the outside surface of the cortex. Aside from the ventral/medial subcortical structures, the interior volume of the brain is predominately white matter axonal tracts. Because neurons metabolize in the cell body, rather than along the axons, we can focus on the grey matter found in the cortical surface because any fMRI signal changes detected in the white matter should theoretically be noise. This is the motivation for surface-based analyses of fMRI.

Freesurfer has a rigid set of assumptions concerning how the input data is organized and labeled. The following instructions will help avoid any violations of these assumptions that might derail your Freesurfer fMRI processing pipeline.

These instructions assume that Freesurfer has already been installed and configured on your workstation.

Organization

Freesurfer data for a collection of subjects is organized into a single project directory, called $SUBJECTS_DIR. Try this in the Linux terminal:

echo $SUBJECTS_DIR

It is likely that you will see something like the following, which is the sample 'bert' dataset that comes with a Freesurfer installation:

/usr/local/freesurfer/subjects

Let us assume that you have been collecting data for some lexical decision task experiment. All the data for all subjects should be stored in a single directory, which you will set as your $SUBJECTS_DIR variable. For example, if we keep all our data in ~/ubfs/cpmcnorg/openfmri/LDT, then we would type the following:

SUBJECTS_DIR=~/ubfs/cpmcnorg/openfmri/LDT
echo $SUBJECTS_DIR

Another trick we can do is to use the Unix pwd command to set the SUBJECTS_DIR to be whatever directory we happen to be in at the moment. The following series of commands will do the same as the previous example command:

cd ~
cd ubfs/cpmcnorg/openfmri
cd LDT
SUBJECTS_DIR=`pwd`
echo $SUBJECTS_DIR

The first line above, cd ~ moves you to your home directory. The second line moves you from your home directory to the ubfs network folder containing several sets of experiments. The third line of code moves you into the subdirectory containing the LDT data. The fourth line sets the SUBJECTS_DIR environment variable to whatever gets printed out when you execute the pwd command (the pwd command prints the current working directory). As a result, the current working directory becomes the new SUBJECTS_DIR after you execute this command, as you can see when you execute the last line of code.

Subject directory organization

Data for each subject should be kept in their own directory. Moreover, different types of data (i.e., anatomical/structural or bold/functional) are kept in separate subdirectories. Assuming your raw data are in the .nii format, the basic directory structure for each participant ('session' in Freesurfer terminology) looks like this:

• SUBJECTS_DIR
  • Subject_001
    • mri
      • orig.nii
    • bold
      • 001/f.nii
      • 002/f.nii
      • 003/f.nii
      • etc.
  • Subject_002
    • mri
      • orig.nii
    • bold
      • 001/f.nii
      • 002/f.nii
      • 003/f.nii
      • etc.

Note that all the functional data (in the 'bold' subdirectory) are stored in sequentially numbered folders (3-digits), and all are called 'f.nii'. This seems to be a requirement. It may be possible to circumvent this requirement, but this is a relatively minor concern at this time.

Structural Preprocessing

The structural mri file (orig.nii) is transformed over a series of computationally-intensive steps invoked by the recon-all Freesurfer program. Recon-all is designed to execute all the steps in series without intervention, however in practice it seems preferable to execute the process in a series of smaller groups of steps and check the output in between. This is because the process is automated using computational algorithms, but if one step doesn't execute correctly, everything that follows will be compromised. The steps take many hours to complete, so by inspecting the progress along the way can save many hours of processing time redoing steps that had been done incorrectly.

Image Format: Slicer

The first thing that you will need to do is convert the orig.nii file to .mgz format using Slicer. Though Freesurfer is capable of reading .nii files, it natively uses .mgz files, and so this conversion step will ensure that the structural data file has all the information that Freesurfer expects.

Recon-All

The computationally-intensive surface mapping is carried out by a Freesurfer program called recon-all. This program is extensively spaghetti-documented on the Freesurfer wiki here. Though the Freesurfer documentation goes into much detail, it is also a little hard to follow at times and sometimes does some odd things. Notably, it assumes you're going to just try to jam your data into the program and hope for the best. This might work well for data that you already know is going to be problem-free, but we seldom have that guarantee. Instead, this guide will split the recon-all processing into sub-stages where you can do quality-control inspection at each step.

1. Autorecon1
2. Autorecon2
3. Autorecon3

Functional Analysis

The previous steps have been concerned only with processing the T1 anatomical data. Though this might suffice for a purely structural brain analysis (e.g., voxel-based brain morphometry, which might explore how cortical thickness relates to some cognitive ability), most of our studies will employ functional MRI, which measures how the hemodynamic response changes as a function of task, condition or group. In the Freesurfer pipeline, this is done using a program called FS-FAST.

FS-FAST Setup Overview

Each of these steps are detailed more extensively elsewhere, but generally speaking you will need to follow these steps before starting your functional analysis:

1. Create a subjects file in your $SUBJECTS_DIR
2. Create (or copy if experiment used a fixed schedule) your paradigm files ("Par-Files") for each fMRI run
3. Configure your analyses
   1. mkanalysis-sess
   2. mkcontrast-sess

Trouble Shooting

Is Freesurfer in your path?

This is an unlikely issue, but it is possible that your ~/.bashrc file doesn't add Freesurfer to your path. To check, launch a new terminal window. You should see something like the following:

-------- freesurfer-Linux-centos6_x86_64-stable-pub-v5.3.0 --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME   /usr/local/freesurfer
FSFAST_HOME       /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /usr/local/freesurfer/subjects
MNI_DIR           /usr/local/freesurfer/mni

If you don't, then open up your .bashrc file with a text editor:

gedit ~/.bashrc

Then add the following lines to the bottom of the file:

#FREESURFER
export FREESURFER_HOME=/usr/local/freesurfer
source ${FREESURFER_HOME}/SetUpFreeSurfer.sh

#FSL
export FSLDIR=/usr/share/fsl/5.0
source ${FSLDIR}/etc/fslconf/fsl.sh

Save your changes, log out of Linux and log back in.

ERROR: Flag unrecognized.

Most Linux programs take parameters, or flags that modify or specify how they are run. For example, you can't just call the recon-all command; you have to tell the progam what data you want to work on, and so this information is provided using the -i flag. Other flags might tell the program how aggressive to be when deciding to remove potential skull voxels, for example. There are no hard-and-fast rules, but to find the set of flags that you can use for a particular Linux program, there are a few options you can try:

1. man program_name
2. program_name -help
3. program_name -?

Though often the program_name -some_flag option causes the usage information to be displayed if some_flag is not a valid flag.

When you see an error message concerning an unrecognized flag, it is most likely because there is a typo in your command. For example:

recon-all -autorecon1 watershed 15

Each of the flags is supposed to be prefixed with a '-' character, but in the example above, -watershed was instead typed as watershed without the '-' character. These little typos can be hard to spot.

If you are completely perplexed why something doesn't work out when you followed the directions to the letter, the first thing you should do is throw out your assumption that you typed in the command correctly.