1. Tutorial
It is easy to get familiar with this package, just open this file on-line, and follow the steps in this section.
1.1. [The
Graph command]
Issue the following commands in the CommandTool:
% BringOver -p /DATools/DATools6.0/Top/Graph.df
% Graph Simple.list -- a command to plot data in the file, Simple.list.
You would see a Graph viewer created on the color monitor from ascii data in the file Simple.list. Open Simple.list and see what's in there.
Fine point: The Graph viewer would be created on the left (or right) column if you had an entry in the user profile saying: Graph.Column: left (or right, instead of color).
1.2. [The
Color menu]
Follow these simple steps below to try with the Color menu.
1.2.1. Click the
Color menu, and select the "black and white" entry in the pop-up menu.
-- the graph should become black and white.
1.2.2. Click the
Color menu again, and select the "
my colors" entry.
-- the graph should resume its original colors.
1.2.3. Now click the same menu and select the "cedar default colors" entry.
-- the whole screen may turn into some kind of grayish color.
1.2.4. Then click the same menu and select the "my colors" entry.
-- the graph should resume its original colors.
This menu is not only useful for you to customize your own colors (see 3.1.1.), but also useful when you are running more than one programs that fiddle the color map. The maps used by these programs may not agree with each other. This menu can be used to resume the desired colors for your graph when another program has changed the color map.
This is why the first entry in the pop up menu is labeled "my colors", instead of "current colors".
1.3. [The
Cursor and
Background menus]
Try all options with the Cursor and Background menus and see what effects each command listed on the pop-up menus have.
When background is black or dark gray, in order for the axes, ticks, grids, and all black texts to be visible, they are displayed in white.
1.4. [The
List menu]
Select the text "Foo" (don't include the double quotes) and click the List menu. A pop up menu would show up asking you to confirm listing the data in the graph into Foo.list. Confirm it by moving the cursor into the only white entry in the pop up menu and click. You will see a viewer opened up and moved to top of its column, displaying the file Foo.list, which contains a listing of the names of the variables in this graph, and a matrix of the x and y values. Are the variables and values the same as those in Simple.list, from which the graph was created? They should be. Now close the listing, or destroy it if you like.
1.5. [The
Get menu]
Select the text "Waves" (don't include the double quotes) and click the Get menu. A pop up menu should show up asking you to confirm replacing the graph with "[]<>...>Waves.graph". Now confirm it by moving the cursor into the only white entry in the pop up menu. This menu is similar to the Get menu on a tioga viewer. You will see a different graph displayed in the Graph viewer, and the caption of the viewer is changed, indicating where the data came from.
1.6. [The
Merge menu]
Select the text "Simple.list" (don't include the double quotes) and click the Merge menu. Confirm by clicking in the entry showing "[]<>...>Simple.list". This is different from the previous Get menu in that the previous graph remains, and new graph is merged together with the old. The name of the viewer should remain as []<>...>Waves.graph.
1.7. [The
Store menu]
Now select "Foo" and click the
Store menu. You will see a message in the Message Viewer saying that "Foo.graph" has been written. This file should contain all plotting information currently displayed on the Graph viewer. You might want to verify it by typing the following in the CommandTool
% graph foo.graph
You will see another Graph viewer created with the same curves in it, except that two curves seem to be "missing".
Two curves are missing?
No, in fact they are not. They are not displayed for the following reason. It is often the case that there may be many curves in a graph file. The graph will be too busy, if we always plot all of them out. As you will see in the following sections, it is very easy to show the "missing" curves to the graph or erase plotted curves from the graph. Therefore this program arbitrarily chooses six as the limit for the number of curves to be diplayed initially when a graph file is read.
1.8. [The
Controller menu]
Close the new viewer created by the exercise in 1.7., and open Waves.graph to go on from where we were with some other interesting things. Click the Controller menu on the Graph viewer, and you will see the controller's viewer created. There should be two lines of menus on top of the controller's viewer. Below the menus is a "spec" control panel with some bold-faced entry buttons, and some fields following each entries. If you have clicked the Controller menu, destroy the Graph viewer. -- Yes, destroy the graph!
1.9. [The
Chart,
Spec,
Values,
Table, and
Levels menus]
There are five menus on the first line of menus on the controller, namely,
Chart,
Spec,
Values,
Table, and
Levels. Click at each of them a couple of times and see what the effects are.
When Chart is clicked, the Graph viewer should be created for you, if it has been destroyed. Otherwise it will show up as the top viewer in its column.
Below the menus can be a spec panel, a values panel, or a table of all texts and curves in the graph. When Spec, Values, or Table is clicked, one of them will show up, replacing the others.
The Levels menu and the third line of menus associated with it are the same as those on a tioga viewer to change the level of display for the table of texts and curves.
1.10. [The
Spec panel]
Lets take a look at the spec panel first. (Click the Spec menu on the controller, if the spec panel has disappeared.) There are nine entries on the spec. Each entry has a bold-faced "entry button". Following the entry button are some "fields".
Each boolean field is enclosed by a bounding box. If the color of the text in the box is white on black background, it means that the field value is TRUE; if it is black texts on white background, it means FALSE.
The top five entry buttons are a little different from the other four in that, they don't have a parameter enclosed by parentheses. The parameter is either an index or an id. It is necessary for the latter four entries to have a parameter, because there may be quite a few items associated with each of these entries. For example, there may be many curves in a graph.
1.11. [Showing the spec] - red
Left clicking an entry button, we will see field values in the program's memory for the entry displayed on the panel.
As an exercise, set the id: parameter of the Curve entry to 9, and red-click the Curve entry. It will show the specification for curve number 9, called "Third Y" in your graph.
1.12. [Changing the spec] - control-red
It's simple to change the spec in your graph, too. Lets play with the auto-divisions feature. Click the Auto field in the Divisions: entry so that it shows black letters on white background, meaning FALSE; and set the x: value in the Divisions: entry to 6. With the control key pressed down, red-click the entry button (Divisions:). You will see the number of x divisions on the graph becomes six, as we just specified.
In general, clicking any of the entry button with control-red, will update the values of the associated fields (e.g., the divisions in this example) according to the specified values in the entry on the spec panel.
It is worth noting that, as we can alter the field values at any time, fields values displayed on the spec panel may be different from the current values in the program's memory until you click the entry button with control-red, or red.
1.13. [Adding text or curve] - control-red
We can add new text (or curve) by control-red clicking at the
Text (or
Curve) entry, if only its id has not been used by any other texts (or curves) already in the program's memory. As an exercise, set the
id: parameter of the
Text entry to 1, and set the other fields as follows:
Text( id: 1
):
name: XEROX
place x: 0 x-justification: left (just click at it) y: 1.1 y-justification: center
color: 3 font: 10 rotation: 0
Check if you have made the right changes as listed above. Now control-red click the Text entry button on the spec panel. You shall see the XEROX logo close to the upper left corner of the graph.
Text's location is relative.
Note that the location of a text is not represented in the same way as all the other things in the graph. It is taking the lower-left corner of the bounding axes as the origin, the width and height of the bounding box as the unit length for x and y. One of the reasons to choose this representation for texts' locations is to make sure that texts won't go away when user changes the bounds for x and y.
Fine point: If you are curious, there was already one "text" in the graph, the title "Waves", with id = 0.
1.14. [Removing text or curve] - blue
The text (or curve) on the graph may be removed by many ways. One of the ways is to use the spec panel. All it takes is to set the text's (or curve's) id in the id: field, and blue-click the entry button. As an exercise, blue click the Curve entry button. What if you red-click at it again?
If the text (or curve) with the specified id has been in the program's memory, but not plotted on the graph, red-clicking at the entry button will plot it out, if its id is specified in the id: field.
1.15. [Integer fields and enumerated fields]
You should have learned how to set the "enumerated" field such as the justification fields for a text. (Recall what you did in creating the XEROX logo.) There is a different "enumerated" field on the spec panel, namely, the mark: field for a curve. Probably by intuition, you will know how to red or blue click at it to change its value.
You can increment (or decrement) an integer field's value (such as an index or an id) by shift-red (or shift-blue) clicking at the field label.
Now try this: if you have red-clicked the Curve entry with id = 9, it should be showing the spec for the curve named "Third Y". Shift-red clicking its color: label to show 12, and click with red or blue at the the mark: label so that its value shows "dollor". Then control-red click the Curve entry button. What do you get?
1.16. [Toggle menus on controller]
We have learned about the spec panel. Now lets take a look at the second line of menus on the controller. They are in fact software toggles. In general, red-clicking any of them turns on the associated feature, while blue-clicking turns it off.
As an exercise, red or blue click the AutoDiv menu a couple of times, and observe the changes on the Graph viewer as well as the spec panel. As another exercise, click the GridX or GridY menus with red or blue button.
1.17. [The
Clear
/ Refresh menu]
If you have removed some curves or grids from the graph, you might have noticed that the remaining curves on the graph are broken. It's OK. We can refresh the graph by the Clear/Refresh menu on the Graph viewer. If you click at it, a pop up menu will show up listing four options.
Select the first option, and observe what it does to the graph.
The second option will do the same thing, but it will clear the screen first. This option is provided in case the graph gets dirty for some reasons. The third option will update the divisions and/or bounds if autoDivision and/or autoBounds are TRUE.
What will the last option do? To see if you are correct, just try it. Yes, try it!
1.18. [The table of texts and curves]
You might have removed all the curves from the graph, I guess. Don't regret, for there are plenty of ways to get your curves back. Now lets go ahead with some other interesting things to try.
Click the Table menu on the controller. Do you see a list of all the texts and curves that were on your graph? Red-click the text "Wave # 1" and see what will happen. What do you think it may happen if you blue-click at it again? -- You're probably right.
How about blue-clicking at the texts on the table? And how about red-clicking at them? Try it.
Isn't it fun?
1.19. [The Values panel]
Use the "skills" you just learned and display all the texts and curves back on the graph. Then click the Values menu on the first line of menus on the controller.
There are two areas on the values panel separated by a thin line. We will talk about the math operations in the first area later. There are two bold-faced buttons in the second area, namely, curve and cross-section.
Red and control-red works on the curve button in a way similar to clicking at entry buttons on the spec panel. As an exercise, set its id: field to 7 and left click the curve button. It should show the (x, y) pairs for the curve number 7 (the "First Y" in your graph). Its x values are 0, 1, 2, 3, and 4, with corresponding y values being 1, 2, 3, 4, and 5. Generally a carriage return is automatically inserted after every four pairs, and a comment is inserted there to tell us which pair the last one on that line is.
Now lets change the y value of the second pair from 2.0 to 2.5, and click at the curve button with control-red. What does it do to this curve on the graph? It is not straight any more.
As to the
cross-section buttons, it only takes the red-click command at this time. The result is obvious, so lets skip it.
Fine points: In case you wonder who used the id number 6, it has been used by the x of the second group of curves. The first group of curves are those in Waves.graph, whose x uses the id 0; the second group of curves are those in Simple.list.
1.20. [The keyboard commands on the Graph viewer]
There are quite a few commands on the Graph viewer. Here is an introduction to some of them.
A. select a graph
It's easy to get a Graph viewer's attention, i.e., grab the input focus such that any keys typed won't show up elsewhere in other viewers. Just like for tioga viewers, clicking in a Graph viewer with red or yellow will get its attention. Clicking with red will also show up a cross hair, called "primary caret". Now try it.
B. select a curve
With the key for letter c (as in curve) pressed down, red-click at one of the waves. You don't have to move the cursor right on the curve, the caret should jump to the closest curve it finds.
Many curve-related commands are operated with the c key pressed down for an obvious reason.
C. remove the selected curve
What do you think the key should be for this? Yes, press the c key and click the blue button.
D. select a text
What should be the key? Well, pressing the t key (for text) and red-click inside a text should select it. A text caret will show up at the selected text's location. Note that the legend (or the labels for the ticks on axes) are properties of curves (or bounds), so they are not treated as normal selectable text. Now try to select the text "XEROX". The text caret for "XEROX" should be at the center of its left, because it was left and center justified by you in step 1.13.
E. move selected text
Now with t held down, yellow click at any place you like on the graph. The selected text should be moved there.
The following is a somewhat "advanced" command, to rotate the selected text:
With the t key and any of the "number key" (1..9) pressed down, click red. The text should be rotated for n*10 degrees, where n is the number the "number key" represents. If you click with blue instead of red, the same thing will happen, except that it will be turning clock wise.
F. removing selected text
I believe by now you probably already can guess how to do it. (Yes. t-blue.)
G. switches
The following are some of the keys to turn some of the features on (and off). Try some of them.
b: auto-bound
d: auto-division
ctrl-1, ctrl-2, ctrl-3: turns the primary, secondary, or text caret on (or off).
shift-1, shift-2, shift-3: starts or stops the primary, secondary, or text caret's blinking.
....
H. moving primary caret on curves
You can move the primary caret to any place on the graph by simple red clicking. In addition, there are some commands for you to move it on curves. For example, if you press the s key (for same curve or slide), and move the mouse, the primary caret will try to follow the cursor along the selected curve. (Of course it won't work if no curve is selected. Recall that a curve may be selected by c-red.)
Holding the h (or v) key down and click with red or blue, the primary caret will jump horizontally (or vertically) to another curve. Clicked with red, it will move left (or up); clicking with blue, it will move right (or down). To try it, select one of the "waves". Then holding the h key and click red or blue a few times.
If h (for horizontal) and s (for same curve) keys are both held down when red (or blue) button is clicked, the primary caret will jump to left (or right) to another point on the same curve.
J. for a complete list of the keyboard commands on a Graph viewer, see 4.2.
1.21. [Math operations]
Now lets try some math operations on the curves. (Click the Values menu on the controller, if the values panel has disappeared.) Make sure that the operand: field shows "selected y" in white letters on black background. Select one of the sinusoidal curves, and click abs. (The ABS function.)
Now click at Resume.
Put 2.5 in the argument field, and click at +.
1.22. [Hardcopy]
Now that you have a beautiful graph, you might want to make a hardcopy.
If you click the Interpress menu on the Graph viewer, there will be two options shown up in the pop up menu, namely, color or black-and-white. If you choose color, then it's better to print the interpress master through a color printer, otherwise you may not be able to distinguish curves easily.
Lets make a hardcopy through a black and white printer, say, RockNRoll. Select "Foo" (excluding the double quotes), and click the
Interpress menu. Choose black-and-white in the pop up menu, and confirm writing the interpress file Foo.ip. When you see a message saying it's written, type the following in the CommandTool:
% InterpressToPD Foo.pd ← Foo.ip raven384
% print -h rocknroll foo.pd
If RockNRoll is on line, wait a couple of minutes and go to RockNRoll to pick up the hardcopy of the graph.
Just to save the ink (or toner, or whatever) for the printer, the background color is always white for hardcopy, even if the background color is not white on the screen.
1.23. [Programming interface]
Issue the following command in the CommandTool:
% Waves
It will plot something out. If you want to see how simple this graph is created by some simple procedure calls, take a look at the file WavesImpl.mesa. It uses only some of the procedures in the interface called GraphOps. The procedures in GraphOps should be sufficient for most purposes, as far as drawing curves and texts are concerned. More information on the use of these procedures is documented in GraphOps.mesa.
If you are really ambitious, take a look at GraphPrivate, or even every module of the Graph package.
1.24. [Text input]
Open Simple.list. Do you find it very simple? Just list the names of variables, and a matrix of the x and y values, you can make what ever graphs you like. To plot it out, we can use the Get or Merge menus on a Graph viewer; or the Graph command in the CommandTool, as you have practiced.
Of course once we get it plotted, we can change the graph or add new things in it, using the commands or buttons on the Graph viewer and/or its controller.
1.25. [Congratulations]
You have completed this tutorial. Creating customized graphs is very easy for you now. For more information, please read the other parts of this documentation at your leisure.