          Chapter 4: Plotting Axis Systems and Titles

4.1 Plotting Axis Systems

An  axis system  defines  an area  on the page  for plotting
data.  Various axis systems  can be  plotted  to accommodate
different applications. For two-dimensional graphics, a max-
imum of two parallel  X- and Y-axes  can be drawn.  The axis
system is scaled  to fit the range of data points and can be
labeled with values, names and ticks.  Two-dimensional  axis
systems  are plotted  with a call  to the routines  GRAF  or 
GRAFP.

                              G R A F

GRAF plots a two-dimensional axis system.

The call is:  CALL GRAF (XA, XE, XOR, XSTEP, 
                         YA, YE, YOR, YSTEP)         level 1

XA, XE        are the lower and upper limits  of the X-axis.
XOR, XSTEP    are the first  X-axis label  and the  step be-
              tween labels.
YA, YE  are   the lower and upper limits of the Y-axis.
YOR, YSTEP    are the first  Y-axis label  and the  step be-
              tween labels.

Notes:     -  GRAF must be called  in level 1  and automati-
              cally sets the level to 2.  When plotting more
              than  1 axis system  on a page, ENDGRF must be
              called  in between each new set of axes in or-
              der to set the level back to 1.
           -  The position  of the lower left corner and the
              size of an axis system can be changed with the
              routines AXSPOS and AXSLEN.
           -  The axis scaling is linear by default  and can
              be changed with AXSSCL.  For logarithmic  sca-
              ling,  the corresponding  parameters  in  GRAF
              must be exponents of base 10.
           -  One of several label types can be chosen  with
              the routine LABELS or user-defined with MYLAB.
              Single  labels  can be  suppressed  by calling
              AXENDS.
           -  The routine NAME defines axis titles.
           -  The number of ticks between axis labels can be
              changed with the routine TICKS.
           -  SETGRF  can be  used  to remove  a piece of or
              complete axis from an axis system.
           -  If the numerical value  of the lower  limit of
              an axis is larger than the upper limit and the
              label step is negative,  axis scaling  will be
              in descending order.
           -  The routine  FRAME  defines the thickness of a
              frame plotted  around an axis system.  A frame
              can also be plotted outside of  GRAF  with the
              statement CALL BOX2D.

                              G R A F P

The routine GRAFP plots a two-dimensional polar axis system.

The call is:  CALL GRAFP (XE, XOR, XSTEP, YOR, YSTEP)
                                                     level 1

XE            is upper limit  of the  X-axis (radius coordi-
              nate).
XOR, XSTEP    are the first  X-axis label  and the  step be-
              tween labels.
YOR, YSTEP    are the first  Y-axis label  and the  step be-
              tween labels specified in degrees.  The Y-axis
              is scaled from 0 to 360 degrees.

Notes:      - The direction and position of the angle labels
              can be modified with the routine POLMOD.
            - GRAFP is a new name for the old routine POLAR,
              since  polar  is also a C99 function.  The old 
              routine POLAR  is still in the  DISLIN librar-
              ies.  

4.2 Termination of Axis Systems

                         E N D G R F

The routine  ENDGRF  terminates  an axis system and sets the
level back to 1.

The call is:  CALL ENDGRF                         level 2, 3

Note:         ENDGRF  contains  a call of the routine SENDBF
              that can be disabled with the routine BUFMOD.

4.3 Plotting Titles

                         T I T L E

This routine plots  a title  over an axis system.  The title
may contain up to four lines of text designated with TITLIN.

The call is:  CALL TITLE                          level 2, 3

Note:         All lines  are centred  by default  but can be
              left- or right-justified using TITJUS.

4.4 Plotting Grid Lines

                         G R I D

The routine GRID overlays a grid on an axis system.

The call is:      CALL GRID (IXGRID, IYGRID)      level 2, 3

IXGRID, IYGRID    are the numbers  of grid lines between la-
                  bels.

Note:             GRID uses automatically GRDPOL for a polar 
                  axis system.

                         G R D P O L

The routine GRDPOL plots a polar grid.

The call is:      CALL GRDPOL (IXGRID, IYGRID)    level 2, 3

IXGRID            is the numbers of circles between labels.
IYGRID            is the numbers of sector lines between 360
                  degrees.

                         A X G I T

The  routine  AXGIT  plots  vertical  and  horizontal  lines
through X = 0 and Y = 0.
The call is:  CALL AXGIT                          level 2, 3

Note:         The statement  CALL XAXGIT plots only the line
              Y = 0 while CALL YAXGIT plots only X = 0.

                         C R O S S

The routine  CROSS plots vertical  and horizontal lines with
additional ticks through X = 0 and Y = 0.

The call is:  CALL CROSS                          level 2, 3

Note:         The statement  CALL XCROSS plots only the line
              Y = 0 while CALL YCROSS plots only X = 0.

4.5 Plotting Additional Labels

                         A D D L A B

Additional  single labels  can be plotted  on an axis system
with the routine ADDLAB.

The call is:  CALL ADDLAB (CSTR, V, ITIC, CAX)    level 2, 3

CSTR          is a character string containing a label.
V             is an  user coordinate  that  defines the axis
              position of the label.
ITIC          is an integer option  that  defines  if a tick
              mark is plotted.  ITIC = 0 means  that no tick
              is plotted,  ITIC = 1 defines a minor tick and
              ITICK = 2 defines a major tick.
CAX           is a character string that defines the axis.
              CAX can have the values  'X', 'Y', 'Z', 'XTOP'
              and 'YRIGHT'.

4.6 Secondary Axes

The following routines  plot single  X- and Y-axes; they are
called secondary axes  because they do not define  or change
any of the  axis scaling parameters.  Secondary axes  can be
used to add additional labels to the axis systems.

The plotting routines for secondary axes are:

    XAXIS  plots a linear X-axis.              level 1, 2, 3
    YAXIS  plots a linear Y-axis.              level 1, 2, 3
    XAXLG  plots a logarithmic X-axis.         level 1, 2, 3
    YAXLG  plots a logarithmic Y-axis.         level 1, 2, 3

The call is:  CALL XAXIS (A, B, OR, STEP, NL, CSTR, IT,
                                                     NX, NY)

A, B          are the lower and upper limits of the axis.
OR, S         are the first  label and the step  between la-
              bels.
NL            is the length of the axis in plot coordinates.
CSTR          is a  character  string  containing  the  axis
              name.
IT            indicates how ticks,  labels and the axis name
              are plotted. If IT = 0,  they are plotted in a
              clockwise direction. If IT = 1, they are plot-
              ted  in an  counter-clockwise direction.
NX, NY        are  the  plot  coordinates  of the axis start
              point.  The X-axis  will be plotted  from left
              to right  and the Y-axis from bottom to top.

Analogue:     YAXIS, XAXLG, YAXLG

Notes:     -  Secondary axes can be called  from level  1, 2
              or 3.  Note again  that  secondary axes do not
              change  the scaling of  an axis system defined
              by GRAF.  Similarly,  curves cannot be plotted
              with only secondary axes,  they require a call
              to GRAF.
           -  As in GRAF, the parameters of logarithmic axes
              must be exponents of base 10.
           -  User-defined  labels  may also  be plotted  on
              secondary axes  with  MYLAB  and the  argument
              'MYLAB' in the routine LABELS. 
           -  The number of ticks  can be changed by calling
              TICKS.

4.7 Calculating Axis Parameters

                         G A X P A R

The routine  GAXPAR  calculates parameters  for  GRAF from a 
minimum and maximum of data values.

The call is:  CALL GAXPAR (V1,V2,COPT,CAX,A,B,OR,STEP,NDIG)
                                               level 1, 2, 3

V1, V2        are the lower and upper limits of the axis. If
              V1 > V2, the calculated parameters  will be in
              descending order.
COPT          is a character string that can have the values
              'NOEXTEND' and 'EXTEND'.  For COPT = 'EXTEND',
              the calculated  axis  limits are extended to a
              full axis step.  Otherwise, V1 and V2 are used
              as axis limits.
CAX           is a character string that defines the axis. 
              CAX can have the values 'X', 'Y', and 'Z'.
A, B          are the calculated limits of the axis.
OR, STP       are the first axis label  and the step between
              labels.
NDIG          is the  calculated number of digits  after the
              decimal point that should be set with the rou-
              tine LABDIG for the labels.
    
Notes:      - The  same  algorithm as in  SETSCL for setting 
              automatic axis scaling is applied to GAXPAR.  
            - The  current  axis  settings such as linear or
              logarithmic scaling  are used by  GAXPAR.  For 
              logarithmic scaling,  the parameters V1 and V2
              must be exponents of base 10.

