Chapter 9 FreeSurfer v6 Hippocampus and Amygdala

The hippocampal subfield module requires the Matlab R2014 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. This is a different runtime then the one required for hippcampus and brainstem, because we will use the FreeSurfer developmental version.

cd ~/apps/freesurfer-dev
curl "https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime?action=AttachFile&do=get&target=runtime2014bLinux.tar.gz" -o "runtime.tar.gz"
tar xvf runtime.tar.gz
rm runtime.tar.gz

You also need to copy your original license to the new developmental version of FreeSurfer.

cp ~/apps/freesurfer/license.txt ~/apps/freesurfer-dev/

9.1 Job Script

On the remote computer create job script.

vi ~/scripts/ACAP/fsHA-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-dev
source $FREESURFER_HOME/SetUpFreeSurfer.sh

# INSERT CODE, AND RUN YOUR PROGRAMS HERE
segmentHA_T1.sh \
${1} \
/work/${username}/data/ACAP/mindboggle/freesurfer_subjects/

9.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/fsHA-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/fsHA-job.sh \
  ${subjid}
  sleep 1
done

9.3 Submit Jobs with Batch Script

Submit jobs.

sh ~/scripts/ACAP/fsHA-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*

9.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/

9.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-ACAP1001/mri/):

  • [lr]h.hippoSfVolumes-T1.v2x.txt: these text files store the estimated volumes of the hippocampal substructures and of the whole hippocampus.
  • [lr]h.amygNucVolumes-T1.v2x.txt: these text files store the estimated volumes of the nuclei of the amygdala and of the whole amygdala.
  • [lr]h.hippoAmygLabels-T1.v2x.mgz: they store the discrete segmentation volumes at subvoxel resolution (0.333 mm).
  • [lr]h.hippoAmygLabels-T1.v2x.FSvoxelSpace.mgz: they store the discrete segmentation volume in the FreeSurfer voxel space (normally 1mm isotropic, unless higher resolution data was used in recon-all with the flag -cm).
  • [lr]h.hippoAmygLabels-T1.v2x.[hierarchy].mgz: they store the segmentations with the different hierarchy levels.
  • [lr]h.hippoAmygLabels-T1.v2x.[hierarchy].FSvoxelSpace.mgz: same as above, but in FreeSurfer voxel space.

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}
# LEFT HIPPOCAMPUS
asegstats2table \
--subjectsfile subjects.txt \
--statsfile=hipposubfields.lh.T1.v21.stats \
--skip \
--delimiter comma \
--tablefile tablefiles/hipposubfields-lh-stats.csv

# RIGHT HIPPOCAMPUS
asegstats2table \
--subjectsfile subjects.txt \
--statsfile=hipposubfields.rh.T1.v21.stats \
--skip \
--delimiter comma \
--tablefile tablefiles/hipposubfields-rh-stats.csv

# LEFT AMYGDALA
asegstats2table \
--subjectsfile subjects.txt \
--statsfile=amygdalar-nuclei.lh.T1.v21.stats \
--skip \
--delimiter comma \
--tablefile tablefiles/amygdalarnuclei-lh-stats.csv

# RIGHT AMYGDALA
asegstats2table \
--subjectsfile subjects.txt \
--statsfile=amygdalar-nuclei.Rh.T1.v21.stats \
--skip \
--delimiter comma \
--tablefile tablefiles/amygdalarnuclei-rh-stats.csv

If you want to view the segmentation:

cd /Volumes/bobo/data/ACAP/mindboggle/freesurfer_subjects/sub-ACAP1004/mri
freeview -v nu.mgz -v lh.hippoAmygLabels-T1.v21.CA.mgz:colormap=lut -v rh.hippoAmygLabels-T1.v21.CA.mgz:colormap=lut