Surface Warp Protocol Implementation

Overview

This page describes the implementation of protocol as a collection of applications, scripts and pipeline workflows.

The protocol is implemented with three levels of abstraction. On the low level, there are applications that operate on individual data files. On the middle level, there are scripts that tie these applications together to operate on individual subjects. On the high level, there are scripts and LONI Pipeline workflows that apply the mid-level scripts to entire studies. The user may use the protocol on any level; however, there should not be a situation where the user is required to use anything but the high-level implementation.


High-Level Implementation

There are several high-level implementations of the protocol: the LONI Pipeline workflows, the Sun Grid Engine build and the Serial command-line build. The Pipeline and Grid versions of these implemenations allow for parallelized processing of multiple subjects. This is done by executing the mid-level scripts simultaneously on a compute cluster. These constitute the user interface for the typical user of the protocol, and the user should have no need to know the mid- and low-level implementation details. See the linked pages documentation of use of these interfaces.


Mid-Level Implementation

The Java applications are tied together to operate on individual subjects by bash shell scripts. These scripts do not perform any major computation, but they handle system-level issues such as file names and memory allocation. Essentially, these scripts implement the filename conventions for input and output, preparing the calls to the Java applications using paths to data provided by the user.

Scripts

The following scripts constitute the mid-level implementation:

Parameters

The script that creates the algorithm parameters allows the user to specify the following parameters:

Note that the elastic parameters are equivalent up to a scalar multiple. E.g. for parameters (mu, lambda) and real number c, the parameters (mu, lambda) will give equivalent results for the warp as (c * mu, c * lambda), though the error measurements will be different by that scalar.

Filenames

The input filenames are expected to follow a naming convention, which is defined at assumptions about data.

The output filenames are described in this section with the pattern "filename : description". The file formats are flexible, so the surface and contour filenames will use ".suf" as a placeholder. Since there are an arbitrary number of and names for the contours, an asterisk is used when listing contours.

Starting Files (in each subject's directory):

Files created by the flattening script (in each subject's directory):

Files created by the averaging script (in the atlas directory):

Files created by the warping script (in each subject directory):


Low-Level Implementation

The low level implementation consists of a collection of Java applications. All of the high-cost computations are performed by these applications.

The following programs constitute the low-level implementation:

These applications are built with the aid of the following libraries:


Debugging

Some of the warp applications support debugging and verbose modes. Enabling these flags will cause extensive debugging information to be generated. To enable this, follow these steps:

  1. edit the protocol_constants.sh script
    1. set the DEBUG variable to "-debug"
    2. set the VERBOSE variable to "-verbose"

this will be added to all calls of all programs.