Table of Contents

Freesurfer

FreeSurfer is a software package for the analysis and visualization of structural and functional neuroimaging data from cross-sectional or longitudinal studies. It is developed by the Laboratory for Computational Neuroimaging at the Athinoula A. Martinos Center for Biomedical Imaging. FreeSurfer is the structural MRI analysis software of choice for the Human Connectome Project.

The Freesurfer container is still in development on Comet and is awaiting further user feedback.

Running Freesurfer on Comet

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

… and a command it provides named container.run.

There is a corresponding .sh script for each version of the container image we make available.

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 the recon-all Freesurfer tool, you would run: 

$ source /nobackup/shared/containers/freesurfer.8.0.20.sh
$ container.run recon-all

USAGE: recon-all

 Required Arguments:
   -subjid <subjid>
   -<process directive>

 Fully-Automated Directive:
  -all           : performs all stages of cortical reconstruction
  -autorecon-all : same as -all

 Manual-Intervention Workflow Directives:
  -autorecon1    : process stages 1-5 (see below)
  -autorecon2    : process stages 6-23
                   after autorecon2, check white surfaces:
                     a. if wm edit was required, then run -autorecon2-wm
                     b. if control points added, then run -autorecon2-cp
                     c. proceed to run -autorecon3
...
...

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.

Using this command you can embed calls to Freesurfer in your Slurm sbatch jobs or srun calls and any of your existing compute pipelines.

Graphical Freesurfer tools on Comet

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

In the terminal window, source the freesurfer.8.0.20.sh file again, and this time run freeview: 

$ source /nobackup/shared/containers/freesurfer.8.0.20.sh
$ container.run freeview

You do not need to allocate a GPU to the VNC Desktop Session. A GPU is not needed for the simple tools / viewers, but more complex Freesurfer options (e.g. 3D object manipulation) may benefit from accelerated GPU rendering.

Accessing Data

While running Freesurfer 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 one of the Freesurfer commands 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:

… all refer to real directories outside the container on Comet, so restrict your reading/writing data to those three locations only.

If you use any of the graphical tools in Freesurfer (e.g. freeview), 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, anything else it shows you in the file select dialogue window refers to folders inside the container.

Building Freesurfer for Comet

To be added

Back to Software