A Brief Graffer Tutorial
Contents
The object of this tutorial is to get you started by demonstrating the
main ways of creating and modifying datasets.
Note: To see the included images properly you will need to set the
width of you viewer to about 950 pixels. For the benefit of users with
text-based browsers, the embedded images have links to themselves so
you can download them to a viewer.
The items here are examples of the ways in which it is possible to
create a dataset which can be read into GRAFFER.
In many cases, particularly if the data originate from outside IDL,
the easiest way to create a dataset is to put the values into a file
and then read the file into GRAFFER.
Create the following files using your favourite editor:
- test.dat
-
0.1 1.2 0.1
0.3 3.7 0.22
0.6 1.22 0.1
0.8 0.65 0.05
1.1 0.02 0.01
1.7 0.001 0.001
This file is will yield an XY plot with errors on the Y values.
- test2.dat
-
#XX
-.3 -.22 .1 .05
-.1 -.57 .2 .1
.15 -0.61 .1 .1
.3 .2 .05 .05
.5 3.1 .1 inf
This file is will yield an XY plot with errors on the X values with
the error bars being different lengths in the plus & minus
directions. The infinite value on the last error will yield a limit
(this may not work on VMS platforms).
This file is will yield an XY plot with errors on the Y values.
IDL Variables
The second major way to get data into GRAFFER is from variables at the
main program level.
You should now enter IDL and ensure that the graffer
routines are in your search path. e.g. (the syntax here is suitable
for a unix system):
$ idl
< IDL entry messages >
IDL> !PATH = '/datan9f/sjt/graffer:'+!PATH ; Or wherever GRAFFER is located
We now want to create two arrays with our X & Y values.
IDL> x = findgen(21)/10. - 1. ; Values -1 to 1
IDL> y = exp(-(x^2)*2.)*(1+randomu(seed,21)*.2) ; a Gaussian + noise
Start Graffer
Having prepared the materials that we shall need, we can now start up
GRAFFER.
IDL> graffer, 'test.grf'
This will generate the main GRAFFER window with an empty file.
The main GRAFFER window, before the entry of data
If you have a small screen it is possible that you will find that
GRAFFER starts up in compact mode with two windows. The functions are
the same but the locations of the buttons driving them may be
different. For a more detailed discussion of the compact mode see below.
The first dataset
We can now add the first dataset, this is the data you have entered
into test.dat. Find the button marked "XY Data"
towards the lower right of the control panel, when you click on it it
will generate a pulldown menu. Select the "From file" option. This
will produce the file selector pop-up menu from which you can select
"test.dat".
The File chooser for reading a dataset from a file
Click on the filename and then on the "OK" button, this will load the
dataset into GRAFFER.
You should now see two changes, firstly part of the dataset will
appear in the plotting window and secondly a button with a cross on it
will appear in the far lower right of the window, this is a indicator
that the file has been changed since the last time it was saved.
Scaling the axes to the data
You will also see that only one point from the dataset actually appears
on the plot because the default range of the plot is not suitable for
this dataset. To match the range of the plot to the dataset(s)
present, find the X & Y axis control panels (to the left of the
main plotting window. For each axis in turn, click on the X (or Y)
style button to generate the style pulldown. Right at the bottom of
the pulldown is an item "Autoscale" which in turn generates
a further pulldown with two options: "Extend" and
"Extend or shrink", selecting the latter will scale the
axes to show all the data.
Setting the dataset attributes
There are several attributes that can be set for a dataset. With the
exception of the dataset name, all the pulldowns and entry boxes are
under the main plotting window.
-
Name
- The name of a dataset is just a descriptive tag which identifies
it to the user. This field is also used if a key or legend is added to
the plot. To give the dataset a name, move the cursor into the
"DS Name:" box on the lower left of the main window and
enter: Test DS 1.
-
Symbol
- Any of IDL's predefined plotting symbols may be used to mark the
data points, along with a number defined internally by GRAFFER. To
select a symbol, use the Symbol: pulldown. Pull it down and
select the filled diamond. You should now see that each point is
marked with a small filled diamond.
Now make the symbol bigger by moving the cursor into the
Size: box, deleting the current value of 1.0 and
entering 2.5. You should now see that the diamonds are much bigger,
and also that the caps on the error bars are enlarged.
-
Line
- Now modify the properties of the line joining the points.
First: Pull down the Join: pulldown and select the
"Histo" option. This will change the line joining the
points to a sort of histogram form.
Next: Change to a dashed line by pulling down the Style
menu and selecting the short-dashed line.
Finally: Move the cursor into the Thick entry box, delete
the current value of 1 and enter 3.
The main window should now look like this:
The main GRAFFER window after the addition of the first
dataset.
Save the file
You should now save the file. There are two ways to do this:
- The simple way is just to click on the change indicator
button. This will save the file under its current name in binary
format.
- If you want to change the name, or to save in ASCII format, then
you need to pull down the Save pulldown at the top left of
the main window and select the appropriate option. The main reason
for using ASCII format is to make a file which can be transported to a
different system.
Whichever method you use, the change indicator should disappear,
indicating that the file in memory has not been changed since the last
save.
A second dataset
It is often necessary to put several plots on a single set of
axes. GRAFFER allows you to do this by means of multiple datasets.
For our second dataset we will use the x & y arrays you created
before you entered GRAFFER.
The first step is to create a new dataset to receive the values and
make it current (otherwise you'll just replace the current dataset). To
do this click on the "New" button towards the lower left of
the main window. When you do this you should see that all the dataset
properties displayed below the main plot panel revert to the default
settings.
This time let us set the dataset properties before we load the
dataset. Set the name to "Test DS 2", the symbol to an
asterisk, the joining to None and the symbol size to
2.0. Finally set the colour to blue using the colour pulldown.
Now go to the XY data and select the top-level
variables option. This will generate the top-level variables
pop-up.
The top-level variables pop-up
You will see that there are six entry boxes, of which only two are
enabled. The remaining four are for error limits and are enabled as
needed by the errors pulldown. For this dataset however we
do not have any errors, so we just need to enter the x and y variable
names. Move the cursor into the X variable box and enter
x, then go to the Y variable box and enter
y. Finally, click on the Do it button.
You should now see two changes, the blue asterisks that have appeared
in the plot window and the reappearance of the change indicator.
Now rescale the plot axes in the X direction, using the X
Style pulldown. This will bring the whole dataset into view.
Adding annotation
Now let us add some annotations to the plot:
-
Plot title
- Move the cursor into the Title box near the upper left
of the main GRAFFER window and type in GRAFFER Tutorial
plot. This text will appear at the top of the plot.
-
Axes
- Each axis can have a label. To add a label to the X axis move the
cursor into the X label box and type:
Displacement. Now go to the Y label box and
type: Speed (km s!u-1!n).
You may feel the text of the annotations is rather small, so go to the
Charsize box in the upper left part of the main window and
replace 1.0 with 1.5.
Now save the plot by clicking on the change indicator.
You should now see your main window looking like this:
The main window after the addition of the second dataset.
Now exit from GRAFFER by clicking on the Exit button at the
extreme top left of the window.
Restart in compact mode
Now restart GRAFFER with the compact key set:
IDL> graffer, 'test.grf', /compact
Now instead of the single large window you will see two smaller
windows, one with all the control buttons and the other with the
plotting window alone. When you move the cursor from one to the other
the window entered will be popped to the front.
The GRAFFER compact-mode control panel
The GRAFFER compact-mode plot panel
Now add another new dataset from test2.dat.
- Make a new data set by clicking on the New button
- Set its name to Test DS 3
- Read in the dataset via the XY Data From
File option.
- Rescale the Y axis.
- Change the colour to Red, the thickness to 3 and the symbol size
to 2.
Note the appearance of the final point which has a infinite error in
the +X direction. GRAFFER uses "Infinite" errors to denote limits.
Add a function dataset
In addition to plotting data, GRAFFER can also plot functions. A
function can be any IDL expression which when given an array argument
returns another array of the same length.
- Create another new dataset.
- Call it Function 1
- Pull down the Function pulldown and select the y
= f(x)... option. This will generate the function definition
popup.
The GRAFFER function definition menu
- Enter the function x^2 * beselj(x,1) into the
Function entry box. Leave the limits and evaluation count
as they are.
A more complicated function example
Let us now add another function to demonstrate some of the other
features of functions.
- Create another new dataset with the New button.
- Name it "Parametric function.
- Set it to have a magenta long-dashed line of thickness 2.
- Select the x=f(t) & y=g(t) option of the
Function pulldown. This will generate the parametric
function pop-up.
- Enter the function sin(10*t)^2 in the X function box
and sin(3*t)+.5 in the Y function box
- Change the upper limit from 1 to 6.28 (i.e. 2*pi).
The Parametric function entry pop-up
- Click on Do it.
You should notice that the function is very obviously made up of
straight-line segments. This is because unlike the previous function,
25 evaluations are insufficient. To rectify this, re-invoke the
parametric function pop-up; it will appear with the functions and
limits displayed. Now change the number of evaluations to 200 and
click on Do it.
Your plot window should now look like this.
Save the plot by clicking on the change indicator.
Selecting and editing datasets
For a graphing tool to be useful it must be possible to go back and
alter the properties and even the values in previously defined
datasets.
GRAFFER provides two ways to select datasets:
- Using the Next and Previous buttons in the
dataset operations panel which
make respectively the next or the previous dataset the current
one. These are both cyclical; i.e. the next dataset after the last is
the first.
- With the dataset selector pop-up, which is activated by the
Select... option of the Other pulldown in the
dataset operations area.
Select the first dataset
Pull down the Other pulldown and choose the
Select... option. The selection pop-up should appear as
shown below:
The dataset selection menu
The fields are:
- The dataset index number
- The number of points in the dataset
- Whether the dataset is current
- The type of data in the dataset, most items should be obvious
except that F denotes errors in the X values.
- The name of the dataset
Click on dataset number 1 (Test DS 1).
Edit some of the values
Goto the XY Data pulldown and select the Edit
Values option. This will generate the Data input and editing
pop-up.
The GRAFFER data entry and editing widget
Now do the following:
Now change the Join option to None.
Safety lock
GRAFFER will not allow you to inadvertently destroy a modified file. To
demonstrate this, now click on the Exit button. Instead of
exiting immediately, a warning window will appear.
The warning generated when a modified file would be destroyed by
the selected operation.
This allows you to cancel the operation, save the file or to continue
and destroy your changes (e.g. if you just made a mess of
things). Click on the CANCEL option. Save the file by
clicking on the change indicator.
Adding text strings
In addition to the standard IDL plot annotations, GRAFFER can also put
strings in arbitrary locations on the plot.
- Go to the Draw/text mode pulldown and select
Text mode. You will see that the cross hairs are now dashed
instead of solid when you move the cursor in the plotting window and
that they now extend to the edge of the plotting window.
- Move the cursor to a blank area in the upper right of the plot
and click with the left mouse button. The text-entry pop-up
will now appear.
The GRAFFER text entry widget
- Enter the string Message in the Text
box. You should see the string reflected in the window above the text
box. This indicates the size and font of the text as it will appear on
the plot.
- Change the Charsize to 2.0. and select the
Complex Roman font.
- Click on Update. You will now see the text appear on
the main plot.
- Now change the orientation to 60. (This is not reflected in the
window on the editor for practical reasons).
- Click on Done.
Note the little arrow by the text string; this marks the Anchor
point of the text. If you want to edit an existing text string
you must click with the centre mouse button within 5 pixels of the
anchor point. To delete a text string click the right mouse
button within 5 pixels of the anchor point.
Print the plot
All this would be of little use if you could only admire your
handiwork by looking at it on the screen.
To print the file, select the Set up... option of the
Hard copy pulldown. This will produce the hardcopy pop-up
to set the hard copy options.
The GRAFFER hardcopy option setter
The default settings are suitable for printing the file to a printer
with A4 size paper on a SYSV Unix system. For other systems
you may need to change options to produce the required output.
Set those options which you need to change and click on the Do
it button. The options are stored in the file so that you will
not need to reset them unless you actually want to change the
settings.
One item which may need some explanation is the middle button of the
pulldown menus at the top of the panel. This controls whether the file
is a normal PostScript file (suitable for printing) or an Encapsulated
PostScript file (suitable for including into (e.g.) a LaTeX
document).
Save the file, exit from graffer and from IDL.
Conclusion
This tutorial does not cover by any means all of the facilities of
GRAFFER. For more details you should consult the
GRAFFER manual.
You will probably already have noticed that in the main menu and some
of the more complex pop-ups a brief description of the function of a
button is displayed when the cursor is placed over that button.