Differences between revisions 1 and 2

FreeSurfer Setup and Configuration

Basic setup

To start using FreeSurfer, open a Terminal window by going to Finder then clicking Application -> Utilities -> Terminal. In order to load FreeSurfer you will need to type the following commands into the terminal window:

export FREESURFER_HOME=/Applications/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

You have the option of either typing those commands everytime you open a new terminal window OR adding those two lines somewhere in the .profile file in your home directory. If you choose the latter method, FreeSurfer will load everytime you open a new terminal window and you won't have to type the two commands above. Regardless of the method you choose, once FreeSurfer is loaded, the terminal window should display some basic information and appear similar to the snapshot below.

The file Application/freesurfer/SetUpFreeSurfer.sh is a bash script that will configure the environment so that FreeSurfer can be used. It sets a few environment variables, sources other shell 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.

License

If you haven't done so already, obtain a license, and copy the .license file to your $FREESURFER_HOME directory (e.g. /Applications/freesurfer). This can be done using TextEdit (Applications -> TextEdit). Unfortunately the default behavior of TextEdit is to append .rtf at the end of the filename so you will end up with a file called .license.rtf. This will render the .licese file useless. To fix this behavior, go to TextEdit -> Preferences and under Format select Plain text.

Ultimately, the goal is simply to get a file called .license with the contents of the email, into your home directory. This can be done with TextEdit, gedit, vim, emacs, or countless other simple text editors.

Optional configuration settings

The defaults declared in the SetUpFreeSurfer.sh 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.sh 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.sh script, or prior to calling it:

export 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:

export=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):

export FSL_DIR=/usr/local/fsl

5. Save the file. You will need to source this file (SetUpFreeSurfer.sh) 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:

Package	Version	$FREESURFER_HOME Location
MNI	1.4*	/mni
Tcl/Tk/Tix/BLT	8.4.6**	/lib/tcltktixblt

*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.sh setup script will now point to those tools.

Testing FreeSurfer

Next: testing your FreeSurfer installation.

-Deletions are marked like this.
+Additions are marked like this.
 Line 7:
-Open a Terminal window by going to '''Finder''' then clicking '''Application -> Utilities -> Terminal'''



In order to load !FreeSurfer you will need to type the following commands into the terminal window:
+To start using !FreeSurfer, open a Terminal window by going to '''Finder''' then clicking '''Application -> Utilities -> Terminal'''. In order to load !FreeSurfer you will need to type the following commands into the terminal window:
-Line 16:
+Line 14:
-You have the option of either typing those commands everytime you open a new terminal window OR adding those two lines somewhere in the '''.profile''' file in your home directory. Regardless of the method you choose, once !FreeSurfer is loaded, the terminal window should display some basic information ad appear similar to the snapshort below.
+You have the option of either typing those commands everytime you open a new terminal window OR adding those two lines somewhere in the '''.profile''' file in your home directory. If you choose the latter method, !FreeSurfer will load everytime you open a new terminal window and you won't have to type the two commands above. Regardless of the method you choose, once !FreeSurfer is loaded, the terminal window should display some basic information and appear similar to the snapshot below.
-Line 19:
+Line 17:
+{{attachment:terminal.png}}
-Line 20:
+Line 19:
-Usage of C shell (csh) or enhanced C shell (tcsh) is recommended, although 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. 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.



To setup the tools to run, from a tcsh or csh, type:

{{{

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

}}}



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, the '''.tcshrc''' for enhanced C-shell, the '''.bashrc''' file for Bash, and '''.profile''' for sh, to include the previous two lines (which setenv FREESURFER_HOME, and then source the !SetUpFreeSurfer.csh(or sh) script).



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.
+The file {{{Application/freesurfer/SetUpFreeSurfer.sh}}} is a bash script that will configure the environment so that !FreeSurfer can be used. It sets a few environment variables, sources other shell 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.
-Line 66:
+Line 23:
-If you haven't done so already, [[Registration|obtain a license]], and copy the .license file to your $FREESURFER_HOME.
+If you haven't done so already, [[Registration|obtain a license]], and copy the .license file to your $FREESURFER_HOME directory (e.g. /Applications/freesurfer). This can be done using !TextEdit ('''Applications -> !TextEdit'''). Unfortunately the default behavior of !TextEdit is to append ''.rtf'' at the end of the filename so you will end up with a file called '''.license.rtf'''. This will render the .licese file useless. To fix this behavior, go to '''!TextEdit -> Preferences''' and under '''Format''' select '''Plain text'''. 



{{attachment:plain-text.png}}



Ultimately, the goal is simply to get a file called '''.license''' with the contents of the email, into your home directory. This can be done with !TextEdit, [[https://wiki.gnome.org/Apps/Gedit|gedit]], vim, emacs, or countless other simple text editors.
-Line 70:
+Line 31:
-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:
+The defaults declared in the !SetUpFreeSurfer.sh script should work for most installations.  However, users should free to edit this file to customize certain environment variables:
-Line 72:
+Line 33:
-. Your declaration of the FREESURFER_HOME variable could be moved within the !SetUpFreeSurfer.csh script.
+. Your declaration of the FREESURFER_HOME variable could be moved within the !SetUpFreeSurfer.sh script.
-Line 74:
+Line 35:
-. 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:
+. 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.sh script, or prior to calling it:
-Line 76:
+Line 37:
-     `setenv SUBJECTS_DIR <full path to subject dir>`
+     `export SUBJECTS_DIR=<full path to subject dir>`
-Line 80:
+Line 41:
-     `setenv NO_FSFAST`
+     `export=NO_FSFAST`
-Line 90:
+Line 51:
-     `setenv FSL_DIR /usr/local/fsl`
+     `export FSL_DIR=/usr/local/fsl`
-Line 92:
+Line 53:
-. Save the file. You will need to source this file (!SetUpFreeSurfer.csh) every time you want to use Freesurfer.
+. Save the file. You will need to source this file (!SetUpFreeSurfer.sh) every time you want to use !Freesurfer.
-Line 113:
+Line 74:
-The !FreeSurferEnv.csh setup script will now point to those tools.
+The !FreeSurferEnv.sh setup script will now point to those tools.