top | previous | next

FreeSurfer Setup and Configuration

Basic setup

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 FreeSurfer.

Shell Types

The shell is the command-line interpreter that the terminal window uses. Usage of C shell (csh) or enhanced C shell (tcsh) is recommended, although Bourne shell (bash/sh) scripts are also provided for the setup scripts. The shell type on your system can be checked by typing ps at the command line in a terminal window. Macs usually run bash by default.

You can change the default shell the terminal window uses (more on this later). If you don't want to make tcsh your default shell, you can explicitly launch it every time you open a terminal window by typing the following command:

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

Sourcing the FreeSurfer Script

There are two options for sourcing the FreeSurfer script. You could do it every time you open a terminal window by typing a few commands. Or you can configure your settings so the FreeSurfer script is sourced automatically when a terminal window is open. These two options are described below.

If you want to manually source FreeSurfer every time you open a terminal

To setup the tools to run, from a tcsh or csh, type the following in your terminal window:

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

Where <freesurfer_installation_directory> is replaced with the path of whereever you installed the distribution.

If using bash or sh, type:

export FREESURFER_HOME=<freesurfer_installation_directory>/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

If you want FreeSurfer to be automatically sourced every time you open a terminal

Alternately, the configuration file for the shell can be set up to source the FreeSurfer script 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, the .tcshrc for enhanced C-shell, the .bashrc file for Bash, or .profile for sh. To this file, add the two lines from one of the boxes below.

For tcsh or csh, add:

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

For bash or sh, add:

export FREESURFER_HOME=<freesurfer_installation_directory>/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

**Where <freesurfer_installation_directory> is replaced with the path of whereever you installed the distribution.

How to know FreeSurfer is being sourced correctly

Open a new terminal window. Upon 'sourcing' the SetUpFreeSurfer.csh(sh) script, you should see output like this (assuming an installation path of /usr/local):

Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer
FSFAST_HOME     /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii
SUBJECTS_DIR    /usr/local/freesurfer/subjects
MNI_DIR         /usr/local/freesurfer/mni

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.

License

If you haven't done so already, obtain a license, and copy the license.txt file to the same location as your $FREESURFER_HOME.

Optional configuration settings

The defaults declared in the SetUpFreeSurfer.csh script should work for most installations. However, users should free to edit this file to customize certain environment variables:

1. Your declaration of the FREESURFER_HOME variable could be moved within the SetUpFreeSurfer.csh script.

2. The default SUBJECTS_DIR, which is $FREESURFER_HOME/subjects, is most likely the first variable that you will want to customize, as you may keep different groups of subjects in different directories. You may include the following either directly in the SetUpFreeSurfer.csh script, or prior to calling it:

• setenv SUBJECTS_DIR <full path to subject dir>

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

• setenv NO_FSFAST

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

• fsfasthome = getenv('FSFAST_HOME');
  fsfasttoolbox = sprintf('%s/toolbox',fsfasthome);
  path(path,fsfasttoolbox);
  

4. You may also wish to declare a path to an FSL installation you might have (required for TRACULA):

• setenv FSL_DIR /usr/local/fsl

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

Optional removal of third-party packages

Freesurfer includes in its distribution several third-party open-sourced packages which are required for Freesurfer to fully function. The distributed packages have not been modified from their source origins, so it is possible to delete the distributed package if an equivalent package is already installed on your system. Please be aware that the packages distributed with Freesurfer have been tested for compatibility with its tools.

The distributed packages, their version, and location are listed here:

*refers to MINC version **refers to Tcl/Tk version

To use a prior installed package, just move or delete the Freesurfer directory containing the package, and replace with a symbolic link to your own package. For instance, assuming an MNI toolkit is already installed in /usr/local/mni:

cd $FREESURFER_HOME
mv mni mni-backup
ln -s /usr/local/mni mni

The FreeSurferEnv.csh setup script will now point to those tools.

Testing FreeSurfer

Next: testing your FreeSurfer installation.