\chapter{Basics}

\section{QDP files}
\label{qdpfiles}

The quickest and most convenient way to use PLT is with a QDP file.
A QDP file is an ASCII text file that contains a rectangular array
of data.
Since QDP files are ASCII they are easy to create and
highly portable to different computer systems.
All QDP files must contain a two dimensional array of data.
The row-column location of a number in the file determines the
row-column index in the data array passed to PLT.
It is possible, but not necessary,
to include QDP and/or PLT commands at the top of the QDP file.
These commands often serve to document the data.
All the QDP program does is to read the file,
and to pass the information to the PLT subroutine.

In order to try out the examples in this chapter and the next,
you should first create a ``{\tt DEMO.QDP}'' file that contains
the following:
\begin{verbatim}
   1   1  16
   2   4   9
   3   9   4
   4  15   1          ! Yes 15 and NOT 16
\end{verbatim}
({\tt XANADU:[PLOT.QDP]DEMO.QDP} contains a pre-typed version of this
file.)
This example file contains no QDP or PLT commands.
The QDP default is to assume that each column of numbers is a separate
vector.

This example illustrates that QDP files can contain comments.
Comments begin with the comment character \verb@ ! @
and continue to the end of the line.
The above example contains the comment ``\verb@Yes 15 and NOT 16@''.
Comments are completely ignored.
This documentation will often include a comment with the example commands.
When trying out the command,
you do not need to type the comment;
however, if you do type it, then no harm will be done.

The QDP data lines are free format
and the numbers can be separated by spaces, a comma, or tabs.
Every row should contain the same number of columns;
however, if some data are missing,
you can enter the word {\tt NO} instead of an actual number.
QDP translates the {\tt NO} into the PLT no-data flag;
which will be ignored by PLT.

\section{Plot the file}

Once you have created a version of {\tt DEMO.QDP}, you can run QDP by
typing:
\begin{verbatim}
$ QDP DEMO
\end{verbatim}
(If QDP fails to run, then you might need to define the QDP symbol
as described in Appendix~\ref{install}, {\bf Installation Guide}.)
It is not necessary to enter the \verb@.QDP@ extension as the QDP
program assumes that as the default.
When the program starts,
you will receive the following message:
\begin{verbatim}
To produce plot, please enter
PGPLOT file/type:
\end{verbatim}
You should enter the PGPLOT specification
for the device on which you wish to plot.
If you do not know the device name,
then enter \verb@ ? @ and all the device types
supported by your local version of PGPLOT will be listed.
If your terminal supports Tektronix graphics, then enter \verb@ /TE @
to make the plot appear on your terminal.
You might also try \verb@ /RE @ for Retrographics.
Most Tektronix emulators support the Retrographics extensions
that allow the software to toggle between text and graphics modes.

A graph containing two lines will now be drawn as illustrated in
Figure \ref{fig21}.
\begin{figure}
   \vspace{11cm}
   \special{psfile=fig21.ps hscale=70 vscale=40}
   \caption{The default appearance of the {\tt DEMO.QDP} file.}
   \label{fig21}
\end{figure}
Since the file contained three columns of numbers,
the default mode assumes there are three plot groups.
The first plot group determines the $x$ coordinate.
The next two columns are plotted as two lines.
On a color display the first line will be red and the second green,
which are the default colors for plot groups 2 and 3.
The name of the QDP file appears in the top left of the plot
and your userid, current date, and time
appear in the bottom right of the plot.
The \verb@ PLT> @ prompt will now appear.
In the following sections
you will see how to enter various commands to change the default plot.
The most useful command for beginners is the \verb@ HElp @ command
which can be used to get instructions on how to use any command.

Another useful command is \verb@EXit@ that will get you out of
the PLT subroutine.
If you are in QDP, control will be returned to the operating system;
in other programs, control will be returned to the calling program.

\section{Rescaling}

PLT chooses a default scale that makes all the data visible.
The examples in this section will illustrate
the {\tt Rescale} command that can be used to change this scale.
Using the plot created in the previous section, enter
\begin{verbatim}
PLT> R X 0 5
\end{verbatim}
When you enter this command, the graph is redrawn
with 0.0 on the left side and 5.0 on the right side of the viewport.
Likewise \verb@ R Y 0 20 @ will put 0.0 on the bottom and 20.0 on the top.
If you wish to change one number without the other,
you can skip the field with commas
or terminate the line before changing the default.
For example, both
\begin{verbatim}
PLT> R Y 0 20    ! Set both lower and upper limit
\end{verbatim}
and
\begin{verbatim}
PLT> R Y,,20     ! Set upper limit to 20, leaving lower unaffected
PLT> R Y 0       ! Set lower limit to 0, leaving upper unaffected
\end{verbatim}
will produce the same effect.
If you wish to change both the {\tt X} and {\tt Y} limits,
then use
\begin{verbatim}
PLT> R 1 5 1 16  ! Set X-range to 1 to 5, and Y-range 1 to 16
\end{verbatim}
If you wish to go back to the default scale, then use {\tt R} with
no arguments:
\begin{verbatim}
PLT> R Y         ! Will reset Y limits to default
PLT> R           ! Will reset both X and Y limits to default
\end{verbatim}

At any time you can find out what the current scale limits are with
\begin{verbatim}
PLT> R ?
 Current Gap=   .025
Window   XLAB      XMIN        XMAX         YLAB      YMIN        YMAX
   1 :             .9250    ,  4.075     :             .6250    ,  16.38
PLT>
\end{verbatim}
This produces a table of the current scaling parameters.
The current gap is the default size of the gap
between the edge of the data and the edge of the plot.
For the default scale, the difference between the minimum/maximum
and the data~minimum/data~maximum is due to the gap.
With a gap of zero, the default minimum/maximum value will
exactly match the data~minimum/data~maximum.
The default is to plot all plot groups into just one window
hence only one row appears in the table corresponding to that window.
The columns labeled {\tt XLAB} and {\tt YLAB} contain the
current $x$ and $y$ labels, which are currently blank.

If you want to see what the data minimum and maximum values are
you should use
\begin{verbatim}
PLT> SHow Group

Grp  Wind    Label     XData Min    XData Max    YData Min    YData Max
  1    -1             :  1.000    ,   4.000     :  1.000    ,   4.000
  2     1             :  1.000    ,   4.000     :  1.000    ,   15.00
  3     1             :  1.000    ,   4.000     :  1.000    ,   16.00
\end{verbatim}
The three rows correspond to the three plot groups.
The column labeled {\tt Wind} contains the window in which the group is
currently being plotted, and a negative number indicates that the
group is not actually plotted.
In this example, group 1 is used to determine the $x$ coordinate and
so is not actually plotted.
The columns labeled {\tt YData Min} and {\tt YData Max} contain
the actual data minimum and maximum of that plot group.

\section{Making a hardcopy}
PLT makes a hardcopy by using the same PGPLOT routines but routed
to a different graphics device.
Thus the command does not make a hardcopy of what is currently on
your screen,
but rather, what would be plotted if you reissued the {\tt Plot} command.
The {\tt HArd~?} command will display the name of your current
default hardcopy device.
It is possible to override this default when you enter the \verb@HArd@
command, thus {\tt HArd /VPS} would make a vertical (portrait) mode
Postscript file no matter what the default is.
If you would like a default different from what is set up on your system,
then you should define the logical name, or on UNIX, the environment
variable, \verb@PLT_HARDCOPY@ to contain the default you want.
Let's assume the default is OK\@.
So, merely enter
\begin{verbatim}
PLT> CSize 1.3   ! To increase the character size a bit
PLT> FOnt Roman  ! To use the nice looking Roman font
PLT> HArdcopy    ! To make a hardcopy file
\end{verbatim}
PGPLOT would have now made a file in your current directory.
You should consult your PGPLOT manual
for the rules on how to print this file.
On many systems it is possible to use the {\tt @HARD} command that
will both create a file and then spool the file to the printer.

The default PLT font is the Simple font because it plots the fastest.
When you are making a hardcopy, speed is less important than quality.
Therefore, you are encouraged to use the Roman font,
which will give a more professional look to your hardcopy.
As most journals greatly reduce the size of figures before printing,
you should increase the character size.
In the above example, \verb@CSize 1.3@ makes the character size a
factor of 1.3 times larger than the default.
The default line width is one, which is the thinest possible line.
On some laser printers, this is too thin, and therefore, you should
increase the line width, using the \verb@LWidth@ command.
Using \verb@LWidth 7@ is not unreasonable for publication quality
on some printers.
In general the default hardcopy plot will fill the page on
which it is being plotted.
If a viewgraph was made of a full page plot,
the projected size would overfill most screens.
Therefore, it is useful to decrease the default size of the plot a
bit.
This can be done with the \verb@Viewport@ command.
The default viewport is \verb@.1 .1@ which means the box
containing the graph extends from 0.10 to 0.90 of the total
physical plotting area.
To make a plot half the size, use \verb@View .3 .3@.
\verb@View .2 .2@ will result in a good size for most viewgraphs.
