FSL

FSL is a comprehensive library of analysis tools for FMRI, MRI and diffusion brain imaging data. It runs on macOS (Intel and Apple Silicon), Linux, and Windows (via the Windows Subsystem for Linux), and is very easy to install. Most of the tools can be run both from the command line and as GUIs (“point-and-click” graphical user interfaces).

• For further information: https://fsl.fmrib.ox.ac.uk/fsl/docs/index.html

We have installed FSL following the recommended container installation guide. FSL is not installed as a module. We use Apptainer as the container toolset - please read our guide for more general information on how this works … this document is not intended to be a comprehensive guide to container tools.

The FSL container is stored in the /nobackup/shared/containers directory and is accessible to all users of Comet. You do not need to take a copy of the container file; it should be left in its original location.

You can find the container file here:

• /nobackup/shared/containers/fsl.6.0.7.19.sif

We have provided a convenience script that will automate all of the steps necessary for launching FSL inside the container, down to just two simple commands.

• /nobackup/shared/containers/fsl.6.0.7.19.sh

Just source this file and it will take care of loading apptainer, setting up your bind directories (thus allowing the container to read/write to your $HOME, the /scratch and /nobackup directories) and calling the exec command for you - and give you a single command called container.run (instead of a really long apptainer exec command) to then run anything you want inside the container, for example - to run our fslmaths.

To run fslmaths from inside the container, just run:

$ source /nobackup/shared/containers/fsl.6.0.7.19.sh
$ container.run fslmaths

You should see the normal fslmaths output:

$ source /nobackup/shared/containers/fsl.6.0.7.19.sh
$ container.run fslmaths

Usage: fslmaths [-dt <datatype>] <first_input> [operations and inputs] <output> [-odt <datatype>]

Datatype information:
 -dt sets the datatype used internally for calculations (default float for all except double images)
 -odt sets the output datatype ( default is float )
 Possible datatypes are: char short int float double input
 "input" will set the datatype to that of the original image

Binary operations:
  (some inputs can be either an image or a number)
 -add <number> | <image> : add following input to current image
 -sub <number> | <image> : subtract following input from current image
 -mul <number> | <image> : multiply current image by following input
 -div <number> | <image> : divide current image by following input
 -rem <number> | <image> : modulus remainder - divide current image by following input and take remainder
 -mas <image>            : use (following image>0) to mask current image
 -thr <number>           : threshold below the following number (zero anything below the number)
 -thrp <number>          : threshold below the following percentage (0-100) of ROBUST RANGE
 -thrP <number>          : threshold below the following percentage (0-100) of the positive voxels' ROBUST RANGE
 -uthr <number>          : upper-threshold above the following number (zero anything above the number)
 -uthrp <number>         : upper-threshold above the following percentage (0-100) of the ROBUST RANGE
 -uthrP <number>         : upper-threshold above the following percentage (0-100) of the positive voxels' ROBUST RANGE
 -max <number> | <image> : take maximum of following input and current image
 -min <number> | <image> : take minimum of following input and current image
 -seed  : seed random number generator with following number
 -restart : replace the current image with input for future processing operations
 -save : save the current working image to the input filename
...
...
$

You can continue to use the container.run command as many times as you need in the same script or same bash session:

$ source /nobackup/shared/containers/fsl.6.0.7.19.sh
$ container.run fslmaths
$ container.run imcp

We strongly recommend that you use this helper script and the container.run command to run software from inside the container as it will always ensure that you have correctly set up the bind directories and you are using the correct container version - it will automatically, if available, make an Nvidia GPU available to FSL (if you have allocated one in your Slurm resources).

Using this command you can embed calls to FSL in your Slurm sbatch jobs and existing compute pipelines.

If you run a Linux Desktop session using our Open OnDemand service you can also launch the various graphical FSL tools in a graphical compute environment on Comet.

• Start the VNC Desktop Session:

• Open the terminal window

• You can still run the command line FSL tools from within this environment, remember to source the fsl.6.0.7.19.sh file, and then use container.run to run fslmaths again:

• But we can also start the FSL GUI window by running container.run fsl:

• For more interactive work, tools such as fsleyes can also be started via container.run:

• Most GUI tools will run perfectly on a non-GPU desktop session, but for more complex or detailed visualisation, you may want to allocate a GPU. FSL will automatically use hardware acceleration for 3D rendering if available:

While running FSL tools you have two different filesystems to consider: inside the container and outside the container. As long as you use the container.run helper you will automatically get access to most of the directories you need while FSL is running and will usually not need to do anything special to access your input and output files.

If an FSL tool offers to import or export data via a file browser, you must remember that paths such as '/, /usr, /usr/local, /bin, or similar all refer to directories inside the container. The three directories:

• /scratch
• /nobackup
• $HOME (or /mnt/nfs/home)

… all refer to real directories outside the container on Comet.

If you use the graphical tools, and they offer to browse/open files or output directories on your behalf, remember that only those three locations actually refer to real Comet filesystem directories. Alternatively, if you are looking for FSL sample or reference data files, these are all installed inside the container (usually under /usr/local/fsl).

Build Script

#!/bin/bash

echo "Loading modules..."
module load apptainer

echo ""
echo "Building container..."
export APPTAINER_TMPDIR=/scratch

apptainer build fsl.sif fsl.def 2>&1 | tee fsl.log

Container Definition:

Bootstrap: docker
From: ubuntu:noble

####################################################################
#
# FSL container
# ==================
# This is a runtime environment for the FSL toolset.
# Please see: 
#	https://hpc.researchcomputing.ncl.ac.uk/dokuwiki/dokuwiki/doku.php?id=advanced:software:fsl
#
# Built according to:
#	https://fsl.fmrib.ox.ac.uk/fsl/docs/install/container.html
#
# Following additions made:
#	1. less, aptitude, vim, libxft2 OS packages added
#	2. FSL environment variables added to %environment to work around lack of bashrc in exec mode
#	3. source of fsl.sh added to /etc/bash.bashrc to work in run (shell) mode
#	
####################################################################

%post
    # Prevent interactive prompts
    export DEBIAN_FRONTEND=noninteractive
	export LANG=en_GB.UTF-8

####################################################################
#
# Basic system packages
#
####################################################################

    # Update & install only necessary packages
    apt-get update
	apt-get upgrade -y
	apt-get install -y \
		less 		\
		aptitude	\
		python3		\
		python3-pip \
		wget		\
		file		\
		dc			\
		mesa-utils	\
		pulseaudio	\
		libquadmath0	\
		libgtk2.0-0	\
		firefox		\
		libgomp1	\
		libxft2		\
		vim			

    # Clean up APT cache to save space
    apt-get clean 
	
	# Remove any Python cache files after pip
	pip3 cache purge

	# Run the FSL installer
	mkdir /src
	cd /src
	wget https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fslinstaller.py
	python3 ./fslinstaller.py \
		-d /usr/local/fsl/ \
		--extra truenet \
		--extra osl-dynamics
	
	# Add fsl.sh to bashrc
	echo "export FSLDIR=/usr/local/fsl" >> /etc/bash.bashrc
	echo "source /usr/local/fsl/etc/fslconf/fsl.sh" >> /etc/bash.bashrc
	
	# Add notification to sourcing of fsl.sh
	echo "echo 'FSL initialised'" >> /usr/local/fsl/etc/fslconf/fsl.sh	
	
	# Remove all src packages
	echo ""
	echo "Cleaning up downloaded src tree"
	echo "=================================="
	cd
	rm -rf /src
	pip3 cache purge
	
	echo ""
	echo "7. All done"

%environment
	# These should mimic "source /usr/local/fsl/etc/fslconf/fsl.sh" 
	export FSLDIR=/usr/local/fsl
	export PATH=$FSLDIR/bin:$FSLDIR/share/bin:$PATH
	export FSLTCLSH="${FSLDIR}/bin/fsltclsh"
	export FSLWISH="${FSLDIR}/bin/fslwish"
	export FSLOUTPUTTYPE=NIFTI_GZ
	export FSLMULTIFILEQUIT=TRUE
	export FSL_LOAD_NIFTI_EXTENSIONS=0
	export FSL_SKIP_GLOBAL=0

%runscript
	sh -c . /usr/local/fsl/etc/fslconf/fsl.sh && /bin/bash

Runtime Helper:

This includes the optional pass-through of Nvidia GPU device to the container. Note that this container refers to fsl.6.0.7.19.sif, but this is just an example. It would be updated to point to the most current version.

#!/bin/bash

module load apptainer

IMAGE_NAME=/nobackup/shared/containers/fsl.6.0.7.19.sif

container.run() {
    # Run a command inside the container...
    # automatically bind the /scratch and /nobackup dirs
    # pass through any additional parameters given on the command line
    apptainer exec --nv --bind /scratch:/scratch --bind /nobackup:/nobackup ${IMAGE_NAME} $@
}

Back to Software