Grace User's Guide (v0.3)

by the Grace Team

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

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.

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

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

-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 allowed time slice for real time inputs 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

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

4. Guide to menus and popups

Not written yet... Read the 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

The grace_np library is a set of compiled functions that allows you to launch and drive a Grace subprocess from your C or Fortran application. Functions are provided to start the subprocess, to send it commands or data, to stop it or detach from it.


Function
Arguments Description
int GraceOpen (int buf_size) launch a Grace subprocess and open a communication channel with it
int GraceIsOpen (void) test if a Grace subprocess is currently connected
int GraceClose (void) close the communication channel and exit the Grace subprocess
int GraceClosePipe (void) close the communication channel and leave the Grace subprocess alone
int GraceFlush (void) flush all the data remaining in the buffer
int GracePrintf (const char* format, ...) format a command and send it to the Grace subprocess
int GraceCommand (const char* cmd) send an already formated command to the Grace subprocess
GraceErrorFunctionType
GraceRegisterErrorFunction
(GraceErrorFunctionType f) register a user function f to display library errors
grace_np library C functions.


Function
Arguments Description
integer GraceOpenF (integer buf_size) launch a Grace subprocess and open a communication channel with it
integer GraceIsOpenF (void) test if a Grace subprocess is currently connected
integer GraceCloseF (void) close the communication channel and exit the Grace subprocess
integer GraceClosePipeF (void) close the communication channel and leave the Grace subprocess alone
integer GraceFlushF (void) flush all the data remaining in the buffer
integer GraceCommandF (character*(*) cmd) send an already formatted command to the Grace subprocess
GraceFortranFunctionType
GraceRegisterErrorFunctionF
(GraceFortranFunctionType f) register a user function f to display library errors
grace_np library F77 functions.

There is no fortran equivalent for the GracePrintf function, you should format all the data and commands yourself before sending them with GraceCommandF.

The Grace subprocess listen for the commands you send and interpret them as if they were given in a batch file. You can send any command you like (redraw, autoscale, ...). If you want to send data, you should include them in a command like "g0.s0 point 3.5 4.2".

Apart from the fact it monitors the data sent via the anonymous pipe, the Grace subprocess is a normal process. You can interact with it through the GUI. Note that no error can be sent back to the parent process. If your application send erroneous commands, an error popup will be displayed by the subprocess.

If you exit the subprocess while the parent process is still using it, the broken pipe will be detected. An error code will be returned to every further call to the library (but you can still start a new process if you want to manage this situation).

Here is an example use of the library, you will find this program in the distribution.

#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include "grace_np.h"

#ifndef EXIT_SUCCESS
#  define EXIT_SUCCESS 0
#endif

#ifndef EXIT_FAILURE
#  define EXIT_FAILURE -1
#endif

void my_error_function(const char *msg)
{
    fprintf(stderr, "library message : \"%s\"\n", msg);
}

int
main (int argc, char* argv[])
{
    int i;

    GraceRegisterErrorFunction (my_error_function);

    /* Start Grace with a buffer size of 2048 and open the pipe */
    if (GraceOpen(2048) == -1) {
        fprintf (stderr, "Can't run Grace. \n");
        exit (EXIT_FAILURE);
    }
    
    /* Send some initialization commands to Grace */
    GracePrintf ("world xmax 100");
    GracePrintf ("world ymax 10000");
    GracePrintf ("xaxis tick major 20");
    GracePrintf ("xaxis tick minor 10");
    GracePrintf ("yaxis tick major 2000");
    GracePrintf ("yaxis tick minor 1000");
    GracePrintf ("s0 on");
    GracePrintf ("s0 symbol 1");
    GracePrintf ("s0 symbol size 0.3");
    GracePrintf ("s0 symbol fill pattern 1");
    GracePrintf ("s1 on");
    GracePrintf ("s1 symbol 1");
    GracePrintf ("s1 symbol size 0.3");
    GracePrintf ("s1 symbol fill pattern 1");

    /* Display sample data */
    for (i = 1; i <= 100 && GraceIsOpen(); i++) {
        GracePrintf ("g0.s0 point %d, %d", i, i);
        GracePrintf ("g0.s1 point %d, %d", i, i * i);
        /* Update the Grace display after every ten steps */
        if (i % 10 == 0) {
            GracePrintf ("redraw");
            /* Wait a second, just to simulate some time needed for
               calculations. Your real application shouldn't wait. */
            sleep (1);
        }
    }

    if (GraceIsOpen()) {
        /* Tell Grace to save the data */
        GracePrintf ("saveall \"sample.agr\"");

        /* Flush the output buffer and close Grace */
        GraceClose();

        /* We are done */
        exit (EXIT_SUCCESS);
    } else {
        exit (EXIT_FAILURE);
    }

}

7.3 FFTW tuning

When the FFTW capabilities are compiled in, Grace looks at two environment variables to decide what to do with the FFTW 'wisdom' capabilities. First, a quick summary of what this is. The FFTW package is capable of adaptively determining the most efficient factorization of a set to give the fastest computation. It can store these factorizations as 'wisdom', so that if a transform of a given size is to be repeated, it is does not have to re-adapt. The good news is that this seems to work very well. The bad news is that, the first time a transform of a given size is computed, if it is not a submultiple of one already known, it takes a LONG time (seconds to minutes).

The first environment variable is GRACE_FFTW_WISDOM_FILE. If this is set to the name of a file which can be read and written (e.g., $HOME/.grace_fftw_wisdom) then Grace will automatically create this file (if needed) and maintain it. If the file is read-only, it will be read, but not updated with new wisdom. If the symbol GRACE_FFTW_WISDOM_FILE either doesn't exist, or evaluates to an empty string, Grace will drop the use of wisdom, and will use the fftw estimator (FFTW_ESTIMATE flag sent to the planner) to guess a good factorization, instead of adaptively determining it.

The second variable is GRACE_FFTW_RAM_WISDOM. If this variable is defined to be non-zero, and GRACE_FFTW_WISDOM_FILE variable is not defined (or is an empty string), Grace will use wisdom internally, but maintain no persistent cache of it. This will result in very slow execution times the first time a transform is executed after Grace is started, but very fast repeats. I am not sure why anyone would want to use wisdom without writing it to disk, but if you do, you can use this flag to enable it.

7.4 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
\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 limitations

Grace can output plots using several device backends. The list of available devices can be seen (among other stuff) by specifying the "-version" command line switch.

8.3 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


Command
Description
grayscale set grayscale output
color set color output
optimize:on/off enable/disable optimization
quality:value set compression quality (0 - 100)
smoothing:value set smoothing (0 - 100)
baseline:on/off do/don't force baseline output
progressive:on/off do/don't output in progressive format
dct:ifast use fast integer DCT method
dct:islow use slow integer DCT method
dct:float use floating-point DCT method
JPEG driver options

8.4 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_*