Subset of PGPLOT Subroutine Descriptions

Introduction

PGBEG -- open a graphics device

      INTEGER FUNCTION PGBEG (UNIT, FILE, NXSUB, NYSUB)
      INTEGER       UNIT
      CHARACTER*(*) FILE
      INTEGER       NXSUB, NYSUB

Note: new programs should use PGOPEN rather than PGBEG. PGBEG
is retained for compatibility with existing programs. Unlike PGOPEN,
PGBEG closes any graphics devices that are already open, so it
cannot be used to open devices to be used in parallel.

PGBEG opens a graphical device or file and prepares it for
subsequent plotting. A device must be opened with PGBEG or PGOPEN
before any other calls to PGPLOT subroutines for the device.

If any device  is already open for PGPLOT output, it is closed before
the new device is opened.

Returns:
 PGBEG         : a status return value. A value of 1 indicates
                   successful completion, any other value indicates
                   an error. In the event of error a message is
                   written on the standard error unit.
                   To test the return value, call
                   PGBEG as a function, eg IER=PGBEG(...); note
                   that PGBEG must be declared INTEGER in the
                   calling program. Some Fortran compilers allow
                   you to use CALL PGBEG(...) and discard the
                   return value, but this is not standard Fortran.
Arguments:
 UNIT  (input)   : this argument is ignored by PGBEG (use zero).
 FILE  (input)   : the "device specification" for the plot device.
                   (For explanation, see description of PGOPEN.)
 NXSUB  (input)  : the number of subdivisions of the view surface in
                   X (>0 or <0).
 NYSUB  (input)  : the number of subdivisions of the view surface in
                   Y (>0).
                   PGPLOT puts NXSUB x NYSUB graphs on each plot
                   page or screen; when the view surface is sub-
                   divided in this way, PGPAGE moves to the next
                   panel, not the  next physical page. If
                   NXSUB > 0, PGPLOT uses the panels in row
                   order; if <0, PGPLOT uses them in column order.

PGCONL -- label contour map of a 2D data array

      SUBROUTINE PGCONL (A, IDIM, JDIM, I1, I2, J1, J2, C, TR,
     1                   LABEL, INTVAL, MININT)
      INTEGER IDIM, JDIM, I1, J1, I2, J2, INTVAL, MININT
      REAL A(IDIM,JDIM), C, TR(6)
      CHARACTER*(*) LABEL

Label a contour map drawn with routine PGCONT. Routine PGCONT should
be called first to draw the contour lines, then this routine should be
called to add the labels. Labels are written at intervals along the
contour lines, centered on the contour lines with lettering aligned
in the up-hill direction. Labels are opaque, so a part of the under-
lying contour line is obscured by the label. Labels use the current
attributes (character height, line width, color index, character
font).

The first 9 arguments are the same as those supplied to PGCONT, and
should normally be identical to those used with PGCONT. Note that
only one contour level can be specified; tolabel more contours, call
PGCONL for each level.

The Label is supplied as a character string in argument LABEL.

The spacing of labels along the contour is specified by parameters
INTVAL and MININT. The routine follows the contour through the
array, counting the number of cells that the contour crosses. The
first label will be written in the MININT'th cell, and additional
labels will be written every INTVAL cells thereafter. A contour
that crosses less than MININT cells will not be labelled. Some
experimentation may be needed to get satisfactory results; a good
place to start is INTVAL=20, MININT=10.

Arguments:
 A      (input) : data array.
 IDIM   (input) : first dimension of A.
 JDIM   (input) : second dimension of A.
 I1, I2 (input) : range of first index to be contoured (inclusive).
 J1, J2 (input) : range of second index to be contoured (inclusive).
 C      (input) : the level of the contour to be labelled (one of the
                  values given to PGCONT).
 TR     (input) : array defining a transformation between the I,J
                  grid of the array and the world coordinates.
                  The world coordinates of the array point A(I,J)
                  are given by:
                    X = TR(1) + TR(2)*I + TR(3)*J
                    Y = TR(4) + TR(5)*I + TR(6)*J
                  Usually TR(3) and TR(5) are zero - unless the
                  coordinate transformation involves a rotation or
                  shear.
 LABEL  (input) : character strings to be used to label the specified
                  contour. Leading and trailing blank spaces are
                  ignored.
 INTVAL (input) : spacing along the contour between labels, in
                  grid cells.
 MININT (input) : contours that cross less than MININT cells
                  will not be labelled.

PGCONS -- contour map of a 2D data array (fast algorithm)

      SUBROUTINE PGCONS (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR)
      INTEGER IDIM, JDIM, I1, I2, J1, J2, NC
      REAL    A(IDIM,JDIM), C(*), TR(6)

Draw a contour map of an array. The map is truncated if
necessary at the boundaries of the viewport.  Each contour line is
drawn with the current line attributes (color index, style, and
width).  This routine, unlike PGCONT, does not draw each contour as a
continuous line, but draws the straight line segments composing each
contour in a random order.  It is thus not suitable for use on pen
plotters, and it usually gives unsatisfactory results with dashed or
dotted lines.  It is, however, faster than PGCONT, especially if
several contour levels are drawn with one call of PGCONS.

Arguments:
 A      (input)  : data array.
 IDIM   (input)  : first dimension of A.
 JDIM   (input)  : second dimension of A.
 I1,I2  (input)  : range of first index to be contoured (inclusive).
 J1,J2  (input)  : range of second index to be contoured (inclusive).
 C      (input)  : array of contour levels (in the same units as the
                   data in array A); dimension at least NC.
 NC     (input)  : number of contour levels (less than or equal to
                   dimension of C). The absolute value of this
                   argument is used (for compatibility with PGCONT,
                   where the sign of NC is significant).
 TR     (input)  : array defining a transformation between the I,J
                   grid of the array and the world coordinates. The
                   world coordinates of the array point A(I,J) are
                   given by:
                     X = TR(1) + TR(2)*I + TR(3)*J
                     Y = TR(4) + TR(5)*I + TR(6)*J
                   Usually TR(3) and TR(5) are zero - unless the
                   coordinate transformation involves a rotation
                   or shear.

PGDRAW -- draw a line from the current pen position to a point

      SUBROUTINE PGDRAW (X, Y)
      REAL X, Y

Draw a line from the current pen position to the point
with world-coordinates (X,Y). The line is clipped at the edge of the
current window. The new pen position is (X,Y) in world coordinates.

Arguments:
 X      (input)  : world x-coordinate of the end point of the line.
 Y      (input)  : world y-coordinate of the end point of the line.

PGEND -- close all open graphics devices

      SUBROUTINE PGEND

Close and release any open graphics devices. All devices must be
closed by calling either PGCLOS (for each device) or PGEND before
the program terminates. If a device is not closed properly, some
or all of the graphical output may be lost.

Arguments: none

PGENV -- set window and viewport and draw labeled frame

      SUBROUTINE PGENV (XMIN, XMAX, YMIN, YMAX, JUST, AXIS)
      REAL XMIN, XMAX, YMIN, YMAX
      INTEGER JUST, AXIS

Set PGPLOT "Plotter Environment".  PGENV establishes the scaling
for subsequent calls to PGPT, PGLINE, etc.  The plotter is
advanced to a new page or panel, clearing the screen if necessary.
If the "prompt state" is ON (see PGASK), confirmation
is requested from the user before clearing the screen.
If requested, a box, axes, labels, etc. are drawn according to
the setting of argument AXIS.

Arguments:
 XMIN   (input)  : the world x-coordinate at the bottom left corner
                   of the viewport.
 XMAX   (input)  : the world x-coordinate at the top right corner
                   of the viewport (note XMAX may be less than XMIN).
 YMIN   (input)  : the world y-coordinate at the bottom left corner
                   of the viewport.
 YMAX   (input)  : the world y-coordinate at the top right corner
                   of the viewport (note YMAX may be less than YMIN).
 JUST   (input)  : if JUST=1, the scales of the x and y axes (in
                   world coordinates per inch) will be equal,
                   otherwise they will be scaled independently.
 AXIS   (input)  : controls the plotting of axes, tick marks, etc:
     AXIS = -2 : draw no box, axes or labels;
     AXIS = -1 : draw box only;
     AXIS =  0 : draw box and label it with coordinates;
     AXIS =  1 : same as AXIS=0, but also draw the
                 coordinate axes (X=0, Y=0);
     AXIS =  2 : same as AXIS=1, but also draw grid lines
                 at major increments of the coordinates;
     AXIS = 10 : draw box and label X-axis logarithmically;
     AXIS = 20 : draw box and label Y-axis logarithmically;
     AXIS = 30 : draw box and label both axes logarithmically.

For other axis options, use routine PGBOX. PGENV can be persuaded to
call PGBOX with additional axis options by defining an environment
parameter PGPLOT_ENVOPT containing the required option codes.
Examples:
  PGPLOT_ENVOPT=P      ! draw Projecting tick marks
  PGPLOT_ENVOPT=I      ! Invert the tick marks
  PGPLOT_ENVOPT=IV     ! Invert tick marks and label y Vertically

PGERRB -- horizontal or vertical error bar

      SUBROUTINE PGERRB (DIR, N, X, Y, E, T)
      INTEGER DIR, N
      REAL X(*), Y(*), E(*)
      REAL T

Plot error bars in the direction specified by DIR.
This routine draws an error bar only; to mark the data point at
the start of the error bar, an additional call to PGPT is required.

Arguments:
 DIR    (input)  : direction to plot the error bar relative to
                   the data point. 
                   One-sided error bar:
                     DIR is 1 for +X (X to X+E);
                            2 for +Y (Y to Y+E);
                            3 for -X (X to X-E);
                            4 for -Y (Y to Y-E).
                   Two-sided error bar:
                     DIR is 5 for +/-X (X-E to X+E); 
                            6 for +/-Y (Y-E to Y+E).
 N      (input)  : number of error bars to plot.
 X      (input)  : world x-coordinates of the data.
 Y      (input)  : world y-coordinates of the data.
 E      (input)  : value of error bar distance to be added to the
                   data position in world coordinates.
 T      (input)  : length of terminals to be drawn at the ends
                   of the error bar, as a multiple of the default
                   length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X, Y, and E must be greater
than or equal to N. If N is 1, X, Y, and E may be scalar
variables, or expressions.

PGFUNX -- function defined by Y = F(X)

      SUBROUTINE PGFUNX (FY, N, XMIN, XMAX, PGFLAG)
      REAL FY
      EXTERNAL FY
      INTEGER N
      REAL XMIN, XMAX
      INTEGER PGFLAG

Draw a curve defined by the equation Y = FY(X), where FY is a
user-supplied subroutine.

Arguments:
 FY     (external real function): supplied by the user, evaluates
                   Y value at a given X-coordinate.
 N      (input)  : the number of points required to define the
                   curve. The function FY will be called N+1 times.
                   If PGFLAG=0 and N is greater than 1000, 1000
                   will be used instead.  If N is less than 1,
                   nothing will be drawn.
 XMIN   (input)  : the minimum value of X.
 XMAX   (input)  : the maximum value of X.
 PGFLAG (input)  : if PGFLAG = 1, the curve is plotted in the
                   current window and viewport; if PGFLAG = 0,
                   PGENV is called automatically by PGFUNX to
                   start a new plot with X limits (XMIN, XMAX)
                   and automatic scaling in Y.

Note: The function FY must be declared EXTERNAL in the Fortran
program unit that calls PGFUNX.  It has one argument, the
x-coordinate at which the y value is required, e.g.
  REAL FUNCTION FY(X)
  REAL X
  FY = .....
  END

PGHIST -- histogram of unbinned data

      SUBROUTINE PGHIST(N, DATA, DATMIN, DATMAX, NBIN, PGFLAG)
      INTEGER N
      REAL    DATA(*)
      REAL    DATMIN, DATMAX
      INTEGER NBIN, PGFLAG

Draw a histogram of N values of a variable in array
DATA(1...N) in the range DATMIN to DATMAX using NBIN bins.  Note
that array elements which fall exactly on the boundary between
two bins will be counted in the higher bin rather than the
lower one; and array elements whose value is less than DATMIN or
greater than or equal to DATMAX will not be counted at all.

Arguments:
 N      (input)  : the number of data values.
 DATA   (input)  : the data values. Note: the dimension of array
                   DATA must be greater than or equal to N. The
                   first N elements of the array are used.
 DATMIN (input)  : the minimum data value for the histogram.
 DATMAX (input)  : the maximum data value for the histogram.
 NBIN   (input)  : the number of bins to use: the range DATMIN to
                   DATMAX is divided into NBIN equal bins and
                   the number of DATA values in each bin is
                   determined by PGHIST.  NBIN may not exceed 200.
 PGFLAG (input)  : if PGFLAG = 1, the histogram is plotted in the
                   current window and viewport; if PGFLAG = 0,
                   PGENV is called automatically by PGHIST to start
                   a new plot (the x-limits of the window will be
                   DATMIN and DATMAX; the y-limits will be chosen
                   automatically.
                   IF PGFLAG = 2,3 the histogram will be in the same
                   window and viewport but with a filled area style.
                   If pgflag=4,5 as for pgflag = 0,1, but simple
                   line drawn as for PGBIN

PGLAB -- write labels for x-axis, y-axis, and top of plot

      SUBROUTINE PGLAB (XLBL, YLBL, TOPLBL)
      CHARACTER*(*) XLBL, YLBL, TOPLBL

Write labels outside the viewport. This routine is a simple
interface to PGMTXT, which should be used if PGLAB is inadequate.

Arguments:
 XLBL   (input) : a label for the x-axis (centered below the
                  viewport).
 YLBL   (input) : a label for the y-axis (centered to the left
                  of the viewport, drawn vertically).
 TOPLBL (input) : a label for the entire plot (centered above the
                  viewport).

PGLINE -- draw a polyline (curve defined by line-segments)

      SUBROUTINE PGLINE (N, XPTS, YPTS)
      INTEGER  N
      REAL     XPTS(*), YPTS(*)

Primitive routine to draw a Polyline. A polyline is one or more
connected straight-line segments.  The polyline is drawn using
the current setting of attributes color-index, line-style, and
line-width. The polyline is clipped at the edge of the window.

Arguments:
 N      (input)  : number of points defining the line; the line
                   consists of (N-1) straight-line segments.
                   N should be greater than 1 (if it is 1 or less,
                   nothing will be drawn).
 XPTS   (input)  : world x-coordinates of the points.
 YPTS   (input)  : world y-coordinates of the points.

The dimension of arrays X and Y must be greater than or equal to N.
The "pen position" is changed to (X(N),Y(N)) in world coordinates
(if N > 1).

PGMOVE -- move pen (change current pen position)

      SUBROUTINE PGMOVE (X, Y)
      REAL X, Y

Primitive routine to move the "pen" to the point with world
coordinates (X,Y). No line is drawn.

Arguments:
 X      (input)  : world x-coordinate of the new pen position.
 Y      (input)  : world y-coordinate of the new pen position.

PGOPEN -- open a graphics device

      INTEGER FUNCTION PGOPEN (DEVICE)
      CHARACTER*(*) DEVICE

Open a graphics device for PGPLOT output. If the device is
opened successfully, it becomes the selected device to which
graphics output is directed until another device is selected
with PGSLCT or the device is closed with PGCLOS.

The value returned by PGOPEN should be tested to ensure that
the device was opened successfully, e.g.,

      ISTAT = PGOPEN('plot.ps/PS')
      IF (ISTAT .LE. 0 ) STOP

Note that PGOPEN must be declared INTEGER in the calling program.

The DEVICE argument is a character constant or variable; its value
should be one of the following:

(1) A complete device specification of the form 'device/type' or
    'file/type', where 'type' is one of the allowed PGPLOT device
    types (installation-dependent) and 'device' or 'file' is the 
    name of a graphics device or disk file appropriate for this type.
    The 'device' or 'file' may contain '/' characters; the final
    '/' delimits the 'type'. If necessary to avoid ambiguity,
    the 'device' part of the string may be enclosed in double
    quotation marks.
(2) A device specification of the form '/type', where 'type' is one
    of the allowed PGPLOT device types. PGPLOT supplies a default
    file or device name appropriate for this device type.
(3) A device specification with '/type' omitted; in this case
    the type is taken from the environment variable PGPLOT_TYPE,
    if defined (e.g., setenv PGPLOT_TYPE PS). Because of possible
    confusion with '/' in file-names, omitting the device type
    in this way is not recommended.
(4) A blank string (' '); in this case, PGOPEN will use the value
    of environment variable PGPLOT_DEV as the device specification,
    or '/NULL' if the environment variable is undefined.
(5) A single question mark, with optional trailing spaces ('?'); in
    this case, PGPLOT will prompt the user to supply the device
    specification, with a prompt string of the form
        'Graphics device/type (? to see list, default XXX):'
    where 'XXX' is the default (value of environment variable
    PGPLOT_DEV).
(6) A non-blank string in which the first character is a question
    mark (e.g., '?Device: '); in this case, PGPLOT will prompt the
    user to supply the device specification, using the supplied
    string as the prompt (without the leading question mark but
    including any trailing spaces).

In cases (5) and (6), the device specification is read from the
standard input. The user should respond to the prompt with a device
specification of the form (1), (2), or (3). If the user types a 
question-mark in response to the prompt, a list of available device
types is displayed and the prompt is re-issued. If the user supplies
an invalid device specification, the prompt is re-issued. If the user
responds with an end-of-file character, e.g., ctrl-D in UNIX, program
execution is aborted; this  avoids the possibility of an infinite
prompting loop.  A programmer should avoid use of PGPLOT-prompting
if this behavior is not desirable.

The device type is case-insensitive (e.g., '/ps' and '/PS' are 
equivalent). The device or file name may be case-sensitive in some
operating systems.

Examples of valid DEVICE arguments:

(1)  'plot.ps/ps', 'dir/plot.ps/ps', '"dir/plot.ps"/ps', 
     'user:[tjp.plots]plot.ps/PS'
(2)  '/ps'      (PGPLOT interprets this as 'pgplot.ps/ps')
(3)  'plot.ps'  (if PGPLOT_TYPE is defined as 'ps', PGPLOT
                 interprets this as 'plot.ps/ps')
(4)  '   '      (if PGPLOT_DEV is defined)
(5)  '?  '
(6)  '?Device specification for PGPLOT: '

[This routine was added to PGPLOT in Version 5.1.0. Older programs
use PGBEG instead.]

Returns:
 PGOPEN          : returns either a positive value, the
                   identifier of the graphics device for use with
                   PGSLCT, or a 0 or negative value indicating an
                   error. In the event of error a message is
                   written on the standard error unit.
Arguments:
 DEVICE  (input) : the 'device specification' for the plot device
                   (see above).

PGPAGE -- advance to new page

      SUBROUTINE PGPAGE

Advance plotter to a new page or panel, clearing the screen if
necessary. If the "prompt state" is ON (see PGASK), confirmation is
requested from the user before clearing the screen. If the view
surface has been subdivided into panels with PGBEG or PGSUBP, then
PGPAGE advances to the next panel, and if the current panel is the
last on the page, PGPAGE clears the screen or starts a new sheet of
paper.  PGPAGE does not change the PGPLOT window or the viewport
(in normalized device coordinates); but note that if the size of the
view-surface is changed externally (e.g., by a workstation window
manager) the size of the viewport is changed in proportion.

Arguments: none

PGPT -- draw several graph markers

      SUBROUTINE PGPT (N, XPTS, YPTS, SYMBOL)
      INTEGER N
      REAL XPTS(*), YPTS(*)
      INTEGER SYMBOL

Primitive routine to draw Graph Markers (polymarker). The markers
are drawn using the current values of attributes color-index,
line-width, and character-height (character-font applies if the symbol
number is >31).  If the point to be marked lies outside the window,
no marker is drawn.  The "pen position" is changed to
(XPTS(N),YPTS(N)) in world coordinates (if N > 0).

Arguments:
 N      (input)  : number of points to mark.
 XPTS   (input)  : world x-coordinates of the points.
 YPTS   (input)  : world y-coordinates of the points.
 SYMBOL (input)  : code number of the symbol to be drawn at each 
                   point:
                   -1, -2  : a single dot (diameter = current
                             line width).
                   -3..-31 : a regular polygon with ABS(SYMBOL)
                             edges (style set by current fill style).
                   0..31   : standard marker symbols.
                   32..127 : ASCII characters (in current font).
                             e.g. to use letter F as a marker, let
                             SYMBOL = ICHAR('F').
                   > 127  :  a Hershey symbol number.

Note: the dimension of arrays X and Y must be greater than or equal
to N. If N is 1, X and Y may be scalars (constants or variables). If
N is less than 1, nothing is drawn.

PGSCI -- set color index

      SUBROUTINE PGSCI (CI)
      INTEGER  CI

Set the Color Index for subsequent plotting, if the output device
permits this. The default color index is 1, usually white on a black
background for video displays or black on a white background for
printer plots. The color index is an integer in the range 0 to a
device-dependent maximum. Color index 0 corresponds to the background
color; lines may be "erased" by overwriting them with color index 0
(if the device permits this).

If the requested color index is not available on the selected device,
color index 1 will be substituted.

The assignment of colors to color indices can be changed with
subroutine PGSCR (set color representation).  Color indices 0-15
have predefined color representations (see the PGPLOT manual), but
these may be changed with PGSCR.  Color indices above 15  have no
predefined representations: if these indices are used, PGSCR must
be called to define the representation.

Argument:
 CI     (input)  : the color index to be used for subsequent plotting
                   on the current device (in range 0-max). If the
                   index exceeds the device-dependent maximum, the
                   default color index (1) is used.

PGSLW -- set line width

      SUBROUTINE PGSLW (LW)
      INTEGER  LW

Set the line-width attribute. This attribute affects lines, graph
markers, and text. The line width is specified in units of 1/200
(0.005) inch (about 0.13 mm) and must be an integer in the range
1-201. On some devices, thick lines are generated by tracing each
line with multiple strokes offset in the direction perpendicular to
the line.

Argument:
 LW     (input)  : width of line, in units of 0.005 inch (0.13 mm)
                   in range 1-201.

PGTEXT -- write text (horizontal, left-justified)

      SUBROUTINE PGTEXT (X, Y, TEXT)
      REAL X, Y
      CHARACTER*(*) TEXT

Write text. The bottom left corner of the first character is placed
at the specified position, and the text is written horizontally.
This is a simplified interface to the primitive routine PGPTXT.
For non-horizontal text, use PGPTXT.

Arguments:
 X      (input)  : world x-coordinate of start of string.
 Y      (input)  : world y-coordinate of start of string.
 TEXT   (input)  : the character string to be plotted.