Getting Started

This tutorial uses one of the existing ASHS atlas packages to perform hippocampal subfield segmentation. It assumes that ASHS software has been installed on the system, and that the environment variable ASHS_ROOT has been set to point at the root of the ASHS installation.

We recommend also installing ITK-SNAP on the system. ITK-SNAP can be used to view images and segmentation results. If possible, install ITK-SNAP version 3.6, which allows you to debug registration problems easily and to perform manual registration when automatic registration fails.
  • Linux VNC/X2GO users: make sure to download the "Qt4" version of ITK-SNAP, the default version does not work over VNC and X2GO.
The instructions below assume that ITK-SNAP can be invoked from the command line by entering itksnap.

Examining the Image Data

To run ASHS, we need a T1-weighted MRI scan and a T2-weighted MRI scan, preferably in NIFTI format. Let's assume the T1-weighted scan has the filename subj001_mprage.nii and the T2-weighted scan is called subj002_tse.nii. Coronal and sagittal slices from the kinds of scans that can be used with ASHS are shown below.

If your images are in DICOM format, we recommend using the dcm2nii program to convert to the NIFTI format. One additional advantage of using dcm2nii is that it removes extraneous neck tissue in the image.

Verify that the T2-MRI Slices are in the Z-Direction

The T2-weighted MRI should be oblique coronal, oriented along the main axis of the hippocampus. It should have high in-plane resolution (0.4mmx0.4mm) which it typically achieved at the cost of higher slice thickness (1.0-3.0mm). Importantly, the slice direction (anterior-posterior direction) should be the last dimension of the image. You can use the following command to verify this:

> $ASHS_ROOT/ext/Linux/bin/c3d subj001_tse.nii -info

Image #1: dim = [384, 384, 25];  bb = {[-72.148 -59.7914 -67.2827], [77.852 90.2086 -17.2827]};  vox = [0.390625, 0.390625, 2];  range = [0, 2981];  orient = Oblique, closest to RIA

The output of the command gives the dimension of the image, along with other information. In the example above, the dimensions are 384x384x25, indicating that the third dimension is the slice dimension, as required by ASHS.

If the dimensions of your image do not conform to this (e.g., you get dim = [25, 384, 384]), then the image needs to be reformatted. We recommend using the fslswapdim program from the FSL toolbox to do this.

Verify that the T1-MRI and T2-MRI are in the same space 

Every NIFTI image includes information about the position and orientation of the image relative to the scanner coordinate system. It is a good idea to check that this information is encoded correctly. To do so, load both the T1-MRI and T2-MRI image using ITK-SNAP (in two different windows). If the information is encoded correctly, positioning the ITK-SNAP crosshair in one ITK-SNAP window will also cause the crosshair to be positioned properly in the other window.

> itksnap subj001_mprage.nii &
> itksnap subj002_tse.nii &

The image below shows synchronized cursors in the two ITK-SNAP windows. The cyan crosshair in both modalities points to the same location in the hippocampus.

If the synchronized crosshairs in the two ITK-SNAP windows point to different locations, the NIFTI headers are probably incorrect. Try converting your DICOM data into NIFTI differently, to make sure the headers are correct.

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

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/ -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, -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/ -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/ -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

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:

 Code     Interpretation
 heur This is the result after applying the multi-atlas segmentation algorithm (joint label fusion, Wang et al., 2013) without any post-hoc correction 

In evaluation studies, this result is less accurate relative to manual segmentation than the other two results.

 corr_usegray This is the result of post-processing the heur result with a machine learning algorithm that learns the pattern of local voxel-level errors made by the joint label fusion algorithm, and tries to correct them (Wang et al., 2011).

This is the preferred result when the MRI intensity characteristics of the T2-weighted image are similar/consistent with the intensity characteristics of the images in the atlas package (located in the "train" directory of the atlas package).

 corr_nogray Similar to corr_usegray but the learning algorithm ignores image intensity information and only uses positional/shape information. 

This is the preferred result when the MRI intensity characteristics of the T2 scan being segmented are substantially different from the T2 scans in the atlas package.

A good way to visualize segmentation results is to use ITK-SNAP. From the command line type the following:

itksnap -g subj001_t2.nii
    -s $HOME/myworkdir/subj001/final/subj001_left_lfseg_corr_usegray.nii.gz 
    -l $HOME/myatlasdir/snap/snaplabels.txt

The results might look something like this: