\chapter{Introduction}

\section{Overview}

The {\em Quick and Dandy Plotter (QDP)} program reads ASCII files
containing various plotting commands and data.
{\em QDP} then calls the {\em PLT} subroutine which then executes
the commands and plots the data.
At this point the ``\verb@PLT>@'' prompt appears and the user can
then proceed to enter additional PLT commands which can:
\begin{itemize}
\item Display information on about the interactive commands
{\it via} {\tt HElp},

\item Override various PLT defaults,

\item Override the PLT commands found in the QDP file,

\item Add/remove labels,

\item Plot data with various combinations of lines, markers, and error bars,

\item Change the appearance/style of the of the plot, for example converting
all text into the Roman Font,

\item Plot the data as a function of a different $x$ variable,

\item Change the number of panels in which the data is plotted,

\item Define models and calculate the `best fit' parameter values,

\item Generate a hardcopy.
\end{itemize}

Thus the interactive PLT commands allow you to both
tailor the plot to your needs/taste and
to do some simple analyses of the data.
PLT commands can be placed in the QDP file, in an indirect command
and/or in a command array created by the calling program.
For example, if you have a set of commands that you commonly use,
you can place those commands in a file, and then have PLT
execute the commands that it finds in that file.
Since exactly the same command syntax is used, it is
not necessary to learn a special programming language to write software
that uses PLT.
Programmers can try out PLT commands interactively to find
a set that works best with the type of data being plotted,
and then make these commands the default values.

The PLT software is highly portable.
It uses the PGPLOT Graphics Subroutine Library written by
T. J. Pearson at the California Institute of Technology.
PGPLOT has been ported to many systems ranging from MS-DOS
machines to UNICOS Crays.
PLT is actively supported on VAX VMS, SUN UNIX, and NeXT systems.
The code is in standard Fortran and so can easily be ported to other
systems and runs on MS-DOS, PRIME, and IBM RS/6000 systems.

This manual provides an overview of how to use PLT.
Not all commands will be described in the overview.
However, Appendix B includes the contents of the on-line help which
does contain every command.

The rest of this introduction defines a few terms and discusses
the syntax conventions used.
If you wish to get started quickly, you should skip to the next chapter.
Once you have mastered the basics, you should come back and
read the following sections.

\section{Definitions}

PLT operates on quantities called {\em vectors} which can consist
of one, two, or three columns in this rectangular array.
If the data contains no errors, then each column is a vector.
If the data contains symmetric errors,
then it takes two columns to denote a single vector.
Likewise, if you have two-sided errors ({\it e.g.}, +5,$-$2),
it will take 3 columns to denote a vector.
If one number in a vector has an error,
then all numbers in that vector must have the same type of error.
The vectors are independent of each other,
and so some vectors can have errors and others not.

The PLT default is to make each vector an independent plot group.
The PLT {\tt SKip} command can be used if you have just two vectors
and you wish to create several plot groups within those vectors.

{\em Viewport} denotes the physical area of the plotting surface
that you are using.
PLT ({\it via} PGPLOT) uses device-independent coordinates to denote
the viewport,
with (0.0,0.0) denoting the bottom left corner of the display surface,
and (1.0,1.0) the top right corner.

PLT can be used to fit a model to the data.
A {\it model} consists of one or more components which are added together.
Each component must have one or more parameters;
when fitting the data,
the parameters are varied to minimize $\chi^2$.
There is no way to multiply the built-in components together.

A {\it COD file} is an ASCII text file
that contains a function written in the COD programming language.
PLT allows you to define a model in which one of the components
is a function contained a COD file.
When FIT evaluates that component,
the COD function is called and should return
with the function evaluated for the current parameter set.

\section{Syntax}

PLT does not distinguish between upper and lower case.
When PLT matches the characters you type with possible commands,
it only matches characters in the {\em shortest unique abbreviation}
which, in this documentation, is denoted by upper case.
Thus both {\tt color} and {\tt colour} will match the {\tt COlor}
command.
Of course, some caution is required as {\tt cosmopolitan} will also
match {\tt COlor}.
As new commands are added, a previously acceptable abbreviation
could refer to one of the new commands.
To avoid such potential conflicts,
you are encouraged to use three letter abbreviations.

In this documentation, a name in all lower case name is a mnemonic
and should not be entered.
For example, in {\tt Rescale X xmin,xmax} both ``\verb@xmin@'' and
``\verb@xmax@'' should be replaced with numbers.

In PLT, arguments can be separated by a comma and/or any number of
spaces and tab characters.
Thus, the strings \ {\tt 1~2~3}~, \ {\tt 1,2,3}~, \ {\tt 1,~2,~3}~,
and \ {\tt 1~,~2~,~3 } are all parsed as three arguments.
Sometimes it is necessary to leave a place-holder that indicates an
argument should be skipped.
This is done by entering two adjacent commas.
The string \ {\tt 1,,3} \ is parsed as three arguments with the
second argument being null.
Null arguments are often used to indicate that the current value should
not be changed.
If it is necessary to enter any special character as part of an
argument, the argument should be enclosed in quotation marks.
The string \ {\tt 1,"2,3,4",5} \ would be parsed as three arguments
and the second argument would be the string \ {\tt 2,3,4}\ .

PLT allows you to embed the simple mathematical operators,
\ {\tt +} \ , \ {\tt -} \ , \ {\tt *} \ , and \ {\tt /} \ into numbers.
Thus, the argument \ {\tt 2*3} \ would be parsed as 6.
The numeric expression is evaluated from left to right;
hence, the argument \ {\tt 1+2/4} \ is parsed 3/4 or 0.75.
This syntax can be useful in QDP files.
For example, suppose column 1 is the time in seconds,
and you wish to plot time in hours.
This can be done with a global edit
that appends the string {\tt /3600.} to the numbers in column 1.

The character \ {\tt \#} \ is used to denote a number.
When you see this character, you should not type \ {\tt \#}~,
but rather replace it with a number.
Likewise, the character \ {\tt \$} \ denotes a string.
Optional arguments are enclosed in square brackets
\ {\tt [}\ldots {\tt ]}~\ \@.
If an argument must be one of several discrete choices,
the choices will be listed separated by vertical lines \ {\tt |}~.

\section{Questions}

Please address suggestions for improvements,
or reports of software bugs, to the author:

\begin{tabbing}
Indent this far \=  and then again \= \kill
\> \> Allyn Tennant, ES-65\\
\> \> NASA MSFC\\
\> \> Huntsville, \ AL \ \ 35812\\
\> \> USA\\
\> \> \\
\> {\it Telephone:} \> 205 544-3424\\
\> {\it FAX:}       \> 205 544-7754\\
\> \> \\
\> {\it SPAN:}      \> SSL::TENNANT or 7207::TENNANT\\
\> {\it Internet:}  \> tennant\%ssl.span@fedex.msfc.nasa.gov\\
\end{tabbing}

\noindent
Please address requests for copies of this manual or the software to:

\begin{tabbing}
Indent this far \=  and then again \= \kill
\> \> COSMIC\\
\> \> The University of Georgia\\
\> \> 382 East Broad Street\\
\> \> Athens, \ GA \ \ 30602\\
\> \> USA\\
\> \> \\
\> {\it Telephone:} \> 404 542-3265\\
\end{tabbing}

\section{Acknowledgements}

These days most non-trivial software packages have evolved over a
long period of time and PLT is no exception.

The first program to bear the name of QDP was written in the late
1970's by Andy Szymkowiak for use by the X-ray group on a PDP 11/70
at Goddard Space Flight Center.  Although I don't think that a single
line of code has survived from that original version, I am grateful
to Andy for that version, and hence for the basic idea of an interactive
graphics program.

The QDP/PLT development flourished during my years at the Institute
of Astronomy, Cambridge, U.K.  I am grateful to Andy Fabian for being
able to fund my stay there, and also for providing the stimulating
environment where such working software could be developed.  It is
important that PLT was developed not as a software project, but rather
to meet real needs in the analysis of data.

Now that I am at Marshall Space Flight Center, I would like to thank
Martin Weisskopf for his continuing support of these efforts.

I am grateful to Tim Pearson for providing and for continuing to support
the PGPLOT graphics package.  PGPLOT is flexible, easy to use, portable
and device independent.

Numerous other people have made contributions to PLT, ranging from
simple comments, such as ``it doesn't work when I do this", to actually
providing the code for new features.  Some of these people are mentioned
in the on-line help file under the ``history" subtopic.  I would like
to say thank you to all the people who have offered comments.
