This chapter introduces the basic subroutines needed to create a graph using PGPLOT, by way of a concrete example. It does not describe all the capabilities of PGPLOT; these are presented in later chapters.
A simple graph is composed of several elements: a box or axes delineating the graph and indicating the scale, labels if required, and one or more points or lines. To draw a graph you need to call at least four of the PGPLOT functions and subroutines:
To draw more than one graph on the same device, repeat steps (2) and (3). It is only necessary to call PGOPEN and PGCLOS once each, unless you want to plot on more than one device.
This chapter presents a very simple example program to demonstrate the above four steps. The example program is presented in both Fortran and C.
A typical application of PGPLOT is to draw a set of measured data points and a theoretical curve for comparison. This chapter describes a simple program for drawing such a plot; in this case there are five data points and the theoretical curve is y = x².
Here is the complete Fortran code for the program:
PROGRAM SIMPLE INTEGER I, ID, PGOPEN REAL XR(100), YR(100) REAL XS(5), YS(5) DATA XS/1.,2.,3.,4.,5./ DATA YS/1.,4.,9.,16.,25./ ID = PGOPEN('?') IF (ID.LT.1) STOP CALL PGENV(0.,10.,0.,20.,0,1) CALL PGLAB('(x)', '(y)', 'A Simple Graph') CALL PGPT(5,XS,YS,9) DO 10 I=1,60 XR(I) = 0.1*I YR(I) = XR(I)**2 10 CONTINUE CALL PGLINE(60,XR,YR) CALL PGCLOS END
And here is the complete C code for the program; note that PGPLOT programs should include the header file cpgplot.h
:
#include "cpgplot.h" int main(void) { int i; float xs[5] = {1., 2., 3., 4., 5.}; float ys[5] = {1., 4., 9., 16., 25.}; float x, xr[100], yr[100]; if (cpgopen("?") < 1) return 1; cpgenv(0., 10., 0., 20., 0, 1); cpglab("(x)", "(y)", "A Simple Graph"); cpgpt(5, xs, ys, 9); for (i=1; i<=60; i++) { x = 0.1*i; xr[i-1] = x; yr[i-1] = x*x; } cpgline(60, xr, yr); cpgclos(); return 0; }
The following sections of this chapter describe how the program works, and the resulting plot is shown in Figure 2.1.
Figure 2.1: Output of Example Program
We store the x and y coordinates of the five data points in arrays XS
and YS
. For convenience, this values are defined in the program, but a more realistic program might read them from a file. Arrays XR
and YR
will be used later in the program for the theoretical curve.
REAL XR(100), YR(100) REAL XS(5), YS(5) DATA XS/1.,2.,3.,4.,5./ DATA YS/1.,4.,9.,16.,25./
float xs[5] = {1., 2., 3., 4., 5.}; float ys[5] = {1., 4., 9., 16., 25.}; float xr[100], yr[100];Note for Fortran users: all floating-point scalars and arrays used with PGPLOT should be declared
REAL
, not DOUBLE PRECISION
.
Note for C users: arrays used in PGPLOT must be float
, not double
; scalar arguments should also be float
, but double
arguments will be converted following the function prototypes in cpgplot.h
.
The first thing the program must do is to start up PGPLOT and select the graphics device for output:
INTEGER PGOPEN ID = PGOPEN('?') IF (ID.LT.1) STOP
if (cpgopen("?") < 1) return 1;
PGOPEN has one argument: a character string which gives a ``device specification'' for the interactive graphics device or disk file for hardcopy graphics. This program makes use of a special shorthand feature of PGPLOT, however: if the argument is set to '?'
, the program will ask the user to supply the device specification at run-time. An explicit device specification might look like
ID = PGOPEN('pgfile.ps/PS')
The value returned by PGOPEN (ID
) is an identifier that can be used to distinguish this PGPLOT device from other open devices. It is important to test the returned value: a value less than 1 indicates an error, such as an invalid device specification. (Fortran users: note that PGOPEN is a Fortran function, not a subroutine, and must be declared INTEGER
.)
Subroutine PGENV starts a new picture and defines the range of variables and the scale of the plot. PGENV also draws and labels the enclosing box and the axes if requested. In this case, the x-axis of the plot will run from 0.0 to 10.0 and the y-axis will run from 0.0 to 20.0.
CALL PGENV(0.,10.,0.,20.,0,1)
cpgenv(0., 10., 0., 20., 0, 1);
PGENV has six arguments:
Subroutine PGLAB may (optionally) be called after PGENV to write identifying labels on the x and y axes, and at the top of the picture:
CALL PGLAB('(x)', '(y)', 'A Simple Graph')
cpglab("(x)", "(y)", "A Simple Graph");
All three arguments are character variables or constants; any of them can be blank (' '
).
Subroutine PGPT draws graph markers at one or more points on the graph. Here we use it to mark the five data points:
CALL PGPT(5,XS,YS,9)
cpglab("(x)", "(y)", "A Simple Graph");
If any of the specified points fall outside the window defined in the call to PGENV, they will not be plotted. The arguments to PGPT are:
The following code draws the ``theoretical curve'' through the data points:
DO 10 I=1,60 XR(I) = 0.1*I YR(I) = XR(I)**2 10 CONTINUE CALL PGLINE(60,XR,YR)
for (i=1; i<=60; i++) { x = 0.1*i; xr[i-1] = x; yr[i-1] = x*x; }
We compute the x and y coordinates at 60 points on the theoretical curve, and use subroutine PGLINE to draw a curve through them. PGLINE joins up the points with straight-line segments, so it is necessary to compute coordinates at fairly close intervals in order to get a smooth curve. Any lines which cross the boundary of the window defined in PGENV are ``clipped'' at the boundary, and lines which lie outside the boundary are not drawn. The arguments of PGLINE are like those of PGPT:
Subroutine PGCLOS must be called to complete the graph properly, otherwise some pending output may not get sent to the device:
CALL PGCLOS
pgclos();
The commands required to compile, link, and run a PGPLOT program vary greatly from system to system, and are described in the next chapter. For example, under UNIX, the commands are something like the following:
f77 -o simple simple.f -L/usr/local/pgplot -lpgplot
cc -c -I/usr/local/pgplot simple.c
f77 -o simple simple.o -L/usr/local/pgplot -lcpgplot -lpgplot
When you run the program, it will ask you to supply the graphics
device specification. Type in any allowed device specification, or
type a question-mark (?
) to get a list of the available
device types. For example, if you are using an X-Window display, type
/XSERVE
: the graph will appear in a window on the
workstation screen.
If you want a hard copy, you can run the program again, and specify
a different device type, e.g., simple.ps/PS
to make a
disk file in PostScript format. To obtain the hard copy, print the
file on a PostScript printer. You may be able to preview the file with
a program such as GhostView.