2. Simple Use of PGPLOT
2.1 Introduction
The PGPLOT Graphics Subroutine Library is a Fortran- or C-callable, device-independent
graphics package for making simple scientific graphs. It is intended for
making graphical images of publication quality with minimum effort on the
part of the user. For most applications, the program can be device-independent,
and the output can be directed to the appropriate device at run time. The
PGPLOT library consists of two major parts: a device-independent part and
a set of device-dependent ``device handler'' subroutines for output on
various terminals, image displays, dot-matrix printers, laser printers,
and pen plotters. Common file formats supported include PostScript and
GIF. PGPLOT itself is written mostly in standard Fortran-77, with a few
non-standard, system-dependent subroutines. PGPLOT subroutines can be called
directly from a Fortran-77 or Fortran-90 program. A C binding library (cpgplot)
and header file (cpgplot.h) are provided that allow PGPLOT to be called
from a C or C++ program; the binding library handles conversion between
C and Fortran argument-passing conventions. PGPLOT has been tested with
UNIX (most varieties, including Linux, SunOS, Solaris, HPUX, AIX, and Irix)
and OpenVMS operating systems. I am unable to provide support for DOS,
Windows, Windows/NT, or MacOS, but I do distribute code provided by users
for use with these operating systems. 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 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:
-
PGBEG,
to start up PGPLOT and specify the device you want to plot on;
-
PGENV,
to define the range and scale of the graph, and draw labels, axes etc;
-
one or more calls to PGPT
or PGLINE
or both, or other drawing routines, to draw points or lines.
-
PGEND
to close the plot.
To draw more than one graph on the same device, repeat steps (2) and (3).
It is only necessary to call PGBEG and
PGEND 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.
2.2 An Example
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, IER, PGBEG
REAL XR(100), YR(100)
REAL XS(5), YS(5)
DATA XS/1.,2.,3.,4.,5./
DATA YS/1.,4.,9.,16.,25./
IER = PGBEG(0,'?',1,1)
IF (IER.NE.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 PGEND
END
The following sections of this chapter describe how the program works,
and the resulting plot is shown in Figure
2.1.
2.3 Data Initialization
We shall store the x and y coordinates of the five data points
in arrays XS and YS. For convenience, this program defines
the values in DATA statements, 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./
2.4 Starting PGPLOT
The first thing the program must do is to start up PGPLOT and select the
graphics device for output:
INTEGER PGBEG
IER = PGBEG(0,'?',1,1)
IF (IER.NE.1) STOP
Note that PGBEG
is a Fortran function, not a subroutine, and must be declared INTEGER.
It has four arguments, and returns an integer code which will have value
1 if the device was opened successfully.
-
The first argument is present for historical reasons. It should always
be set to zero (0).
-
The second argument is a character string which gives a ``device specification''
for the interactive graphics device or disk file for hardcopy graphics
(see Chapter 1 and Appendix
D). This program makes use of a special shorthand feature of PGPLOT,
however: if this argument is set to '?', the program will ask
the user to supply the device specification at run-time.
-
The last two arguments are described in Section 3.2. Usually they are both
set to 1, as in this example.
2.5 Defining Plot Scales and Drawing Axes
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)
PGENV has six arguments:
-
the left and right limits for the x (horizontal) axis (real numbers,
not integers).
-
the bottom and top limits for the y (vertical) axis (also real numbers).
-
An integer argument: if this is 1, the scales of the x-axis and
y-axis
(in units per inch) will be equal; otherwise the axes will be scaled independently.
In this case we have not requested equal scales.
-
Another integer argument, that controls whether an enclosing box, tick-marks,
numeric labels, and/or a grid will be put on the graph. The recommended
value is 0. Some of the allowed values are: -2: no annotation; -1: draw
box only; 0: draw box, and label it with coordinate values around the edge;1:
in addition to the box and labels, draw the two axes (lines x=0,
y=0)
with tick marks; 2: in addition to the box, labels, and axes, draw a grid
at major increments of the x and y coordinates.
2.6 Labeling the Axes
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')
All three arguments are character variables or constants; any of them can
be blank (' ').
-
A label for the x-axis (bottom of picture).
-
A label for the y-axis (left-hand edge).
-
A label for the plot (top of picture).
2.7 Drawing Graph Markers
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)
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 number of points to be marked (integer).
-
The x and y coordinates of the points (real arrays).
-
The number of the symbol to be used to mark the points. In this example,
we use symbol number 9 which is a circle with a central dot. The available
symbols are shown in Chapter 4.
2.8 Drawing Lines
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)
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:
-
The number of points defining the line (integer).
-
The x and y coordinates of the points (real arrays).
2.9 Ending the Plot
Subroutine PGEND
must be called to complete the graph properly, otherwise some pending output
may not get sent to the device:
CALL PGEND
2.10 Compiling and Running the Program
To compile the program and link it with the PGPLOT library, see Chapter
1. For example, under Unix:
emacs simple.f
...
f77 -o simple simple.f -lpgplot -lX11
for C
cc -c simple.c
f77 -o simple simple.o
-lcpgplot -lpgplot -lX11
Under VMS:
$ EDIT SIMPLE.FOR
...
$ FORTRAN SIMPLE
$ LINK SIMPLE
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
/XWIN: the graph will
appear on the terminal 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 (but first
check with your system manager what the correct print command is; it is
possible to waste a lot of paper by using the wrong command or sending
a file to the wrong sort of printer!).
Next: Chapter
3
PGPLOT
Tim Pearson, California Institute of Technology, tjp·astro.caltech.edu
Copyright ¿ 1995 California Institute of Technology