Surface Warp Protocol Quick Start Guide

This page provides the user with a cursory introduction to using the surface warping protocol. The first section describes the files that are used in all examples. The other sections describe each of the ways the user may run the protocol.

Prepare the files

There are several options for running the protocol, but the necessary file structure is common to all of these. You will probably have to rename and move the data to match the expected file structure. See this page for a description of the expected structure. Suppose we have a study directory '/a_path/Data/'. Inside this directory, there are three subject directories. In each these subject directories, there is a surface file and a collection of contours. Note that the subjects do not need to have the same collection of contours. Here are directory listings of this example:

$ ls /a_path/Data
Subject_1  Subject_2  Subject_3
$ ls /a_path/Data/*
Subject_1:
contour_A.obj  contour_B.obj  contour_C.obj  contour_D.obj  surface.obj

Subject_2:
contour_A.obj  contour_B.obj  contour_C.obj  contour_D.obj  surface.obj

Subject_3:
contour_A.obj  contour_B.obj  contour_C.obj  surface.obj

Run the protocol using the LONI Pipeline

If the user would like to run the protocol using the LONI Pipeline, read this section; otherwise, explore the other sections of this page. First, the user should get the newest example workflow from the appropriate location specified on the downloads page. Typically, you will want to use an OctahedralSurfaceWarp workflow; for more details, please consult our workflow descriptions page.

When specifying the input data to the workflow, a list of subject directories should be generated. This can be done by typing the paths, or it can be done with the following command:

$ echo /a_path/Data/* | awk '{gsub(" ", "\n"); print}'
/a_path/Data/Subject_1
/a_path/Data/Subject_2
/a_path/Data/Subject_3

  1. Double-Click the "Subject Directories" data source element (a circle near the top left of the workflow) and edit the text box contents to show the list of subject data directories previously generated).
  2. Double-Click the "Atlas Directory" data source element (another gray circle) and edit it's text box contents to be the path to a directory in which the warp atlas files will be stored.
  3. The user may execute the workflow locally or remotely, depending on which Pipeline Workflow has been chosen.

Execute Remotely:

To run the workflow, first copy the data to a path accessible by the cranium cluster. For simplicity, we'll assume the example path is accessible. Next, the list of subject directories should be copied to the "Subject Directory" data source module in the workflow. Next, an atlas directory should be created:

$ mkdir /a_path/Atlas

This directory should be copied to the "Atlas Directory" module. The workflow may then be executed, and the subject directories will then contain the warped surfaces and all intermediate data for analysis.

Execute Locally:

When executing locally, the data should be located on the user's local machine, and the paths to the data should be copied like above. The use of the workflow for local execution is the same as the remote except the user must specify a workflow variable value. The user must specify the value of the workflow variable 'TOOLS_PATH', which must point to the local protocol tools directory. The protocol tools directory contains the jars, scripts and data used by the protocol. After doing this, the user can run the workflow.

Run the protocol using the command-line scripts

If the user would like to run the protocol using the command-line, read this section; otherwise, explore the other sections of this page. When using the command-line scripts, the user may execute the workflow in serial or parallel, using the Sun Grid Engine.

For both serial and parallel use, the user must create a list of the subject directories that are to be processed. This can be done with a text editor or using the following command:

$ echo /a_path/Data/* | awk '{gsub(" ", "\n"); print}' > /a_path/subjects.list;
$ cat /a_path/subjects.list 
/a_path/Data/Subject_1
/a_path/Data/Subject_2
/a_path/Data/Subject_3

Execute in Parallel:

To execute in parallel, the process may be started with the following command:

$ /nethome/users/shapetls/bin/SurfaceWarpTools/scripts/grid/parallel_process_all.sh /nethome/users/shapetls/bin/SurfaceWarpTools/scripts/octahedral_protocol /a_path/subjects.list /a_path/Atlas /a_path/Logs

The directory '/nethome/users/shapetls/bin/SurfaceWarpTools/scripts/octahedral_protocol' is the path to the protocol scripts that should be used. The directory '/a_path/Atlas', should not exist unless the user wished to provide an existing atlas for use when warping. All progress will be written to the text files in the directory '/a_path/Logs'.

These scripts will work on any Unix variant machine (Unix, Linux, Mac OS X, Irix, Solaris) that is a submit node to a Sun Grid Engine cluster.

Execute in Serial

To execute in serial, the process may be started with the following command:

$ /nethome/users/shapetls/bin/SurfaceWarpTools/scripts/serial/serial_process_all.sh /nethome/users/shapetls/bin/SurfaceWarpTools/scripts/octahedral_protocol /a_path/subjects.list /a_path/Atlas

The directory '/nethome/users/shapetls/bin/SurfaceWarpTools/scripts/octahedral_protocol' is the path to the protocol scripts that should be used. The directory '/a_path/Atlas', should not exist unless the user wished to provide an existing atlas for use when warping. All progress will be written to standard output.

These scripts will work on any Unix variant machine (Unix, Linux, Mac OS X, Irix, Solaris) that supports the bash shell.