Grace User's Guide (v0.2)

by the Grace Team

19.03.1999


This document explains the usage of Grace, a 2D plotting tool for scientific data.

1. Introduction

1.1 What is Grace?

Grace is a tool to make two-dimensional plots of scientific data. It runs under various (if not all) flavours of UNIX with X11 and Motif. 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.

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-95 Paul J Turner, Portland, OR
Copyright (©) 1996-99 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.

1.3 Comments and bug reports

2. Getting started

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...

2.4 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.

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).

Sets

A set is a way of representing numerical data (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).

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.

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.

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

2.5 Command line options

-arrange rows cols

Arrange the graphs in a grid rows by cols

-autoscale x|y|xy

Override any parameter file settings

-batch batch_file

Execute batch_file on start up

-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

-cols gcols

Arrange graphs in gcols columns

-dpipe descriptor

Read data from descriptor (anonymous pipe) on startup

-hdevice hardcopy_device_name

Set default hardcopy device

-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

-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

-logwindow

Open the log window

-maxblock number_of_columns

Set the number of columns for block data (default is 30)

-maxboxes number_of_boxes

Set the number of boxes

-maxellipses number_of_ellipses

Set the number of ellipses

-maxlines number_of_lines

Set the number of lines

-maxstr number_of_strings

Set the number of strings

-mono

Run Grace in monochrome mode (affects the display only)

-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

-nologwindow

No log window, overrides resource setting

-noprint

In batch mode, do not print

-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 the results from regression to results_file

-rows grows

Arrange graphs in grows rows

-rvideo

Exchange the color indices for black and white

-saveall save_file

Save all graphs to save_file

-seed seed_value

Integer seed for random number generator

-source disk|pipe

Source type of next data file

-timer delay

Set timer for named pipes to delay ms

-timestamp

Add timestamp to plot

-settype xy|xydx|...

Set the type of the next data file

-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

2.6 Customization

Environment variables

Init file

Upon start-up, Grace loads its init file, gracerc. The file is searched for in the 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.

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; 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 init file.

X resources

The following Grace-specific X resource settings are supported:

It is also possible to customize menus by assigning key accelerators to any item.

The list below describes the menu X resources. For example, in order to make Grace popup the Non-linear curve fitting by pressing Control+F, you would add the following two lines

XMgrace*transformationsMenu.nonLinearFit.acceleratorText: Ctrl+F
XMgrace*transformationsMenu.nonLinearFit.accelerator: Ctrl<Key>f

to your .Xresources file (the file which is read when an X session starts; it could be .Xdefaults, .Xsession or some other file - ask your system administrator when in doubt).

-> fileMenu
        * open
        * save
        * saveAs
        * describe
        -------------
        -> readMenu
                * sets
                * parameters
                * blockData
        -> writeMenu
                * sets
                * parameters
        -------------
        * clearAll
        -------------
        * print
        * deviceSetup
        -------------
        * workingDirectory
        -------------
        * exit
-> editMenu
        * dataSets
        * setOperations
        -------------
        * arrangeGraphs
        * overlayGraphs
        * autoscale
        -------------
        -> regionsMenu
                * status
                * define
                * clear
                * reportOn
        * hotLinks
        -------------
        * setLocatorFixedPoint
        * clearLocatorFixedPoint
        * locatorProps
        -------------
        * preferences
-> dataMenu
        -> dataSetOperationsMenu
                * Sort
                * reverse
                -------------
                * dropPoints
                * pruneData
                * geometricTransforms
        -> regionOperationsMenu
                * evaluate
                * extractPoints
                * extractSets
                * deletePoints
                * killSets
        -------------
        -> transformationsMenu
                * join
                * split
                * evaluateExpression
                * histograms
                * fourierTransforms
                * regression
                * nonLinearFit
                * runningAverages
                * differences
                * seasonalDifferences
                * integration
                * correlation
                * interpolation
                * splines
                * samplePoints
                * digitalFilter
                * linearConvolution
                * featureExtraction
-> plotMenu
        * plotAppearance
        * graphAppearance
        * setAppearance
        * axisProperties
-> viewMenu
        () showLocatorBar
        () showStatusBar
        () showToolBar
        -------------
        * redraw
-> windowMenu
        * commands
        * pointTracking
        * drawingObjects
        * fontTool
        * results
-> helpMenu
        * onContext
        * userGiude
        * tutorial
        * faq
        * changes
        * comments
        -------------
        * licenseTerms
        * about

3. Xmgr to Grace migration guide

This is a very brief guide describing problems and workarounds for reading in project files saved with Xmgr. You should read the docs or just play with Grace to test new features and controls.

  1. DOCUMENTATION IS VERY SPARSE YET!!!
  2. Grace must be explicitly told the version number of the software used to create a file. You can manually put "@version VERSIONID" string in the beginning of the file. The VERSIONID is built as MAJOR_REV*10000 + MINOR_REV*100 + PATCHLEVEL; so 40101 corresponds to xmgr-4.1.1. Projects saved with Xmgr-4.1.2 do NOT need the above, since they already have the version string in them.
  3. The above relates to the ascii projects only. The old binary projects (saved with xmgr-4.0.*) are not automatically converted anymore. An input filter must be defined to make the conversion work on-the-fly. Add the following line to  /.gracerc or the system-wide $GRACE_HOME/gracerc resource file: DEFINE IFILTER "grconvert %s -" MAGIC "00000031" See docs for more info on the I/O filters.
  4. Grace is WYSIWYG. Xmgr was not. Many changes required to achieve the WYSIWYG'ness led to the situation when graphs with objects carefully aligned under Xmgr may not look so under Grace. Grace tries its best to compensate for the differences, but sometimes you may have to adjust such graphs manually.
  5. Smith plots don't work now. They'll be put back soon.
  6. A lot of symbol types (all except *real* symbols) are removed. "Location *" types can be replaced (with much higher comfort) by A(nnotating)values. "Impulse *", "Histogram *" and "Stair steps *" effects can be achieved using the connecting line parameters (Type, Drop lines). "Dot" symbol is removed as well; use the filled circle symbol of the zero size with no outline to get the same effect.
  7. Default page layout switched from free (allowing to resize canvas with mouse) to fixed. For the old behaviour, put "PAGE LAYOUT FREE" in the Grace resource file or use the "-free" command line switch.
  8. System variables GR_* renamed to GRACE_*

4. Guide to menus and popups

Not written yet... Read Tutorial.

5. Canvas actions

5.1 Hotkeys

When the pointer focus is on the canvas (where the graph is drawn), there are some shortcuts to activate several actions. They are:

5.2 Clicks and double clicks

A single click inside a graph switches focus to that graph. This is the default policy, but it can be changed from the "Edit/Preferences" popup.

Double clicking on parts of the canvas will invoke certain actions or raise some popups:

The double clicking actions can be enabled/disabled from the "Edit/Preferences" popup.

6. Command interpreter

6.1 Definitions

Not written yet...

6.2 Graph properties

Not written yet...

6.3 Set properties

Not written yet...

6.4 Device parameters


Command
Description
PAGE SIZE xdim ydim set page dimensions (in pixels) of terminal device (Display)
DEVICE devname PAGE SIZE xdim ydim set page dimensions (in pixels) of device devname
DEVICE devname DPI dpi set device's dpi (dots per pixel)
DEVICE devname FONT onoff enable/disable usage of built-in fonts for device devname
DEVICE devname FONT ANTIALIASING onoff enable/disable font aliasing for device devname
DEVICE devname OP options set device specific options (see Device-specific settings)
HARDCOPY DEVICE devname set device devname as current hardcopy device
Device parameters.

6.5 Functions and variables

Not written yet...

6.6 Procedures

Not written yet...

7. Advanced topics

7.1 Adding/replacing fonts

7.2 Interaction with other applications

Using pipes

Using grace_np library

7.3 DL modules

8. References

8.1 Typesetting

Grace permits quite complex typesetting on a per string basis. Any string displayed (titles, legends, tick marks,...) may contain special control codes to display subscripts, change fonts within the string etc.


Control code
Description
\f{x} switch to font named "x"
\f{n} switch to font number n (not recommended)
\f{} return to original font
\u begin underline
\U stop underline
\o begin overline
\O stop overline
\c begin using upper 128 characters of set
\C stop using upper 128 characters of set
\z{x} zoom x times
\z{} return to original zoom
\v{x} shift vertically by x
\v{} return to unshifted baseline
\h{x} horizontal shift by x
\m{n} mark current position as n
\M{n} return to saved position n
\dl LtoR substring direction
\dr RtoL substring direction
\dL LtoR text advancing
\dR RtoL text advancing (not implemented yet)
\x switch to Symbol font (same as \f{Symbol})
\+ increase size (same as \z{1.19} ; 1.19 = sqrt(sqrt(2)))
\- decrease size (same as \z{0.84} ; 0.84 = 1/sqrt(sqrt(2)))
\s begin subscripting (same as \v{-0.4}\z{0.71})
\S begin superscripting (same as \v{0.6}\z{0.71})
\N return to normal style (same as \v{}\z{})
\\ print \
Control codes.

Example:

F\sX\N(\xe\f{}) = sin(\xe\B)\c7\Ce\S-X\N\c7\Ccos(\xe\f{})

prints roughly

                       -x
       F (e) = sin(e)·e  ·cos(e)
        x
       

using string's initial font and e prints as epsilon from the Symbol font.

NOTE: Characters from the upper half of the char table can be entered directly from the keyboard, using appropriate xmodmap(1) settings, or with the help of the font tool ("Window/Font tool").

8.2 Device-specific settings

Some of the output devices accept several configuration options. You can set the options by passing a respective string to the interpreter using the "DEVICE devname OP options" command (see Device parameters). A few options can be passed in one command, separated by commas.


Command
Description
grayscale set grayscale output
color set color output
level1 use only PS Level 1 subset of commands
level2 use also PS Level 2 commands if needed
xoffset:x set page offset in X direction x pp
yoffset:y set page offset in Y direction y pp
PostScript driver options


Command
Description
grayscale set grayscale output
color set color output
bbox:tight enable "tight" bounding box
bbox:page bounding box coinsides with page dimensions
EPS driver options


Command
Description
binary set binary output
binary:on same
ascii:off same
ascii set ASCII output
ascii:on same
binary:off same
PDF driver options


Command
Description
interlaced:on make interlaced image
interlaced:off don't make interlaced image
transparent:on produce transparent image
transparent:off don't produce transparent image
GIF driver options


Command
Description
format:pbm output in PBM format
format:pgm output in PGM format
format:ppm output in PPM format
rawbits:on "rawbits" (binary) output
rawbits:off ASCII output
PNM driver options