|
Size: 8520
Comment:
|
← Revision 35 as of 2015-08-24 15:23:06 ⇥
Size: 6937
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| [wiki:Self:FreeSurferWiki top] | [wiki:Self:Installation previous] | ## page was renamed from SetupConfiguration [[DownloadAndInstall|top]] | [[Installation|previous]] | [[TestingFreeSurfer|next]] |
| Line 5: | Line 6: |
| === 3.0 Setting up environment === | == 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. |
| Line 7: | Line 9: |
| The read-me screen of the installer provides directions on setting up the environment to allow running FreeSurfer, and this is reviewed next. | === 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. |
| Line 9: | Line 12: |
| ## attachment:install-6readme.jpg 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 an X terminal window: |
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: |
| Line 13: | Line 14: |
| tcsh | tcsh |
| Line 17: | Line 18: |
| If you do not have a preference for a particular shell, the default shell under Mac OS X can be permanently switched from bash to tcsh by typing the following: | If you do not have a preference for a particular shell, the default shell can be permanently switched to tcsh by typing the following: |
| Line 22: | Line 23: |
| The file freesurfer/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. | |
| Line 24: | Line 24: |
| This can be done manually via typing the following command in an X terminal window: | === 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: |
| Line 26: | Line 30: |
| source /Users/Shared/freesurfer/SetUpFreeSurfer.csh | setenv FREESURFER_HOME <freesurfer_installation_directory>/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.csh |
| Line 28: | Line 33: |
| 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: | Where <freesurfer_installation_directory> is replaced with the path of whereever you installed the distribution. If using bash or sh, type: |
| Line 30: | Line 37: |
| source /Users/Shared/freesurfer/SetUpFreeSurfer.csh | export FREESURFER_HOME=<freesurfer_installation_directory>/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.sh |
| Line 33: | Line 41: |
| A sample subject directory is provided with the full installation, in /Users/Shared/freesurfer/subjects. If custom subject directories are created using mksubjectdirs or a different sample data set is used, let FreeSurfer know where to look by inserting the following line before the source command above: | ==== 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: |
| Line 35: | Line 46: |
| setenv SUBJECTS_DIR [path to subject directory] | setenv FREESURFER_HOME <freesurfer_installation_directory>/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.csh |
| Line 38: | Line 50: |
| Make sure to use C shell (csh) or enhanced C shell (tcsh). 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: | For bash or sh, add: |
| Line 40: | Line 53: |
| tcsh | export FREESURFER_HOME=<freesurfer_installation_directory>/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.sh |
| Line 42: | Line 56: |
| 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. | |
| Line 44: | Line 57: |
| 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: | **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): |
| Line 46: | Line 62: |
| 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 |
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 |
| Line 61: | Line 74: |
| === 4.0 Practice data === | == License == |
| Line 63: | Line 76: |
| 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]. | If you haven't done so already, [[Registration|obtain a license]], and copy the license.txt file to the same location as your $FREESURFER_HOME. |
| Line 65: | Line 78: |
| Once the file is downloaded, move the file to the $FREESURFER_HOME/subjects directory, and uncompress and install with the following command: | == Optional configuration settings == |
| Line 67: | Line 80: |
| {{{ tar zxvf buckner_public_distribution.tar.gz }}} |
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: |
| Line 71: | Line 82: |
| The downloaded file can then be deleted. | 1. Your declaration of the FREESURFER_HOME variable could be moved within the !SetUpFreeSurfer.csh script. |
| Line 73: | Line 84: |
| 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: `# Local setup.` [[BR]] `setenv FREESURFER_HOME <full path to freesurfer/>`[[BR]] [[BR]] `# Additional configurations will go here.`[[BR]] [[BR]] `# Call configuration script.`[[BR]] `cd $FREESURFER_HOME`[[BR]] `source Free``Surfer``Env.csh`[[BR]] The full path to your freesurfer directory should be something like: `/home/username/freesurfer` 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: |
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: |
| Line 106: | Line 88: |
| 3. If you installed the MINC tools, then add the following lines to the additional configuration section: `setenv MINC_BIN_DIR /usr/pubsw/packages/mni/current/bin`[[BR]] `setenv MINC_LIB_DIR /usr/pubsw/packages/mni/current/lib` If you did not install the MINC tools, then add the following line in the local setup section: `setenv NO_MINC` 4. If you do NOT intend to use the functional tools, then add the following line to the additional configuration section: |
3. If you do NOT intend to use the functional tools, then add the following line to the additional configuration section: |
| Line 121: | Line 94: |
| `fsfasthome = getenv('FSFAST_HOME');` [[BR]] `fsfasttoolbox = sprintf('%s/toolbox',fsfasthome);` [[BR]] `path(path,fsfasttoolbox);` [[BR]] |
`fsfasthome = getenv('FSFAST_HOME');` <<BR>> `fsfasttoolbox = sprintf('%s/toolbox',fsfasthome);` <<BR>> `path(path,fsfasttoolbox);` <<BR>> |
| Line 125: | Line 98: |
| 5. Save the file. You will need to source this file every time you want to use Freesurfer. | 4. You may also wish to declare a path to an FSL installation you might have (required for TRACULA): |
| Line 127: | Line 100: |
| 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. | `setenv FSL_DIR /usr/local/fsl` |
| Line 129: | Line 102: |
| To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command: | 5. Save the file. You will need to source this file (!SetUpFreeSurfer.csh) every time you want to use Freesurfer. |
| Line 131: | Line 104: |
| `tcsh` | == Optional removal of third-party packages == |
| Line 133: | Line 106: |
| 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. | 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. |
| Line 135: | Line 108: |
| 7. Source the script. | The distributed packages, their version, and location are listed here: |
| Line 137: | Line 110: |
| `source Set``Up``Free``Surfer.csh` | || '''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 |
| Line 139: | Line 116: |
| You should see output like this: | 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 }}} |
| Line 141: | Line 123: |
| `Setting up enviroment for Free``Surfer/FS-FAST`[[BR]] `FREESURFER_HOME /home/freesurfer`[[BR]] `FSFAST_HOME /home/freesurfer/fsfast`[[BR]] `AFNI_DIR /home/freesurfer/afni`[[BR]] `FSL_DIR /home/freesurfer/fsl`[[BR]] `SUBJECTS_DIR /home/freesurfer/subjects`[[BR]] |
The !FreeSurferEnv.csh setup script will now point to those tools. |
| Line 148: | Line 125: |
| 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. | == Testing FreeSurfer == |
| Line 150: | Line 127: |
| 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 Set``Up``Free``Surfer.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). |
'''Next:''' [[TestingFreeSurfer|testing your FreeSurfer installation]]. |
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:
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.csh setup script will now point to those tools.