Surface Warp Protocol Pipeline Use
Overview
The protocol may be run using the LONI Pipeline environment. This page documents the workflows for both the "dual" and "octahedral" protocols, noting differences when applicable. Here are the general steps to run the protocol:
- Organize the data to conform to the expected file structure
- Copy the atlas destination directory to the atlas data source
- Copy the subject directories to the subject data source
- Copy the warped surface filenames to the output data sink
- Set the algorithm parameter to the desired values (optional)
- Validate and Run the workflow
Workflow Design
The workflow parallelizes the process at the subject level. This means that each subject is processed in serial. There are three important parts to the process, which control how the parallelization is implemented. First, each subject's data must be flattened-- this is performed in parallel. Once all subjects have been flattened, the atlas is computed. This is done in serial. After the atlas is created, each subject's flattened data must be warped and inflated-- this is done in parallel. Each of these steps is represented by a module in the work flow.
The modules in the workflow operate on directories of data, where a filename convention is expected. See the expected file structure page for details of this. Since each modules creates many files, they are not explicitly directed as output to the module. Therefore, there are output nodes that do not actually represent data flow, but they only provide a way to synchronize the operations to ensure the proper order of execution. The names of these nodes are 'input_sync' and 'output_sync'. When the user needs a file from a subject's directory for processing further down stream, there is a module 'Get File' that given a subject directory and filename will return the specified file, providing the user with a pipeline node to connect to the next module in the processing stream. This module is in place for the final warped surface.
Workflow Variables
There are several variables that need to be set in the workflow. All variables will work with the default value. Here is an enumeration with descriptions of those variables that affect the algorithm:
- 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 as well.
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.
Using an existing atlas
In some cases, the user will need to warp a collection of subjects to an existing atlas. This may occur when the process is performed while the data is being collected. If the user has already run the process on some subjects and several subjects worth of data is then collected, these new subjects can be registered to the existing atlas without running the process a second time on the entire dataset. The downside is that the atlas will not reflect these incoming subjects; however, if the atlas was computed using a large collection of subjects and there are few new subjects, the difference may be negligible. To implement this, remove the 'Create Atlas' module and connect the output sync nodes of 'Flatten Subject' to the input sync notes of 'Warp Subject'. The atlas provided in the 'Atlas Directory' data sink will then be used when warping.