====== 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 [[https://www.martinos.org/lab/lcn|Laboratory for Computational Neuroimaging]] at the [[http://martinos.org/|Athinoula A. Martinos Center for Biomedical Imaging]]. FreeSurfer is the structural MRI analysis software of choice for the [[https://github.com/Washington-University/Pipelines/wiki/v3.4.0-Release-Notes,-Installation,-and-Usage|Human Connectome Project]].

<WRAP round box todo>
The Freesurfer container is still in development on Comet and is awaiting further user feedback.
</WRAP>

   * For more information: https://surfer.nmr.mgh.harvard.edu/

----

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

   * ''/nobackup/shared/containers/freesurfer.8.0.20.sh''

... and a command it provides named ''container.run''.

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

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

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 [[advanced:software:x11|Linux Desktop session]] using our [[advanced:interactive|Open OnDemand]] service you can //also// launch the various graphical Freesurfer tools in a graphical compute environment on Comet.

   * Start the VNC Desktop Session:

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

   * Open the terminal window

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

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

<code lang=bash>
$ source /nobackup/shared/containers/freesurfer.8.0.20.sh
$ container.run freeview
</code>

   * The ''freeview'' graphical application will launch:

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

<WRAP round box tip>
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.
</WRAP>

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

   * ''/scratch''
   * ''/nobackup''
   * ''$HOME'' (or ''/mnt/nfs/home'') 

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

<WRAP round box todo>
To be added
</WRAP>

-----

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