FreeSurfer
https://docs.rc.uab.edu/
Please use the new documentation url https://docs.rc.uab.edu/ for all Research Computing documentation needs.
As a result of this move, we have deprecated use of this wiki for documentation. We are providing read-only access to the content to facilitate migration of bookmarks and to serve as an historical record. All content updates should be made at the new documentation site. The original wiki will not receive further updates.
Thank you,
The Research Computing Team
Overview
FreeSurfer is a freely available software package developed by investigators at the Athinoula A. Martinos Center for Biomedical Imaging used for a number of procedures including:
- Creation of computerized models of the brain from magnetic resonance imaging (MRI) data.
- Processing of functional magnetic resonance imaging (fMRI) data.
- Measuring a number of morphometric properties of the brain including cortical thickness and regional volumes.
- Intersubject averaging of structural and functional data using a procedure that aligns individuals based on their cortical folding patterns for optimal alignment of homologous neural regions.
Working with FreeSurfer on a Cluster
FreeSurfer run its process in a non-parallel environment, so there won't be much benefit from a dual/quad/hex core machine for a single case analysis. However a number of FreeSurfer recon-all processes can be started in the same machine, thereby, theoretically reducing the time to analyze a group of cases.
Following steps detail on how to run an example FreeSurfer process on Cheaha
Set up Environment
Setting up an environment to run FreeSurfer on Cheaha, consists of defining FreeSurfer related variables and their installation paths. To set up your environment on Cheaha, open $HOME/.bashrc with your favorite text editor such as vim, nano, emacs etc., and copy-paste the contents below:
export FREESURFER_HOME=/share/apps/freesurfer/4.5 source $FREESURFER_HOME/SetUpFreeSurfer.sh export FSFAST_HOME=$FREESURFER_HOME/fsfast export FSF_OUTPUT_FORMAT=nii export MNI_DIR=$FREESURFER_HOME/mni export FSL_DIR=$HOME/fsl export PATH=$FREESURFER_HOME/bin:$FSFAST_HOME/bin:$MNI_DIR/bin:$PATH
Source the above environment variables. Only needed to continue this tutorial. Need not source env variables defined in .bashrc from the next time you login to Cheaha (as at login bashrc is auto-sourced).
source $HOME/.bashrc
Prep for running example recon_all process
This is a simple SGE script to submit recon-all process. This script first copies your subjects directory form your $HOME containing the MRI data to Cheaha's high performance file system, $UABGRID_SCRATCH, so as to ramp the speed of recon-all process. The recon-all process is then executed on $UABGRID_SCRATCH.
NOTE: Modify the SUBJECTS_DIR location to your local settings
#!/bin/bash
function run_recon-all() {
for patient in `ls -1`
do
unset SUBJECTS_DIR
SUBJECTS_DIR=$UABGRID_SCRATCH/subjects
export SUBJECTS_DIR
cat > submit_recon-all-$patient.sh <<EOF
#!/bin/bash
#$ -S/bin/bash
#$ -cwd
#
#$ -N recon-all-job$patient
# Set the hard and soft run time limits (ex: 1hour/58 min)
#$ -l h_rt=30:00:00,s_rt=29:55:00
#$ -j y
#
#$ -M YOUR_EMAIL_ADDRESS
#$ -m eas
# Load the appropriate module file(s) for your job
mri_convert -oi -os $SUBJECTS_DIR/$patient.nii $SUBJECTS_DIR/$patient.mgz
sleep 15
recon-all -sd $SUBJECTS_DIR -s $patient
EOF
qsub submit_recon-all-$patient.sh
done
}
cp -r $HOME/subjects $UABGRID_SCRATCH/
cd $UABGRID_SCRATCH/subjects
run_recon-all
Make the above script executable
chmod +x <name-of-script-above>
Then submit that script with
./name-of-script-above
Check on it with qstat.
qstat -u $USER
After the completion of the recon-all process, copy the results back to your $HOME and delete the contents from scratch
cp -r $UABGRID_SCRATCH/subjects $HOME/subjects-results rm -rf $UABGRID_SCRATCH/subjects