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