Building an Atlas for T1-MRI

Preparing the Data

Please see "Examining the Image Data" section under Getting Started. All the input images should satisfy the requirements in that section.

Some additional preparation is required to build an atlas package. You will need to create the following files to run ASHS. Each file is described below.

1. Data manifest file (required)
2. Label description file (required)
3. Configuration file (optional)
4. Slice heuristics file (optional)
5. Cross-validation file (optional)

Data Manifest File

The data manifest file is just a text file that describes the data used to build the atlas. Create it using your favorite text editor (Vim, Emacs, or gEdit). Each row in the file corresponds to one subject. Each row contains 5 entries, separated by spaces. The entries are:

1. Subject ID (no spaces)
2. Path to T1-weighted MRI in NIFTI format
3. Duplicate path to T1-weighted MRI in NIFTI format
4. Path to the Left MTL segmentation in NIFTI format
5. Path to the Right MTL segmentation in NIFTI format

All entries must not contain spaces. Example manifest file follows:

XZY001 data/xzy001_t1.nii data/xzy001_t1.nii seg/xzy001_l.nii seg/xzy001_r.nii

XZY002 data/xzy002_t1.nii data/xzy002_t1.nii seg/xzy002_l.nii seg/xzy002_r.nii

To avoid errors, we recommend using full paths in the manifest file (in the example above we used relative paths for brevity)

Label Description File

The label description file is used to specify the names of the anatomical labels used in your protocol, as well as the color that should be used when generating figures. The best way to create this file is to use ITK-SNAP.

1. Load your T2-weighted MRI in ITK-SNAP (File->Open Image)
2. Load your left or right segmentation (Segmentation->Open Segmentation)
3. Open the label editor (Tools->Label Editor)
4. Specify a name and a color for each of the labels used in your segmentation.
5. Save your labels to a file (Segmentation->Export Label Descriptions)

The saved label description file should look like this:

################################################

# ITK-SnAP Label Description File

# File format:

# IDX   -R-  -G-  -B-  -A--  VIS MSH  LABEL

# Fields:

#    IDX:   Zero-based index

#    -R-:   Red color component (0..255)

#    -G-:   Green color component (0..255)

#    -B-:   Blue color component (0..255)

#    -A-:   Label transparency (0.00 .. 1.00)

#    VIS:   Label visibility (0 or 1)

#    IDX:   Label mesh visibility (0 or 1)

#  LABEL:   Label description

################################################

    0     0    0    0        0  0  0    "Clear Label"

    1   255    0    0        1  1  1    "Hippocampus"

    2     0  255  255        1  1  1    "EC"

    3   255    0  255        1  1  1    "PRC"

    4   255  239  213        1  1  1    "Cyst"

As an alternative to using ITK-SNAP, create a file in the same format using a text editor instead.

Handling Left vs. Right: In our lab, we use the same labels for the left and right structures. So left CA1 and right CA1 would both have label 1. If you prefer to assign different labels to the left CA1 and right CA1, you may. ASHS should still work.

Configuration File (Optional)

The configuration file can be used to tune ASHS performance to your own data. You should not need to provide your own configuration file when working with image resolution and dimensions comparable to the ones used in the ASHS-provided atlas packages, i.e.:

• T1-MRI has ~1.0 x 1.0 x 1.0 mm³ resolution and covers whole brain
• Structures are < 5 cm³ in volume

However, if your images are much larger than that, you may need to override some settings in the configuration file. To do so, copy the configuration file in the ASHS bin directory and edit the entries in this file to suit your situation. The entries are documented in the file itself.

> cp $ASHS_ROOT/bin/ashs_config.sh work/my_ashs_config.sh

> gedit work/my_ashs_config.sh

Cross-validation File (Optional)

During atlas generation, you may choose to perform some cross-validation to measure segmentation accuracy. This cross-validation is invoked using the -x option to ashs_train. When using this option, you must supply a file that specifies which subjects are treated as test subjects in each cross-validation experiment.

Notes:

• Cross-validation involves leave-K-out segmentation of the input datasets. However, some of the registrations between input datasets performed during atlas building are reused during cross-validation.
• Cross-validation can take as much or more time than atlas building.
• Currently, cross-validation statistics (overlaps, etc.) are not generated by ashs_train and must be computed by the user.

The cross-validation file is a text file. Each row corresponds to one cross-validation experiment, and contains the Subject IDs of the subjects who should be used as test subjects for that experiment. For simple leave-one-out cross-validation, simply provide a file with the ID of each subject on a separate row:

xzy001

xzy002

...

For leave-five-out cross-validation, the file would look like this:

xzy001 xzy023 xzy025 xzy039 xzy042 

xzy007 xzy011 xzy015 xzy026 xzy041

... 

Building the Atlas

To build the atlas, execute the command ashs_train.sh. We recommend writing a small bash script file that will run the command (let's call it runme.sh). This way you can re-run ashs_train.sh later without having to retype all the parameters. Here is an example script:

#!/bin/bash

# Script for running ASHS training pipeline

$ASHS_ROOT/bin/ashs_train.sh \

  -D manifest.txt \

  -L snaplabels.txt \

  -w /home/pauly/work/ashs/testatlas \

  -Q \

  | tee ashs_train.log

This script runs the program with the minimal set of required options:

• -D specifies the manifest file
• -L specifies the label description file
• -w gives the working directory where the atlas will be created
• -Q specifies that we are running atlas building in parallel on a cluster that has the Grid Engine (qsub) scheduling system.

To provide your own configuration and cross-validation files, use the options -C and -x, respectively. For example:

#!/bin/bash

# Script for running ASHS training pipeline

$ASHS_ROOT/bin/ashs_train.sh \

  -D manifest.txt \

  -L snaplabels.txt \

  -w /home/pauly/work/ashs/testatlas \

  -Q \

  -C my_config.sh \

  -x my_xval.txt \

  | tee ashs_train.log

To see a full listing of options, call

> $ASHS_ROOT/bin/ashs_train.sh -h

Now, use nohup to launch your script:

> nohup bash ./runme.sh &

Examining the Output and Using the Atlas

When atlas building completes, the working directory should contain the folder final. Inside that folder you should see the following files and directories:

> ls -l final

drwxr-xr-x  4 pauly jboss   29 Jul 23  2013 adaboost

-rw-r--r--  1 pauly jboss   36 Jul 23  2013 ashs_atlas_vars.sh

-rw-r--r--  1 pauly jboss 7403 Jul 17  2013 ashs_system_config.sh

-rwxr-xr-x  1 pauly jboss  132 Jul 17  2013 ashs_user_config.sh

drwxr-xr-x  2 pauly jboss   64 Aug  2  2013 ref_hm

drwxr-xr-x  2 pauly jboss   38 Sep 12  2013 snap

drwxr-xr-x  2 pauly jboss 4096 Apr 16 12:24 template

drwxr-xr-x 31 pauly jboss 4096 Jul 23  2013 train

The contents of the final directory should be on the order of several gigabytes (depending on the number and size of the input images, of course). Run the following command to examine the size of the output to check that everything is there.

> du -h --max-depth=1

58M         ./template

12M         ./ref_hm

2.0G ./train

4.0K ./snap

1.4M ./adaboost

2.1G .

If the sizes of your subdirectories don't look similar, check the output for errors.

The final directory and its contents constitute the atlas package. You should be able to provide the path the final directory to ashs_main script in order to segment new datasets using your atlas package. This is the best way to test whether package building worked.