FreeSurfer: Difference between revisions

From Cheaha
Jump to navigation Jump to search
(add toc, extra headers)
(format text, add note for fsl)
Line 11: Line 11:
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.
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
Here's how to run many recon-all processes on Cheaha.


=== Set up Environment ===
=== Set up FreeSurfer Environment ===
Setting up an environment to run FreeSurfer on Cheaha, consists of defining FreeSurfer related variables and their installation paths.  
 
Setting up an environment to run FreeSurfer on Cheaha, consists of defining FreeSurfer related variables and their installation paths. Steps 1 and 2 are a one-time set up, ie., the first time you login to Cheaha. Need not set up and source env variables defined in .bashrc from the next time you login to Cheaha (as at login bashrc is auto-sourced).  
   
   
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:
1. 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:
<pre>
<pre>
export FREESURFER_HOME=/share/apps/freesurfer/4.5
export FREESURFER_HOME=/share/apps/freesurfer/4.5
Line 24: Line 25:
export MNI_DIR=$FREESURFER_HOME/mni
export MNI_DIR=$FREESURFER_HOME/mni
export FSL_DIR=$HOME/fsl
export FSL_DIR=$HOME/fsl
export PATH=$FREESURFER_HOME/bin:$FSFAST_HOME/bin:$MNI_DIR/bin:$PATH
export PATH=$FREESURFER_HOME/bin:$FSFAST_HOME/bin:$MNI_DIR/bin:$FSL_DIR/bin:$PATH
</pre>
</pre>
NOTE: In the above bashrc, FSL_DIR is also defined. FSL is not part of FreeSurfer, but needs to be installed separately. [http://www.fmrib.ox.ac.uk/fsldownloads/ Download FSL from here].


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).  
2. Source the above environment variables.  
<pre>
<pre>
source $HOME/.bashrc
source $HOME/.bashrc
Line 33: Line 35:


=== Prep for running example recon_all process ===
=== 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.  
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.  
Line 42: Line 43:
#!/bin/bash
#!/bin/bash


function run_recon-all() {
function run-recon-all() {


for patient in `ls -1`
for patient in `ls -1`
Line 49: Line 50:
SUBJECTS_DIR=$UABGRID_SCRATCH/subjects
SUBJECTS_DIR=$UABGRID_SCRATCH/subjects
export SUBJECTS_DIR
export SUBJECTS_DIR
cat > submit_recon-all-$patient.sh <<EOF  
cat > submit-recon-all-$patient.sh <<EOF  
#!/bin/bash
#!/bin/bash
#$ -S/bin/bash
#$ -S/bin/bash
Line 70: Line 71:
EOF
EOF


qsub submit_recon-all-$patient.sh
qsub submit-recon-all-$patient.sh


done
done
Line 80: Line 81:
cd $UABGRID_SCRATCH/subjects
cd $UABGRID_SCRATCH/subjects


run_recon-all
run-recon-all


</pre>
</pre>

Revision as of 17:37, 27 July 2010

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:

  1. Creation of computerized models of the brain from magnetic resonance imaging (MRI) data.
  2. Processing of functional magnetic resonance imaging (fMRI) data.
  3. Measuring a number of morphometric properties of the brain including cortical thickness and regional volumes.
  4. 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.

Here's how to run many recon-all processes on Cheaha.

Set up FreeSurfer Environment

Setting up an environment to run FreeSurfer on Cheaha, consists of defining FreeSurfer related variables and their installation paths. Steps 1 and 2 are a one-time set up, ie., the first time you login to Cheaha. Need not set up and source env variables defined in .bashrc from the next time you login to Cheaha (as at login bashrc is auto-sourced).

1. 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:$FSL_DIR/bin:$PATH

NOTE: In the above bashrc, FSL_DIR is also defined. FSL is not part of FreeSurfer, but needs to be installed separately. Download FSL from here.

2. Source the above environment variables.

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