2. Simple Use of PGPLOT

2.1 Introduction

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:

  1. PGBEG, to start up PGPLOT and specify the device you want to plot on;
  2. PGENV, to define the range and scale of the graph, and draw labels, axes etc;
  3. one or more calls to PGPT or PGLINE or both, or other drawing routines, to draw points or lines.
  4. 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.

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:

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 (' ').

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:

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:

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
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