====== 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

----
===== FSL on Comet =====

We have installed FSL following the recommended container [[https://fsl.fmrib.ox.ac.uk/fsl/docs/install/container.html|installation guide]]. FSL is **not** installed as a module. We use [[advanced:apptainer|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''

<WRAP round box info>
**Container Image Versions**

We //may// reference a specific container file, such as **fsl.6.0.7.19.sif**, but you should always check whether this is the most recent version of the container available. Simply ''ls'' the ''/nobackup/shared/containers'' directory and you will be able to see if there are any newer versions listed.
</WRAP>

----
===== Running FSL Commands (command line / batch) =====

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''

<WRAP round box info half>
There is a corresponding ''.sh'' script for //each version// of the container image we make available.
</WRAP>

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:

<code lang=bash>
$ source /nobackup/shared/containers/fsl.6.0.7.19.sh
$ container.run fslmaths
</code>

You should see the normal ''fslmaths'' output:

<code lang=bash>
$ 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
...
...
$
</code>

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

<code lang=bash>
$ source /nobackup/shared/containers/fsl.6.0.7.19.sh
$ container.run fslmaths
$ container.run imcp
</code>

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.

----
===== Running FSL Commands (GUI / X11) =====

If you run a [[advanced:software:x11|Linux Desktop session]] using our [[advanced:interactive|Open OnDemand]] service you can //also// launch the various graphical FSL tools in a graphical compute environment on Comet.

   * Start the VNC Desktop Session:

{{:advanced:software:fsl_01_desktop.jpg?800|}} 

   * Open the terminal window

{{:advanced:software:fsl_02_terminal.png?800|}} 

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

{{:advanced:software:fsl_03_container.run.jpg?800|}}

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

{{:advanced:software:fsl_04_run.fsl.jpg?800|}} 

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

{{:advanced:software:fsl_05_run.fsleyes.jpg?800|}} 

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

{{:advanced:software:fsl_06_run.fsleyes3d.jpg?800|}}

<WRAP round box tip>
You **do not** need to allocate a GPU to the VNC Desktop Session - you //only// need this if you intend to use any of the CUDA accelerated processing tools from FSL at the //same// time in that desktop session. A GPU is not needed for the simple tools / viewers, but more //complex// FSL options (e.g. 3D object manipulation) may benefit greatly from accelerated GPU rendering.
</WRAP>

----

===== Accessing Data =====

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'').

----
===== Building on Comet =====

<WRAP round box important>
**Important!**

This section is only for RSE HPC staff, or those users who are interested in how FSL has been built. If you only need to //run// FSL, you **do not** need to read this section!
</WRAP>

**Build Script**

<code lang=bash title=fsl.build.sh>
#!/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
</code>

**Container Definition:**

<code lang=bash title=fsl.def>
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


</code>

**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.

<code lang=bash title=fsl.sh>
#!/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} $@
}
</code>
----

[[:advanced:software|Back to Software]]