# ACE/gr: Help (draft)

## Release notes

- README v 3.01pl6
- FAQ
- TODO

## Contents

- Introduction
  - Terminology
  - Installation
  - Contacting the author
- Using ACE/gr
  - Execution
  - Command line parameters
  - Setting ACE/gr defaults
  - Setting ACE/gr X defaults
  - Environment variables
  - Batch printing
- Guide to menus and popups
  - File
    - Read sets
    - Read netCDF
    - Read HDF
    - Read parameters
    - Read block data
    - Write sets
    - Write parameters
    - Save all
    - Clear all
    - Print
    - Printer setup
    - Command interpreter
    - Status
    - Results
    - Exit
  - Data
    - Status
    - Results
    - Transformations
      - Evaluate expressions
      - Load values
      - Load & evaluate
      - Histogram
      - Fourier
      - Running averages
      - Regression
      - Differences
      - Seasonal differences
      - Integration
      - X/auto-corr
      - Interpolation
      - Splines
      - Sample points
      - Digital filter
      - Linear convolution
      - Geometric transformations
    - Set operations
      - Pick ops
      - Activate
      - De-activate
      - Re-activate
      - Set length
      - Change Set type
      - Copy
      - Move
      - Drop points
      - Join
      - Split
      - Kill
      - Kill all
      - Sort
      - Write set(s)
      - Reverse order
      - Coalesce sets
      - Swap
      - Pack
    - Region operations
      - Define region
      - Evaluate in region
      - Clear region
      - Extract points
      - Delete points
      - Area/perimeter
    - Edit sets
    - Point operations
      - Find points
      - Tracker
      - Delete
      - Add
      - Move
      - Move X only
      - Move Y only
      - Distance, dx, dy, angle
      - Goto
    - Block data
  - Graph
    - Graph operations
      - Activate
      - Copy
      - Swap
      - Kill
      - Focus
      - Show
      - Set graph type
      - Arrange
      - Overlay
      - Invert/flip axes
      - Image
    - World
    - Viewport
    - Autoscale
    - Draw options
    - Title/subtitle
    - Ticks/tick labels
    - Frame
    - Symbols
    - Error bars
    - Legends
    - Strings & Things
    - Flip X-Y
    - Invert X
    - Invert Y
    - Locator
  - Page
    - Free
    - Landscape
    - Portrait
    - Fixed
    - Size
  - View
    - Status bar
    - Tool bar
    - Locator bar
    - Set fixed point
    - Clear fixed point
    - Locator props
  - Main panel items
  - Command interpreter reference and parameter file format
  - Hot keys
    - Hot keys
  - Fonts, subscripts, superscripts
    - Fonts

## Introduction

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

- User defined scaling, tick marks, labels, symbols, line styles, colors.
- Batch mode for unattended plotting.
- Read and write parameters used during a session.
- Linear regression, splines, running averages, DFT/FFT, cross/auto-correlation.
- Hardcopy support for PostScript, HP-GL, and FrameMaker .mif format.

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

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

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:
  - 1 .. PostScript landscape
  - 2 .. PostScript portrait
  - 3 .. FrameMaker .mif landscape
  - 4 .. FrameMaker .mif portrait
  - 5 .. HPGL landscape
  - 6 .. HPGL portrait
  - 7 .. InterLeaf landscape
  - 8 .. InterLeaf portrait

  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.
  - -fixed width height - set the drawing area to have dimensions width and height
  - -portrait - set the drawing area to be 8.5x11 in portrait.
  - -landscape - set the drawing area to be 8.5x11 in portrait.
  - -free - allow the drawing area to be resized (no scrollbars will appear).
-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:

  - xy linear scaling along both x and y.
  - logx linear scaling in y, log scaling in x.,
  - logy linear scaling in x, log scaling in y.
  - logxy log scaling in both x and y.
  - bar vertical bar chart.
  - hbar horizontal bar chart.
  - stackedbar vertical stacked bar chart.
  - stackedhbar horizontal stacked bar chart.
-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:

  - disk - Data file is on disk.
  - pipe - Read from a pipe.
  - stdin - ACE/gr is in a pipe, read from standard input.

  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:

- Xmgr.invertDraw: False

  Use GXinvert to draw rubberband lines and the graph focus markers if this resource is set to True.

- Xmgr.reverseVideo: False

  A boolean resource used to exchange the color indices for black and white.

- Xmgr.maxSets: 30

  Set the number of sets per graph.

- Xmgr.maxGraphs: 10

  Set the number of graphs.

- Xmgr.maxColors: 17

  Set the number of colors allocated. There is no support in the graphical portion of the user interface for more than 16.

- Xmgr.verifyAction: No

  Applies to the Pick set operations and allows an opportunity to accept or cancel any operation performed.

- Xmgr.allowDoubleClick: Yes

  When Yes, allow double clicks on the canvas to bring up various popups depending on the location of the pointer when the double click occurs. Double clicking to the right of a graph brings up the View/Ticks popup set to the Y-axis, below the graph brings up the View/Ticks popup set to the X-axis, inside the graph brings up the files popup if no sets are active or the View/Symbols popup set to the set nearest the pointer. Double clicking above the graph brings up the View/Title-subtitle popup, to the right of the graph, the View/Legend popup.

  The command line option to set this resource is -dc or -nodc.

- Xmgr.autoscaleOnRead: No

  When this resource is Yes or True, allow autoscaling to occur each time a set is read from the File/Read sets popup.

- Xmgr.backingstore: No

  Have ACE/gr handle backing store if the server doesn't.

  The command line option for this is -bs or -nobs.

## Environment variables

- GR_HOME

  Set the location of ACE/gr. This will be where help files, auxillary programs, and examples are located. If you are unable to find the location of this directory, contact your system administrator.

- GR_PS_PRSTR

  Set the command string to use for spooling to a PostScript printer. The default (unless changed during the build process) is "lpr -h".

- GR_MIF_PRSTR

  Set the command string to use for printing the FrameMaker .mif format. The default (unless changed during the build process) is "cat >acegr.mif < ", i.e., output is to a file.

- GR_HPGL_PRSTR

  Set the command string to use for spooling to an HPGL capable printer or plotter.

- GR_HDEV

  Select the hardcopy device.

  The device numbering is as follows:

  - 1. PostScript landscape
  - 2. PostScript portrait
  - 3. FrameMaker interchange format (.mif) landscape
  - 4. FrameMaker interchange format (.mif) portrait.
  - 5. HPGL landscape
  - 6. HPGL portrait
  - 7. Interleaf landscape
  - 8. Interleaf portrait

  ## Batch printing

  Executing ACE/gr as grbatch suppresses the initialization of the graphical user interface and allows hardcopy plots to be made without intervention.

  # Guide to Menus and Popups

  ## File

  Read data from disk or pipes, read variables from netCDF or HDF files, read and write plot parameters, read block data, write one or more ACE/gr datasets, set the current working directory, set the printer options, print (hardcopy), access the command line interpreter, describe the status of data sets, graphs and regions, and display results of computations and other operations.

  ### Read sets

  Read one or more data sets. The list item at the top of the popup displays the contents of the current directory. Select a file or directory by clicking on the item with the right mouse button. The selection is placed in the text item labeled `File:' and checked to see if it is a directory or a file. Selecting a directory causes ACE/gr to change to the new directory and reload the file list with the contents of the new directory. Selecting a file does nothing until the `Accept' button is pressed or is entered. Before `Accept'ing the file, the items describing the file type, file source, and the graph in which to read the data need to be properly set. The type of data file can be one of several formats:

  - A 2 column multi-data set file. Sets are separated by a line containing non-numeric characters, that are neither comment lines (lines with a `#' in column 1) nor parameter lines (lines beginning with an `@'). The sets generated from this file type are all of type XY.

  - A multi column data file. X is assumed to be in the first column, and Y1, Y2, ..., up to Y30 in the remaining columns. The sets generated with this data file format are all of type XY.

  - IHL format. A 3 column data file with the first line an integer value with the number of points to follow.

  - Binary format. - not defined as of this writing.

  - X Y DX format. A 3 column data file consisting of X, Y and a quantity used to form an error bar parallel to the X-axis, i.e., the point will be plotted with an error bar at (X+-DX, Y).

  - X Y DY format. A 3 column data file consisting of X, Y and a quantity used to form an error bar parallel to the Y-axis, i.e., the point will be plotted with an error bar at (X, Y+-DY).

  - X Y DX1 DX2 format. A 4 column data file consisting of X, Y, and the errors in X. The error bar riser is drawn from (X+DX1,Y) to (X-DX2,Y). If both DX1 and DX2 are >0 then the error bar will bracket the datum. If DX2 is <0 and DX1 > 0 the error bars are drawn to the right of the datum. Likewise, if DX1 < 0 and DX2 > 0 the error bar is drawn to the left of the datum.

    There are 4 cases for the error bars' position with respect to the datum:

    - 1. DX1 > 0 and DX2 > 0 ... Error bars bracket the datum.
    - 2. DX1 > 0 and DX2 < 0 ... Error bars are drawn to the right of the datum.
    - 3. DX1 < 0 and DX2 > 0 ... Error bars are drawn to the left of the datum.
    - 4. DX1 < 0 and DX2 < 0 ... Error bars bracket the datum, but reversed from case 1.

  - X Y DY1 DY2 format. A 4 column data file consisting of X, Y, and the errors in Y. The error bar riser is drawn from (X, Y+DY1) to (X, Y-DY2). If both DY1 and DY2 are >0 then the error bar will bracket the datum. If DY2 is <0 and DY1 > 0 the error bars are drawn to the right of the datum. Likewise, if DY1 < 0 and DY2 > 0 the error bar is drawn to the left of the datum. There are 4 cases for the error bars' position with respect to the datum:
    - 1. DY1 > 0 and DY2 > 0 ... Error bars bracket the datum.
    - 2. DY1 > 0 and DY2 < 0 ... Error bars are drawn above the datum.
    - 3. DY1 < 0 and DY2 > 0 ... Error bars are drawn below the datum.
    - 4. DY1 < 0 and DY2 < 0 ... Error bars bracket the datum, but reversed from case 1.
  - X Y DX DY format. A 4 column data file consisting of X, Y, and the errors in X and Y. The error bar risers are drawn from (X+DX, Y) to (X-DX, Y) and (X, Y+DY) to (X, Y-DY).

  - X Y Z format. A 3 column data file consisting of X, Y, Z. Sets with this type are drawn with the Z value in text at (X, Y).

  - X Y R format. A 3 column data file consisting of X, Y, R. Sets with this type are drawn with a circle of radius R at (X, Y).

  - X HI LO OPEN CLOSE format. A 5 column data file consisting of the high, low, open and close values for an observation at X. A data set of this type uses the line style, line width and line color for a normal set when the symbol is drawn.

  Read from: sets the source of the data, either a disk file or a pipe. In the case of a pipe, the information provided by the file filter item is not used, as the `file' in this case will be a command as typed at the UNIX prompt.

  Read to graph: selects a particular graph to serve as the repository for the incoming data. The `Current' graph is the graph that has the focus, and can be any of the available graphs. If you aren't sure which graph is current, the locator item on the main panel displays the current graph number.

  Selecting Autoscale on read: forces an autoscale of the target graph each time a set is read.

  Note: Data are read into the next available set. All data are assumed to be delimited by tabs or blanks.

  For the xy, xydx, xydy, xydxdx, xydydy, xydxdy, xyz, xyr data file formats, sets are separated by a line containing non-numeric characters, that are neither comment lines (lines with a '#' in column 1) nor parameter lines (lines beginning with an `@'). Data files can have imbedded comments by placing a `#' in the first column of the comment line. Plot parameters can be set by placing a `@' in the first column of the line followed immediately by the parameter name and setting. See the command line reference for a description of plot parameters and other commands that may be placed in a data file using the `@' character. Comment lines and parameter lines can occur at any place in the data file, and are not used to indicate data set separators. I recommend a single `&' on a line to use as a data set separator.

  Press Accept to read the data. If the read was successful, the graph of the data is drawn using the current plot scaling parameters. If the data lies outside the current plotting limits, the new set(s) will not be visible until the plotting limits are changed by autoscaling or manually through the View/Define world popup.

  Press Cancel to close the popup.

  Open the Status popup to get information on the state of sets. If reading the file generates more than 10 errors you'll be prompted by an alert requesting whether or not you'd like to continue. These errors generally arise when an attempt is made to read a text file - ACE/gr relies on the interpretive capabilities of sscanf() to parse the data. ACE/gr will read data sets until there are no more sets available, after the maximum number of sets have been used, you'll need to free some sets using the [Kill] or [Kill all] items in the Edit/Set operations pullright.

  ### Read netCDF

  File/Read netCDF

  Select X: Select Y:

  netCDF file:

  Load to set:

  Autoscale on read

  Accept Files... Update Query Done

  ---------------------------------------

  Enter the name of the netCDF file in the text item labelled netCDF file: then click on "Update" (note that if -netcdf [filename] was used on the command line, this step is not needed, as the lists will be loaded automatically). This will read the names of all one dimensional variables into the two scrolled lists. The leftmost list is for X and the rightmost for Y. There is an additional item in the X list called INDEX (I'm hoping here that no one names a variable INDEX, maybe I need to change this) that indicates that for X, use the index of the Y variable (numbering starts from 1).

  Select on a variable from the X list to use for X and select a variable from the Y list (only single selections for now).

  If information about the selected variables is desired, click on Query.

  Select a set using "Load to set:" - the default is to load to the next available set.

  If things look OK, click on Accept to read the data and load the set. Use "Autoscale on read" to set/unset autoscaling after a successful read.

  To read data from a new CDF file, enter the filename, or use File... to scan the directory. Click on Update to freshenup the X and Y selection lists.

  Note: Presently, only sets of type XY are created.

  Note: ACE/gr scans and replaces commas with blanks and the `D' in Fortran double precision exponential formats with `e'.

  ### Read parameters

  Enter the parameter file name on the line labeled "File:", press "Accept" to read a saved state of adjustable parameters, legends, strings, etc, to the graph selected by the `Read to graph' cycle. As the graph number is saved in the parameter file this isn't used at the present time.

  ### Read block data

  Select the data source, either Disk or Pipe and enter the block data file name in the text item labeled "File:" to read a data set in block data file format. The block data file format consists of columns of data. For example, the following is a block data file consisting of 4 columns:

          1   2   3   4   5
          6   7   8   9  10
          11 12  13  14  15

  After reading the file of block data, the popup will close if no errors were found, and the Edit/Block data popup will take its place. Use the functions in the Edit/Block data popup to create sets from the block data.

  NOTE: All items are assumed delimited by spaces or tabs. There is presently a 30 column limit. Only one set of block data per session, i.e., reading another set of block data will obliterate the previous set of block data.

  ### Write sets

  Write one or all sets to disk. Select the set to write using the cycle displaying the set numbers (there is an item for selecting all active sets). The item denoted "Format" is the C language format string that will be used to format the data for output - the default should work well for most cases. Enter the file name on the line labeled "File:" and press the button marked [Accept], to write the data. The item, `Imbed parameters,' causes ACE/gr to write not only the data, but the parameters describing the graph or graphs as well.

  A complete dump of the contents of ACE/gr may be accomplished by selecting all sets, imbed parameters, and all active graphs. The file generated this way can then be read as a normal data file, and should recreate the originating environment.

  ### Write parameters

  Select the graph from which to save the parameters. This can be the current graph, any particular graph, or all active graphs. Enter the parameter file name on the line labeled "Write parameters to", press "Accept" to write the current state of adjustable parameters, legends, strings, etc. A prompt will appear if the action would overwrite an existing file. allowing the operation to be cancelled.

  ### Save all

  Perform a `Write sets' using all active sets, all active graphs, and imbed parameters. Use this to save the current session.

  ### Clear all

  Kill all sets, graphs, and annotative text, lines, and boxes. After performing this action, it will be necessary to activate a graph using View/Graphs/Activate graphs.

  ### Print

  Generate a hardcopy of the current plot on the device specified in the File/Printer setup popup.

  ### Printer setup

  Set the hardcopy device parameters. Select the device, where to print (either the printer or a file), and the string to use as a spooling command for the print job, or file name if output is directed to disk. Click on the `Accept' button to make the selections above current, or `Done' to close the popup and cancel the operation. If the selection is accepted, the next time File/Print is selected, hardcopy output will be to the selected device. Click on the `Print' button to accept the settings and print a hardcopy.

  ### Command interpreter

  Command driven version of the interface to ACE/gr. Here, commands are typed at the `Command:' text item and executed when is entered. The command will be parsed and executed, and if no errors are found, the command line is placed in the history list. Items in the history list can be recalled by simply clicking on them with the left mouse button. Save a history list by clicking on the `Save...' button popping up the `Save commands' popup. Clicking on `Read...' will open the `Read commands' popup and allows previously stored commands to be loaded into the history list for future access. `Clear' empties the history list. `Replay' cycles through each item in the history list and executes each instruction in the list. See the command line reference for a description of the command line syntax.

  ### Results

  Display the results of the regression routine and the output of the `Write' button in File/ Status in the monitor window.

  ### Exit

  Click on the Exit button to terminate the session with ACE/gr.

  ## Block data

  Create sets from block data. Select the type of set and the columns to use for each vector of the new set. Press Accept to create the set. Note that reading block data does not affect the scaling of the graph so when a set is created using this popup, the set may not appear within the graph's scaling limits - use AS (Autoscale) to set the scale of the graph if needed (or use View/Define world).

  ## Hot keys

  When the mouse is on the canvas (where the graph is drawn), there are some shortcuts that can be taken to bring up several popups. They are:

  - ^A - autoscale plot
  - ^B - draw a box (using the current settings for boxes)
  - ^D - delete an object (string, line, or box)
  - ^N - move an object (string, line, or box)
  - ^P - draw a line (using the current settings for lines)
  - ^V - set the viewport with the mouse
  - ^W - write a string (using the current settings for strings)
  - ^X - exit ACE/gr
  - ^Z - enable zoom

  ## Fonts

  ### Changing fonts within a string

  To change fonts within a string preceed the font number listed below by a backslash. To turn subscripting or superscripting on or off use \s for subscripts and \S for superscripting. Font selection is current for the remainder of the string or until the next font change. Subscripts and superscripts remain for the remainder of the string or until \N is seen. To print a backslash use \\. To backspace use \b. To begin underlining use \u, to stop underlining use \U. \+ increases the size of the characters and \- decreases the size of the characters.

  ACE/gr uses the Hershey fonts to draw text on the screen, but PostScript fonts for hardcopy. There are discrepancies between the two sets of fonts and of this writing, there are problems with the mapping of Greek and special characters.

  Font # Font

  - 0 .... Complex Roman on screen, maps to Times-Roman.
  - 1 .... Triplex Roman on screen, maps to Times-Bold.
  - 2 .... Complex Italic on screen, maps to Times-Italic.
  - 3 .... Triplex Italic on screen, maps to Times-BoldItalic.
  - 4 .... Simplex on screen, maps to Helvetica.
  - 5 .... Duplex on screen, maps to Helvetica-Bold
  - 6 .... Complex Italic on screen, maps to Helvetica-Oblique.
  - 7 .... Triplex Italic on screen, maps to Helvetica-BoldOblique.
  - 8 .... Simplex Greek on screen, maps to the lower 128 characters of the Symbol font.
  - 9 .... Symbols on screen, maps to the upper 128 characters of the Symbol font.
  - x .... Special symbols

  Summary of other special commands

  - + .... increase size
  - - .... decrease size
  - b .... backspace length of previous character
  - s .... begin subscripting
  - S .... begin superscripting
  - u .... begin underline
  - U .... stop underline
  - N .... return to normal

  Example:

  \0F\sX\N(\8e\0) = sin(\8e\0)*e\S(-X)\N*cos(\8e\0)

  prints roughly FX(e) = sin(e)*e -X*cos(e)

  using font 0 and e prints as epsilon from the Simplex Greek font.

  NOTE: Special characters are mapped to the keyboard, the present mapping is not very well organized and may change.