ACE/gr: Help (draft)


Release notes


Contents


Introduction

ACE/gr is an XY plotting tool for workstations or X-terminals using X. A few of its features are:

While ACE/gr has a convenient point-and-click interface, most parameter settings and operations are available through a command line interface (found in Files/Commands).


Terminology

Sets
Sets are collections of points, with optional associated values at these points. The associated values can be used to display error bars, high-low open-close plots and several other features. Sets are connected to a graph, and, by default, there are 30 sets per graph and each set is numbered from 0 to the maximum number of sets less one. The number of points in a set is limited by the size of virtual memory and are numbered from 1 to N where N is the total number of points in the set. Operations to manipulate sets are found in Data/Set operations, and features such as line styles, symbol types, and others can be changed from Graph/Symbols.
Graphs
Graphs are the collection of data sets, tick marks, titles, etc. drawn to display the data. By default, there are 10 graphs with each graph owning 30 sets (both the number of graphs and the number of sets are adjustable via command line parameters). Operations on graphs are found in the Graphs/Graph operations popup.

There are numerous popups accessible through Graphs pulldown menu that allow the manipulation of graph parameters. Most graph operations work on what is referred to as the `current graph', marked by small filled rectangles at the corners of one graph. The 10 graphs available by default in this version of ACE/gr are numbered from 0 to 9.

Regions
Regions are sections of the graph defined by the interior or exterior of a polygon, or a half plane defined by a line. A region defined by a line can be above, below, to the right, or left of the line. Defining regions and operations on points inside regions are found in Data/Region operations.

Parameters
Parameters are the settings of symbols, line styles, colors, fonts, etc. used to define graphs and the display of the active sets.

Installation

As ACE/gr does not rely on being in a particular directory, installation can be done by simply copying the executable image to some place in the user's path. There is a document, INSTALL, found in the ACE/gr distribution that will describe the installation procedure of the version to be installed. To install grbatch the ACE/gr binary must be symbolically linked or copied to grbatch. There is no grbatch program to speak of, it is simply ACE/gr executed under the name of grbatch.

Contacting the author

For bug reports, comments, etc., send mail to the mailing list

acegr@admin.ogi.edu

As a last resort (don't expect an answer), send mail to

pturner@teleport.com

The home of ACE/gr sources and documentation is ftp.teleport.com in ftp://ftp.teleport.com/pub/users/pturner/acegr.


Using ACE/gr

Execution

The interactive ACE/gr program is called xmgr, if used in batch mode, grbatch. If grbatch is not found, contact your system administrator, or see the section on installation. For grbatch to work properly it is important that it be called grbatch as it is the name that distinguishes xmgr from grbatch. They are the same program, but when executed as grbatch, the X interface is not initialized and grbatch terminates at the end of execution without user intervention.

Please note that grbatch does not read the any X resource files, so that it can be run from dumb terminals and over phone lines. Don't expect resource settings used for xmgr to work for grbatch. See the section on setting defaults using a .xmgrrc file.


Command line parameters

-autoscale x or y or xy
Autoscale the x axis, y axis, or both axes, overiding the settings for axes scaling and tick mark spacing given in any parameter file specified by the -p option.

Example:

xmgr -autoscale x -p params.par data.dat
Reads parameters from params.par and data from data.dat, but overrides any settings for the X axis found in the parameter file.
-noauto y or y or xy
Suppress autoscaling on the given axis (axes). Use this when a data file has imbedded commands that provide axes scaling and tick mark spacing.
-arrange rows columns
Arrange graphs in column major order starting from the lower left corner in a grid rows by columns. For example, -arrange 2 2 will position the first four graphs (0, 1, 2, 3) in a 2x2 matrix of graphs starting with graph 0 in the lower left corner of the plotting surface. This function is not as complete as the similar function found in Graph/Graph operations/Arrange and gives a sightly different result.

Example:

xmgr -arrange 2 2
Creates a 2x2 matrix of graphs.
-rows rows
Arrange the first rows graphs in rows rows.
-cols columns
Arrange the first columns graphs in columns columns.
-results results_file
Write the results of regression and anything else that gets written to the results popup to file results_file.
-device device_number
Set the hardcopy device to device_number. The device numbering follows:

Example:

xmgr -device 2
Sets the hardcopy device to PostScript portrait.
-eps
Tell the PostScript driver to produce EPS.
-printfile graphics_output_file
Write the graphics output to file graphics_output_file rather than spool graphics data to a printer.
-fixed width height
-portrait
-landscape
-free
Set the dimensions of the drawing area. Presently, there is no connection between the hardcopy drivers and these settings. This means that the printer needs to be set to conform to the dimensions of the drawing area.
-batch batch_file
Execute the commands in batch_file on startup. This command line switch is not the same as executing ACE/gr in batch mode as grbatch.

-noask
Assume the answer is yes to all requests, This means that files will be overwritten without asking if they exist, and, if Exit is selected in the GUI, ACE/gr will exit abruptly. This option can be used to overwrite existing files in batch mode. Be careful.

-graph graph_number
Make graph_number the current graph. Graph_number is an integer between 0 and maxgraph-1 (by default maxgraph, the maximum number of graphs, is 10).

For example, to activate four graphs and read data to each graph:

xmgr -arrange 2 2 data0.dat -graph 1 data1.dat -graph 2 data2.dat -graph 3 data3.dat

This command creates 4 graphs arranged in a 2x2 matrix, and reads a file into each graph.

-graphtype graph_type
Set the current graph type to graph_type. Where graph_type is one of:

-type data_set_type
The format of the next data source is data_set_type. Where data_set_type is one of xydx (XY data with error bars along X), xydy (XY data with error bars along Y), xydxdx (XY data with error bars along X of differing values), xydydy (XY data with error bars along Y of differing values), xydxdy (error bars along X and Y), xyr (a circle drawn at XY of radius R) and xyhilo (XY data with high-low open-close data). This setting remains in effect until a new format type is specified.
-ihl IHL_formatted_file
Assume IHL_formatted_file or the next source of data is in IHL format (a local format).

-nxy
The format of the next data source is X1, Y1, Y2, ..., Yn.

-xydx
The format of the next data source is X Y DX

-xydy
The format of the next data source is X Y DY

-xydxdx
The format of the next data source is X Y DX1 DX2

-xydydy
The format of the next data source is X Y DY1 DY2

-xydxdy
The format of the next data source is X Y DX DY

-xyz
The format of the next data source is X Y Z where Z is a value drawn as text at X, Y.

-xyr
The format of the next data source is X Y R, where a circle of radius R is drawn at X, Y.

-xybox
The format of the next data source is XMIN YMIN XMAX YMAX VALUE, where (XMIN, YMIN) is the lower lefthand corner of a rectangle and (XMAX, YMAX) are the upper righthand corner of a rectangle. VALUE is an integer used to specify the color to use to fill the rectangle. To set the fill, use Graph/Symbols and set the fill style to anything but None.
-boxplot
The format of the next data source is X AVG

-ihl
The format of the next data souce is in IHL format, this format leads to a data set of type XY.

-hilo
The format of the next data source is X HIGH LOW OPEN CLOSE, where a symbol denoting the open, close, the high and the low values for an observation is drawn at X.

-netcdf netCDF file
-netcdfxy [xvar or "null"] yvar
Where xvar and yvar are the names of the variables to read. if xvar == "null", then load the index of yvar. These command line options may be used to read variables from a netCDF file. For example:

xmgr -netcdf t.nc -netcdfxy null y

Reads y from t.nc and loads to X the index (starting from 1).

xmgr -netcdf t.nc -netcdfxy x y -netcdfxy x1 y1

Reads x and y from t.nc, then x1 and y1 from the same file. 2 sets are created, both of type XY, one with (x, y), the other composed of (x1, y1). another example reading data from 2 CDF files:

xmgr -netcdf t.nc -netcdfxy x y -netcdf t2.nc -netcdfxy x1 y1

-saveall filename
Write all active sets to filename.

-wd
Set the current working directory. This option can be used to read files from several different directories. For example:

xmgr -wd examples mlo.dat -wd ../moredat brw.d hilo.dat
Unfortunately, this option not allow wild cards, as they are expanded in the current directory only.

-image X_window_dump_file
Read the window dump file X_window_dump_file. The format is the same as generated by xwd or Frame's capture utility.

-imagexy X Y
Set the upper lefthand corner position of the image at screen coordinates (X, Y). Note that screen coordinates have as their origin the upper lefthand corner of the drawing area and positive, increasing Y points down.

-block
Assume the format of the next data file is block data. No sets are formed by reading block data, and only one set of block data is allowed in an active session. To create sets from the block data, use Edit/Block data.

-bxy col1:col2
Create sets from a previously read block data. Using -bxy col1:col2, will create a set using the current set type (default is XY) and using column col1 and column col2 from the most recently read set of block data. Col1 and col2 are integers indicating the numbers of the columns - column numbers start from 1. For example:
  xmgr -block block.d -bxy 1:4 -bxy 2:6
will read block.d and generate 2 sets of type XY using columns 1 and 4 for the first set, and 2 and 6 for the second set.
  xmgr -block block.d -type xydy -bxy 1:3:4
will read block.d and generate a set of type XYDY (an XY set with error bars) using column 1 and 3 for X and Y, and column 4 for the error bars.

-log x or y or xy
Set the current graph type to logarithmic depending the the string x or y or both axes by xy.

-parameter parameter_file
-p parameter_file

Read the parameter file parameter_file.

-pexec parameter_string
Interpret parameter_string as a parameter setting.

-result result_file
Write results from regression to result_file

-rvideo
Exchange the color indices for black and white.

-mono
Limit colors to black and white, affects the display only.

-dc
Allow double click canvas operations, overriding any application default setting.

-nodc
Disallow double click canvas operations.

-redraw
Redraw the entire page if ACE/gr receives an Expose event.

-noredraw
Do not redraw the entire page when Expose events are received.

-maxcolors number_of_colors
Set the maximum number of colors allocated.

-world xmin ymin xmax ymax
Set the scaling of the axes for the current graph. The X axis will run from (xmin, xmax) the Y axis from (ymin, ymax)

-view xmin ymin xmax ymax
Set the viewport of the current graph to a rectangle described by (xmin, ymin) and (xmax, ymax).

-source data_source
Set source for the next data file, the argument takes on the following values:

The source setting stays in effect until the next -source command is given.

-pipe
Read from standard input and plot each set when the end of the set is seen. Use the -pipe option to monitor the results coming from a model or other data stream. The following is an illustrative example:

1974.33 333.1  <- 1st set
1974.42 332.1
&
# the following instructions are needed to scale the plot
# and refresh the screen, the sleep holds the picture a bit..
@autoscale
@redraw
@sleep 1
1974.92 329.6  <- second set
1975 330.6

Save the preceding to 't.d' and execute with:

cat t.d | xmgr -pipe

-remove
Erase the most recently read file. Use this option when using ACE/gr to read a temporarily constructed file that is not needed once read. Note that this option does not request confirmation.

-legend load
For each data set read, make the set legend label the same as the filename the data set originated.

-seed seed_value
Initialize the random number generator using seed seed_value. This value is used in a call to the math library function srand48().

-GXinvert
-GXxor
GXinvert and GXxor set the type of graphics operation used to draw rubberband lines and draw the graph focus markers. In a colormapped display, the xor of a source and destination pixel may not generate a color visible on the drawing area. The default is to use xor to draw rubberband lines, if the lines don't show, try -GXinvert. This draw mode can be set via X resource settings (see below).

-maxplot number_of_sets
Set the maximum number of data sets per graph. Number_of_sets must be greater than 30. If -maxplot is used in conjunction with -maxgraph, then the -maxplot setting must precede the -maxgraph setting.

-maxgraph number_of_graphs
Set the maximum number of graphs per session. Number_of_graphs must be greater than 10. If -maxgraph is used in conjuction with -maxplot, then -maxplot must precede the use of -maxgraph.

-nonl
Activate the Non-linear curve fitting module. WARNING, this module is a prototype and should not be used for analysis.

-digit
Activate the Digitizing module. WARNING, this module is a prototype and should not be used for analysis.

-usage
Display a brief explanation of command line settings

data_files
The files or commands in the case of a pipe from which data are read.

Setting ACE/gr defaults

On startup ACE/gr will look for a .xmgrrc file in the users' home directory allowing changes to the default behavior of ACE/gr. The construction of the ACE/gr default file is the same as for a parameter file.


Setting ACE/gr X defaults The following X resource settings are supported:


Environment variables


pturner@teleport.com