PVWAVE is a powerful, yet easy to learn software package.
This document is intended to be a brief introduction to some of the features
of PVWAVE. For more detailed information, refer to the PVWAVE manuals (Tutorial,
User’s Guide, and Reference volumes) and to the software’s HELP screens,
which are quite useful and relatively thorough.
2. Starting PVWAVE
PVWAVE is currently only available on the ATM26 machine. To begin PVWAVE, log into ATM26 and at the UNIX prompt, enter
wave
PVWAVE should launch, and you should see a prompt that looks like the following:
WAVE>
If PVWAVE does not launch successfully, check for the following:
exit
2.1 Accessing On-Screen Help
PVWAVE’s help screens can be accessed at any time from the >WAVE prompt by entering
help, ‘<topic>’
PVWAVE will then open the Help screen for your topic.
If the topic is not found, the general Help screen will open. The interface
for the Help system is designed like the Help screens for the Windows 3.x
operating system (including "Contents", "Find", "Back" buttons, etc.).
Use Help frequently – it is thorough enough to be very useful.
3. Navigator
NAVIGATOR is PVWAVE’s graphical interface. It is a user-friendly Windows-like point-and-click GUI which allows a novice user to see some of the features of PVWAVE. This is not intended to be a tool for the power user.
To start NAVIGATOR, enter the following at the >WAVE prompt
navigator
The NAVIGATOR Windows-like interface should open, complete with icons and pull-down menus. You can move the mouse pointer over the icons to see what they are.
The icons are all VDA (visual data analysis) utilites of NAVIGATOR. The following is an example of a few of NAVIGATOR’s features.
EXAMPLE:
We will import a text file for analysis, then plot the data.
We can use the WZPreview utility to preview the file.
Once WZPlot is running, you can easily change anything about its look. Additional items, known as objects can be placed on the plot. Objects include text, lines, boxes and legends. To create any such objects, choose the appropriate object from the CREATE menu, or use the right-most four icons. To create a title:
ATTRIBUTES -> VIEW ATTRIBUTES lets you view or change the attributes for the actual plot (e.g. maxima and minima for axes, where the plot lies on the screen, colors, etc.)
ATTRIBUTES -> VARIABLE -> <your variable> lets you change the attributes of the particular plotted variable (e.g. thickness of line, color, line style, etc.)
NAVIGATOR has additional features not described here. It is, however, user-friendly enough to allow for easy experimentation and hands-on learning.
The plots made by NAVIGATOR, although created by a point-and-click
method, really are driven by running the corresponding PVWAVE commands
in the background. The interface is just a method of allowing a user to
use a GUI to make a relatively simple plot. Since actual PVWAVE commands
are being executed, NAVIGATOR allows you to save a plot as a program, which
shows the actual PVWAVE commands that generated the particular plot. This
is done by choosing FILE -> SAVE.
4. Using PVWAVE Commands to Create Plots
Although NAVIGATOR may be easy to use, the power of PVWAVE
is more readily accessed through actual commands and programs.
4.1 Basics of PVWAVE Commands
To exit PVWAVE:
exit
To get on-screen Help:
help, ‘<topic>’
To see the last command typed, push the Up-Arrow key. Pushing Up-Arrow twice gives you the next to last command typed. The last twenty commands are saved.
To continue a long command on the next line, enter ‘$’ as the last character of the line.
Example:
plot,x,y,z,ticklen=.05,xtitle=’X Values’, $
ytitle=’Y Values’,linestyle=3
To enter more than one command per line, separate the commands with ‘&’
Example:
x=x*5 & plot,x,y
To enter in a long series of commands and have PVWAVE process them all after the last one (instead of after each one), enter ‘&$’ at the end of each line except the last.
Example:
plot x,y &$
x=x+5 &$
oplot x,y
Entering UNIX commands:
UNIX commands may be entered at a >WAVE prompt by beginning the line with the $ character.
Example:
$pwd
Mathematical Note: Taking numbers to powers in PVWAVE
is expressed using ‘^’, NOT ‘**’.
x^2 will take x to the second power while x**2 is a syntax
error.
4.2 2-D Plots
This example will create a basic 2-D plot and introduce some PVWAVE plotting functions.
x=findgen(801)
FINDGEN: Returns a single precision floating point array with the specified dimensions.
Similar functions:
BINDGEN: Returns a byte array with the specified dimensions
CINDGEN: Returns a complex single precision floating
point array.
In this case, x has been created to be a 801-element vector
as follows...
x= [0.,1.,…800]
The following commands transform x to the following vector: [-80,-79.8,-79.6,-79.4,…,79.8,80]
x=x/5 (x is now [0,.2,.4,…,160]
x=x-80 (x is now [-80,-79.8,…,80]
We can print the values of x to the screen with
print, x
We can see information on x (dimensions, number type, etc.)
info, x
Now we assign y as a function of x (note y does not have to be dimensioned beforehand):
y=x*sin(x)
Now we can plot y:
plot, y
This creates a new window which contains the plot with the values of y on the Y axis and the X axis ranging from 0 to 800 (the number of elements of the x vector). This command is similar to the EZX command in NCAR Graphics.
To plot x values vs. y values
plot,x,y
This creates a new plot. Now the X axis goes ranges from
–80 to 80 (the range of values in x). This command is similar to the EZXY
command in NCAR Graphics.
4.3 System Variables
PVWAVE stores a number of internal system variables. Upon start-up, these variables are all set to a default value. System variables all begin with an exclamation point (!) followed by one letter, a period, and a keyword.
!p.ticklen, for example stores the value of the length of the tick marks on each plot. The value is in normal coordinate units, i.e. a percentage of the window. So if the value of !p.ticklen is .1, the tickmarks are 10% of the length or width of the window. A !p.ticklen value of .5 therefore creates a grid, since the two tickmarks on either side of the window are half the length of the window in size, and thus join in the middle.
System variables may be changed with a simple command such as
!p.ticklen = <value>
However, changing a system variable is a global change which will affect all future plots. These variables can be changed on a plot-by-plot basis by being called with keywords within each plotting command.
For example,
plot,x,y,ticklen=<value>
will only change the tick mark length for this particular plot.
Most internal system variables can be called by similar corresponding keywords in plotting commands as an alternative to a global change. Similarly, most keywords (including the ones covered in this document) have corresponding internal system variables that can be changed if the user wishes a global change.
The info or print commands will also work to give you information on system variables (in addition to user-defined variables), for example:
info, !p.ticklen
or
print, !p.ticklen
Unfortunately, the only way to restore system variables
to their default values (other than manually) is to log out of PVWAVE,
then log back in.
4.4 Changing the Look of The Plot
Each plot can be embellished and altered with the use
of keywords after the plot commands.
4.4.1 Changing the Attributes of the Plotting Window
The window which contains the plot has a default pixel size of 640x512. To create a window with different dimensions and a title, use the following command:
window,0,xsize=875,ysize=800,Title='My Plot'
This creates an empty window onto which you can plot with a plot command. The first argument "0" is the window index. When multiple plotting windows are open, this is how PVWAVE keeps track of them. Note that this title applies to the actual window, not the plot. The title entered with a Window command appears on the status bar along the top edge of the window, outside of the plot. Titles for plots are discussed in 4.4.2 below.
When multiple windows are open, specifying which window is the active window is done via the wset command. For example,
wset,1
will mark window number 1 as the active window to be used by the graphics and imaging routines.
Within the plotting window, a certain region is set aside to do the actual plot. This plotting region is controlled by the internal system variables !p.region and !p.position (see more on internal system variables in Sec 4.3). !p.region and !p.position hold four values corresponding to [xmin,ymin,xmax,ymax], set as fractional distances, independent of the window size. The defaults are !p.region=[0,0,1,1] and !p.position=[0,0,1,1]. Entering the following change
!p.region = [0,.3,1,.7]
or
!p.position = [0,.3,1,.7]
creates a long horizontal plot., as the y values have shrunk.
The single difference between !p.region and !p.position is that when setting !p.region, PVWAVE allows for marginal labels and annotations, while for !p.position it does not. So setting !p.position to [0,0,1,1] will set the plot flush against the sides of the window, cutting off any axis labels or other annotations. With !p.region, PVWAVE does account for this. When using these two system variables simultaneously, PVWAVE will only recognize the last one set.
As mentioned above, changing a system variable is a global change which will affect all future plots. To make such changes on a plot by plot basis, one may add the position keyword, which corresponds to changing !p.position for only one particular plot. An example:
plot,x,y,position=[.5,.5,1,1]
will plot x and y in the upper right corner of the active
window.
4.4.2 Adding a Title
A title can be added to the plot with the title keyword. The following command adds a title to the plot of y.
plot,y,title=’Plotting Y’
This plot has been printed and is shown as Figure 1.
The following command adds a title to the plot of x vs. y.
plot,x,y,title=’Plotting X vs. Y’
This plot has been printed and is shown as Figure
2.
4.4.3 Changing the Range of the Axes
PVWAVE will automatically determine the range of the axes it plots. However, you can tell it to plot a specific range using the XRange and YRange keywords. The following plot will zoom in on the plot of x vs. y, only showing us x=[-25,25] and y=[-25,25].
plot,x,y,title='Magnified Plot of X vs. Y',xrange=[-25,25],yrange=[-25,25]
This plot has been printed and is shown as Figure 3.
For a global change, corresponding system variables !x.range
and !y.range may be changed.
4.4.4 Changing the Style of the Plotted Lines
You can control the thickness of the plotted lines with the thick keyword. For example, triple the thickness of the plotted lines with the following command:
plot,x,y,thick=2
By default, PVWAVE will draw your plots as smooth lines. However, instead of a line, you can make the plot consist of other characters using the psym keyword.
plot,x,y,psym=<value>
Values For Psym:
0 - default, smoothed line
1 - + signs
2 - asterisks
3 - dots
4 - small diamonds
5 - triangles (deltas)
6 - squares
7 – x’s
A negative sign in front of the value connects the points.
If Psym=0 (default regular line), the linestyle keyword can be used. Linestyle changes the style of the smoothed line.
plot,x,y,linestyle=<value>
Values for Linestyle:
0 – solid line
1 - dotted
2 - dashed
3 - dash dot
4 - dash dot dot dot
5 - long dashes
4.4.5 Making More Than One Plot on a Window
In PVWAVE, entering consecutive plot commands erase the previous plot. However, the oplot command plots a new plot on the existing window. If we define a new function:
b=x*cos(x)
Then we plot our old function
plot,x,b
To plot w on the same window, enter
oplot,x,w
4.4.6 Adding Axis Labels
Adding axis labels to plots is similar to adding a title to the plot. The keywords to add axis labels are xtitle and ytitle.
plot,x,y,title='My Plot',Xtitle='Index',Ytitle='Function'
Note this title is different from the window's title.
By default the title is 1.25 times as large as the titles on x,y axes.
4.4.7 Changing Fonts
The fonts available to PVWAVE are each indexed with a number. The default is 3. To change fonts, an argument of !<fontnumber> must come before the text to be printed, inside the single quotes. Note that PVWAVE will PERMANENTLY change to this font number unless you change it back to it’s old value. The following command changes to font number 17, but does not change back. The title, xtitle, and ytitle will all be in font 17.
plot,x,y,title='!17My Plot',Xtitle='Index',Ytitle='Function'
The following command prints only the title in font 17, then changes back before the xtitle and ytitle are printed.
plot,x,y,title='!17Another Plot!3',Xtitle='Values of X',Ytitle='Value of f(x)'
This plot has been printed and is shown as Figure
4.
4.4.8 Adding a Subtitle
We can add a subtitle to the plot using the subtitle keyword. We can use this along with the today function. The following statement assigns today’s date to the variable a.
a=TODAY()
However, a is contains the date in a somewhat encrypted form, so we convert it to a string using the dt_to_str function as follows:
dt_to_str,a,b,Date_Fmt=<value>
Date Formats (examples for Oct 15,1997
1 - mm*dd*yyyy - 10/15/1997
2 - dd**mm**yyyy 15-10-1997
3 - ddd*yyyy 288-1997
4 - dd*mmmmmmmmm*yyyy 15/October/1997
5 - yyyy*mm*dd - 1997-10-15
Then we can print a subtitle with the date as follows:
plot,x,y,title='!15My Plot!3',Xtitle='Index',$
Ytitle='Function',subtitle='Plot generated on ' +
b
Remember, the dollar sign ‘$’ tells PVWAVE that your command
is long and is continuing to the next line.
4.4.9 Changing Tick marks
Changing tick mark characteristics requires use of a few different keywords. In all of these cases, if not specified, PVWAVE will choose tick mark characteristics for you. The xticks or yticks keywords control the number of major tick mark intervals on the X and Y axes. For example,
plot,x,y,xticks=2
creates two major tick mark intervals on the X axis. This
means there will be three tick marks. In general, setting the value to
n creates n intervals and n+1 tick marks. Minor tick marks are controlled
with xminor and yminor in the same was as xticks and yticks. However, setting
xminor or yminor to a value of –1 suppresses them altogether.
4.4.10 Placing Labels and Lines on the Plot
Placing labels within the plots can be done with the xyouts command. To place a text string at the position within the plot of x=-60, y=-75, enter
xyouts,-60,-75,'Sine function'
Plotting an additional line on the plot can be done using the oplot command, already introduced above. For example..
oplot, [0,50],[-75,-75],linetstyle=0,thick=3
Oplot draws a line with endpoints [x1,x2],[y1,y2].
4.4.11 Changing Colors
The internal system variable !d.n_colors stores the number of colors available. Remember from Sec 4.3 that internal system variables always begin with (!).
We can display the number of colors by typing
info, !d.n_colors
Then we can use commands like
plot,x,y,color=!d.n_colors-5000,back=100000
This will plot the line with color number (!d.n_colors-5000)
and the background with color number 100000.
4.5 A (Somewhat) Comprehensive Example
The following commands utilize many of the above commands and keywords to produce a plot. The plot has been printed as Figure 5
Here we’re starting from scratch, redefining all the variables we used above.
x=findgen(801)
x=x/5
x=x-80
y=x*sin(x)
w=sin(x)
plot,x,y,title='XSINX and SINX',xrange=[-5,5],yrange=[-5,5],$
thick=3,xminor=2,yminor=2,xtitle='Values of x',ytitle='Values
$
of Functions'
oplot x,w,linestyle=2,thick=3
xyouts, -2,-4,'XSINX',charsize=2
xyouts, -2, -5, 'SINX',charsize=2
oplot, [-.2,1],[-3.9,-.3.9],thick=3
oplot, [-.2,1],[-4.9,-4.9],thick=3,linestyle=2
4.6 Contour Plots
Contour plots work in much the same way as the 2D plots. The command to create a contour plot is contour,<arg1>,<arg2>,<arg3>, keywords where arg1 is the function to be contoured, arg2 (optional) is the variable to be used on the X axis, and arg3 (optional) is the variable to be used on the Y axis. Any applicable keywords can follow arg3.
Many of the same keywords used for 2D plots will still work with contour plots. Some additional keywords used in the contour plots:
c_labels: This is a vector-valued keyword that controls which contours will have labels attached to them. The values can be 0 (don’t print contour line) or 1 (print contour line). If there are 4 contour lines, c_labels = [1,0,0,1] will place labels on the first and fourth contours, but not the second and third. If not specified, the default is used, which is to label every other contour.
levels: Also a vector-valued keyword that specifies which contours will be plotted. For example, levels=[10,11,12] will plot only contours with values 10, 11, and 12. levels=findgen(6)*10+50 puts contours at 50, 60, 70, …, 100. See Sec 4.2 on more about findgen. levels cannot be used simultaneously with nlevels (see below)
nlevels: Defines the number of equally spaced contours to be plotted. For example, nlevels=5 prompts PVWAVE to plot 5 different contours, equally spaced. nlevels cannot be used simultaneously with levels (see above).
c_thick and c_linestyle are used in exactly the same way as thick and linestyle (see Section 4.4.4), only they apply to contours.
The following commands emulate the contour plot made by Dr. Grotjahn in the contour.for sample NCAR Graphics program. This uses the PSIP function.
This plot was printed and is shown as Figure 6.
Note: Lines beginning with ‘C:’ are my comments.
x=findgen(41)
x=x/10
x=x-2
C: x are intervals of length .1 from -2 to 2
y=findgen(21)
y=y/10
y=y-1
C: y are intervals each .1, from -1 to 1
psip=fltarr(41,21)
C: fltarr returns a floating point array with the specified
dimensions.
for i=0,40 do begin &$
for j=0,20 do begin &$
psip(i,j)=17*exp(-x(i)^2 - y(j)^2)&$
endfor &$
endfor
C: This nested loop populates psip
C: Note the &$ at the end of each line to
suspend execution until
C: the last line is entered
contour,psip,x,y,nlevels=5,c_labels=[1,1,1,1,1],c_charsize=1.2
$
,xtitle='X Values',Ytitle='Y Values',title='Contour
of PSI'
4.7 Surface Plots
Surface plots work in much the same way as the 2D and contour plots. The command to create a surface plot is surface,<arg1>,<arg2>,<arg3>, keywords where arg1 is the function to be plotted, arg2 (optional) is the variable to be used on the X axis, and arg3 (optional) is the variable to be used on the Y axis. Any applicable keywords can follow arg3. Most of the keywords defined above for 2D plots also work on surface plots.
Two additional keywords used for surface plots:
Ax: angle of rotation about the x axis in degrees
towards viewer. The default is 30 degrees.
Az: specifies the counterclockwise angle in degrees
of rotation about the Z axis (when looking down the z axis toward origin).
The default is 30 degrees.
For example:
surface,psip,x,y,ax=45,az=90
The following example was printed and is shown as Figure 7. Note these are the same sets of commands used in the example for Figure 6 in Section 4.5 above, save for the last command, which is a call to the surface plot routine rather than the contour plot routine.
x=findgen(41)
x=x/10
x=x-2
C: x are intervals of length .1 from -2 to 2
y=findgen(21)
y=y/10
y=y-1
C: y are intervals each .1, from -1 to 1
psip=fltarr(41,21)
C: fltarr returns a floating point array with the specified
dimensions.
for i=0,40 do begin &$
for j=0,20 do begin &$
psip(i,j)=17*exp(-x(i)^2 - y(j)^2)&$
endfor &$
endfor
C: This nested loop populates psip
C: Note the &$ at the end of each line to
suspend execution until
C: the last line is entered
surface,psip,x,y,xtitle=’X Values’,ytitle=’Y Values’,$
title=’Surface Plot of PSIP’
5. Saving and Restoring Sessions
The save and restore procedures are used together to save the state of the user generated variables, system variables, and compiled procedures and functions.
To save a session’s data to a file, enter
save, filename = '<full path and filename>', /variables, /routine, /verbose
To restore a session...
restore, '<full path and filename>',/verbose
6. Printing Plots
There are five steps to printing a plot.
The first is to change the output device to be something other than the screen. At ATM26, the following command works.
Set_plot, 'ps'
The string ‘ps’ sets the output device to PostScript
The String can be these device driver codes...
CGM - Computer Graphics Metafile
HP - HPGL device
PCL - PCL device
PS - PostScript Device
REGIS - Regis terminal
TEK - Tektronix terminal
Z - Z-buffer pseudo device
X - X Window system
WIN32 - Windows NT
Configure the output device to your specifications. In other words, choose a filename for the plot to get printed to. For example:
device, filename= '/f/castello/pvwave/myplot.ps'
This command specifies the output file name and the type of file.
Enter the PVWAVE commands to display your graphics. The graphics get printed to the specified file as opposed to the screen.
Close the output file with the following command:
device, /close
Enter UNIX print command. Remember, if in PVWAVE, preface any UNIX commands with a $ character. The example below prints my file on the printer in Hoagland 269.
$lpr -Php5 /f/castello/pvwave/myplot.ps
Set the ouptut device back to X Windows with the command
set_plot,'X'
6.1 Converting PostScript Files to JPEG Format
It is often useful to have images in GIF or JPEG format for easy viewing via the Internet. Unfortunately, PVWAVE cannot directly save images in those formats. Instead, it is possible to save an image into PostScript format (as outlined above), and then convert the image from PostScript to JPEG. After going through the above procedure to save a PVWAVE plot to a PostScript format, here is the procedure to convert to JPEG:
Assuming we already have a PostScript file of the name ‘myplot.ps’, we use the Ghostscript utility which is installed on the ATM machines. The command at the UNIX prompt to convert ‘myplot.ps’ to ‘myplot.jpg’ is:
gs -sDEVICE=jpeg -sOutputFile=myplot.jpg myplot.ps
Remember, if you are in PVWAVE when entering this command,
you must precede it with a $ so PVWAVE knows it is a UNIX command.
After entering this command, you will be inside the Ghostscript utility.
Type ‘QUIT’ to get out of it.
7. Programming With PVWAVE
PVWAVE contains a built-in programming language for more
advanced applications. A brief description is given here. For more detailed
examples and commands, please refer to the "PV-WAVE Programmer’s Guide"
7.1 Creating Programs at the Command Line
Functions and procedures are normally created in files, making repeated use easy in future sessions. However, PVWAVE does allow the user to create a short program or function for short-term use. This is done via the .RUN command. Entering .RUN at the command line prompts PVWAVE to enter an interactive programming mode, where the prompt before each line is a dash "-". Lines of code may then be entered, separated by a carriage return. When the user is finished, the END command tells PVWAVE to compile the program and revert back to normal mode.
The following example program will, when executed, print out the square root of the numbers 0 through 5:
.run
-for I=0,5 do begin
-print,’square root of ‘,I,’ is ‘,sqrt(I)
-endfor
-end
PVWAVE will then respond with:
% Compiled module: $MAIN$
square root of 0 is 0.00000
square root of 1 is 1.00000
square root of 2 is 1.41421
square root of 3 is 1.73205
square root of 4 is 2.00000
square root of 5 is 2.23607
The .RUN command can also create procedures and functions which can be saved with your variables, etc. when saving a session (see Sec. 5. "Saving and Restoring Sessions"). The following example creates a function that squares a number:
.run
-function square,number
-return,number^2
-end
PVWAVE will respond with:
% Compiled module: SQUARE
The function SQUARE can now be used to calculate the square of a number. For example:
print,square(24)
prompts PVWAVE to return with:
576
A program created interactively like this cannot be saved
for use in later sessions unless it has a name, in this case SQUARE.
See
Section 5, "Saving and Restoring Sessions" for details on saving sessions.
7.2 Creating and Running Procedures and Functions
Instead of defining a function or procedure in the command line as demonstrated in Section 7.1, PVWAVE allows you to create files that define procedures or functions in ASCII text format. The file must have an extension of .PRO and must be located in the current directory, or in a directory accessible by your path.
For example, I can create a text file named CUBE.PRO which consists of the following lines:
Function CUBE, Number
Return, Number^3
End
The file automatically compiles and executes when being called at the prompt. For example, if I type
x = cube (9)
PVWAVE responds with:
% Compiled module: CUBE
If I then print out the contents of my variable x:
print,x
I get:
27
Additional calls to CUBE will not require compilation,
so the "% Compiled module" statement only appears the first time the routine
is called.
7.3 Creating and Running Main Programs
A main program is a series of statements that are compiled as a unit. Since a main program has no heading, it cannot be called from other routines, and cannot be passed arguments. A main program can, however, call outside procedures and functions. A main program should be saved as a text file in either the current directory or a directory within your path.
For example, I can create a text file named "testprog" which consists of the following lines:
for i = 3,5 do begin
print,'Cube of ',i,' is ',i^3
print,'Cube of ',i,' using function CUBE is ',cube(i)
endfor
Notice that the program is calculating the cube of a number in two different ways. The first method is by simply raising the number to the third power. The second method is by using the subroutine CUBE defined in Section 7.2, which takes the cube of a number; this method illustrates how it is possible to call an outside procedure or function. The two methods should yield identical results.
The program is run by entering
.RUN testprog
This yields:
Cube of 3 is 27
% Compiled module: CUBE.
Cube of 3 using function CUBE is 27
Cube of 4 is 64
Cube of 4 using function CUBE is 64
Cube of 5 is 125
Cube of 5 using function CUBE is 125
Notice that the first time CUBE is used, it must be compiled.
You can run multiple programs and process their results
using a command, or batch file within PVWAVE. For more information on this
feature, as well as further details on the programming language provided
within the PVWAVE (which is quite robust), please refer to the "PV-WAVE
Programmer’s Guide"
