An Xmgrace Tutorial

1. Introduction

The purpose of this tutorial is to enable you to start making good quality scientific plots quickly. This will not cover everything - just some of the more important features.

When dealing with items in drop-down menus, we will use something of the form snaf:/foo/bar/bell which means that on the snaf popup, select from the foo menu the submenu bar and from the bar menu, the entry bell. The popup main is the large one with the graph that pops up when you run xmgrace.

Things that are to be typed in will be presented in a typewriter font, eg, type y = 3*sin(x).

2. Reading data from a file

On startup: xmgrace (data file)

This is most useful if you are in the same directory as the data file and the columns you want to graph are the first two. If you don't enter a data file name, xmgrace will start up with an empty plot.

Read in data: Main:Data/Import/ASCII

The browser will show some of the files in your current directory (the ones that are selected using the filter). Select the file you want and double click or hit return or click OK to bring it into the program. You should see a black curve drawn on a graph.

Block (Multi-column) Data:

When selecting the file, choose "Block data" from the "Load as" menu. If the read was successful, a window should pop up asking you to create a set from the block data. At the top it will list how many columns of data were read. First choose the type of set you would like. Choose the columns for the x- and y- coordinates using the drop down menus. The values Y1 through Y4 are used for selecting error bars as may be needed by other set types.

Kill dataset: Main:Edit/Data_sets...

This lists all the datasets, and for the selected set, its type and a few statistics. To eliminate a set from the plot, select it and then press the right mouse button. A menu should appear from which you can select kill or kill data. The former totally eliminates everything associated with a set while the latter eliminates the data but keeps the settings for it so that if new data is read into the set, it will have the same properties like colouring and line width, etc.

3. Axis Properties
Main:Plot/Axis properties or by double clicking the graph frame

Aspects of the axes are controlled by the axes popup. To see the effect of a change, you have to hit the "Apply" button. In the Main menu:

4. Set appearance
Main:Plot/Set appearance... or double clicking near the target set within the graph

This allows you to change the way the sets are graphed. Practically all aspects of the curves are configurable including colour, line thickness, symbols, drop lines, fills, etc. When the window pops up, there will be a list of the sets with their number (eg. G0.S1 refers to set 1 in graph 0). To see the effect of a change, you have to hit the "Apply" button. In the Main menu:

5. Graph appearance
Main:Plot/Graph appearance or by double clicking just above the graph frame.

We can now fill in the title of the graph and by clicking on the "Titles" tab, the font and size and colour can be chosen.

6. Operating on Data

Sorting data, joining or splitting datasets: Main:Data/Data_set_operations

Sorting can be done in ascending or descending order, and by the x- or y-coordinate. It is also possible to combine or split datasets.

Mathematical operations on sets: Main:Data/Transformations/Evaluate expression

Using evaluate expression allows you to create a set by applying an explicit formula to another set. All the classical mathematical functions are available (cos, sin, etc., but also more complex ones). 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.

7. Saving, Printing, and Opening plots

Save plot Main:File/Save

This saves the current plot parameters into a file so that you can produce the exact same graph without starting from scratch. If the current graph has not been saved already, you will be prompted for a name.

Save plot with another name Main:File/Save as

This saves the current plot parameters into a file - you will be prompted for a name.

Open a previously made plot Main:File/Open

This opens and graphs an earlier plot using the previously saved parameters.

Prepare to print a graph Main:File/Print setup

This prepares to either print the graph on the printer, or produce a file for viewing.

Print a graph or output it to file Main:File/Print

This executes your wishes from the "Print setup" menu, printing to the printer using a Unix command or producing a file.

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

Appendix B. Numerical operators and functions

Arguments of both operators and functions can be either scalars or vector arrays. Arithmetic, logical, and comparison operators are given in tables below.

Operator Description
+ addition
- substraction
* multiplication
/ division
% modulus
^ raising to power
Arithmetic operators

Operator Description
AND or && logical AND
OR or || logical OR
NOT or ! logical NOT
Logical operators

Operator Description
EQ or == equal
NE or != not equal
LT or < less than
LE or <= less than or equal
GT or > greater than
GE or >= greater than or equal
Comparison operators

Another conditional operator is the "?:" (or ternary) operator, which operates as in C and many other languages.

(expr1) ? (expr2) : (expr3);

This expression evaluates to expr2 if expr1 evaluates to TRUE, and expr3 if expr1 evaluates to FALSE.

Function Description
abs(x) absolute value
acos(x) arccosine
acosh(x) hyperbolic arccosine
asin(x) arcsine
asinh(x) hyperbolic arcsine
atan(x) arctangent
atan2(y,x) arc tangent of two variables
atanh(x) hyperbolic arctangent
ceil(x) greatest integer function
cos(x) cosine
cosh(x) hyperbolic cosine
exp(x) e^x
fac(n) factorial function, n!
floor(x) least integer function
irand(n) random integer less than n
ln(x) natural log
log10(x) log base 10
log2(x) base 2 logarithm of x
maxof(x,y) returns greater of x and y
mesh(n) mesh array (0 ... n - 1)
mesh(x1, x2, n) mesh array of n equally spaced points between x1 and x2 inclusive
minof(x,y) returns lesser of x and y
mod(x,y) mod function (also x % y)
pi the PI constant
rand pseudo random number distributed uniformly on (0.0,1.0)
rand(n) array of n random numbers
rint(x) round to closest integer
rsum(x) running sum of x
sin(x) sine function
sinh(x) hyperbolic sine
sqr(x) x^2
sqrt(x) x^0.5
tan(x) tangent function
tanh(x) hyperbolic tangent

Function Description
chdtr(df, x) chi-square distribution
chdtrc(v, x) complemented Chi-square distribution
chdtri(df, y) inverse of complemented Chi-square distribution
erf(x) error function
erfc(x) complement of error function
fdtr(df1, df2, x) F distribution function
fdtrc(x) complemented F distribution
fdtri(x) inverse of complemented F distribution
gdtr(a, b, x) gamma distribution function
gdtrc(a, b, x) complemented gamma distribution function
ndtr(x) Normal distribution function
ndtri(x) inverse of Normal distribution function
norm(x) gaussian density function
pdtr(k, m) Poisson distribution
pdtrc(k, m) complemented Poisson distribution
pdtri(k, y) inverse Poisson distribution
rnorm(xbar,s) pseudo random number distributed N(xbar,s)
stdtr(k, t) Student's t distribution
stdtri(k, p) functional inverse of Student's t distribution
Statistical functions

Function Description
MIN(x) min value of array x
MAX(x) max value of array x
AVG(x) average of array x
SD(x) standard deviation of array x
SUM(x) sum of all elements of array x
INT(x,y) integral of y dx
IMIN(x) index of min value of array x
IMAX(x) index of max value of array x
Aggregate functions