1
<!doctype linuxdoc system>
3
<!-- LyX 1.1 created this file. For more info see http://www.lyx.org/ -->
10
<tt>evigmon@tulane.edu</tt>
19
These tutorials assumes that you are a new user to Grace but are somewhat
20
familiar with a windowing system. They are designed to show you some of the
21
basic operation of Grace as well as a few of its less intuitive features. Please
22
feel free to go beyond the bounds of the actions described herein and explore
23
the possibilities of using Grace. After all, you will be the one who benefits.<tt>
29
The purpose of these tutorials are to give brief examples to show you the
30
basics of how to do something. Essentials and some of the more esoteric features
31
of Grace will be demonstrated to give the user an idea of the capabilities
32
of this program. It is not possible to show everything that Grace is capable
33
of doing. That knowledge only comes with use and experimentation. I recommend
34
that you do the tutorial and then by playing around with things, you will begin
35
to understand them. Finally, when you get stuck, read the user guide to help
41
In referring to what item to select, the tutorial will use something of
42
the form <sf>snaf:/foo/bar/bell </sf>which means that on the snaf popup, select from
43
the foo menu the submenu bar and from the bar menu, the entry bell. The popup
44
main is the large one with the graph that pops up when you run xmgrace. If
45
there is a space in the menu item, it will be replaced by an underscore. So
46
, if the menu item was actually "Bell jar" instead of bell in the last example,
47
it would be <sf>snaf:/foo/bar/Bell_jar.</sf>
50
Things that are to be typed in will be presented in a typewriter font,
51
eg, type <tt>y = 3*sin(x)</tt>.
54
Some of examples require you to input a data file or graph. In such instances,
55
there should be a file in the tutorial directory named data.N or N.agr where
56
N is the tutorial number. For example, when doing tutorial 7.1.3, you should
57
look for a file 7.1.3.agr. It is assumed that each major tutorial section starts
63
Some of the following examples require that system commands be run. The
64
commands may be different on your machine or require a slightly different syntax.
65
In this tutorial, an attempt will be made to use the most commonly available
66
UNIX commands. This tutorial was prepared on a Linux machine with kernel 2.0.32.
71
A couple of points should be made about the GUI before we begin to make
77
It is often possible to select more than one item from a list at a time
78
(some lists may prevent it when it makes no sense.). Clicking on a list entry
79
without any keyboard modifier pressed will deselect all other entries and select
80
only that one. Depressing shift while clicking an entry selects all entries
81
from a previously selected entry to the currently selected one. Finally, depressing
82
control allows one to individually toggle the selection of an entry.
84
There are often two buttons on a pop up: Apply and Accept. Changes are
85
not registered until either of these buttons is pressed. The difference between
86
them is that Accept also closes the window.
91
Even though I do my best to keep this up to date with the latest release,
92
I cannot guarantee it. Think of this a perpetual work in progress. Therefore,
93
if something is wrong, you can notify me and I'll fix it but keep in mind that
94
I am doing it in my spare time for no money.
99
The object of this tutorial is to do the most basic function of Grace:
100
read in some data into a graph and then label the graph. Along the way, a few
101
of the basic Grace commands and widgets will be introduced.
104
Reading the data from a file
106
Start by bringing up the set reading widget <em>Main:Data/Import/ASCII</em>. Select
107
the file 2.1.dat (both double clicking and hitting return work). You should
108
see a black curve drawn on a graph.
111
Now we would like to add some more sets to the graph, but this time the
112
data file will be in a slightly different format. Looking at the file "2.1.dat"
113
(with the program of your choice), you can see that its several columns of
114
numbers. One way to interpret this file is the first column gives the x-values
115
and the rest of the columns are y-values. From Grace, again open the "Read Sets"
116
widget. This time, check the "NXY" button. Now select the file "2.1.dat". At this
117
point you will have several differently coloured curves.
120
You should now have 2 copies of the first set since you've read the file
121
twice. It would be nice to eliminate one copy. This is most easily accomplished
122
by bringing up a popup which lists all the sets. Selecting <em>Main:Edit/Data_sets...</em>bring up the Data set props popup. It lists all the sets and for the selected
123
set, its type and a few statistics. To eliminate a set, select it and then
124
press the right mouse button. A menu should appear from which you can select
125
kill. You'll note that there is a kill and kill data. The former totally eliminates
126
everything associated with a set while the latter eliminates the data but keeps
127
the settings for it so that if new data is read into the set, it will have
128
the same properties like colouring and line width, etc. Kill set 0 for now.
133
We would now like style the sets. Practically all aspects of the curves
134
are configurable including colour, line thickness, symbols, drop lines, fills,
135
etc. These operations are available under the "Set appearance" widget which is
136
invoked by selecting <em>Main:Plot/Set appearance...</em> or by double clicking near
137
the target set within the graph frame.
140
When the widget comes up, there will be a list of the sets with their number
141
(eg. G0.S1 refers to set 1 in graph 0). Later operations will require you to
142
know the number. Like the data sets pop up, clicking on mouse button 3 in the
143
set list will bring up the menu of set operations.
146
Colouring all sets differently
148
The simplest way to colour all sets differently is from Set_Appearance:Data/All
149
colors. First select the sets which you wish to recolour and then select Set_Appearance:Data/All
150
colors. Do this now to your graph.
155
When a set in the list is highlighted, the widgets change to reflect the
156
settings. Practically all aspects are configurable. Experiment by changing
157
the line colours and widths, placing a symbol at each data point, not connecting
158
data points and fill the space between the x-axis and the curve. Don't forget
159
to try out what is available under the other tabs besides Main. To see the
160
effect of a change, you have to hit the "Apply" button. <bf>N.B</bf>.: Things are drawn
161
in numerical order so if there is overlap, the highest numbered item will be
162
on top. This applies to graphs and sets within each graph.
165
Labelling the axes using the font tool
167
Aspects of the axes are controlled by the axes popup which is called from
168
<em>Main:Plot/Axis properties</em> or by double clicking the graph frame. All aspects
169
of the axes can be changed like the title, the font, colour, whether or not
170
to draw grid lines, or user defined tick marks and labels. There are many settings
171
and the best thing to do is to experiment to see what each setting does.
174
For now, let's start by labelling the axes. Suppose these curves represent
175
the number of tasks a processor runs as the function of the number of users.
176
To make it more interesting, assume we are doing this in Quebec. That means
177
we want to plot "Nombre de t�ches vs. nombre d'usagers". Note the importance
178
of having the accent over the a in t�ches or we would end up plotting the number
179
of stains which is entirely another case. Bring up the Axes pop up, select
180
the Y axis, and click in the space to enter the label string of the axis label.
181
Start typing Nombre de t. At this point we need to enter a accented letter,
182
so we bring up the font tool by pressing <tt>Control-E. </tt>You will now see what we
183
have typed in the Cstring widget. Move the cursor to where you want to place
184
the accented letter and click on the letter. It should now appear in the string.
185
You can either finish the string here or hit accept and keep editing. Label
186
the x axis as well. This font tool is available wherever text needs to be entered.
189
All the attributes regarding the axis labels like size, colour, font, position
195
Our next exercise will be to title the graph so other. Operation pertaining
196
to this are found in the "Graph appearance" widget which we open by selecting
197
<em>Main:Plot/Graph appearance</em> or by double clicking just above the graph frame.
200
We can now fill in the title of the graph and by clicking on the "Titles"
201
tab, the font and size and colour can be chosen. The Viewport box under the
202
"Main" tab defines the 4 corners of the graph frame. You can type them in or
203
use the mouse to move them by first double clicking on them.
206
Other things which can be controlled in this widget are the frame drawn
207
around the graph, whether or not the graph background is coloured and the legends.
208
Legends will be dealt with a little later.
213
Since we have several lines in our graph, it makes sense that we label
214
them with a legend so that other people can figure out what they mean. The
215
first thing to do is to give each set a label. This is done by entering a legend
216
string for each set in the Set appearance popup. Now, from the Main form in
217
the Graph appearance popup, click on "Display legend" to see the legend box.
218
The location and appearance of the box is controlled by clicking on the "Leg.
219
box" tab. The appearance and spacing of the legend entries is controlled by
220
the "Legends" tab. For simplicity, label the sets alphabetically and then play
221
with the appearance, etc. to get something you like.
224
Specifying the placement of the graph by entering the coordinates can be
225
painful, especially the fine tuning. To alleviate this problem, a graphical
226
method is also available, although not readily apparent. After a legend appears,
227
it may be dragged to a new location. To do this, press Ctrl-L with your mouse
228
on the main canvas. You should see the arrow cursor turn into a hand. If this
229
doesn't work, double click on the main canvas (to get its attention) and then
230
press Ctrl-L. Click on the legend and drag it. To cancel the legend drag mode
231
(as with all other modes), click on mouse button 3.
236
I got bored so I took the data files and produced my own, albeit ugly,
237
graph. See if you can copy <htmlurl url="mygraph.png" name="mygraph.png">
242
A block of data is a table of number which are interpreted as columns of
243
numbers. How sets are created from the columns depends on the information you
244
want to extract from the file.
247
We first need to read in a block of data. We do this from <em>Main:Data/Import/ASCII</em>.
248
Select the file "3.dat" and Load as "Block data". If the read was successful, a
249
window should pop up asking you to create a set from the block data. At the
250
top it will list how many columns of data were read.
253
First we choose the type of set we would like. For now we'll stick with
257
Next we choose which column of data contains the x-ordinate. If there is
258
no column, we can select "index" which will use the index into the column as
259
the x ordinate starting from one.
262
The values Y1 through Y4 are used for selecting error bars as may be needed
266
The last thing to specify is the graph into which to load the set if we
267
have more than 1 set.
270
Finally, hitting accept will create the set.
273
If you close this window, it can reopened by bringing up a set list (eg.
274
<em>Main:Edit/Data_sets</em>) and then selecting Create_new/From_block_data from the
275
menu brought up by right clicking on the set list.
278
Try creating a new set of type XYdY. This is an XY curve with error bars.
279
Try X, Y, and Y1(the error) from different columns.
282
Creating sets within Grace
284
Besides reading in data files, Grace has an extensive scripting language
285
with a large number of math functions built in, These function include the
286
basic add, multiply, square root, etc, and also the cephes library of higher
287
order math functions like Bessel functions and the gamma function. Hence, functions
288
in Grace are basically unlimited. See the user guide for more details. In addition,
289
users can dynamically add libraries to Grace with any desired function. As
290
well, points may be added manually to a set by the use of editors. To begin,
291
choose <em>Main:Edit/Data sets</em>. To create a set, press mouse button 3 (the rightmost
292
one for right handed people) anywhere within the data set list (which may be
293
empty) and select Create new. A menu with 4 different ways of creating new
294
sets will be presented. We'll go through them one by one.
299
The load and evaluate window will pop up when this is selected.
304
The first step is to set up the parameter mesh which will determine the
305
range and sampling of the variable $t. Most often, $t will simply
308
Next, choose the type of set you would like to produce.
310
Using the syntax of the command language, an expression for x is entered
311
which uses $t as the independent variable. This can be an extremely
312
complicated function.
314
Likewise, an expression for y is entered and for any other expressions
315
that may be needed. Fields after y are labelled y1, y2, y3 and y4. For example,
316
if the set type xydxdy is chosen, y1 will hold dx and y2 will hold dy and it
317
will be necessary to enter expressions for them.
319
Pressing apply or accept will perform the calculations and create the new
320
set. You may have to autoscale to see the new set.
323
Below are a few samples:
328
To plot one cycle of a sine wave: Load: Set X, Start load at: <tt>0</tt>, Stop load
329
at: <tt>2*pi</tt>, Length: <tt>100</tt>, X=$t, Y=<tt>sin($t)</tt>
331
A unit circle by parameterization: Start at:<tt>0</tt>, Stop at: <tt>2*pi</tt>, Length: <tt>100</tt>,
332
X=cos($t), Y=sin($t)
337
If your system has the Xbae widget set, this choice brings up a spreadsheet
338
like editor to allow one to enter the points of the set by hand. Initially,
339
it just has the point ( 0, 0 ). Clicking on add will insert a copy of the currently
340
selected row immediately below the selected row. Clicking delete will delete
341
the row which contains the cursor. This method is best suited to examining
342
or modifying existing sets or creating very small sets. The sets gets updated
343
after one hits enter or leaves the cell.
348
If your system doesn't have the Xbae widget set or you want the power of
349
your favourite external editor, a text editor of your choice may be used to
350
enter data. The editor is selected by the GRACE_EDITOR environment variable.
351
If the set is new, it will contain only the point (0,0). During editing, no
352
other operations are possible. After the editor is closed, the set will be
358
This creates a new set from a block of data which has been read in. See
364
Grace supports a large number of command line options which allow the user
365
to control the appearance and placement of graphs. This can be very useful
366
if you want to use it to quickly print something without going through the
367
GUI, use it within a script to automatically generate graphs, or have a plot
368
come up already configured which can be much quicker than going through the
372
Simple nonGUI printing
374
Invoking Grace with the command "grbatch"from the command line will cause
375
Grace to start, produce a plot, send it to the printer (unless a file is specified)
376
and then exit. In its simplest form, to produce a plot of the file a.agr, type
382
If gracebat is unavailable on your system, the hardcopy option to xmgrace
383
will do the same thing. Assuming the hardcopy device is a postscript printer,
387
xmgrace -hdevice PostScript -hardcopy a.agr
392
Often, one wishes to plot several graphs with each graph having different
393
characteristics. This is easily accomplished from the command line. Options
394
specified on the command line are parsed in order and stay in effect until
395
overridden by specifying them again.
400
The first step in plotting multiple graphs is usually telling Grace how
401
many graphs we have and how to arrange them. The interpreter command "arrange"
402
will do this. For example, if we want 4 graphs arranged in a simple 2x2 table,
404
-pexec "arrange ( 2, 2, .1, .1,.1,ON,ON,ON)"
406
all the options is explained in the reference manual.
408
Specify any global options.
410
Specify for each graph, the data to plot and any options. Options should
411
be specified in the following order:
414
"-graph g" where g is the graph number starting at 0. This says to apply
415
all following options to this graph.
417
Set any autoscaling options. Autoscaling is performed when the file is
418
read; ergo, the autoscaling must be specified BEFORE the file is read. Remember,
419
this setting is persistent.
421
Set the set type. This is also a persistent setting.
423
Specify the graph type and the input file.
425
If reading in block data, create the sets with the "-bxy" option.
427
Specify any world scaling. It is important to do this AFTER sets are read
428
(unless autoscaling is off) as the graph gets rescaled when data is read in.
430
Specify anything else
436
Let's try an example. We will assume 5 plots, the first 4 of which are
437
to be stacked vertically, and the fifth inset into the fourth. We wish to plot
438
the files a.dat, b.dat, c.dat and d.dat with the inset graph being a magnified
439
portion of d.dat. Assume a.dat contains multiple columns of data, b.dat is
440
a block of data from which we wish to make a curve from columns 2 and 4 with
441
the error given by column 3, c.dat is to be represented as a bar graph, and
442
for the inset graph, we wish to graph to region (0,0) to (1,1). This can be
446
gracebat -pexec "arrange (4,1,.1,.1,.1,ON,ON,ON)" -nxy a.dat -graph 1 -block
447
b.dat -settype xydy -bxy 2:4:3 -graph 2 -settype bar c.dat -graph 3 -settype
448
xy d.dat -graph 4 d.dat -world 0 0 1 1 -viewport .15 .3 .8 .88
451
Note that the graph numbers start at 0 and that 0 is the default so it
452
does not have to be specified for the first graph.
455
Things for which no command line option exists
457
Undoubtedly, you will reach a point where you want to do something for
458
which no command line option exists. (We have been doing this with the arrange
459
command.) This is where Grace's parameter file language is vital. The option
460
"-pexec" will execute the next argument as if it had read it from a parameter
461
file or excuted on the command line. If you want to do something more complicated
462
than one command, you can use several pexec's or put the commands in a file
463
and run the file with the "-batch" option.
468
To read in the files foo.dat and bar.dat and scale foo.dat in Y by 1000,
472
xmgrace foo.dat bar.dat -pexec "s0.y = s0.y * 1000"
477
To do the same as the previous example but also label the axes and recolour
478
the curves, make a file called "bfile" with the Grace commands
482
#Obligatory descriptive comment
486
title "A Gnasty Graph"
487
xaxis label "Time ( s )"
488
yaxis label "Gnats ( 1000's )"
492
and then run xmgrace with
495
xmgrace foo.dat bar.dat -batch bfile
500
This tutorial will explain some of Grace's curve fitting abilities. Grace
501
can perform two types of fittings. The first type is regression or linear fitting
502
where optimization is done on a linear equation or an equation which can be
503
expressed in a linear form. This includes fitting polynomials and certain forms
504
of equations. The other type of fitting is nonlinear and allows for arbitrary
505
user supplied functions.
508
Let's take a curve and see how each type of fitting works. To begin, create
509
a curve of the function <tt>y = sqrt(x) + exp(x)/3 -1</tt> over the range 0 to 3 with
515
Choosing <em>Main:Data/Transformations/Regression</em> will pop up the Regression
521
Select the set you just created
523
Select the type of fit. For now, pick Linear.
525
We will load the fitted value for now.
527
Press the accept button to see the results of the fit. A window will pop
528
up which will give you the results of the fit including the final expression.
529
You might have to scroll back a bit to see it.
531
See how high of a polynomial is needed to get an acceptable fit and try
532
fitting other types of functions. Note that for the non-polynomial fits, <bf></bf><bf><em>A</em></bf><em></em>
533
and <bf></bf><bf><em>B</em></bf><em></em> are the fitting parameters of the equation.
535
Now, we are not limited to computing our fitted curve at the points of
536
the original function. Suppose these data are quarterly sales and we wish to
537
predict our next quarter. Choose the type of fit which you found to work best.
538
Instead of loading fitted values,<em> Load: Function.</em> Now the bottom of the widget
539
will become active. We wish to extrapolate over the next quarter, so we would
540
like to start at 0 and end at 4 and choose 100 points. Press accept to see
546
We pop up the widget by selecting <em>Main:Data/Transformations/Non-linear
547
curve fitting</em>. You may want to kill all the sets except the original function
548
and the extrapolated function at this point.
553
Begin by selecting the set to optimize, the original function.
555
Next, we write a function of the form we wish to fit. The unknown parameters
556
are labelled a0..a9. You must start with a0 and work your way up. In this case,
557
since you know the form of the equation already, so try: <tt>y = a0*sqrt(x) + a1*exp(x)
560
Next we must specify that we have three parameters to fit which are a0,
561
a1 and a2 and the tolerance of the solution.
563
You must specify initial values for the parameters and put any bounds on
564
them if necessary. Depending on the function you are optimizing, different
565
initial conditions may lead to drastically different optima.
567
The solution process is iterative and you must click on a button to run
568
a certain number of iterations. You should see the parameters change and a
569
curve created with these parameters. In this example, the exact solution is
570
reached within 5 steps. More parameters and more difficult functions may require
571
more steps in which case you may choose to run 20 or 100 or more steps. The
572
newly created optimized curve should converge with an increasing number of
575
As in linear curve fitting, you can choose to load the fit function at
576
the points of the original curve, over an arbitrary range or load the error
577
at each point. For comparison, load the fitted curve over the range (3,4) by
578
selecting Nonlinear:Options/Load/Function and filling in the bottom of the
579
widget. How does the true answer compare to your previous extrapolation?
581
Fitting arbitrary curves can be a tricky business. Initial conditions are
582
very important. If you don't get a good fit, you may have to experiment a lot
583
with the initial parameters values.
585
Finally, note that the fitted curve does not get added until the accept
586
button is pressed. This allows you to "fool around" until you get a good fit
587
without creating a lot of garbage sets.
596
You can rotate sets around an arbitrary axis perpendicular to the canvas
597
(e.g. the Z-axis). Also it is possible to scale sets and translate them.
599
Mathematical operations between sets
601
It is possible to perform operations between sets. With many operations,
602
however, it is required that the 2 sets have the identical abscissa, i.e.,
603
the x values of both sets are the exact same. This is necessary since most
604
operations are performed on a point by point basis. Eg. multiplying 2 sets
605
is done by multiplying the Y values of the 2 sets together to produce a new
606
Y value. About the only operations that don't do this are filtering and convolution.
607
Fortunately, Grace has a function to help out when the abscissas differ. It
608
is called interpolation which interpolates a set over the domain of another
609
set to produce a new curve.
612
Let us now add the cosine of a set to the sine of another set to create
613
a new curve. However, we will complicate this example by having different domains
614
with different sampling:
621
Note how the abscissa are different. We begin by using interpolate to produce
622
a third set which is the second set sampled at the x values of the first. Call
623
up the Interpolate popup from <em>Main:Data/Transformations/Interpolation/splines ...</em>
625
Select S1 as the source set but don't specify a destination set. A set
626
will automatically be made. Use the Strict, linear method, Sampling:Abscissas
627
of another set and use S0 as the Sampling set. Pressing Apply should produce
628
a curve which is S1 interpolated at the points of S0. Note that the new curve
629
only exists over the portion of the x axis common to both curves.
631
We still have a problem since set 2 is sampled the same as set 0 but has
632
a smaller domain. We can perform the computation only over the common region
633
so we now interpolate on set 0 at points from set 2 to produce set 3. Now set
634
2 and set 3 have the exact same abscissas.
636
Call up the command interpreter from <em>Main:Window/Commands</em> ...
638
We need to create a set to hold the result, S4. We can either make a copy
639
(using <em>Main:Edit/Set_operations...</em>) of S2 which will be guaranteed to have
640
the proper size to hold out result or we can use type a command: <tt>s4 length
643
We have to break up the computation into an x part and a y part. In this
644
instance, we simply wish to keep the same x values. The final result will be
645
put into set 4, so we issue the command: <tt>s4.x = s2.x</tt>
647
Now we can perform the math between our interpolated copies of sets 0 and
648
1: <tt>s4.y = cos(s3.y) + sin(s2.y)</tt>.
650
So where is the new set? It's there but it's hidden. Since we already have
651
the command window open, we can unhide the set by typing: <tt>S4 on</tt>. For the GUI
652
minded (no offense intended), bring up a set list with the set operations menu
653
(eg. <em>Main:Edit/Data_sets</em> or <em>Main:Plot/Set_appearance</em>),
654
select set 4 and unhide it by selecting show from the operation menu (mouse button 3).
657
N.B. If the abscissas of the original curves had been the same, we could
658
have started at step 5. If the sampling had been the same we could have skipped
664
Feature extraction is a way of creating one curve from a family of curves.
665
It generates one data point from each curve by measuring a characteristic of
666
the curve. For example, one might have a series of curves which plot the gnat
667
population as a function of time. Each curve is produced by varying some condition,
668
like the number of gnus in the environment. Using feature extraction, one could
669
use this family of curves to produce a new curve of the peak number of gnats
670
as a function of gnus or the time of the peak number of gnats as a function
671
of the number of gnus. This is most often useful with more than one graph.
676
Read in graph 7.1.3.agr
678
Bring up the feature extraction form by clicking on
679
<em>Main:Data/Transformations/Feature_extraction</em>.
682
Select Results to graph 1.
684
Select the feature you are interested in. Choose Y maximum.
686
Select what will determine the x value of the data point. The value of
687
the characteristic determines the Y value. The X value can be determined by
688
the set number. The x or y values of a specified set can also be used to produce
689
the abscissa. Finally, the legend entry of the curve itself can be used to
690
produce the x value. In this case, the legend entry must be specified as a
691
single number. Choose index for now.
693
Press accept, click on graph 1 and then click on the autoscale button to
696
Choose another feature, like frequency, this time and get X values from
697
the legend. Make sure that graph 0 has the focus when you hit accept.
702
Often we only wish to examine part of a data set or perform transformations
703
only on a portion of one. Restrictions allow us to define a region of the graph
704
on which to perform operations.
709
There are several ways a region may be defined. It may be defined by a
710
straight line (left of, right of, above, below), by a polygon (inside or outside),
711
or by a range ( in x, out of x, in y, out of y). Call the define region popup
712
from <em>Main:Edit/Regions/Define</em>. Choose which one of the regions you would like
713
to define, and press the define button.
718
Line type</tag>Define the ends of the line by clicking with mouse button
721
Polygon type</tag>From the define region popup, choose a polygon type and
722
then the define button. Use mouse button 1 to pick the vertices of the polygon
723
and then mouse button 3 when you are done.
725
Range type</tag>From the define region popup, choose a range type and then
726
pick 2 points which define the range.
731
Regions may be only be used to restrict an expression evaluation. Bring
732
up the evaluateExpressions popup (<em>Main:Data/Transformations/Evaluate_expression</em>).
733
Choose the source and destination sets and specify the formula to apply to
734
the region of interest. Not specifying an expression is equivalent to the identity
735
transformation. Choose the region you wish to use. By checking negate, the
736
complement of the specified region is used.
739
Click on Apply to perform the operation. The resultant set will be the
740
expression evaluated only on points contained in the specified region. Thus,
741
if no expression was specified, the effect is to produce a new set of only
742
those points contained in the region. Conversely, to delete points in a region,
743
leave the expression empty, and negate the region selection.
748
Pipes are a way of capturing the output of a running process without the
749
intermediary step of pacing the output in a file. Instead, the executing program
750
puts the data in one end of the pipe, and Grace reads it from the other end
754
Instead of data files
756
On certain popups, e.g. <em>Main:Data/Import/ASCII</em>, the option to read from
757
a file or pipe can be specified. If a pipe is chosen, the command in the selection
758
widget will be run and the stdout will be captured and treated as though it
759
was data which was read from a file.
764
A named pipe is a special case of the pipe previously described. In the
765
previous case, after the program has finished execution and the output had
766
been read, the pipe was destroyed. A named pipe is a static structure with
767
the property that multiple processes can write to and/or read from it. The
768
purpose of using a named pipe with Grace is to start up a Grace window and
769
then control Grace by sending commands and data through a named pipe. This
770
is very powerful and lets you do practically anything you can do directly from
771
the GUI. To use this feature, try the following:
776
Start a named pipe (you will have to find the command specific to your
777
operating system. For example, it could be <em>mkfifo</em> or <em>mknod</em>): <tt>mkfifo pvc</tt>. If
778
you do a directory listing, you should see the file pvc.
780
Start up Grace in the background using the named pipe option: <tt>xmgrace</tt><tt><em> -</em>npipe</tt><em>
781
</em><em><tt></tt></em><tt>p</tt><tt><em>v</em>c</tt>&. Grace is now monitoring the pipe for any data which might be sent
782
to it. It will interpret things as though they were entered using the command
785
For a simple test, we will create a simple graph over the pipe. From your
786
command line, type: <tt>echo "read \"8.2.dat\"" > pvc</tt><bf>. </bf>(The back slashes
787
are needed to escape the quotation marks so that Grace really received the
788
command :read "8.2.dat".) This just told Grace to read the file data. Now we
789
would like to autoscale. We could simply click on the button but the point
790
is to use a named pipe. This time we type <tt>echo</tt><em> </em><em><tt></tt></em><tt>autoscale > pvc</tt><em> </em>followed
791
by<em> </em><em><tt></tt></em><tt>echo redraw > pvc</tt><em>.</em> Your graph should now have autoscaled and redrawn.
792
Exit Grace with <tt>echo</tt><tt><em> </em>exit</tt><tt><em> > </em>pvc</tt>. You should also clean up by removing pvc.
794
The true power in named pipes lies in driving Grace using another program.
795
The controlling program can open a named pipe for writing, which is treated
796
as an ordinary file. It can be opened with the <em>fopen()</em> function or whatever
797
other I/O function you prefer. Commands and data are then written to the file
798
where they are interpreted by Grace.
805
When multiple graphs are present, a graph is selected by clicking inside
806
the graph frame. In cases where graph frames overlap, clicking will cycle among
807
the overlapping graphs.
810
It might be annoying if one is trying to work in a region of overlapping
811
graphs. If will not be possible to double click on something because the each
812
click will be interpreted as a single click and you will only end up changing
813
the graph focus. In such an instance, turning off the graph selection by clicking
814
might be desirable. Choose <em>Main:Edit/Preferences</em> and then set
815
<em>Misc:Graph_focus</em> to "As set". This means one must explicitly set
816
the focus. Simply bring up a graph list (eg. <em>Main:Edit/Overlay_graphs</em>
817
is but one), select the graph you want to work on and then, using the menu under
818
mouse button 3, choose "Focus to".
821
Arranging a tableau of graphs
823
Placing a large number of regularly spaced graphs is easily done with
824
<em>Main:Edit/Arrange_graphs</em>. This will automatically calculate the layout:
829
Choose 3 rows and 3 columns and Apply. You should now see 9 graphs. The
830
Order button refers to the way the graphs are numbered. The beginning of the
831
line on the diagram of the button shows which graph is numbered 0 and how the
832
numbers increase, by row or column.
834
You realize you need horizontal packing, i.e. no horizontal gap between
835
graphs. Click on the Pack button beside the Hgap/width input and then Apply.
837
Suddenly, you realize you only need 6 graphs and not 9. Choose 2 rows and
838
press Apply. There is a slight problem as graphs 6, 7 an 8 are still visible.
839
This is a feature since you don't want to accidentally kill a graph. You can
840
kill the extra graphs by clicking on the "Kill extra graphs" check box. Now,
841
any graphs other than the explicitly arranged ones will be automatically killed.
843
The margins are controlled by the Page Offsets, and the intergraph spacing
844
by the Hgap and Vgap inputs.
846
Press close to remove the window.
850
Note that only graphs which are selected are taken into consideration.
851
So, if you wish to reorganize your existing graphs, make sure they are selected
852
or new ones may be created.
855
Arranging individual graphs
857
Arranging individual graphs may either be done (1) exactly, by specifying
858
the viewport coordinates from <em>Main:Plot/Graph_appearance</em> or
859
using the previously explained Arrange graphs popup, or (2) roughly,
860
by double clicking a graph focus marker and then moving it.
865
Overlaying one graph onto another is useful for creating a graph with two
866
different x axes and/or y axes. For example, you may wish to have a graph which
867
on the x axis has the month of the year. There could be 2 curves on it, one
868
using the left y axis which is number of gnus sold and one using the right
869
y-axis which is the number of gnats exported on a logarithmic scale. Likewise,
870
if one is plotting spectral data, one could have one x axis in Hz and another
871
one in wavelength. Let's proceed with an example:data
876
Begin by selecting <em>Main:Edit/Overlay graphs</em> to bring up the Overlay widget.
879
Select the graph numbers with which we would like to deal. In this example,
880
we will overlay graph 1 onto graph 0. At this point, only graph 0 is visible.
881
We cannot see Graph 1 to select since it does not exist at this point. We need
882
to create simply by pressing mouse button 3 in a graph list window and selecting
885
The overlay type is determined by what is common among the overlayed graphs.
886
In our example, the x axis is common so we will select <em>X-axes same, Y-axes
887
different. </em>This is important because we don't want to alter any axes of the
888
Overlay graph which we set the same as the underlay graph. In this example,
889
we don't want to alter the x-axis of graph 1.
891
We are now ready to label the graph axes and read the data. One thing we
892
must be careful to do is to always make sure that we are working on the intended
893
graph. Seeing as the graphs are overlain, clicking within the frame is ambiguous
894
as to what graph is selected. The rule is that in a region of overlay, clicking
895
will cycle between the graphs. Hence, if graph 1 is selecting, clicking within
896
the frame will toggle to graph 0.
898
Making sure that graph 0 is active, bring up the Axis properties widget.
899
Now set the y axis title to Gnus.
901
Select graph 1 as active as set the title as Gnats. Notice how it overlaps
902
the Gnus. We want to put this on the right side. From the axis label and bar
903
tab, select label Properties/Side=Opposite.
905
Label the x axis to label it. If graph 1 is the current graph, noticed
906
how it is greyed out because only 1 x axis need be active. Select graph 0 and
907
you should now be able to alter the axis label.
909
You are ready to read in data. Just make sure the graph that is active
910
when you read in the data (or create your set) is the one in which you intend
916
Hot links are a way of of updating a set without having to delete it first
917
and then reread it. The Hot Links window is opened available under <em>Main:Data/Hot
921
File containing a Single Set
923
The simplest hot link is to a file containing just one set. To make a hot
924
link to a single set, we must first select the set we want to get updated and
925
then specify the file. We may also link to a pipe in which case we must specify
926
it is a pipe to which we are linking. A command may also be entered which will
927
be run every time the hot link is updated. A common command might be autoscale
928
which will make sure that the entire set can be seen if it changes size. It's
929
possible you may want to execute more commands than one. One could, for example,
930
have a set that is a function of 2 sets that needs to be recomputed if either
931
set is updated. If this is the case, put your commands in a file and then use
932
the "READ BATCH" command.
935
Pressing the Link button will now create the link and if the update button
936
is pressed, the set will be updated with the current contents of the file you
937
linked and the contents of the Command widget will be executed.
940
For a simple example, read in the set 10.1.dat and set up the hot link.
941
Now, run the command shiftdata.sh and update the hotlink. You should have seen
942
the peak in the graph shift. Try repeating this a couple of more times.
945
Multiple sets within a file
947
Sometimes a data file may contain multiple columns of data and we would
948
like to be able to link to all or some of those columns. To specify this, select
949
as many sets as there are xy columns of data in the file. The "x y1 y2" format
950
is assumed. Choose the file the data and <em>link</em>. Now in the link list, the links
951
will show the file name with an appended colon and number. The number tells
952
what column of data the link refers to. Any unwanted columns may be selected
953
and unlinked at this point. When the update button is selected, all sets in
954
the graph will be updated.
959
Instead of having to keep the Hot links window open all the time, the update
960
action is bound to alt-u. If you find that alt-u has no effect, try double
961
clicking inside the graph you want to update and close the window that pops
962
up. This will "alert" the canvas to process future hot key strokes.
added
removed
doc/Tutorial.sgml
