GENPLOT - By Michael O. Thompson (mot1@cornell.edu)

Introduction

GENPLOT is a generic plotting package that is particularly useful for presenting and analyzing scientific research data. It provides powerful, user friendly graphics capabilities with minimal programming effort. A user may make X-Y graphs (no pie charts allowed - this is for scientists, not managers), plot data and simulation curves, transform the data in various ways, and later spruce up the plots for publication.

GENPLOT is an extremely powerful and flexible plotting package for the analysis of scientific and engineering data. However, this flexibility comes at the cost of complexity, and the program is optimized for power at the expense of the novice computer user. The current expectation in software, fostered by Macintoy and Windoze applications, is that one should be able to sit down at a new program without reading any manual and be immediately productive. This is not the model for GENPLOT. If simple command line prompts bring chills and tingles to your spine, this program is probably not for you. However, even as a novice, you can very successfully use the program if you are willing to invest some time to read the manual, and if you can avoid being intimidated at first by the large set of commands and relatively long learning curve. Eventually, a subset of the commands will become like a second language and the true power and flexibility of this program will be made manifest.

GENPLOT has been written over a number of years at Cornell University with input from numerous people, including Larry Doolittle, Rick Cochran and Mike Heisler. Mike Thompson must, however unfortunately, take responsibility for its current gross and unmanageable size.

Invoking GENPLOT

GENPLOT wakes up to the user with a blank data set of X,Y points. Associated with this X,Y data set are two variables called NPT and NPTMAX. NPT specifies the number of points which are currently valid in the X,Y set while NPTMAX gives the dimensioned size of the X,Y arrays (or the initial maximum value of NPT). This X,Y curve is referred to as the DEFAULT curve and is used by most of the GENPLOT commands unless you specify otherwise. Other curves may also be defined, as discussed later. By definition, a CURVE refers to a collection of real X,Y points and an integer representing the number of points, NPT.

The full format of the GENPLOT initialization is:

GENPLOT [-Buffer <npoints>] [-Inifile <file>] [-Quiet] [-Debug <n>] [-Help]

The initial buffer size may be modified from the default 2048 points using the -buffer option; however, this is seldom necessary since GENPLOT will automatically expand the curve as necessary to accomodate the data. Likewise, an initialization file may be specified using the -ini option; if no file is specified, the program assumes GENPLOT.INI. The -HELP option lists out the format of the GENPLOT command and returns immediately.

Once GENPLOT is running, commands are typed at a GENPLOT: prompt in a pseudo English format. Commands and arguments are taken from the typed command line sequentially. The command processor (see Appendix T) allows multiple commands and arguments to be given on a single command line. There is little difference to GENPLOT if commands are given entirely on a single line or broken into multiple lines; GENPLOT will prompt in each case for the information necessary to continue. For the first time user, it is probably better to let GENPLOT prompt each time for the information until one learns the order of parameters for each command. Like many computer programs, the format of the commands is somewhat strict and arguments are usually required in a specific order. The order of these arguments is considered ``natural'' by the author, but if in doubt the command reference and online help provide the specific format for each command. Some commands also accept optional arguments or modifiers which may be given in any order following all required arguments. 





A. Device Control

Selection and control of devices

This section contains commands which select and control the graphic device.
The DEVICE command is used to select which device you want to use for graphics
output as well as to send special commands to the device driver.  The command
DEVICE LIST will provide a list of the currently configured devices on your
machine.  The list may be modified by editing the DEVICES.DAT file.

Details on each type of device and the physical connection to the hardware are
described in Appendix D of the manual.





B. Basic plotting

Basic commands for plotting

This section contains the basic commands for plotting and overlaying data
sets.  PLOT, OVERLAY and AXIS are the most basic commands for generating
plots once a device is selected.  Using options in PLOT, function and curves
and be drawn as well.  Other commands control the automatic operation of
these commands.





C. Files

Commands to read, write and display data files

GENPLOT internally supports both ASCII unformatted data files and a special
BINARY data format.  Data may exists in multiple columns and may include
expressions as well as numbers.  ASCII refers to a character based format
(i.e. human readable) and not to a particular structure.  See examples under
READ.

In general, the BINARY format is preferrable for large data sets which are
read frequently.  BINARY is substantially (factors of 10-100 times) faster
than ASCII but is limited in the structure.  ASCII is flexible at the expense
of reading speed.  Direct write of BINARY files from other programs is
possible; see the information provided in the manual under data formats.  A
useful alternative is to let GENPLOT read the data as ASCII and then WRITE it
out as BINARY.





D. Linetypes Colors etc

Change the plot line type, color, symbols, etc.

When plotting simple data, either symbols or lines may be chosen to represent
the data points.  There are currently 7 line types, 13 symbols and numerous
colors available to highlight specific data.  These commands select the pen
color, symbol type or line type.  Additional commands control the width of
lines drawn (LINESTYLE), the repeat length of dotted lines (VECSIZE) and the
visibility of lines.





E. Axis control

Commands to control the type and scales on the axes

See also sections covering AUTOERASE and SGRAPH commands





F. Size and Position

Controlling the physical plot size and position
Position and Size Commands for Plot

These commands provide control over placement and size of a plot on the
physical device.  All parameters below may be changed.
                 _______________________________________
                 |                                     |   |
                 |           YMARGIN                   |   |
                 |  X  |-------------------------|     |   |
                 |  M  |                         |     |   Y
                 |  A  |      PLOTTING AREA      |     |   S
                 |  R  |                         |     |   I
                 |  G  |                         |     |   Z
                 |  I  |                         |     |   E
                 |  N  |                         |     |   |
                 |     |-------------------------|     |   |
                 |<-------------- XSIZE -------------->|   |
                 |_____________________________________|   |
    |----XOFF----|     !
                       !YOFF
                       !
    |_ Origin          !





G. Plot information

Get information about the plot and its parameters





H. Data analysis

Creating data sets and analyzing data

This section describes commands which analyze, fit or modify an existing data
set or which create new data sets.  Commands in one category transform or
modify the main curve, such as sorting, exchanging X and Y coordinates, edit
the data set, or impose a fixed grid.  The second sub-division is more complex
and includes the commands to create, transform or fit data.





I. Sprucing up

Enhancing the plot with labels, boxes, arrows and other things





J. Function evaluator

Allocate or set variables and functions

GENPLOT includes an extremely powerful and versatile expression and function
evaluator, allowing the user to transform, scale and analyze data in an
endless variety of ways.  At one level, the expression evaluator is invoked
anytime a number is requested by GENPLOT (including reading data from an ASCII
file).  For example, the REGION command may be given as "REGION BOTTOM @MIN(X)
2*SIN(PI/8)".  Legal expressions may include constants, pre-defined variables
and functions, and user defined variables and functions (including your data).
Allowed mathematical operations include all of the basic algebraic operations,
most of the useful intrinsic functions, and a complete set of relational and
logical operators.

In addition to simple constant evaluation, the function evaluator handles the
allocation of memory for local variables, strings and functions for local use.
Variables and functions are required, for example, to use the non-linear
fitting capability of GENPLOT.  Each of these capabilities are described
below.





K. Macros

Using macro command files
Macros - Files containing prewritten GENPLOT command sequences

A macro is basically a DOS ASCII file which contains a series of GENPLOT
commands, much like a subroutine in a programming language.  Executing the
macro causes GENPLOT to take command input from the file instead of from the
console.  Commands in the macro file behave exactly as the same command typed
at the console.  Macros are often written to perform a particular analysis, or
as building blocks for complex publication plots.  An example of one macro
file is GENPLOT.INI which is used to customize the GENPLOT environment during
initialization.  Any DOS file may be considered a macro file and executed.

Nesting of macros is limited to a maximum depth of 5.  Several commands not
normally used at command level allow parameters to be passed from one macro to
the next and to provide flow control.  Additional commands are provided to
write and save temporary macros from the console (using EMACS is a better
option though).





L. Operating & File System Commands

Commands to interact with the operating system, DOS, UNIX, etc.





M. Miscellaneous

Rest of the commands - no good place to describe these





N. EMACS - Built-in EMACS style text editor






Appendix A: DEFINE - Define a general function or string variable


     Usage:  DEFINE name(arg1,arg2, ...) [=] expression

     Examples: DEFINE F(ARC,ANGLE) = SIN(2*PI*ARC)-COS(ANGLE/180*PI)
               DEFINE G(X) = F(X,X/2)
               DEFINE STRING1 = 'This is a random string'
	       CREATE Y = G(X)*SIN(X/2) FROM -10 TO 10 POINTS 200

DESCRIPTION:
     This command provides the means to write and define almost arbitrary
     functions involving arguments given at evaluation time and any other
     constants known in the system.  The command actually allocates a string
     variable to NAME and sets it equal to EXPRESSION.  The dummy arguments
     in EXPRESSION are replaced with special argument place holders (smiley
     faces and such) which are then replaced evaluation time with the
     appropriate values.

SYNTAX:
     The equal sign is optional, however, spaces must separate it from the
     NAME and EXPRESSION if it is given.  Note that only spaces are recognized
     as delimitors in DEFINE.  EXPRESSION may not contain any spaces unless
     it is enclosed in single quotes.

     DEFINE may also be used simply to allocate and set string variables.  If
     no arguments are given, the string is copied to the variable NAME.  Note
     that evaluation of a STRING variable may result in rubbish.

ERRORS:
     No checking is done as to the validity of the expression at definition
     time.  A definition error occurs only if there is no space left in the
     system to allocate to new variables.  At evaluation time, the function
     will generate errors as any normal expression.

     It is possible to redefine the system intrinsics using DEFINE, such
     as SIN(X).  However, defining SIN(X) = SIN(X/180*PI) to work with
     degrees will fail since will SIN(X) will recursively call itself at
     evaluation time and end up blowing the stack!





Appendix D: Device drivers