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:
- Organize the data according to the common file structure
- Execute the script 'parallel_process_all.sh', specifying the protocol directory, the subject directory list, atlas directory and log directory.
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".
- parallel_process_all.sh:
- This script takes a protocol directory, a subject directory list, an atlas directory, and a log directory as input. The script flattens all subjects in the study directory list. If the given atlas directory does not exist, then the atlas is computed. Otherwise, the existing atlas data is used. Then, all subjects in the study directory are warped to the atlas. All standard output is written to files in the log directory. This requires the SGE. This is the "master" script for the process, and it calls all other scripts as necessary.
- parallel_flatten_all.sh
- This scripts takes a protocol directory, a subject directory list, and a log directory as input. The script applies the "flatten_subject.sh" script to all subjects in the study directory, writing the standard output to files in the log directory.
- parallel_warp_all.sh:
- This script takes a study directory, an atlas directory and a log directory as input. The script then applies the "warp_subject.sh" script to all subjects in the study directory, writing the standard output to files in the log directory.
- grid_constants.sh
- This script defines the constant values used in the grid-related scripts. All other scripts "source" this script.
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.