[wiki:FreeSurferWiki top] | [wiki:Installation previous]

FreeSurfer Setup and Configuration

1.0 Basic setup

Usage of C shell (csh) or enhanced C shell (tcsh) is recommended. The shell type on your system can be checked by typing ps at the command line in an X terminal window. If csh or tcsh does not appear as one of the processes in the right hand column of output, the default shell must be changed to csh or tcsh. Otherwise, explicitly launch csh or tcsh before attempting to go further. To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command in a terminal window:

tcsh 

The prompt may change, and some login files may not be run in the new shell environment. See the man pages for tcsh for details.

If you do not have a preference for a particular shell, the default shell can be permanently switched to tcsh by typing the following:

chsh -s /bin/tcsh

The file <freesurfer_installation_directory>/SetUpFreeSurfer.csh is a csh (C-shell) script that will configure the environment so that FreeSurfer can be used. It sets a few environment variables, sources other csh scripts to set up support libraries, and performs some checks that need to be passed before FreeSurfer can start. This file needs to be 'sourced' before running any FreeSurfer binaries.

This can be done manually via typing the following command in a terminal window:

source <freesurfer_installation_directory>SetUpFreeSurfer.csh

Alternately, the resource file for the shell can be configured to source the file automatically each time the shell is started. In the home directory of the user who will be running FreeSurfer binaries, edit the file .cshrc if C-shell will be used, or .tcshrc for enhanced C-shell, to include the line:

setenv FREESURFER_HOME <freesurfer_installation_directory>
source $FREESURFER_HOME/SetUpFreeSurfer.csh

where <freesurfer_installation_directory> is replaced with the name of the directory where FreeSurfer was installed, typically the directory /usr/local/freesurfer.

Make sure to use C shell (csh) or enhanced C shell (tcsh), per the prior instructions. This can be checked by typing ps at the command line in an X terminal window. If csh or tcsh does not appear as one of the processes in the right hand column of output, the default shell must be changed to csh or tcsh. Otherwise, explicitly launch csh or tcsh before attempting to go further. To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command in an X terminal window:

tcsh 

The prompt may change, and some login files may not be run in the new shell environment. See the man pages for tcsh for details.

As the shell starts up, messages are printed out showing the environment variables that have been set by the configuration scripts. The following example shows a case where the SUBJECTS_DIR has been set to something other than the default:

Setting up environment for FreeSurfer/FS-FAST
FREESURFER_HOME /Users/Shared/freesurfer
FSFAST_HOME     /Users/Shared/freesurfer/fsfast
SUBJECTS_DIR    /Users/Shared/freesurfer/subjects
FUNCTIONALS_DIR /Users/Shared/freesurfer/sessions
MINC_BIN_DIR    /Users/Shared/freesurfer/lib/mni/bin
MINC_LIB_DIR    /Users/Shared/freesurfer/lib/mni/lib
QTDIR           /Users/Shared/freesurfer/lib/qt
LIBS_DIR        /Users/Shared/freesurfer/lib/misc

If any warnings appear, it's usually safe to ignore them, but make sure that they are not stating that a file or directory that should exist cannot be found.

If any error messages appear, check that the installation process was successfully completed.

4.0 Practice data

A public distribution data set is available to run the tutorials. It contains 40 subjects, and occupies about 21G of disk-space. The file is available from the [ftp://surfer.nmr.mgh.harvard.edu/pub/dist distribution site], and is called [ftp://surfer.nmr.mgh.harvard.edu/pub/dist/buckner_public_distribution.tar.gz buckner_public_distribution.tar.gz].

Once the file is downloaded, move the file to the $FREESURFER_HOME/subjects directory, and uncompress and install with the following command:

tar zxvf buckner_public_distribution.tar.gz

The downloaded file can then be deleted.

To setup the environment variables SUBJECTS_DIR and SUBJECTS to point to this data, type the following command or include in your .cshrc or .tcshrc file:

source $FREESURFER_HOME/subjects/buckner_public_distribution/sample_group_study/scripts/subjects.csh

To configure FreeSurfer

1. Copy the license file into freesurfer/ and rename it to ".license" (no quotes) if necessary.

2. The file freesurfer/FreeSurferEnv.csh is a csh (c-shell) script that will configure your environment so that you can use FreeSurfer. It sets a few envrionment variables and performs some sanity checks. If you are comfortable writing shell scripts, you may wish to set up your system differently, but we recommend the following:

Create a file in your home directory called something like "SetUpFreeSurfer.csh" with the following contents:

BR

BR

The full path to your freesurfer directory should be something like:

2. If you wish to designate a non-default subjects directory, add the following line in the 'additional configurations' section, before 'cd $FREESURFER_HOME' is called:

3. If you installed the MINC tools, then add the following lines to the additional configuration section:

If you did not install the MINC tools, then add the following line in the local setup section:

4. If you do NOT intend to use the functional tools, then add the following line to the additional configuration section:

If you do intend to use the functional tools, then add these lines to your ~/matlab/startup.m file:

5. Save the file. You will need to source this file every time you want to use Freesurfer.

6. Make sure you are using csh or tcsh. You can check by typing 'ps' at the command line. If you do not see csh or tcsh as one of the processes in the right hand column of output, you must change your default shell to csh or tcsh or explicitly launch csh or tcsh first.

To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command:

You may notice your prompt change. Note that some of your login files may not be run in the new shell environment. See the man pages for tcsh for details.

7. Source the script.

You should see output like this:

If you see any warnings, you can probably safely ignore them, but make sure they are not notifying you that it can't find something you think should exist.

If you see any error messages, make sure you have performed the installation process properly, and that your FREESURFER_HOME setting is correct.

From now on, you only need to source the SetUpFreeSurfer.csh script once in a shell session to be able to run FreeSurfer. You may want to do this in our shell's login scripts (i.e. .cshrc or .tcshrc).