Grace User's Guide (for Grace-5.99.1)

The Grace Team

1. Introduction

• 1.1 What is Grace?
• 1.2 Copyright statement

2. Installation guide

• 2.1 Installing from sources
• 2.2 Binary installation

3. Getting started

• 3.1 General concepts
• 3.2 Invocation
• 3.3 Customization

4. Guide to the graphical user interface

• 4.1 GUI controls
• 4.2 The main window
• 4.3 File menu
• 4.4 Edit menu
• 4.5 Data menu
• 4.6 View menu
• 4.7 Tools menu
• 4.8 Help menu

5. Command interpreter

• 5.1 General notes
• 5.2 Definitions
• 5.3 Variables
• 5.4 Numerical operators and functions

6. Advanced topics

• 6.1 Fonts
• 6.2 Interaction with other applications
• 6.3 FFTW tuning
• 6.4 DL modules

7. References

• 7.1 Typesetting
• 7.2 Device-specific limitations
• 7.3 Device-specific settings
• 7.4 Dates in Grace
• 7.5 Xmgr to Grace migration guide

1. Introduction

1.1 What is Grace?

Grace is a WYSIWYG tool to make two-dimensional plots of scientific 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/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.

As of now, most of the Grace codebase has been re-written from scratch.

1.2 Copyright statement

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

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.

2. Installation guide

2.1 Installing from sources

1. Configuration
   • Requirements. Grace usually compiles out of the box in a regular Unix-like environment. You need an ANSI C compiler (gcc is just fine), the X11R5 or above libraries and headers, and an implementaion of the M*tif API, version 1.2 or above (2.1 is highly recommended). If you want to compile your own changes to certain parts of Grace, you will need a parser generator (yacc or, better, bison).
   • Extra libraries. Some features will be available only if additional libraries are installed. Those are:
     • Multi-level undo functionality is based on the libundo library, version 0.8.0.
     • All raster backends (PNG, JPEG, ...) are based on the ( Xmi library), version 1.2.
     • The JPEG backend needs the IJG's ( JPEG library), version 6.x.
     • The PNG backend needs the libpng library (version 0.96 or above).
     • The PDF driver requires the PDFlib library to be installed, which is available here, version 6.0.0 or above.
     • If your computer has the FFTW library (see the FFTW Home page) installed when Grace is compiled, Grace will link itself to this, and drop all conventional FFT's and DFT's. All Fourier transforms will be routed through this package, resulting in higher accuracy and better (much better in many cases) performance. You'll need version 2.1.*, since the FFTW-3 API is not supported as of yet.
     • In order to read/write sets in the NetCDF data format, you will also need the NetCDF libraries.
   • Decide whether you want to compile in a separate place (thus leaving the source tree pristine). You most probably would want it if compiling Grace for more than one OS and keeping the sources in a central shared (e.g. via NFS) location. If you don't need it, skip the rest of this paragraph and go right to the next step. Otherwise, assuming the sources are in /usr/local/src/grace-x.y.z and the compilation will be performed in /tmp/grace-obj, do the following:

       % mkdir /tmp/grace-obj
       % cd /tmp/grace-obj
       % /usr/local/src/grace-x.y.z/ac-tools/shtool mkshadow \
         /usr/local/src/grace-x.y.z .
                      
     

   • The configure shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create Make.conf in the top directory of the package. It also create config.h file containing system-dependent definitions. Finally, it creates a shell script config.status that you can run in the future to recreate the current configuration, a file config.cache that saves the results of its tests to speed up reconfiguring, and a file config.log containing compiler output (useful mainly for debugging configure). If at some point config.cache contains results you don't want to keep, you may remove or edit it.
   • Run ./configure --help to get list of additional switches specific to Grace
   • Run ./configure <options>. Just an example:

       % ./configure --enable-grace-home=/opt/grace 
         --with-extra-incpath=/usr/local/include:/opt/include \
         --with-extra-ldpath=/usr/local/lib:/opt/lib --prefix=/usr
                      
     

     would use /usr/local/include and /opt/include in addition to the default include path and /usr/local/lib and /opt/lib in addition to the default ld path. As well, all stuff would be put under the /opt/grace directory and soft links made to /usr/bin, /usr/lib and /usr/include.
2. Compilation
   • Issue make If something goes wrong, try to see if the problem has been described already in the Grace FAQ (in the doc directory).
3. Testing
   • make tests This will give you a slide show demonstrating some nice features of Grace.
4. Installation
   • make install
   • make links The later (optional) step will make soft links from some files under the Grace home directory to the system-wide default locations (can be changed by the --prefix option during the configuration, see above).

2.2 Binary installation

We neither provide nor support binary builds. Please contact your vendor. Practically all general-purpose GNU/Linux and other Open Source distributions have a Grace package in either main or contributed sections.

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.

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

1. Start the GUI version: xmgrace (return).
2. Load your data with Data/Import/ASCII. 'Load as': 'Single set' for two-column ASCII data, 'Block data' for multi-column ASCII data.
3. Fire up project explorer (Edit/Explorer).
4. Click on the top-level node of the project tree and select/check the page size.
5. Adjust the scales, axis labels and tick marks in "Axis" quark properties.
6. Adjust lines, symbols, legends in "Set" properties.
7. Continue exploring the quark tree for finer tuning.
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/Save'.
10. Select 'File/Print setup' and then 'File/Print' to get a hardcopy. That's it!

3.1 General concepts

Project tree

A plot in Grace is built in a tree-like manner (reflected 1:1 in the Explorer tool) out of "Quarks". Quark is an object that may have its own presentation properties plus a number of children quarks.

Coordinate frames

Some quarks impose a coordinate transform; these are "Project", "Frame", and "Graph". Correspondly, there are three types of coordinates in Grace: the viewport, the frame, and the world coordinates. A child position is always defined in the coordinate frame of its parent, so e.g. points of data sets are defined in the graph's world coordinates.

The frame coordinates go from 0 to 1 in both X and Y dimensions of a Frame.

The viewport coordinates correspond to the image of the plot drawn on the canvas (or printed on, say, PS output page). 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.

The transformation converting the world coordinates into the frame and further into the viewport ones is determined by both the graph type and the axis scaling.

Frames

Frame is a rectangular placeholder for one or more graphs (if there are more than one graph in a frame, such graphs are called overlaid), and optional annotating objects (texts, boxes, etc). As well, Frame is responsible for displaying legend box holding legend entries for all of its children graphs.

Graphs

A graph may hold (every element is optional) Axes, Sets, and additional annotative objects.

The graph type can be any of:

• XY Graph
• XY Chart
• Polar Graph
• Fixed Graph
• Pie chart

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:

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

Regions

Regions are sections of a 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 covered by region.

Regions are auxiliary objects which are not displayed in print outputs.

Project files

A project file contains all information necessary to restore a plot created by Grace. Each plot is represented on a single page (this may change in future), but may have an unlimited number of graphs.You create a project file of your current plot with File/Save,Save as.

Datasets

A dataset is an array of points with X and Y coordinates, up to four optional data values (which, depending on the set presentation type, can be displayed as error bars or like) and one optional character string.

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 supported) or alphanumeric (with or without quotes). Several calendar date formats are recognized automatically and you can specify your own reference for numeric dates formats. Depending on configuration, Grace can also read NetCDF files (see configuration).

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 instance: 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:

• X11
• PostScript (level 1 and level 2), suitable for printing
• EPS (encapsulated PostScript)
• Metafile (which is Grace format, used at the moment mostly for debugging purposes)
• MIF (Maker Interchange Format used by FrameMaker)
• SVG (Scalable Vector Graphics, a language for describing two-dimensional vector and mixed vector/raster graphics in XML)
• PDF (depends on extra libraries, see configuration)
• PNM (portable anymap file format, depends on extra libraries, see configuration)
• JPEG (depends on extra libraries, see configuration)
• PNG (depends on extra libraries, see configuration)

Grace can also be instructed to launch conversion programs automatically based on file name. As an example you can produce many vector formats using pstoedit, or almost any image format using the netpbm suite (see also 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").

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

Set autoscale type

-barebones

Turn off all toolbars

-block block_data

Assume data file is block data

-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

-hardcopy

No interactive session, just print and quit

-hdevice hardcopy_device_name

Set default hardcopy device

-hdevice-options option_string

Set options for default hardcopy device

-install

Install private colormap

-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

-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

-printfile file

Save print output to file

-results results_file

Write results of some data manipulations to results_file

-saveall save_file

Save all graphs to save_file

-seed seed_value

Integer seed for random number generator

-timer delay

Set allowed time slice for real time inputs to delay ms

-settype xy|xydx|...

Set the type of the next data file

-version

Show the program version

-wd directory

Set the working directory

-usage|-help

This message

3.3 Customization

Environment variables

GRACE_HOME

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

GRACE_PRINT_CMD

Print command. If the variable is defined but is an empty string, "Print to file" will be selected as default.

GRACE_EDITOR

The editor used for manual editing of dataset values.

GRACE_HELPVIEWER

Invocation string of an HTML viewer for on-line browsing of help documents. Must include "%s" to be replaced with an URL string.

GRACE_FFTW_WISDOM_FILE and GRACE_FFTW_RAM_WISDOM

These flags control behavior of the FFTW planner (see FFTW tuning for detailed info).

Default template

Whenever a new project is started, Grace loads the default template, templates/Default.xgr. The file is searched for in the magic path (see magic path); once found, the rest of the path is ignored.

X resources

The following Grace-specific X resource settings are supported:

• XMgrace.invertDraw
  Use GXinvert rather than GXxor for rubber-band lines. If the rubber-banding for zooms and lines, etc. doesn't appear on the canvas, set this resource to yes.
• XMgrace.toolBar
  Enables button toolbar
• XMgrace.statusBar
  Enables status bar
• XMgrace.locatorBar
  Enables locator bar
• XMgrace.instantUpdate
  Enables instant update feature of Explorer

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

You'll need to derive the item's X resource name from the respective menu label, which is easily done following these rules:

• All non-alphanumeric characters are skipped
• Start with lower case; each new word (if any) continues from the capital letter
• Add the item's type to the end - "Menu" for pulldown menus, "Button" for menu buttons.

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.nonLinearCurveFittingButton.acceleratorText: Ctrl+F
XMgrace*transformationsMenu.nonLinearCurveFittingButton.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).

Similarly, it may be desirable to alter default filename patterns of file selection dialogs. The recipe for the dialog's name is like for menu buttons outlined above, with "Button" being replaced with "FSB". E.g., to list all files in the "Open project" dialog ("File/Open..."), set the following resource:

XMgrace*openProjectFSB.pattern: *

4. Guide to the graphical user interface

4.1 GUI controls

This section describes interface controls - basic building blocks, used in many popups.

File selection dialogs

Whenever the user is expected to provide a filename, either for reading in or writing some data, a file selection dialog is popped up. In addition to the standard entries (the directory and file lists and the filter entry), there is a pulldown menu for quick directory change to pre-defined locations (the current working directory, user's home directory and the file system root). Also, a "Set as cwd" button is there which allows to set any directory as you navigate through the directory tree as the current working directory (cwd). Once defined, it can be used in any other file selection dialog to switch to that directory quickly.

List selectors

Various selectors are available in several popups. They all display lists of objects (graphs, sets, ...) and can be used to perform simple operations on these objects (copying, deleting, ...). The operations are available from a popup menu that appears when pressing mouse button 3 on them. Depending on the required functionality, they may allow multiple choices or not.

• hide
• show
• delete
• bring to front
• move up
• move down
• send to back
• selector operations
  • select all
  • unselect all
  • invert selection
  • update list

The following shortcuts are enabled (if the result of an action would contradict the list's selection policy, this would be ignored):

• Ctrl+a select all
• Ctrl+u unselect all
• Ctrl+i invert selection

Frame selector

An extension of the list selector. The additional operations that can be performed on frames through the frame selector's popup menu are:

• create new

Graph selector

An extension of the list selector. The additional operations that can be performed on graphs through the graph selector's popup menu are:

• create new
• focus to selected

Double-clicking on a list entry will switch the focus to that graph.

Set selector

An extension of the list selector. The additional operations that can be performed on sets through the set selector's popup menu are:

• edit
  • in spreadsheet (see Spreadsheet data set editor)
  • in text editor
• create new
  • by formula
  • in spreadsheet (see Spreadsheet data set editor)
  • in text editor
  • from block data

Double-clicking on a list entry will open the spreadsheet editor (see Spreadsheet data set editor) on the set data.

Pen chooser

Pen chooser lets you select a pen (a color+pattern combination) for drawing a line or filling in an object. When you click on the button, a dialog with color and pattern selectors will appear. When applied, the pen chooser will itself be painted by the pen. A faster way to alter pen's color is to press the right mouse button on it, which will invoke a color-change menu.

Spreadsheet data set editor

The dialog presents an editable matrix of numbers, corresponding to the data set being edited. The set type (and hence, the number of data columns) can be changed using the "Type:" selector. Clicking on a column label pops up a dialog allowing to adjust the column formatting. Clicking on the row labels toggles the respective row state (selected/unselected). The selected rows can be deleted via the dialog's "Edit" menu. Another entry in this menu lets you add a row; the place of the new row is determined by the row containing a cell with the keyboard focus on. As well, just typing in an empty cell will add one or several rows (filling the intermediate rows with zeros).

To resize columns, drag the vertical rules using Shift+Button 2.

4.2 The main window

The canvas

Canvas hotkeys

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

• Ctrl <Key>A: Autoscale the current graph
• Ctrl <Key>U: Refresh hotlinks
• Ctrl <Key>Z: Zoom

Clicks and double clicks

Mouse wheel (if you got one) scrolls the canvas vertically. With <Ctrl> pressed, the scroll direction is horizontal. Alternatively, simply drag the canvas with the mouse.

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 an object will invoke Explorer with the relevant Quark selected.

Dragging an object with mouse is possible while <Ctrl> is pressed.

Pressing 3-rd mouse button on an object pops up a context-sensitive menu.

Toolbar buttons

Along the left-hand side of the canvas (if shown) is the ToolBar. It is armed with several buttons to provide quick and easy access to the more commonly used Grace functions; most of them operate on the current graph.

4.3 File menu

The file menu contains all entries related to the input/output features of Grace.

New

Reset the state of Grace as if it had just started (one empty graph ranging from 0 to 1 along both axes). If some work has been done and not yet saved, a warning popup is displayed to allow canceling the operation.

Open

Open an existing project file. A popup is displayed that allow to browse the file system.

Save

Save the current work in a project file, using the name that was used for the last open or save. If no name has been set (i.e., if the project has been created from scratch) act as save as.

Save as

Save the current work in a project file with a new name. A popup allows to browse the file system and set the name, the format to use for saving data points (the default value is "%16.8g"), and a textual description of the project. A warning is displayed if a file with the same name already exists.

Revert to saved

Abandon all modifications performed on the project since the last save. A confirmation popup is fired to allow the user canceling the operation.

Print setup

Set the properties of the printing device. Each device has its own set of specific options (see Device-specific settings). According to the device, the output can be sent either directly to a printer or directed to a file. The global settings available for all devices are the sizing parameters. The size of the graph is fixed. Changing the 'Page' settings changes the size of the canvas underneath the graph. Switching between portrait and landscape rotates the canvas. Make sure the canvas size is large enough to hold your graph. Otherwise you get a 'Printout truncated' warning. If your canvas size cannot easily be changed because, for example, you want to print on letter size paper, you need to adjust the size of your graph ('Viewport' in Plot/Graph Appearance).

Print

Print the project using the current printer settings

Exit

Exit from Grace. If some work has been done and not saved, a warning popup will be displayed to allow the user to cancel the operation.

4.4 Edit menu

Explorer

This is the most complex dialog. It allows to tune presentation properties of any plot element.

The left pane of the dialog shows the current project's tree structure. By clicking on a node, a "plugin" dialog corresponding to the quark selected appears in the right pane. A few quarks of the same type can be selected; in this case, changes will be applied to all of them.

Project properties

The project properties dialog lets you set page dimensions and the background color.

Frame properties

The frame properties dialog governs location of the frame rectangle and legend properties.

Graph properties

The main tab includes the properties you will need more often, in particular, properties related to the graph's coordinate frame. For each axis, you can define the axis range and a scale types: linear, logarithmic, or reciprocal, and you can invert the axis (which normally increases from left to right and from bottom to top).

The "Locator" tab allows you to customize the display of the locator, mainly its type and the format and precision of the display.

Set properties

The main tab gathers the properties you will need more often (line and symbol properties or legend string for example), and other tabs are used to fine tune some less frequently used options (drop lines, fill properties, annotated values and error bars properties for example).

You should note that, despite the legend string (related to one given set) is entered in the set properties popup, this is not sufficient to display it. Displaying all legends is a frame-level decision, so the toggle is in the main tab of the frame properties plugin dialog.

If you need special characters or special formatting in your legend, you can use Grace escape sequences (the sequence will appear verbatim in the text field but will be rendered on the graph), see typesetting. If you don't remember the mapping between alphabetic characters and the glyph you need in some specific fonts (mainly symbol and zapfdingbats), you can invoke the font tool from the text field by hitting CTRL-e. You can change fonts and select characters from there, they will be copied back in the text field when you press the "Accept" button.

Axis properties

The main tab includes the properties you will need more often (axis label, tick spacing and format for example), and other tabs are used to fine tune some less frequently used options (fonts, sizes, colors, placements, stagger, grid lines, special ticks, ...).

If you need special characters or special formatting in your label, you can use Grace escape sequences (the sequence will appear verbatim in the text field but will be rendered on the graph), see typesetting. If you don't remember the mapping between alphabetic characters and the glyph you need in some specific fonts (mainly symbol and zapfdingbats), you can invoke the font tool from the text field by hitting CTRL-e. You can change fonts and select characters from there, they will be copied back in the text field when you press the "Accept" button.

Annotated texts

Not written yet...

Drawing objects

Not written yet...

Regions

This dialog is incomplete as of yet.

Arrange frames

This entry fires up a popup to lay out several graph frames in a regular grid given by M rows and N columns.

The frame selector at the top allows one to select a number of frames the arrangement will operate on. If the number of selected frames isn't equal to M times N, new frames may be created or extra frames killed if needed. These options are controlled by the respective checkboxes below the frame selector.

The order in which the matrix is filled in with the frames can be selected (first horizontally then vertically or vise versa, with either of them inverted).

The rest of the controls of the dialog window deal with the matrix spacing: left/right/top/bottom page offsets (in the viewport coordinates) and relative inter-cell distances, vertical and horizontal. Next to each of the vertical/horizontal spacing spinboxes, a "Pack" checkbox is found. Enabling it effectively sets the respective inter-cell distance to zero.

If you don't want the regular layout this arrangement gives you, you can change it afterwards.

Autoscale graphs

Using this entry, you can autoscale a graph according to the specified sets only. This is useful if you need either to have truly comparable graphs despite every one contains data of different ranges, or if you want to focus your attention on one set only while it is displayed with other data in a complex graph.

Preferences

The preferences popup allows you to set miscellaneous properties of your Grace session, such as GUI behavior, cursor type, etc.

4.5 Data menu

Data set operations

This popup gathers all operations that are related to the ordering of data points inside a set or between sets. You can sort according to any coordinate (X, Y, DX, ...) in ascending or descending order, reverse the order of the points, join several sets into one, split one set into several others of equal lengths, or drop a range of points from a set.

Transformations menu

The transformations sub-menu gives you access to all data-mining features of Grace.

Evaluate expression

Using evaluate expression allows you to create a set by applying an explicit formula to another set, or to parts of another set if you use regions restrictions.

All the classical mathematical functions are available (cos, sin, but also lgamma, j1, erf, ...). As usual all trigonometric functions use radians by default but you can specify a unit if you prefer to say cos (x rad) or sin (3 * y deg). For the full list of available numerical functions and operators, see Operators and functions.

In the formula, you can use X, Y, Y1, ..., Y4 to denote any coordinate you like from the source set. An implicit loop will be used around your formula so if you say:

         x = x - 4966.5
         

you will shift all points of your set 4966.5 units to the left.

You can use more than one set in the same formula, like this:

         y = y - 0.653 * sin (x deg) + s2.y
         

which means you use both X and Y from the source set but also the Y coordinate of set 2. Beware that the loop is a simple loop over the indices, all the sets you use in such an hybrid expression should therefore have the same number of points and point i of one set should really be related to point i of the other set. If your sets do not follow these requirements, you should first homogenize them using interpolation.

Histograms

The histograms popup allows you to compute either standard or cumulative histograms from the Y coordinates of your data. Optionally, the histograms can be normalized to 1 (hence producing a PDF (Probability Distribution Function).

The bins can be either a linear mesh defined by its min, max, and length values, or a mesh formed by abscissas of another set (in which case abscissas of the set must form a strictly monotonic array).

Fourier transforms

This popup is devoted to direct and inverse Fourier transforms. The default is to perform a direct transform on unfiltered data and to produce a set with the index as abscissa and magnitude as ordinate. You can filter the input data window through triangular, Hanning, Welch, Hamming, Blackman and Parzen filters. You can load magnitude, phase or coefficients and use either index, frequency or period as abscissas. You can choose between direct and inverse Fourier transforms. If you specify real input data, X is assumed to be equally spaced and ignored; if you specify complex input data X is taken as the real part and Y as the imaginary part.

If Grace was configured with the FFTW library (see configuration), then you may want to use FFTW wisdom files. Then, you should set several environment variables to name them.

Running properties

The running properties popup allows you to compute some values on a sliding window over your data. You choose both the value you need (average, median, minimum, maximum, standard deviation) and the length of the window and perform the operation.

Differences/derivatives

The differences popup is used to compute approximations of the first derivative of a function with finite differences. a period to data of the preceding period (namely y[i] - y[i + period]). Beware that the period is entered in terms of index in the set and not in terms of abscissa!

Integration

The integration popup is used to compute the integral of a set and optionally to load it. The numerical value of the integral is shown in the text field after computation. Selecting "cumulative sum" in the choice item will create and load a new set with the integral and compute the end value, selecting "sum only" will only compute the end value.

Interpolation/Splines

This popup is used to interpolate a set on an array of alternative X coordinates. This is mainly used before performing some complex operations between two sets with the evaluate expression popup.

The sampling array can be either a linear mesh defined by its min, max, and length values, or a mesh formed by abscissas of another set.

Several interpolation methods can be used: linear, spline or Akima spline.

Note that if the sampling mesh is not entirely within the source set X bounds, evaluation at the points beyond the bounds will be performed using interpolation parameters from the first (or the last) segment of the source set, which can be considered a primitive extrapolation. This behaviour can be disabled by checking the "Strict" option on the popup.

The abscissas of the set being interpolated must form a strictly monotonic array.

Non-linear fit

The non linear fit popup can be used for functions outside of the simple regression methods scope. With this popup you provide the expression yourself using a0, a1, ..., a9 to denote the fit parameters (as an example you can say y = a0 * cos (a1 * x + a2)). You specify a tolerance, starting values and optional bounds and run several steps before loading the results.

The fit characteristics (number of parameters, formula, ...) can be saved in a file and retrieved as needed using the file menu of the popup.

In the "Advanced" tab, you can additionally apply a restriction to the set(s) to be fitted (thus ignoring points not satisfying the criteria), use one of preset weighting schemes or define your own (notice that "dY" in the preset "1/dY^2" one actually refers to the third column of the data set; use the "Custom" function if this doesn't make sense for your data set), and choose whether to load the fitted values, the residuals or the function itself. Choosing to load fitted values or residuals leads to a set of the same length and abscissas as the initial set. Choosing to load the function is almost similar to load the fitted values except that you choose yourself the boundaries and the number of points. This can be used for example to draw the curve outside of the data sample range or to produce an evenly spaced set from an irregular one.

Correlation/covariance

This popup can be used to compute autocorrelation of one set or cross correlation between two sets. You only select the set (or sets) and specify the maximum lag. A check box allows one to evaluate covariance instead of correlation. The result is normalized so that abs(C(0)) = 1.

Linear convolution

The convolution popup is used to ... convolve two sets. You only select the sets and apply.

Sample points

This popup provides a way to sample a set by selecting only the points that satisfy a boolean expression you specify.

Prune data

This popup is devoted to reducing huge sets (and then saving both computation time and disk space).

The interpolation method can be applied only to ordered sets: it is based on the assumption that if a real point and an interpolation based on neighboring points are closer than a specified threshold, then the point is redundant and can be eliminated.

The geometric methods (circle, ellipse, rectangle) can be applied to any set, they test each point in turn and keep only those that are not in the neighborhood of previous points.

Feature extraction

Given a set of curves in a graph, extract a feature from each curve and use the values of the feature to provide the Y values for a new curve.

Import menu

ASCII

Read new sets of data in a graph. A graph selector is used to specify the graph where the data should go (except when reading block data, which are copied to graphs later on).

Reading as "Single set" means that if the source contains only one column of numeric data, one set will be created using the indices (from 1 to the total number of points) as abscissas and read values as ordinates and that if the source contains more than one column of data, the first two numeric columns will be used. Reading as "NXY" means that the first numeric column will provide the abscissas and all remaining columns will provide the ordinates of several sets. Reading as "Block data" means all column will be read and stored and that another popup will allow to select the abscissas and ordinates at will. It should be noted that block data are stored as long as you do not override them by a new read. You can still retrieve data from a block long after having closed all popups, using the set selector.

The set type can be one of the predefined set presentation types (see sets).

The data source can be selected as "Disk" or "Pipe". In the first case the text in the "Selection" field is considered to be a file name (it can be automatically set by the file selector at the top of the popup). In the latter case the text is considered to be a command which is executed and should produce the data on its standard output. On systems that allows is, the command can be a complete sequence of programs glued together with pipes.

If the source contains date fields, they should be automatically detected. Several formats are recognized (see appendix dates in grace). Calendar dates are converted to numerical dates upon reading.

The "Autoscale on read" menu controls whether, upon reading in new sets, which axes of the graph should be autoscaled.

NetCDF

This entry exists only if Grace has been compiled with support for the NetCDF data format (see configuration).

Export menu

ASCII

Save data sets in a file. A set selector is used to specify the set to be saved. The format to use for saving data points can be specified (the default value is "%16.8g"). A warning is displayed if a file with the same name already exists.

4.6 View menu

Show/hide

Locator bar

This toggle item shows or hides the locator below the menu bar.

Status bar

This toggle item shows or hides the status string below the canvas.

Tool bar

This toggle item shows or hides the tool bar at the left of the canvas.

Page zoom

Smaller

Zoom out page.

Larger

Zoom in page.

Original size

Reset page zoom.

Page rendering

Set the rendering properties of the display device (font anti-aliasing and color transformations).

Redraw

This menu item triggers a redrawing of the canvas.

Update all

This menu item causes an update of all GUI controls. Usually, everything is updated automatically, unless one makes modifications by entering commands in the Console tool.

4.7 Tools menu

Font tool

Not written yet...

Console

The console window displays errors and results of some numerical operations, e.g. nonlinear fit (see Non-linear fit). The window is popped up automatically whenever an error occurs or new result messages appear. This can be altered by checking the "Options/Popup only on errors" option.

The dialog also provides an interface to the command driven version of Grace. Here, commands can be typed in the "Command:" text item and executed when <Return> is pressed. The command will be parsed and executed, and the command line is placed in the history list. Items in the history list can be recalled by using the keyboard arrow buttons. Depending on the state of the "Options/Auto redraw" and "Options/Auto update" checkboxes, each command entered will cause an immediate resync of the canvas and/or the GUI, respectively. For a reference on the Grace command interpreter, see Command interpreter.

Dataset statistics

Using the dataset statistics popup, you can view statistical properties of datasets (min, max, mean, standard deviation). A horizontal scrollbar at the bottom allows to get the two last properties, they are not displayed by default. Also note that if you find some columns are too narrow to show all significant digits, you can drag the vertical rules using Shift+Button 2.

4.8 Help menu

On context

Click on any element of the interface to get context-sensitive help on it. Only partially implemented at the moment.

User's guide

Browse the Grace user's guide.

FAQ

Frequently Asked Questions with answers.

Changes

The list of changes during the Grace development.

Examples

The whole tree of submenus each loading a sample plot.

Web support

Home page

Open the official Grace home page.

Forums

Go to Grace forums, where you can participate in discussions.

Report an issue

Use this to send your suggestions or bug reports.

License terms

Grace licensing terms will be displayed (GPL version 2).

About

A popup with basic info on the software, including some configuration details. More details can be found when running Grace with the "-version" command line flag.

5. Command interpreter

5.1 General notes

The interpreter parses its input in a line-by-line manner. There may be several statements per line, separated by semicolon (;). The maximal line length is 4 kbytes (hardcoded). The parser is case-insensitive and ignores lines beginning with the "#" sign.

5.2 Definitions

Not finished yet...

5.3 Variables

Not finished yet...

5.3 Variables

Not finished yet...

5.3 Variables