FreeSurfer

From CCN Wiki
Jump to navigation Jump to search

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.

Getting started with raw data

The first step to running files through a program is to first get said files! To do this, you will need to access ownCloud. The website for semcat is tinyurl.com/blobs-catburgers; the website for LDT is tinyurl.com/lexitron5000. Chris will be able to give you the password (or it also might be written on the lab whiteboard).

Download the most recent files (ignore the study files) and unzip. These files will be named based on the system used by the MRI group, but you will need to rename the folder based on out system. You can find out who is who using the excel spreadsheets the lab links you to. The line number corresponds to our participant numbers, whereas the scanner ID is what will be shown in the ownCloud.

The important step here is checking to see if all the file components are there. You will need to make sure there is an MPRAGE file (the anatomical image) and a set of BOLD files, often numbered from 700-1200 (intervals of 100). You should expect these bold files to be in the ballpark of 50-60 MB. If there are more files than you expect, or if any of the BOLD files are smaller than you would expect, check with the individual who ran the participant that day, or see if there are any indicators on the Google spreadsheet. The MRI center always gives us all the files they reconstruct, even if the file is useless. One common occurrence is a glitch that requires us to abort and then restart the scan. In this case, there might be 7 sets of BOLD files, with one of them being very small. As long as there are 6 full runs, all is good in the hood.

If all goes well, simply extract, create folders, and move around files as instructed below.

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. Note that in the SUBJECTS_DIR=`pwd` line, those are back-quotes, which you might find on your keyboard sharing a key with the ~ character. ` is not the same character as '. When you enclose a command in a pair of back-quotes, you are telling the operating something along the lines of "this is a command that I want you to execute first, before using its output to figure out the rest of this business."


Subject directory organization

n.b.: Just kidding!

n.b.: orig.nii is the MRPAGE file (anatomical MPRAGE image)

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. The basic directory structure for each participant ('session' in Freesurfer terminology) looks like this (see also Freesurfer BOLD files):

  • SUBJECTS_DIR
    • Subject_001
      • mri
      • bold
        • 001
        • 002
        • 003
        • 004
        • 005
        • 006

To organize data from the raw data, extract the MPRAGE and put it into the mri. Discard any bold files that are under the ~50kb threshold; as long as there are 6 full bold files, the numbers don't matter (see "Getting started with raw data" above). Extract these as well. Sort them into the bold folders numerically (001 gets the lowest bold number, 006 gets the highest). Organizing these files correctly is critical at this stage. If there are redundant BOLD files (e.g., for aborted runs, or runs that were re-acquired) or missing BOLD files (e.g., because some technical glitch caused a failure to reconstruct the data from one run into a usable file), then we run the risk of mismatching the fMRI data to the experimental conditions!

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

By the end, your data should look like this:

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

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.

Keeping Track

For every subject you run, create a LOG_FS_xxxx.txt file. A template file can be found in ubfs in the LDT folder. After completing each step for processing (both structural and functional) mark an x next to the corresponding line. It can be really easy to forget to do this, but it will ensure that others accessing the folder on ubfs will know what's been done. This file should be a resource for you anyway since it contains a list of commands. More elaboration can be found on the wiki.

Since most of the folders on ubfs do not contain this file, it is hard to know what steps of functional analysis have been done. I am working on writing down what specific files/folders are created at each step to use as markers. I will fill this in as I process a new participant. For now, here is the template:

  • slicer (a window-based graphical program) or mri_convert (a command-line program)
    • MPRAGE.mgz
  • autorecon1
    • brainmask.mgz
  • autorecon2
  • autorecon3
  • parfiles
  • mkanalysis
  • mkconstrast
  • preproc
  • selxavg3

Make sure to update ubfs! It's a bummer to run a participant through all the steps and then realize the files were just sitting completed on someone's computer locally.

In order to help you through analysis, there is a file called commands in the LDT folder of ubfs. This has all the commands you need to go from raw data to time courses (no GLM though). This is a good skeleton for reference, but it will still be necessary to reference the wiki to recognize what's going on at each step and address any errors.

Image File Format

The first thing that you will need to do is convert the orig.nii file to .mgz format. This can be done using the graphic-based Slicer program, or in the terminal using mri_convert. 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 (there's no reason to expect a problem if using .nii files, but we have run into problems with archival data that had funny data header information).

Using mri_convert

Slicer seemed to be useful for automatically fixing goofy .NII header info, however, if there's nothing wrong with your file header you might find the mri_convert utility to be the fastest means of converting your files. 

INFILE_BASE=orig
INFILE_EXT=.nii.gz
mri_convert --in_type nii --out_type mgz -i ${INFILE_BASE}.${INFILE_EXT} -o ${INFILE_BASE}.mgz

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 describes a generally problem-free case. 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

After running autorecon1, it is best to run autorecon2 immediately afterward. Usually autorecon1 does an alright job skull stripping. If it doesn't, the results will be evident after autorecon2 is completed if you use the tksurfer SUBJECTID HEMI inflated. Fill in the SUBJECTID, and fill in HEMI with lh or rh (but check both). If the brain appears overly lumpy or there are odd points sticking out, proceede to Autorecon2 editing.

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 Functional Analysis

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. Copy BOLD data to the Freesurfer subject folder (see page for Freesurfer BOLD files)
  2. Create (or copy if experiment used a fixed schedule) your paradigm files for each fMRI run, and edit them using matlab (see "Par-Files").
    • When editing par files, be sure to check how many volumes to drop for each par file; it may be different every time! See above link for more details.
  3. Create a subjects text file in your $SUBJECTS_DIR called "subjectname" that contains a list of your subjects necessary for later (used for preproc-sess)
    • A quick way to do this, assuming you want to preprocess everyone, is to pipe the results of the ls command with the -1 switch (1 per line) into grep and then redirect the output to a file:
    • ls -1 | grep "^FS" > subjects
    • This will list the contents of the current directory, 1 per line, then keep only lines starting with FS
  4. Configure your analyses (using mkanalysis-sess)
  5. Configure your contrast (using mkcontrast-sess)
  6. Preprocess your data (smoothing, slice-time correction, intensity normalization and brain mask creation) (using preproc-sess)
  7. Check the *.mcdat files in each of the subject_name/bold/xxx directories to inspect the amount of motion detected during the motion correction step. Data associated with periods of excessive movement (>1mm) should be dealt with carefully. Columns in the text document from left to right are: (1) time point number (2) roll rotation (in ) (3) pitch rotation (in ) (4) yaw rotation (in ) (5) between-slice motion or translation (in mm) (6) within slice up-down motion or translation (in mm) (7) within slice left-right motion or translation (in mm) (8) RMS error before correction (9) RMS error after correction (10) total vector motion or translation (in mm). We need to look at column 10. If any of these values are above 1, this might be indicative of excessive movement. Consult with someone further up the chain for advice (undergrads ask a grad student; grad students ask Chris or a Postdoc if he ever has the funding to get one).
  8. Run the GLM for Single Subjects(selxavg3-sess)
    • Typically, we will do a group-level GLM. I have come to realize that it should generally suffice to do all processing in fsaverage surface space (mri_glmfit requires all operations to be done in a common surface space).
    • This will be relevant to the parameters you use in steps 4,6 and 8
  9. Run the group-level GLM (mri_glmfit)

Lab-specific documentation can be found on this wiki, but a more thorough (and accurate) description can be found on the Freesurfer Wiki

Trouble Shooting

Missing surfaces

Not sure how this came to pass, as I have never encountered this before, but probably was the result of one of the autorecon steps stopping early. I was running preproc-sess using the fsaverage surface (having already successfully run it on the self surface) and got an error message about being unable to find lh.sphere.reg. A quick google found a FreeSurfer mailing list archive email that was concerned with a different issue that had a similar solution. In Bruce the Almighty's words: 

> >> you can use mris_register with the -1 switch to indicate that the target 
> >> is a single surface not a statistical atlas. You will however still have to
> >> create the various surface representations and geometric measures we expect
> >> (e.g. ?h.inflated, ?h.sulc, etc....). If you can convert your 
> >> surfaces to our binary format (e.g. using mris_convert) to create
> >> an lh.orig, it would be something like:
> >>
> >> mris_smooth lh.orig lh.smoothwm
> >> mris_inflate lh.smoothwm lh.inflated
> >> mris_sphere lh.inflated lh.sphere
> >> mris_register -1 lh.sphere $TARGET_SUBJECT_DIR/lh.sphere ./lh.sphere.reg
> >>
> >> I've probably left something out, but that basic approach should work.
> >>
> >> cheers
> >> Bruce

The subject that had given me a problem already had ?h.inflated files, but no ?h.sphere files. I tried running some of the above steps but there were missing dependencies. Right now running: 

recon-all -s $SUBJECT -surfreg

This allegedly produces the surf.reg files as an output.

My script can't find my data

Some versions of the autorecon*.sh scripts have the SUBJECTS_DIR hard-coded. Or sometimes you will close your terminal window (e.g., at the end of the day), and then launch a new terminal window when you come back to the workstation (or resume working at a different computer). There's a good chance that your Freesurfer malfunction is the result of your SUBJECTS_DIR environment variable being set to the incorrect value. Troubleshooting step #1 should be the following: 

echo $SUBJECTS_DIR

If the wrong directory name is printed to the screen, setting it to the correct value may well fix your problem.

At this point you might expect me to tell you how to set SUBJECTS_DIR to the correct value. But I'm not going to do that, and here's why:

  1. It's documented elsewhere on the wiki
  2. If you're confused about how to set SUBJECTS_DIR, you're also likely to just blindly type whatever example command I give without understanding what the command does. If this is the case, please become more proficient with the lab's procedures and software.

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.

Retrieved from "https://ccn-wiki.caset.buffalo.edu/index.php?title=FreeSurfer&oldid=1412"