Surface Warp Protocol Grid Usage

Overview

This page describes how to use Surface Warp protocol on the command-line using the Sun Grid Engine (SGE). This documentation applies to both the Dual Surface Warp protocol and the Octahedral Surface Warp Protocol, and any differences are noted.

Use

Here are general steps to take in running the protocol:

The reference copy of 'parallel_process_all.sh" is in the directory: /nethome/users/shapetls/bin/SurfaceWarpTools/scripts/grid

An example of calling the above script is here.

Note: all paths must be absolute. This is necessary because the grid's environment will not respect the users current working directory after starting jobs for parallel processing.

If the user has a precomputed atlas, that directory should be passed to the 'parallel_process_all.sh' script. Otherwise, the atlas will be computed.

Optionally, the user may perform the steps of the protocol with a greater degree of control. The user may flatten a single subject in serial or directory of subjects in parallel. Given a collection of subjects with flattened data, the user may compute an atlas. Given an atlas and a subject with flattened data the user may warp that subject to the atlas in serial or warp a directory of subjects with flattened data to a given atlas in parallel.

Parallel Processing

Since the flattening and warping stages are computed independently for each subject, there are scripts that perform these operations given a single subject's data directory. This script runs serially, and they do not require the Sun Grid Engine (SGE). For each of these serial subject-specific scripts, there is a batch processing script that executes the script on a collection of subjects in parallel using the SGE. Furthermore, there is a batch processing script that flattens all subjects, creates the atlas (if it does not exist) and then warps all subjects. See the next section for an enumeration of these scripts.

There are sequencing concerns when computing in parallel. In particular, the flattening must finish before averaging, and the averaging and flattening must finish before the warping. To enforce this sequence the implementation uses files to indicate the status of a particular step. These files are created by the UNIX program 'touch' and contain no data, so their existence is used to determine if a process is complete. For example, the flattening and the atlasing steps may be initiated simultaneously, but the atlasing waits until all subjects' directories contain a certain file before proceeding.

Scripts

The following is an enumeration of the scripts, with a brief description of each. See the scripts' comments for a more information. These scripts require the user to provide the directory containing the protocol scripts, whether they are dual or octahedral. This directory is referred to as the "protocol directory".

Filenames and Parameters

See the page on implementation for specific filenames and algorithm parameters.

Errors

When the user suspects that an error has occurred, the logs should be reviewed. In the event of an error, the programs further in the stream will continue to run because they are waiting for files to exist. This means that the user should kill all of the warp-related processes in the event of an error. For example, if a subject contains a contour file that does not properly encode the data to the expected format, an error will occur. This subject will not finish flattening. Consequently, the atlasing will wait forever to proceed. The flattening and atlasing steps are much faster than the warping step, so if these are taking an exceptionally long amount of time, the logs should be reviewed.