Freesurfer for Singularity

Singularity for Freesurfer

One of the first uses for Singularity on Flux was to provide the capability to continue to use older versions of the neuroimaging packages FSL and FreeSurfer on Flux.

Creating the container

NOTE: These notes are now outdated. The commands to build Singularity containers differ significantly now. We recommend that you install Singularity 3.4 or later to create your Singularity images. Please see the Singularity web site for details.

The container was created using a virtual machine installed with the version of the operating system needed to run the older software version by running Singularity’s bootstrap process. The FSL and FreeSurfer software was then copied into the container and set up as it would be set up on a computer running the older operating system. The container was created to run an external bash to provide maximum flexibility.

We did need to add, after the fact, the /scratch directory to enable mapping between the container and the data files that are in Flux’s /scratch filesystem.

On Flux, the setup for FSL and FreeSurfer was done using Modules, as it still is for the current versions. For the container, though, we need to set those paths and source the setup scripts manually. Except for that change, no additional changes were needed to make this work.

Files used

For those who might be interested, the bootstrap configuration file used to create the container contained this.

# Bootstrap definition Centos-6

BootStrap: yum
OSVersion: 6
MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/$basearch/
Include: yum

%setup
    echo "Looking in directory '$SINGULARITY_ROOTFS' for /bin/sh"
    if [ ! -x "$SINGULARITY_ROOTFS/bin/sh" ]; then
        echo "Hrmm, this container does not have /bin/sh installed..."
        exit 1
    fi
    exit 0

%post
    echo "Installing Development Tools YUM group"
    yum -y groupinstall "Development Tools"
    yum -y install bc
    mkdir /scratch

%runscript
    echo "Arguments received: $*"
    exec /bin/bash "$@"

The script we used to use to run the FreeSurfer progam looked like this.

#!/bin/bash

echo "Running recon-all..."
recon-all -subjid $SUBJECT -all

The changed version, called run-fs.sh that is now used with Singularity looks like this.

#!/bin/bash

export FSLDIR=/usr/local/fsl/4.1.9
source $FSLDIR/etc/fslconf/fsl.sh
export FREESURFER_HOME=/usr/local/freesurfer/5.1.0
source $FREESURFER_HOME/FreeSurferEnv.sh

echo "Running recon-all..."
cd ${FREESURFER_WORK}
recon-all -subjid $SUBJECT -all

and it is run using

singularity run -B /scratch freesurfer.img $(pwd)/run-fs.sh $SUBJECT