- 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?
- Why does an FSL program crash when it is trying to process a very large dataset?
Where can I find help, tutorials or papers about FSL?
Documentation for all FSL tools can be found via the FSL wiki: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/
A tutorial-based set of lecture slides and practicals can be found at https://fsl.fmrib.ox.ac.uk/fslcourse/ and is related to the content of the FSL course which is held once or twice each year - see the course website 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 https://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 https://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 version of FSL are you using? You can find this out by running cat $FSLDIR/etc/fslversion in a terminal.
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 software on? Please make sure that the data is not corrupted: check your input data by loading it into fsleyes. 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. If it is possible to do so, share your data online (for example with Dropbox or Google Drive), so we can try and reproduce the problem ourselves.
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.
What image format does FSL need?
FSL programs primarily expect to read NIFTI-1/NIfTI-2 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). We recommend using dcm2niix for DICOM to NIfTI conversion.
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
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*)
4D -> 3D
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 FSLeyes. For more information about orientation, the NIfTI format and FSLeyes 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
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 physical 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.