Grace User's Guide (for Grace-5.1.22)

by the Grace Team

20.05.2008
This document explains the usage of Grace, a WYSIWYG 2D plotting tool for numerical data. (A German translation of this document, made by Tobias Brinkert, is available here: Grace Benutzerhandbuch.)

1. Introduction

2. Installation guide

3. Getting started

4. Guide to the graphical user interface

5. Command interpreter

6. Advanced topics

7. References

1. Introduction

1.1 What is Grace?

Grace is a WYSIWYG tool to make two-dimensional plots of numerical data. It runs under various (if not all) flavors of Unix with X11 and M*tif (LessTif or Motif). It also runs under VMS, OS/2, and Windows (95/98/NT/2000/XP). Its capabilities are roughly similar to GUI-based programs like Sigmaplot or Microcal Origin plus script-based tools like Gnuplot or Genplot. Its strength lies in the fact that it combines the convenience of a graphical user interface with the power of a scripting language which enables it to do sophisticated calculations or perform automated tasks.

Grace is derived from Xmgr (a.k.a. ACE/gr), originally written by Paul Turner.

From version number 4.00, the development was taken over by a team of volunteers under the coordination of Evgeny Stambulchik. You can get the newest information about Grace and download the latest version at the Grace home page.

When its copyright was changed to GPL, the name was changed to Grace, which stands for ``GRaphing, Advanced Computation and Exploration of data'' or ``Grace Revamps ACE/gr''. The first version of Grace available is named 5.0.0, while the last public version of Xmgr has the version number 4.1.2.

Paul still maintains and develops a non-public version of Xmgr for internal use.

1.2 Copyright statement 

Copyright (©) 1991-1995 Paul J Turner, Portland, OR
Copyright (©) 1996-2007 Grace Development Team

Maintained by Evgeny Stambulchik


                         All Rights Reserved

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

For certain libraries required to build Grace (which are therefore even included in a suitable version) there may be different Copyright/License statements. Though their License may by chance match the one used for Grace, the Grace Copyright holders can not influence or change them.


Package License
cephes library Free
T1lib LGPL
Xbae BSD-like
Tab Widget BSD-like
Licenses

2. Installation guide

2.1 Installing from sources

  1. Configuration
  2. Compilation
  3. Testing
  4. Installation

2.2 Binary installation

  1. Getting pre-built packages
  2. Installation
  3. Running tests

2.3 Alternative packaging schemes (RPM, ...)

Not written yet...

3. Getting started

For a jump-in start, you can browse the demos ("Help/Examples" menu tree). These are ordinary Grace projects, so you can play with them and modify them. Also, read the Tutorial.

O.k. Here's a VERY quick introduction:

  1. Start the GUI version: xmgrace (return).
  2. Select/check the output medium and canvas size in File/Device Setup.
  3. If needed, set the graph size ('Viewport' in Plot/Graph Appearance).
  4. Load your data with Data/Import/ASCII. 'Load as': 'Single set' for two-column ASCII data, 'Block data' for multi-column ASCII data.
  5. Adjust the scales, axis labels and tick marks in Plot/Axis properties. Acknowledge all changes with 'Apply'.
  6. Adjust lines, symbols, legends in Plot/Set appearance.
  7. Adjust titles, plot frame and legend display in Plot/Graph Appearance.
  8. Data can be manipulated in Data/Transformations. To shift a data set by 20 to the left, e.g., in 'Evaluate Expression' select the same set on the left and the right, and say Formula: y=y-20. As you'll probably notice, Grace can do MUCH more than that. Explore at your leisure.
  9. When you like your plot, select File/Print. That's it!

3.1 General concepts

Project files

A project file contains all information necessary to restore a plot created by Grace, as well as some of preferences. Each plot is represented on a single page, but may have an unlimited number of graphs.You create a project file of your current graph with File/Save,Save as.

Parameter files

A parameter file contains the detailed settings of your project. It can be used to transfer these settings to a different plot/project. You generate a parameter file with File/Save menu entry selected from the "Plot/Graph appearance popup". You can load the settings contained in a parameter file with File/Open.

Input file formats

Grace understands several input files formats. The most basic one is ASCII text files containing space and comma separated columns of data. The data fields can be either numeric (Fortran 'd' and 'D' exponent markers are also supported) or alphanumeric (with or without quotes). Several calendar date formats are recognized automatically and you can specify your own reference for numeric date formats. Lines beginnig with "#" are ignored. Blank lines indicate new dataset. Grace also has a command language (see command interpreter), you can include commands in data files using lines having "@" as their first non-blank character, though this is not recommended. Depending on configuration, Grace can also read NetCDF files (see configuration).

Graphs

A graph consists of (every element is optional): a graph frame, axes, a title and a subtitle, a number of sets and additional annotative objects (time stamp string, text strings, lines, boxes and ellipses).

The graph type can be any of:

The idea of "XY Chart" is to plot bars (or symbols in general) of several sets side by side, assuming the abscissas of all the sets are the same (or subsets of the longest set).

Datasets

A dataset is a collection of points with x and y coordinates, up to four optional data values (which, depending on the set type, can be displayed as error bars or like) and one optional character string.

Sets

A set is a way of representing datasets. It consists of a pointer to a dataset plus a collection of parameters describing the visual appearance of the data (like color, line dash pattern etc).

The set type can be any of the following:


Set type # of num. cols Description
XY 2 An X-Y scatter and/or line plot, plus (optionally) an annotated value
XYDX 3 Same as XY, but with error bars (either one- or two-sided) along X axis
XYDY 3 Same as XYDX, but error bars are along Y axis
XYDXDX 4 Same as XYDX, but left and right error bars are defined separately
XYDYDY 4 Same as XYDXDX, but error bars are along Y axis
XYDXDY 4 Same as XY, but with X and Y error bars (either one- or two-sided)
XYDXDXDYDY 6 Same as XYDXDY, but left/right and upper/lower error bars are defined separately
BAR 2 Same as XY, but vertical bars are used instead of symbols
BARDY 3 Same as BAR, but with error bars (either one- or two-sided) along Y axis
BARDYDY 4 Same as BARDY, but lower and upper error bars are defined separately
XYHILO 5 Hi/Low/Open/Close plot
XYZ 3 Same as XY; makes no sense unless the annotated value is Z
XYR 3 X, Y, Radius. Only allowed in Fixed graphs
XYSIZE 3 Same as XY, but symbol size is variable
XYCOLOR 3 X, Y, color index (of the symbol fill)
XYCOLPAT 4 X, Y, color index, pattern index (currently used for Pie charts only)
XYVMAP 4 Vector map
XYBOXPLOT 6 Box plot (X, median, upper/lower limit, upper/lower whisker)
Set types

Not all set types, however, can be plotted on any graph type. The following table summarizes it:


Set type XY Graph XY Chart Fixed Polar Pie
XY + + + + +
XYDX + - + - -
XYDY + + + - -
XYDXDX + - + - -
XYDYDY + + + - -
XYDXDY + - + - -
XYDXDXDYDY + - + - -
BAR + + + - -
BARDY + + - - -
BARDYDY + + - - -
XYHILO + - - - -
XYZ + - + + -
XYR - - + - -
XYSIZE + + + + -
XYCOLOR + + + + +
XYCOLPAT - - - - +
XYVMAP + - + - -
XYBOXPLOT + - - - -
Graph/Set type connection

Regions

Regions are sections of the graph defined by the interior or exterior of a polygon, or a half plane defined by a line. Regions are used to restrict data transformations to a geometric area occupied by region.

Real Time Input

Real Time Input refers to the ability Grace has to be fed in real time by an external program. The Grace process spawned by the driver program is a full featured Grace process: the user can interact using the GUI at the same time the program sends data and commands. The process will adapt itself to the incoming data rate.

Hotlinks

Hotlinks are sources containing varying data. Grace can be instructed a file or a pipe is a hotlink in which case it will provide specific commands to refresh the data on a mouse click (a later version will probably allow automatic refresh).

Devices

Grace allows the user to choose between several output devices to produce its graphics. The current list of supported devices is:

Note that Grace no longer supports GIF due to the copyright policy of Unisys. Grace can also be instructed to launch conversion programs automatically based on file name. As an example you can produce MIF (FrameMaker Interchange Format) or Java applets using pstoedit, or almost any image format using the netpbm suite (see the FAQ).

Magic path

In many cases, when Grace needs to access a file given with a relative pathname, it searches for the file along the following path: ./pathname:./.grace/pathname:~/.grace/pathname:$GRACE_HOME/pathname

Dynamic modules

Grace can access external functions present in either system or third-party shared libraries or modules specially compiled for use with it. The term dynamic refers to the possibility Grace has to open the library at run time to find the code of the external function, there is no need to recompile Grace itself (the functions already compiled in Grace are "statically linked").

Coordinate frames

There are two types of coordinates in Grace: the world coordinates and the viewport coordinates. Points of data sets are defined in the world coordinates. The viewport coordinates correspond to the image of the plot drawn on the canvas (or printed on, say, PS output page). The transformation converting the world coordinates into the viewport ones is determined by both the graph type and the axis scaling.

Actually, there is yet another level in the hierarchy of coordinates - the device coordinates. However, you (as a user of Grace) should not worry about the latter. The mapping between the viewport coordinates and the device coordinates is always set in such a way that the origin of the viewport corresponds to the left bottom corner of the device page, the smallest of the device dimensions corresponds to one unit in the viewport coordinates. Oh, and the most important thing about the viewport -> device transformation is that it is homotetic, i.e. a square is guaranteed to remain a square, not a rectangle, a circle remains a circle (not an ellipse) etc.

3.2 Invocation

Operational mode

With respect to the user interface, there are three modes of operation that Grace can be invoked in. The full-featured GUI-based version is called xmgrace. A batch-printing version is called gracebat. A command-line interface mode is called grace. Usually, a single executable is called in all cases, with two of the three files being (symbolic) links to a "real" one.

Command line options

-autoscale x|y|xy

Override any parameter file settings

-barebones

Turn off all toolbars

-batch batch_file

Execute batch_file on start up (i.e., after all other options have been processed and the UI initialized)

-block block_data

Assume data file is block data

-bxy x:y:etc.

Form a set from the current block data set using the current set type from columns given in the argument

-datehint iso|european|us|days|seconds|nohint

Set the hint for dates analysis

-dpipe descriptor

Read data from descriptor (anonymous pipe) on startup

-fixed width height

Set canvas size fixed to width*height

-free

Use free page layout

-graph graph_number

Set the current graph number

-graphtype graph_type

Set the type of the current graph

-hardcopy

No interactive session, just print and quit

-hdevice hardcopy_device_name

Set default hardcopy device

-install

Install private colormap

-legend load

Turn the graph legend on

-log x|y|xy

Set the axis scaling of the current graph to logarithmic

-maxpath length

Set the maximal drawing path length

-mono

Run Grace in monochrome mode (affects the display only)

-netcdf file

Assume data file is in netCDF format. This option is present only if the netCDF support was compiled in

-netcdfxy X_var Y_var

If -netcdf was used previously, read from the netCDF file X_var Y_var variables and create a set. If X_var name is "null" then load the index of Y to X. This option is present only if the netCDF support was compiled in

-noask

Assume the answer is yes to all requests - if the operation would overwrite a file, Grace will do so without prompting

-noinstall

Don't use private colormap

-noprint

In batch mode, do not print

-nosafe

Disable safe mode

-nosigcatch

Don't catch signals

-npipe file

Read data from named pipe on startup

-nxy nxy_file

Assume data file is in X Y1 Y2 Y3 ... format

-param parameter_file

Load parameters from parameter_file to the current graph

-pexec parameter_string

Interpret string as a parameter setting

-pipe

Read data from stdin on startup

-printfile

file Save print output to file

-remove

Remove data file after read

-results results_file

Write results of some data manipulations to results_file

-rvideo

Exchange the color indices for black and white

-safe

Run in the safe mode (default) - no file system modifications are allowd through the batch language

-saveall save_file

Save all graphs to save_file

-seed seed_value

Integer seed for random number generator

-settype xy|xydx|...

Set the type of the next data file

-source disk|pipe

Source type of next data file

-timer delay

Set allowed time slice for real time inputs to delay ms

-timestamp

Add timestamp to plot

-version

Show the program version

-viewport xmin ymin xmax ymax

Set the viewport for the current graph

-wd directory

Set the working directory

-world xmin ymin xmax ymax

Set the world coordinates for the current graph

-usage|-help

This message

3.3 Customization

Environment variables

Init file

Upon start-up, Grace loads its init file, gracerc. The file is searched for in the magic path (see magic path); once found, the rest of the path is ignored. It's recommended that in the gracerc file, one doesn't use statements which are part of a project file - such defaults, if needed, should be set in the default template (see default template).

Default template

Whenever a new project is started, Grace loads the default template, templates/Default.agr. The file is searched for in the magic path (see magic path); once found, the rest of the path is ignored. It's recommended that in the default template, one doesn't use statements which are NOT part of a project file - such defaults, if needed, should be set in the gracerc (see init file).

X resources

The following Grace-specific X resource settings are supported: