GRF - Generalized rotational fit methods
Version 1.0
12 September 1991
F. James Rohlf ()
and
Dennis Slice (dslice@life.bio.sunysb.edu)
While the program is copyrighted, you may freely distribute it to others
for research and educational purposes.
-------------------------------------------------------------------------
HOW TO USE THE GRF PROGRAM
The program is easy to use so that this README.GRF
file should be sufficient. For technical details about the
algorithms used, consult:
Rohlf and Slice 1990. Extensions of the Procrustes method for the
optimal superimposition of landmarks. Syst. Zoology, 39:40-59.
That paper also includes illustrations of the output produced
by GRF and suggestions for its interpretation.
There is no install procedure -- just copy all of the files to your
working disk. You will need one of the *.BGI files (corresponding to
whatever type of graphics monitor you have) and the *.CHR files to plot
the labels in graphics mode.
Type "GRF" to run the program. The use of the program is
fairly obvious. Press the F1 function key for "help" about what
the options mean (the help window for the main menu also will
display the maximum number of objects and landmarks that
the program can handle at present).
To use the program you should first select the Files window
(where you can specify the name of the input data file). Then go
to the Load window to actually load the data into the computer.
Next, you can go directly to the Run window or else go to the
Toggles window first to set some options. After the Run window
you normally will go to the Plot window in order to see the
results.
When in the Plot program a mouse cursor will be displayed if
have a mouse and the mouse driver program has been loaded before
you started the GRF program. You can then click the left mouse
button on an upper left corner and then the lower right corner of
a box around a region of interest. That area will then be zoomed
up to full screen. Press the right mouse button or any key on
the keyboard to exit. The vectors for each object are plotted in
different colors to help you identify which is which. There are
15 colors available and they are used in the following order:
Blue = 1
Green = 2
Cyan = 3
Red = 4
Magenta = 5
Brown = 6
LightGray = 7
DarkGray = 8
LightBlue = 9
LightGreen = 10
LightCyan = 11
LightRed = 12
LightMagenta = 13
Yellow = 14
White = 15
If there are more than 15 objects, then the colors are "recycled".
That is, object 16 is colored blue, etc. Note that the
reference object is not plotted. Its location is shown by the
origin of the vectors.
The Groups window will allow you to specify how many groups of
objects there are and how many objects belong to each group.
Each group must consist of sequence of consecutive objects in
the input file. Note: the specification of groups only
affects the output display. This information is not used as
part of the fitting process. At present a maximum of 11 groups
can be used.
The Toggles window will allow you to set (or unset) various
options. Move the cursor to an option and then press the Enter
key to change a "+" to a "-" (or vice versa). This is where you
specify whether or not affine transformations are to be used.
The "plot outlines" option assumes the landmarks represent points
along an outline. If this option is selected, then a line will
be drawn from landmark 1 to landmark 2 to landmark 3 etc.
The affine toggle does not take effect until you RUN some
analysis after it is set.
Most of the options are provided to give you some control over
the format of the plots. Press the F2 key to exit with the
changes you may have made. Press the Esc key to exit with no
changes in the options.
DATA FILES
The format of the input data files is quite simple. Each file
consists of n X,Y-coordinate pairs for n landmarks recorded for t
objects. Each object's coordinates is preceded by a line with an
object label beginning in column 1. It must not contain blanks.
It is followed on the same line with at least one blank space and
then the integer n. Its X,Y-coordinates begin on the next line.
They may be entered all on one line or with each X,Y pair on a
line by itself. The input is free format. In addition, the label
line for the first object must also contain t, the number of
objects.
Example: 3 objects with 6 landmarks each (part of the T3 dataset).
TRI1 6 3
-200.00 0.00
200.00 0.00
0.00 200.00
400.00 400.00
-400.00 400.00
0.00 -400.00
T2 6
-707.00 -357.00
-1126.00 65.00
-1171.00 -305.00
-1731.00 50.00
-1147.00 -1012.00
-384.00 72.00
T3 6
726.00 -671.00
1088.00 -422.00
799.00 -365.00
1067.00 -12.00
346.00 -452.00
1193.00 -836.00
Several sample files are included on the distribution disk.
Consult them for examples of the format for the data. File T3
consists of 2 groups of short and long-nosed wedges. It is useful
for comparison of least squares versus resistant fit. The
LIN1.DTA etc. files are useful for seeing the effects of uniform
shape change and how the use of affine transformations can align
the objects. Again you can compare least squares with resistant
fit. We think you will agree that the resistant fit method is to
be preferred (unless you are concerned with computer time). The
MOSQ.DTA is a real dataset.
Plotting a single object
While the program was not intended for such an application, you
can read in a file with only a single object in it. If you
RUN the generalized least-squares option you can then run the
PLOT plot program to plot this single object. You can also
set the plot outlines option first so that the landmarks will
be connected by a line.
Special Note: Affine Resistant Fitting
Affine resistant fitting examines triplets of landmarks to determine
the uniform shape change parameters to be applied to the entire
configuration. The number of all possible landmark triplets increases
rapidly with the number of landmarks, and examining all of them can
appreciably slow program execution. Because of this, you are asked to
specify an 'ACCURACY LEVEL' ranging from 1 to 3 to limit the number of
triplets examined by the program. At the lowest level, two
intermediately situated landmarks are selected and parameters estimated
from only those triplets of landmarks including both points. At level
2, more triplets are examined, and at level 3, all sets of three
landmarks are used. The first level is suggested for program testing or
rapid data examination. Actual analysis should use the highest level.
Finally, we have found the convergence of GARF to be quite good, but we
know of at least one data set that after many iterations appeared to
have 'collapsed'. That is repeated iterations led to extreme flattening
of the objects. We are currently working on new scaling procedures to
detect and prevent this occurrence, but until these are ready we advise
that if convergence requires many iterations or there ceases to be a
monotonic decrease in the convergence criterion that you redo the
analysis and interrupt the fitting by pressing any key at some iteration
before the point where the instability was observed.
--------------------------------------------------------------------
PROBLEMS?
Please let us know if you have trouble using the program or if
you find data for which the methods do not seem to work well.
This is a preliminary version. It is still at the "research level" and
the algorithms are subject to change.
F. James Rohlf & Dennis Slice
Department of Ecology and Evolution
State University of New York
Stony Brook, NY 11794-5245
631-632-8580