\chapter {Simple Use of PLPLOT} \label{simple}

\section {Plotting a Simple Graph}
We shall first consider plotting simple graphs showing the dependence 
of one variable upon another. Such a graph may be composed of several 
elements:
\begin{itemize}
   \item A box which defines the ranges of the variables, perhaps with axes
         and numeric labels along its edges,
   \item A set of points or lines within the box showing the functional 
         dependence,
   \item A set of labels for the variables and a title for the graph.
\end{itemize}   
In order to draw such a graph, it is necessary to call at least four of 
the PLPLOT functions:
\begin{enumerate}
   \item {\tt plstar}, to specify the device you want to plot on,
   \item {\tt plenv}, to define the range and scale of the graph, and
                      draw labels, axes, etc.,
   \item One or more calls to {\tt plline} or {\tt plpoin} to draw
         lines or points as needed. Other more complex routines include
         {\tt plbin} and {\tt plhist} to draw histograms, {\tt plerrx} and 
         {\tt plerry} to draw error-bars, \label{draw}
   \item {\tt plend}, to close the plot.
\end{enumerate}
More than one graph can be drawn on a single set of axes by making
repeated calls to the routines listed in item \ref{draw} above. The routine
{\tt plstar} needs to be called only once, unless a different output device
is required.

\section {Starting PLPLOT} \label{startingup}
Subroutine {\tt plstar} selects a graphics device or opens a disk file to
receive a plot for later display. If {\tt plstar} is called again during
a program, the previously opened file will be closed. When called,
the user is prompted for a number representing the device on which 
the plot is to appear. The syntax for {\tt plstar} is:

\name{plstar(nx,ny);}
\argu{{\tt nx, ny} (int, input)}
{The number of plots to a page. The page is divided into 
{\tt nx}~$\times$~{\tt ny} subpages, with {\tt nx} in the horizontal 
direction, and {\tt ny} in the vertical direction.}

Subpages are useful for placing several graphs on a page, but all
subpages are constrained to be of the same size. For greater flexibility 
in placing graphs on a page, read page \pageref{viewport} in Section 
\ref{viewport} which discusses viewports.

\section{Defining plot scales and axes}
The function {\tt plenv} is used to define the scales and axes for simple
graphs. {\tt plenv} starts a new picture on the next subpage (or a new page
if necessary), and defines the ranges of the variables required. The
routine will also draw a box, axes, and numeric labels if requested.
The syntax for {\tt plenv} is:

\name{plenv(xmin,xmax,ymin,ymax,just,axis);}
\argu{{\tt xmin, xmax} (float, input)}
{The left and right limits for the horizontal axis.}
\argu{{\tt ymin, ymax} (float, input)}
{The bottom and top limits for the vertical axis.}
\argu{{\tt just} (int, input)}
{This should be zero or one. If {\tt just} is one, the scales of the 
x-axis and 
y-axis will be the same (in units per millimeter); otherwise the axes are 
scaled independently. This parameter is useful for ensuring that objects
such as circles have the correct aspect ratio in the final plot.}
\argu{{\tt axis} (int, input)}
{{\tt axis} controls whether a box, tick marks, labels, axes, and/or a 
grid are drawn.
\begin{itemize}
     \item {\tt axis=-2}: No box or annotation.
     \item {\tt axis=-1}: Draw box only.
     \item {\tt axis= 0}: Draw box, labelled with coordinate values around edge.
     \item {\tt axis= 1}: In addition to box and labels, draw the two axes 
                          X=0 and Y=0.
     \item {\tt axis= 2}: As for {\tt axis=1}, but also draw a grid at the major tick interval.
     \item {\tt axis=10}: Logarithmic X axis, linear Y axis.
     \item {\tt axis=11}: Logarithmic X axis, linear Y axis and draw line Y=0.
     \item {\tt axis=20}: Linear X axis, logarithmic Y axis.
     \item {\tt axis=21}: Linear X axis, logarithmic Y axis and draw line X=0.
     \item {\tt axis=30}: Logarithmic X and Y axes.
\end{itemize} 
}

Note: Logarithmic axes only affect the appearance of the axes and their 
labels, so it is up to the user to compute the logarithms prior to passing 
them to {\tt plenv} and any of the other routines. Thus, if a graph has a 3-cycle
logarithmic axis from 1 to 1000, we need to set {\tt xmin}$=\log_{10}1=0.0$, 
and {\tt xmax}$=\log_{10}1000=3.0$.

For greater control over the size of the plots, axis labelling and tick
intervals, more complex graphs should make use of the functions
\rou{plvpor}, \rou{plwind}, and \rou{plbox}
described in Chapter \ref{reference}.

\section {Labelling the graph} 
The function {\tt pllab} may be called after {\tt plenv} to write labels
on the x and y axes, and at the top of the picture. All the
variables are character variables or constants. Trailing spaces
are removed and the label is centred in the appropriate field.
The syntax for {\tt pllab} is:

\name{pllab(xlbl,ylbl,toplbl);}
\argu{{\tt xlbl} (char *, input)}
{Pointer to string with label for the X-axis (bottom of graph).}
\argu{{\tt ylbl} (char *, input)}
{Pointer to string with label for the Y-axis (left of graph).}
\argu{{\tt toplbl} (char *, input)}
{Pointer to string with label for the plot (top of picture).}

More complex labels can be drawn using the function rou{plmtex}.
See also Section \ref{graph-text} on page
\pageref{graph-text} for information about the function {\tt plptex} which
writes labels within a graph.

\section {Drawing the Graph}

PLPLOT can draw graphs consisting of points with optional error bars,
line segments or histograms. Functions which perform each of these
actions may be called after setting up the plotting environment 
using {\tt plenv}. All of the following functions draw within the box 
defined by {\tt plenv}, and any lines crossing the boundary are clipped.
Functions are also provided for drawing surface and contour representations
of multi-dimensional functions. These are described in 
Chapter \ref{advanced}.

\subsection {Drawing Points}
{\tt plpoin} and {\tt plsym} mark out {\tt n} points 
{\tt (x[i],y[i])} with the 
specified symbol. The routines differ only in the interpretation 
of the symbol 
codes. {\tt plpoin} uses an extended ASCII representation, with the 
printable 
ASCII codes mapping to the respective characters in the current font, and 
the codes from 0-31 mapping to various useful symbols. 
In {\tt plsym} however, 
the code is a Hershey font code number. Example programs are provided
which display each of the symbols available using these routines.
 
\name{plpoin(n,x,y,code); {\rm and } plsym(n,x,y,code);}
\argu{{\tt n} (int, input)}
{the number of points to plot.}
\argu{{\tt x, y} (float *, input)}
{pointers to arrays of the coordinates of the {\tt n} points.}
\argu{{\tt code} (int, input)}
{code number of symbol to draw.}

\subsection {Drawing Lines or Curves}

PLPLOT provides two functions for drawing line graphs. 
All lines are drawn in
the currently selected color and line style. See page \pageref{colour} in
Section \ref{colour} and page \pageref{style} in Section \ref{style} for
information about changing these parameters.

{\tt plline} draws a line or curve. The curve consists of {\tt n-1} line 
segments joining the {\tt n} points in the input arrays. For single line
segments, {\tt pljoin} is used to join two points.

\name{plline(n,x,y);}
\argu{{\tt n} (int, input)}
{the number of points.}
\argu{{\tt x, y} (float *, input)}
{pointers to arrays with coordinates of the {\tt n} points.}

\name{pljoin(x1,y1,x2,y2);}
\argu{{\tt x1, y1} (float, input)}
{coordinates of the first point.}
\argu{{\tt x2, y2} (float, input)}
{coordinates of the second point.}

\subsection {Writing Text on a Graph} \label {graph-text}

{\tt plptex} allows text to be written within the limits set by 
{\tt plenv}. The reference point of a text string may be located 
anywhere along an imaginary horizontal line passing through the string 
at half the height of a capital letter. The parameter "just" specifies 
where along this line the reference point is located. The string is then
rotated about the reference point through an angle specified by the
parameters {\tt dx} and {\tt dy}, so that the string becomes parallel 
to a line joining {\tt (x,y)} to {\tt (x+dx,y+dy)}.

\name{plptex(x,y,dx,dy,just,text);}
\argu{{\tt x, y} (float, input)}
{coordinates of the reference point.}
\argu{{\tt dx, dy} (float, input)}
{these specify the angle at which the text is to be printed. The text is 
 written parallel to a line joining the points {\tt (x,y)} to 
 {\tt (x+dx,y+dy)} on the graph.}
\argu{{\tt just} (float, input)}
{determines justification of the string by specifying which point within
 the string is placed at the reference point {\tt (x,y)}. This parameter
 is a fraction of the distance along the string. Thus if {\tt just=0.0}, 
 the reference point is at the left-hand edge of the string.
 If {\tt just=0.5}, it is at the center and if {\tt just=1.0}, it is at 
 the right-hand edge.}
\argu{{\tt text} (char *, input)}
{pointer to the string of characters to be written.}

\subsection {More Complex Graphs (Histograms and Error Bars)}

Functions rou{plbin} and \rou{plhist} are provided for
drawing histograms, and functions rou{plerrx}
and \rou{plerry} draw error bars about specified
points. They are described in detail in Chapter \ref{reference}.

\section {Finishing up}

Before the end of the program, always call \rou{plend}
to close any output plot file and to free up any memory that may
have been allocated.
For devices that have separate graphics
and text modes, {\tt plend} always resets the device into text mode. If
it is required to switch between modes within a program, the functions
\rou{plgra} and \rou{pltext} set the device to graphics and text modes
respectively.