Local ASHS: Basic Usage

Be sure to complete the local ASHS installation tutorial before proceeding to this section

Make sure that your MRI data is compatible with ASHS

Overview

This tutorial uses one of the existing ASHS atlas packages to perform medial temporal lobe subregion segmentation. It assumes that ASHS software has been installed on your system, and that the environment variable ASHS_ROOT has been set to point at the root of the ASHS installation. In order to use the ASHS-PMC-T1 atlas, fast-ashs v2.0.0 is required.

Running ASHS using a Provided Atlas Package

Running ASHS with one of atlas packages provided by the developers is easy. Suppose the atlas package has been unpacked into the directory $HOME/myatlasdir.

Verify that this directory contains the atlas package files:

> ls $HOME/myatlasdir

adaboost

ashs_atlas_vars.sh

ashs_system_config.sh

ashs_user_config.sh

README.txt

ref_hm

snap

template

train

Running ASHS on a single core

If you wish to run ASHS on a single CPU core, enter the following command:

> nohup $ASHS_ROOT/bin/ashs_main.sh -I subj001 -a $HOME/myatlasdir 

   -g subj001_mprage.nii.gz -f subj001_tse.nii.gz 

   -w $HOME/myworkdir/subj001 &

[1] 86770

appending output to nohup.out

The -g and -f options supply the T1 and T2-weighted MRI scans, respectively, for the T2-pipelines. If you are using the ASHS-PMC-T1 atlas, supply the T1-weighted MRI scan to both -g and -f arguments. -a points to the location of the atlas package, -w points to the working directory where the ASHS output will reside, and the -I option provides the ID for the subject, which will be included in the output filenames.

The optional nohup ... & commands make the command execute in the background, and make sure that it will run even if you close the terminal window from which you ran it. This is the safest option when you are connecting to the Linux server remotely. It prevents loss of network connection from interrupting ASHS execution. You can view ASHS output by typing

> tail -f nohup.out

Running ASHS on multiple cores using Grid Engine

Running ASHS on a single CPU core can take on the order of 1-2 hours to complete. If you have access to a computing cluster with Sun Grid Engine (SGE), then you can obtain results much faster by running ASHS subtasks in parallel.

First, verify that you have SGE installed on your system. Try submitting a simple job (which does nothing but quit after 1000 seconds).

> qsub -j y -o /eraseme.out -b y -N mytest sleep 1000

Your job 1824919 ("mytest") has been submitted

Now wait 30 seconds or so, and make sure that the job is running

> qstat

job-ID  prior   name       user         state submit/start at     

--------------------------------------------------------------

1824919 0.50500 mytest     pauly        r     08/19/2014 11:58:30        

You should see in the output the name of the job (mytest) and under state it should say r (running) or qw (waiting for a slot in the queue). If the job does not show up or the state has the letter E (error), something is wrong. Check with your system administrator.

Once you check that SGE works on your system, run ASHS as above, but providing the -Q option:

> nohup $ASHS_ROOT/bin/ashs_main.sh -Q -I subj001 

   -a $HOME/myatlasdir

   -g subj001_mprage.nii.gz -f subj001_tse.nii.gz 

   -w $HOME/myworkdir/subj001 &

[1] 86770

appending output to nohup.out

When you use -Q, ASHS will launch multiple registration subtasks in parallel. It may use on the order of 40-60 cores, depending on the size of the atlas package.

Run qstat periodically to make sure that jobs launched by ASHS are running. There should be multiple jobs in the queue with name "ashs_stgX_..." in running (r) or waiting (qw) states.

In some environments, you may need to provide additional options to SGE. For example, on some clusters, users must specify what queue to run jobs in, or you may need to request more than the default amount of memory per core (we recommend at least 2GB of RAM per core). These options can be passed in using the lowercase -q option to ashs_main. It may be a good idea to discuss with a system administrator if you are not sure which options to use.

Running ASHS on multiple cores using GNU parallel

GNU parallel is available for various Linux distributions and on MacOS via Homebrew. It makes it possible to run command-line jobs on multiple CPU cores on a single machine. To use ASHS with GNU parallel, supply the -P flag.

> nohup $ASHS_ROOT/bin/ashs_main.sh -P -I subj001 

   -a $HOME/myatlasdir

   -g subj001_mprage.nii.gz -f subj001_tse.nii.gz 

   -w $HOME/myworkdir/subj001 &

[1] 86770

appending output to nohup.out

Viewing ASHS Segmentation Results

ASHS places its final segmentation results in the final subdirectory of the working directory specified in the -w option to ashs_main. There you should find 6 NIFTI images:

> ls $HOME/myworkdir/subj001/final/*nii.gz

subj001_left_lfseg_corr_nogray.nii.gz

subj001_left_lfseg_corr_usegray.nii.gz

subj001_left_lfseg_heur.nii.gz

subj001_right_lfseg_corr_nogray.nii.gz

subj001_right_lfseg_corr_usegray.nii.gz

subj001_right_lfseg_heur.nii.gz

These are the results obtained for the left and right hemispheres using three different variants of the segmentation algorithm. Please see the table below for which one to use:

Please note, if you are using ASHS-PMC-T1 atlas, it is recommended to use the "JLF result".