Contents
-
General
- Where can I find help, tutorials or papers about FSL?
- How do I best report problems to the FSL email list?
- What image format does FSL need?
- How do I convert between 3D and 4D NIFTI images?
- How can I modify the orientation of my data?
- How do I know right from left in the images?
- How do I run the GUIs or command lines?
- How do I get my command line to run?
- How can I make old scripts work with FSL>=3.2?
- Installation
General
Where can I find help, tutorials or papers about FSL?
Every installation of FSL comes with html documentation in $FSLDIR/doc In addition, there are general FSL web pages, including some documentation and related references, at http://www.fmrib.ox.ac.uk/fsl
A tutorial-based set of lecture slides and practicals can be found at http://www.fmrib.ox.ac.uk/fslcourse and is related to the content of the FSL/Freesurfer course which is held once or twice each year - see http://www.fmrib.ox.ac.uk/fslcourse/announce.html for details on upcoming/recent courses.
Further help can also be obtained via the public FSL email list. Note that you must join the list in order to post questions.
Finally, detailed technical reports can be found at http://www.fmrib.ox.ac.uk/analysis/techrep/ and a full list of conference and journal papers produced by the FMRIB Analysis Group can be found at http://www.fmrib.ox.ac.uk/analysis/fmribindex/.
How do I best report problems to the FSL email list?
In order to understand and analyse problems please provide the following pieces of information:
- What part of FSL did not work as expected?
In the case of FEAT / MELODIC problems, please check the log (report.log/melodic.log) files first, e.g. you might be out of space or certain files might actually not be readable.
- What type of input data were you running the sofware on?
Please make sure that the data is not corrupted: check your input data by loading it into fslview (or slices). If your input data is not what you expect, try and fix this first. You can also obtain useful header information with fslhd filename and useful information about the image intensity range from fslstats -r -R. If you need to report a problem, please provide this information in an email.
- Does the software run on the FEEDS example data?
If you cannot resolve the problem then please run the command: fslerrorreport in the directory that the problem occurred. The output from this gives information on log files, the platform are you running FSL on: CPU type, OS type & version, how much RAM, Swap space etc. is available, etc.
Please attach the entire output of this command to your email. Note that the output is written to a file in /tmp (filename is given at the end of the output message) for convenience in attaching it to an email. Also, please be as specific as possible about command line error messages.
NOTE: Please do not send Analyze/NIFTI files (AVW/NII) to the email list; If these are needed to resolve the problem, place them somewhere to download!
What image format does FSL need?
FSL programs expect to read NIFTI-1 format images. These files can be read and written in compressed (gzip format) or uncompressed form. To convert between these different formats, use the fslchfiletype utility or the environment variable FSLOUTPUTTYPE. These are described more fully in the nifti1 page.
An image can be 2D or 3D or 4D (multiple time points).
FSL programs for FMRI analysis use single 4D NIFTI images, not lots of 3D images (such as SPM does).
You will need some other program to convert between formats (e.g. DICOM). A list of such converters can be found at: http://www.sph.sc.edu/comd/rorden/mricron/dcm2nii.html
How do I convert between 3D and 4D NIFTI images?
In order to convert between multiple 3D and single 4D images, use the following programs (found in $FSLDIR/bin):
3D -> 4D
fslmerge -t outputname in1 in2 ....... inN
note that if your 3D files have numbers that are zero padded (eg in0001 etc.) then you can do this more easily. For example, with Analyze files:
fslmerge -t outputname in*.hdr will work.
In general, due to the multiple file formats, we recommend using the utility imglob for getting filenames. For example:
fslmerge -t outputname `imglob -oneperimage in*`
(NB: the above command contains backquotes, not forward quotes)
4D -> 3D
fslsplit input
this program automatically chooses the output name.
How can I modify the orientation of my data?
Please look at the "Orientation-related Utilities" section of the FSLUTILS documentation page.
How do I know right from left in the images?
Look at the labels in FSLView. For more information about orientation, the NIfTI format and FSLView display, see the "Orientation-related Utilities" and "Background information on NIfTI Orientation" sections of the FSLUTILS documentation page.
How do I run the GUIs or command lines?
On most machines the GUIs can be run by:
Typing fsl at the (terminal/shell) prompt, which brings up a graphical menu of the main FSL GUIs
Typing the name of the required program, with the first letter capitalised: e.g. Flirt
However, under MacOSX the GUIs are run by:
- Typing fsl_gui at the (terminal/shell) prompt, which brings up a graphical menu of the main FSL GUIs
Typing the name of the required program, with the first letter capitalised followed by _gui: e.g. Flirt_gui
On all machines, the command line versions can be run by typing the name of the program, all in lower case: e.g. flirt Note: with no arguments the command line versions return a help statement that includes usage lines and available options.
How do I get my command line to run?
Many things might be the cause of this, but the following list covers the vast majority of problems:
- Check that you have setup FSL correctly
- Check that you are setting all the compulsory arguments
- Check that you can find the files that you are specifying and/or that you are in the right directory
If using a double minus option that takes an argument, make sure you use an equals sign and no spaces (e.g. --start=2 ). This often causes the error Missing non-optional argument! when a space is used incorrectly.
- Check for typos and be particularly careful about confusing the number 1 and the lowercase letter L
How can I make old scripts work with FSL>=3.2?
Due to the use of new file formats, with different extensions, most scripts need some modification to work fully with FSL>=3.2. However, the changes are relatively straightforward and are described in a separate scripting page.
Installation
How do I install (or compile) FSL?
Instructions on downloading and installing FSL can be found at: http://www.fmrib.ox.ac.uk/fsl/fsl/downloading.html Instructions on compiling FSL can be found at: http://www.fmrib.ox.ac.uk/fsl/fsl/compiling.html
Note the special instructions for installing on MacOSX and Windows.
Note that you must set up the environment variable FSLDIR to point to the directory where FSL is installed on your machine. It is also necessary to source a setup file. This can be done by:
bash users: . $FSLDIR/etc/fslconf/fsl.sh
tcsh users: source $FSLDIR/etc/fslconf/fsl.csh
Also, you would normally want to include $FSLDIR/bin in your PATH. In general these are best done in your shell startup file (e.g. .bashrc or .profile). The syntax required depends on the shell you use, but is normally either one of the following (where /usr/local/fsl is used as an example for the installation location):
bash users: export FSLDIR=/usr/local/fsl; . $FSLDIR/etc/fslconf/fsl.sh ; export PATH=$PATH:$FSLDIR/bin;
tcsh users: setenv FSLDIR /usr/local/fsl; source $FSLDIR/etc/fslconf/fsl.csh ; setenv PATH ${PATH}:$FSLDIR/bin; rehash;
What sort of system requirements does FSL have?
FSL is supported on the following hardware: Linux, Mac, Windows running a Linux Virtual Machine. FSL is supported for the following operating systems: Linux (Cent OS 4 and 5, Debian/Ubuntu), MacOS X 10.5 and 10.6, Windows XP (with VMplayer)
Note: that FSL also works with other flavours of Linux such as SuSE - although they may need to be built from source rather than using the precompiled Cent OS binaries.
It is recommended that the following memory and disk requirements are met:
- RAM - 1GB or more (at least 2GB if running a virtual machine on Windows)
- Swap space - at least equal to RAM (2GB min recommended; check with top)
- Disk space - at least 10 times the size of your data sets
Be warned that too little swap space causes "unexplained" crashes!
How can I test if my installation works?
Download and run the FSL Evaluation and Example Data Suite (FEEDS). See also: How do I get and run FEEDS?
How do I get and run FEEDS?
Information on how to run the FSL Evaluation and Example Data Suite (useful for testing that your installation is working and to get a benchmark for speed) can be found at: http://www.fmrib.ox.ac.uk/fsl/feeds/doc/index.html
This site includes a link to the download URL at: http://www.fmrib.ox.ac.uk/fsldownloads
A timing table using FEEDS as a benchmark for comparing relative performance between machines can be found at: http://www.fmrib.ox.ac.uk/fsl/feeds/doc/timings.html
Why does an FSL program crash when it is trying to process a very large dataset?
Certain programs in FSL can require a large amount of memory (RAM) to run, depending on the size of the data that you are trying to analyse. For example:
- FMRI timeseries analysis with FILM (called by FEAT), if you have a large number of timepoints and/or regressors
- FMRI timeseries analysis with MELODIC, if you have a large number of timepoints
- FMRI multi-subject analysis with MELODIC, if you have a large image matrix or large number of timepoints or subjects
- DTI FA analysis with TBSS (at the stage of running tbss_skeleton or randomise) if you have a large number of subjects
The memory available to a program depends on how much physical RAM you have on your computer, what other programs are already running, and how much "virtual memory" (swap) you have configured. Swap is hard disk space that is used to act as additional memory on top of your actual memory, allowing programs larger than your physical memory to run, but much more slowly. Hence, if your program is running out of memory you should consider increasing your physcial RAM and/or your swap space (the latter is cheaper but a slower solution). Your local sysadmin can easily increase swap space if you have spare hard disk space available.
However, there is one further caveat. On 32-bit computers there is a limit on the size that a single program can be, regardless of how much RAM/swap you have. This limit is normally 2GB. The best solution to this is to move to a 64-bit computer (for example, all Apple computers are now 64-bit, and it is easy to find cheap 64-bit PCs to install 64-bit Linux on). On a 64-bit computer, as long as you have enough RAM/swap, there is effectively no limit to the size of the programs that you can run.