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.
The latest version of Freesurfer available is 5.3.0. The last update to this software was 2 March 2013.
FreeSurfer on Cheaha
FreeSurfer-4.5 and FreeSurfer-5.3 versions are installed on Cheaha. module command can be used to find out the current(latest) installed version. For Freesurfer, use
module whatis freesurfer
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 is a tutorial to setup your Freesurfer environment and to run an example recon-all process on Cheaha.
SSH-key Config
Windows: Configure putty to connect to Cheaha with ssh-keys.
Follow this link for ssh key config on linux.
Follow this link for ssh key config on mac.
Environment Setup
For setting up an environment to run FreeSurfer on Cheaha, you need to load it's module to your environment:
module load freesurfer/freesurfer-5.3.0
A lot of environment variables are set up, when you load freesurfer module, such as:
FREESURFER_HOME=/share/apps/freesurfer/5.3.0 FSFAST_HOME=$FREESURFER_HOME/fsfast FUNCTIONALS_DIR=$FREESURFER_HOME/sessions FSF_OUTPUT_FORMAT=nii MNI_DIR=/share/apps/freesurfer/5.3.0/mni MINC_BIN_DIR=$FREESURFER_HOME/mni/bin MINC_LIB_DIR=$FREESURFER_HOME/mni/lib MNI_DATAPATH=$FREESURFER_HOME/mni/data FSL_DIR=$HOME/fsl PERL5LIB $FREESURFER_HOME/mni/lib/perl5/5.8.5 FS_OVERRIDE 0 FMRI_ANALYSIS_DIR $FREESURFER_HOME/fsfast PATH $FREESURFER_HOME/bin:$FREESURFER_HOME/fsfast/bin:$FREESURFER_HOME/mni/bin:/share/apps/freesurfer/QA_TOOLS QA_TOOLS /share/apps/freesurfer/QA_TOOLS
NOTE:
- FSL_DIR is also defined when you load FreeSurfer module. FSL is not part of FreeSurfer, but is installed and available to all users on Cheaha. To start using FSL/bedpostx see this documentation.
- QA_TOOLS are also included, which are intended to be used in assessing the quality of one or more FreeSurfer recons. To use QA_TOOLS see this documentation.
Example recon_all
1. Prepare by creating a subjects directory to hold image files in .nii format
mkdir $HOME/subjects cd $HOME/subjects
2. Get example image by copying the line below
wget http://repo.uabgrid.uab.edu/files/freesurfer/example.nii.gz gunzip example.nii.gz
Create job submission script
This is a simple SGE script to submit recon-all process. This script first copies your subjects directory from your $HOME containing the MRI data to Cheaha's high performance file system, $USER_SCRATCH, so as to ramp the speed of recon-all process. The recon-all process is then executed on $USER_SCRATCH.
NOTE: For the example run, we've created a subjects directory at $HOME to hold the example.nii image. For your actual run with real images, if you've copied your images to another location, then make sure to change $HOME/subjects (line no 7) accordingly in the script below.
Open a text editor and copy-paste the below contents:
#!/bin/bash
scratch=$USER_SCRATCH
jobs=$scratch/jobs
sub=$scratch/subjects
mkdir $jobs
cp -r $HOME/subjects $scratch/
function run-recon-all() {
cd $scratch
#create submit script for each patient in the subjects directory
for patient in `ls -1 $sub`
do
unset SUBJECTS_DIR
SUBJECTS_DIR=$sub
export SUBJECTS_DIR
cat > $jobs/recon-all-$patient.sh <<EOF
#!/bin/bash
#$ -S /bin/bash
#$ -cwd
#
#$ -N recon-all-$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
# set up FreeSurfer environment variables
mri_convert -oi -os $SUBJECTS_DIR/$patient $SUBJECTS_DIR/$patient.mgz
sleep 15
recon-all -sd $SUBJECTS_DIR -s $patient
EOF
done
#submit job script for each patient in the jobs directory to the cluster
pushd $jobs
for script in `ls -1`
do
echo "submitting job $script"
qsub $script
done
popd
}
run-recon-all
Make script executable
Make the above script executable
chmod +x <name-of-script-above>
Submit job script
Then submit that script with
./name-of-script-above
Track status of job
Check on the job status with qstat.
qstat -u $USER
Clean-up scratch
After the completion of the recon-all process, copy the results and logs back to your $HOME and delete the contents from scratch
cp -r $USER_SCRATCH/subjects $HOME/subjects-results cp -r $USER_SCRATCH/jobs $HOME/jobs-results rm -rf $USER_SCRATCH/subjects rm -rf $USER_SCRATCH/jobs
Transfer files from Cheaha to local computer
Transfer the subjects/jobs directory from your home account on Cheaha to your local computer with psftp. Here's how to transfer files using psftp.