\documentclass[preprint]{aastex}
\usepackage{graphicx}

\begin{document}
\newcommand{\plot}{\verb&plot& }
\newcommand{\oplot}{\verb&oplot& }
\newcommand{\oploterr}{\verb&oploterr& }
\newcommand{\setplot}{\verb&set\_plot& }
\newcommand{\device}{\verb&device& }
\newcommand{\startplot}{\verb&startplot& }
\newcommand{\eplot}{\verb&endplot& }
\newcommand{\xyouts}{\verb&xyouts& }
\newcommand{\lab}{\verb&label& }
\newcommand{\refer}{\verb&ref& }
\newcommand{\openplotps}{\verb&openplotps& }
\newcommand{\closeplotps}{\verb&closeplotps& }

\setlength{\parskip}{.02in}

%\begin{figure}[!ht]
%\begin{center}
%\leavevmode
%\epsscale{.85}
%\plotone{}
%\plottwo{}{}
%\end{center}
%\caption{}\label{}
%\end{figure}

%\begin{table}[ht]
%\begin{center}
%\begin{tabular}{c|c} \hline
%  & \\
%\hline
%\hline
%  &  \\
%\hline
%  &  \\
%\hline
%  &  \\
%\hline
%\end{tabular}
%\caption{}\label{}
%\end{center}
%\end{table}

\title{THE IDL {\tt plot} COMMANDS for BEGINNERS \\ (IDLPLOTCOMS)}

\author{Carl Heiles\footnote{Original by Josh Walawender in 2002} \\ \today} 

This is an introduction to the IDL {\tt plot} command for the computer
terminal (X window). To make a PostScript file for insertion into a
Latex document, see \S \ref{psfiles} and our handout *****. This
document is only an {\it introduction}: you can do almost anything with
the {\tt plot} command! See the on-line documentation.

\section{The {\tt plot} Command}

We can call {\tt plot} with several keywords and optional inputs and
these are what we'll explore here.  Figure \ref{exampleplot1} is the
plot generated by the following command: (Note that the \$ symbol tells
IDL that the command is continuing on the next line)

\begin{verbatim}
IDL> plot, xdata, ydata, psym=7, $
xrange=[0,10], yrange=[0,20], /xstyle, /ystyle, $
xtitle='x-axis label (units)', $
ytitle='y-axis label (units)', $
title='Title for entire plot'
\end{verbatim}

\begin{figure}[!ht]
\begin{center}
\epsscale{.6}
\plotone{ex1.ps}
\vspace{-0.4in}\end{center}

\caption{An example plot.}\label{exampleplot1}
\end{figure}

	Now we can look at the properties of Figure   \ref{exampleplot1}
and see what commands created them.  First we should note that by
prepending a / onto an IDL keyword we are setting that keyword's value
to one---many keywords simply look to see if it has a value or not, a
sort of true/false setting. 

{\tt xdata} and y{\tt data}:  the data arrays which contain the data to be
plotted on the x and y axis. 

{\tt psym=4}:  sets the data symbol.  By setting this to 7 we select the
$\times$ symbol to represent the data.  You can select other numbers to use other
symbols (i.e.  3=dots, 4=squares, 5=triangles, 6=squares, 7=$\times$s,
10=histogram style).  When psym is set to a negative number, then
the data points are connected by lines. 

{\tt (xy)range}: setting these equal to a two element array causes the
plot ranges to be set to the values in those arrays.  For {\tt x}, the
(first, second) elements are the (left, right) axis limits and for {\tt
y}, the (bottom, top).

{\tt /(xy)style}: Normally, the x and y ranges are rounded to make
human-comfortable numbers (like 10 instead of 9.5).  Setting these {\tt
styles} to unity forces the ranges to be exactly what you specify. There
are lots of other options for the {\tt style} keywords.  

{\tt (xy)title}: set this to a string which becomes the title for that
axis or for the plot itself. 

\section{Overplotting with the {\tt oplot} command}\label{oplot}

We can also use the {\tt oplot} command to overlay other plots on top
of ones we have already made.  For example, if we wanted to place a
dashed line representing the theoretical model through our data (see
Figure   \ref{ex2}) we would use the following command:

\begin{verbatim}
IDL> oplot, xdata, ytheory, linestyle=2
\end{verbatim}

\begin{figure}[!ht]
\begin{center}
\leavevmode
\epsscale{.7}
\plotone{ex2.ps}
\end{center}
\caption{An example plot with an additional plot overlayed.}\label{ex2}
\end{figure}

{\tt linestyle}:  sets the linestyle.  By setting this to 2 we selected
a dashed line.  Other numbers represent, for example, a dotted line or a
dash-dot line.  (linestyle also works in {\tt plot}).

{\tt ytheory}:  the array of theoretical values calculated for y. 

\section{Plotting Error Bars with {\tt oploterr}}\label{ploterr}

	We can add also error bars to our plot using the {\tt oploterr}
command.  In our example we can plot the y-axis uncertainty (see Figure  
\ref{ex3}) using the following command:

\begin{verbatim}
IDL> oploterr, xdata, ydata, yerrors
\end{verbatim}

\begin{figure}[!ht]
\begin{center}
\leavevmode
\epsscale{.7}
\plotone{ex3.ps}
\end{center}
\caption{An example plot with the error bars plotted.}\label{ex3}
\end{figure}

{\tt yerrors}:  the array of errors on the y measurements.

	There are other ways to plot error bars.  See, for example, {\tt errplot}  and {\tt ploterr} .

\section{The {\tt plots} command}\label{plots}

The {\tt plots} command allows you to plot individual point, or an array
of points, all with different colors and/or symbols.

\section{Annotate and Create Plot Legends with the {\tt xyouts} command}

The {\tt xyouts} command lets you annotate plots. In the example below, {\tt
xyouts, 7.0, 6.0, 'data points'} writes the string {\tt data points}
beginning at the specified locations of (x,y) = (7.0, 6.0).

You can add legends to your plots using {\tt plots} and {\tt
xyouts}.  The legends in Figure \ref{ex4} were made with the following
commands:

\begin{verbatim}
IDL> plots, 6.8, 6.1, ps=7
IDL> xyouts, 7.0, 6.0, 'data points'
IDL> plots, 6.5,6.9,5.5,5.5, lines=2
IDL> xyouts, 7.0, 5.4, 'theory'
IDL> plots, 6.8,6.8,4.6,5.1
IDL> xyouts, 7.0, 4.8, 'error bars'
\end{verbatim}

That's the hard way!  The easy way: use GSFC's {\tt legend} command. To
see its documentation, type {\tt doc, 'legend'} in IDL.

\begin{figure}[!ht]
\begin{center}
\leavevmode
\epsscale{.7}
\plotone{ex4.ps}
\end{center}
\caption{An example plot with a legend.}\label{ex4}
\end{figure}

\subsection{You Want Greek Letters or Math? Use {\tt textoidl}}

        There are two ways to do Greek letters and sub/superscripting.
One is IDL's native embedded formatting, which is infinitely flexible
and consequently complicated; the other is the popular non-native
procedure {\tt textoidl}, which lets you use \TeX\ notation to generate
fancy IDL characterstrings.  For example, suppose we want to annotate a
graph with the string $Density^2 / Radius_1^3 \leq \gamma$.  Using
\verb$textoidl$ you'd write

\begin{verbatim}
xyouts, xloc, yloc, textoidl('Density^2 / Radius_1^3 \leq \gamma'
\end{verbatim}

\noindent If this looks like Greek to you, then you don't know
\TeX. As a scientist, you'll need to learn it!
 
\section{Making Arrays of Plots using the {\tt !p.multi} System Variable}\label{pmulti}

	The {\tt !p.multi} system variable in IDL allows you to place
multiple plots into the same window\footnote{{\tt !p.multi} is an IDL system
variable because it is prepended by a ! . System variables are always
accessible, whether you are at the main level or in any procedure or
function. Some other noteworthy system variables are {\tt !pi, !dtor, 
!radeg} .}.  To accomplish this, set {\tt !p.multi} equal to an array with the
first element zero, the second element equal to the number of plots across
the window and the third element equal to the number of plots down the
window.  Then give your plotting commands.  For example, to 
place six plots in one window with two across and three down:

\begin{verbatim}
idl> !p.multi=[0,2,3]
idl> plot, x1, y1
idl> plot, x2, y2
idl> plot, x3, y3
idl> plot, x4, y4
idl> plot, x5, y5
idl> plot, x6, y6
idl> !p.multi=[0,1,1]
\end{verbatim}

\noindent Always remember to set {\tt !p.multi} back to [0,1,1] or
equivalently, to 0, when you're done;
otherwise your next window will have places for six plots.

{\tt !p.multi} allows enough space around each plot for its own axis titles,
and a plot title. Often, the x-axes and/or the y-axes have identical
titles or scales. In such cases, the space around each plot is annoying
and wasteful. You can eliminate it by using GSFC's {\tt
multiplot.pro}. Check its documentation.

\section{Turning Your Plots into Postscript Files}\label{psfiles}

There's an art---based human physiology, document printing technology,
and PowerPoint technology---to making images that are easily read and
absorbed into the human psyche. It includes using easily-readable
fonts, thick lines, and contrasting colors that are distinguishable even
by the colorblind\footnote{Whose numbers, especially among males, are a
surprisingly high $\sim 15\%$ .}. IDL makes exportable images in many
formats, but the one you'll use for most purposes is PostScript. It's
easy to make great PostScript images and plots in IDL! See our document
entitled ******.
\end{document}
