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:
- flatten_subject.sh:
- This script takes a single subject directory as input. The script resamples and flattens all contours. The surface is flattened. When finished the directory will contain: a resampled 3D version of every contour, a resampled and flattened version of every contour, the flattened cortical coordinate data, the flattened cortical color data and an empty file indicating the process is complete. The user may optionally provide a file that specifies user-defined algorithm parameters.
- create_atlas.sh:
- This script takes a study directory and an atlas directory as input. The script waits each subject to be flattened, then for each piece of anatomy, it creates a list of the resampled and flattened contours across subjects and computes the average. When finished, the directory will contain: lists of contours across subject for each piece of anatomy, the average contour for every piece of anatomy and an empty file indicating the process is complete. The user may optionally provide a file that specifies user-defined algorithm parameters.
- warp_subject.sh:
- This script takes a single subject directory and an atlas directory as input. The script waits for the flattening and the averaging to finish, then it warps the flattened surface to the given atlas. The user may optionally provide a file that specifies user-defined algorithm parameters.
- protocol_constants.sh
- This script defines the constant values used in the protocol. This includes default values for the algorithms. All other scripts "source" this script.
- create_algorithm_parameters.sh
- This script generates a file that may be used to specify user-defined algorithm parameters in the flattening, averaging and warping scripts.
Parameters
The script that creates the algorithm parameters allows the user to specify the following parameters:
- NUM_POINTS
- The number of points used when resampling contours.
- MU
- The first elastic PDE parameter, roughly speaking, this is the smoothness parameter. Reasonable values are from the interval (0,2].
- LAMBDA
- The second elastic PDE parameter, roughly speaking, this is the strength of the coupling of the coordinate axes. Reasonable values are from the interval (0,2].
- ITER
- The number of iterations. This is the number of smooth operations in the algorithm. Acceptable results are possible with 1000 results.
- MAX_DISTANCE (dual protocol only)
- A control value used when determining if a pair of contours "falls off". If the distance between a pair of target and reference landmarks exceeds this distance, the contour including that pair is excluded from the warp. The default value is 160.
- THRESHOLD (dual protocol only)
- A threshold used in determining whether a contour should be excluded completely from the warp. After the ContourTopologyChecker has determined if a contour should be included, the results for all subjects are used to determine which should be included. For each contour, the percentage of subjects in which this contour does not "fall off" is computed. If that percentage is less than the threshold, then that contour is excluded from all warps. Otherwise, the contour is included when it does not "fall off".
- WARPED_SURFACE_SUFFIX
- The suffix used when creating the warped surface. The default output is 'ucf', though 'obj' and 'off' are supported.
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):
- surface.suf : the cortical surface
- contour*.suf : the sulcal contours
Files created by the flattening script (in each subject's directory):
- Dual Protocol
- non_dual_color.rdd : the non-dual flattened color data
- dual_color.rdd : the dual flattened color data
- non_dual_coord.rdd : the non-dual flattened coordinate data
- dual_coord.rdd : the dual flattened coordinate data
- rsp_contour*.suf : the resampled three-dimensional contours
- flat_rsp_contour*.suf : the non-dual flattened and resampled contours
- dual_flat_rsp_contour*.suf : the dual flattened and resampled contours
- flatten_finished : the file that indicates the process is complete
- Octahedral Protocol
- color.rdd : the flattened color data
- coord.rdd : the flattened coordinate data
- rsp_contour*.suf : the resampled three-dimensional contour
- flat_rsp_contour*.suf : the flattened and resampled contour
- flatten_finished : the file that indicates the process is complete
Files created by the averaging script (in the atlas directory):
- Dual Protocol
- flat_rsp_contour_*.txt : the lists of non-dual contours across subjects
- dual_flat_rsp_contour_*.txt : the lists of dual contours across subjects
- average_flat_rsp_contour*.suf : the non-dual average contours
- average_dual_flat_rsp_contour*.suf : the average dual contours
- atlas_finished : the file that indicates the process is complete
- Octahedral Protocol
- flat_rsp_contour_*.txt : the lists of contours across subjects
- average_flat_rsp_contour*.suf : the average contours
- atlas_finished : the file that indicates the process is complete
Files created by the warping script (in each subject directory):
- Dual Protocol
- ref_non_dual_contours.txt : the reference (atlas) non-dual contours
- tar_non_dual_contours.txt : the target (subject) non-dual contours
- ref_dual_contours.txt : the reference (atlas) dual contours
- tar_dual_contours.txt : the target (subject) dual contours
- ref_non_dual.lm : the reference non-dual landmarks
- tar_non_dual.lm : the target non-dual landmarks
- ref_dual.lm : the reference dual landmarks
- tar_dual.lm : the target dual landmarks
- ref_non_dual_landmarks.png : the image of the reference non-dual landmarks
- tar_non_dual_landmarks.png : the image of the target non-dual landmarks
- ref_dual_landmarks.png : the image of the reference dual landmarks
- tar_dual_landmarks.png : the image of the target dual landmarks
- non_dual_warp.rdd : the non-dual warp
- dual_warp.rdd : the dual warp
- warped_non_dual_color.rdd : the warped non-dual color data
- warped_dual_color.rdd : the warped dual color data
- warped_non_dual_coord.rdd : the warped non-dual coordinate data
- warped_dual_coord.rdd : the warped dual coordinate data
- blended_color.rdd : the blended color data
- blended_coord.rdd : the blended coordinate data
- warped_surface.suf : the inflated warped surface
- non_dual_color.png : the image of the non-dual color data
- dual_color.png : the image of the dual color data
- warped_non_dual_color.png : the image of the warped non-dual color data
- warped_dual_color.png : the image of the warped dual color data
- non_dual_coord.png : the image of the non-dual coordinate data
- dual_coord.png : the image of the dual coordinate data
- warped_non_dual_coord.png : the image of the warped non-dual coordinate data
- warped_dual_coord.png the image of the warped dual coordinate data
- blended_color.png : the image of the blended color data
- blended_coord.png : the image of the blended coordinate data
- Octahedral Protocol
- ref_contours.txt : the list of reference (atlas) contours
- tar_contours.txt : the list of target (subject) contours
- ref.lm : the reference landmarks
- tar.lm : the target landmarks
- ref_landmarks.png : the image of reference landmarks
- tar_landmarks.png : the image of target landmarks
- warp.rdd : the warp
- warped_coord.rdd : the warped coordinate data
- warped_color.rdd : the warped color data
- warped_surface.suf : the inflated warped surface
- color.png : the image of the color data
- coord.png : the image of the coordinate data
- warped_color.png : the image of the warped color data
- warped_coord.png : the image of the warped coordinate data
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:
- edit the protocol_constants.sh script
- set the DEBUG variable to "-debug"
- set the VERBOSE variable to "-verbose"
this will be added to all calls of all programs.