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
- 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).
- 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.
- 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.