Chapter 10 FreeSurfer v6 Brainstem Substructures

The brainstem substructures module requires the Matlab R2012 runtime; the runtime is free, and therefore NO MATLAB LICENSES ARE REQUIRED TO USE THIS SOFTWARE. Instructions for the installation of the runtime can be found here:

https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime

On the remote computer, install the MATLAB runtime. You don’t have to do this step if you’ve already done this for the hippocampus segmentation.

cd $FREESURFER_HOME
curl "https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime?action=AttachFile&do=get&target=runtime2012bLinux.tar.gz" -o "runtime.tar.gz"
tar xvf runtime.tar.gz
rm $FREESURFER_HOME/runtime.tar.gz

10.1 Job Script

On the remote computer create job script.

vi ~/scripts/ACAP/fsBS-job.sh

Copy and paste.

#!/bin/bash

#SBATCH --time=05:00:00   # walltime
#SBATCH --ntasks=1   # number of processor cores (i.e. tasks)
#SBATCH --nodes=1   # number of nodes
#SBATCH --mem-per-cpu=16G  # memory per CPU core

# LOAD ENVIRONMENTAL VARIABLES
username=`id -un`
export FREESURFER_HOME=/home/${username}/apps/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

# INSERT CODE, AND RUN YOUR PROGRAMS HERE
recon-all \
-subjid ${1} \
-brainstem-structures \
-sd /work/${username}/data/ACAP/mindboggle/freesurfer_subjects/

10.2 Batch Script

First check that your subjid are correct.

cd /work/ashley.ware/data/ACAP/mindboggle/
for subjid in $(ls freesurfer_subjects/ | grep -e "sub*"); do
  echo $subjid
done

If everything is correct then you can create your batch file.

Create batch script.

vi ~/scripts/ACAP/fsBS-batch.sh

Copy and paste.

#!/bin/bash
curTime=`date +"%Y%m%d-%H%M%S"`
username=`id -un`
mkdir -p ~/logfiles/ACAP/${curTime}
cd /work/${username}/data/ACAP/mindboggle/
for subjid in $(ls freesurfer_subjects/ | grep -e "sub*"); do
  sbatch \
  -o ~/logfiles/ACAP/${curTime}/output-${subjid}.txt \
  -e ~/logfiles/ACAP/${curTime}/error-${subjid}.txt \
  ~/scripts/ACAP/fsBS-job.sh \
  ${subjid}
  sleep 1
done

10.3 Submit Jobs with Batch Script

Submit jobs.

sh ~/scripts/ACAP/fsBS-batch.sh

You can check the status of your jobs by checking if it is running or pending.

squeue

You can check the outputs.

tail -n 5 ~/logfiles/ACAP/<date>/output*

10.4 Download Directory / Sync Directory with Arc

Back on your local computer, sync the data from the remote computer to your local computer.

rsync -rauv \
ashley.ware@arc.ucalgary.ca:/work/ashley.ware/data/ACAP/mindboggle/freesurfer_subjects/ \
/Volumes/bobo/data/ACAP/mindboggle/freesurfer_subjects/

10.5 Output

The output will consist of the follwing set of files, which can be found under the subject’s mri directory (in this example, $SUBJECTS_DIR/sub-001/mri/):

  • brainstemSsLabels.v1x.mgz: the volume with the segmentation at 0.333 mm resolution.
  • brainstemSsLabels.v1x.FSvoxelSpace.mgz: discrete segmentation in the voxel space of the other FreeSurfer volumes (nu.mgz, aseg.mgz, etc).
  • brainstemSsVolumes.v1x.txt: a text file with the volumes of the brainstem structures and of the whole brainstem, in cubic mm.

where [lr] refers to the left or right hemisphere, “v2x” is the version (v20 or, in newer dev versions, v21) and [hierarchy] refers to the different hierarchy levels in the segmentation (“HBT”, “FS60 or”CA").

It will also produce files in the stats folder called hipposubfields.[lr]h.T1.v2x.stats and amygdalar-nuclei.[lr]h.T1.v2x.stats. These can be compiled across subject with the following code:

SUBJECTS_DIR=/Volumes/bobo/data/ACAP/mindboggle/freesurfer_subjects/
cd ${SUBJECTS_DIR}

asegstats2table \
--subjectsfile subjects.txt \
--statsfile=brainstem.v12.stats \
--skip \
--delimiter comma \
--tablefile tablefiles/brainstem-stats.csv

If you want to view the segmentation:

cd/Volumes/bobo/data/ACAP/mindboggle/freesurfer_subjects/sub-ACAP1001/mri
freeview -v nu.mgz -v brainstemSsLabels.v12.mgz:colormap=lut