% plotting.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: plotting.tex 1306 2012-09-14 17:59:04Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Plotting: a complete guide}
\label{ch:plotting}

This part of the manual provides a complete description of Pyxplot's commands
for producing graphs and vector graphics. This chapter extends the overview of
the \indcmdt{plot} in Chapter~\ref{ch:first_steps}, providing a systematic
description of how the appearance of plots can be configured.  Subsequent
chapters describe how to produce graphical output in a range of image formats
(Chapter~\ref{ch:image_formats}), how to produce galleries of multiple plots
side-by-side, and how to produce more sophisticated vector graphics
(Chapter~\ref{ch:vector_graphics}).

\section{The {\tt with} modifier}
\label{sec:with_modifier}

In Chapter~\ref{ch:first_steps} an overview of the syntax of the \indcmdt{plot}
was provided, including the {\tt every}, {\tt index}, {\tt select} and {\tt
using} modifiers, which can be used to control {\it which} data should be
plotted. The {\tt with} modifier controls {\it how} data should be plotted. For
example, the statement
\begin{verbatim}
plot "data.dat" index 1 using 4:5 with lines
\end{verbatim}
specifies that data should be plotted with lines connecting each \datapoint\ to
its neighbors. We term the keyword {\tt lines} a {\it plot style}. The {\tt
with} modifier can also be followed by a variety of settings which fine-tune
aspects of how data are displayed.  For example, the statement
\begin{verbatim}
plot "data.dat" with lines linewidth 2.0
\end{verbatim}
would connect \datapoint s with a line of twice the default width.

The next section will provide a complete list of all of Pyxplot's plot styles
-- i.e.\ the words which may be used in place of {\tt lines}. First we list all
of the modifiers such as {\tt line\-width} which may be used to alter the exact
appearance of these plot styles. These are as follows:

\begin{itemize}
\item \indmodt{color} -- used to select the color in which the dataset is to be plotted. It should be followed either by a number, to select a color from the present palette (see Section~\ref{sec:palette}); by a recognised color name, a complete list of which can be found in Section~\ref{sec:color_names}; or by a color object, such as may be created by the functions {\tt gray(g)}, {\tt rgb(r,g,b)}, {\tt cmyk(c,m,y,k)} or {\tt hsb(h,s,b)}. This modifier may also be spelt {\tt colour}.\index{colors!setting for datasets}
\item \indmodt{fillcolor} -- used to select the color in which the dataset is filled. The color may be specified using any of the styles listed for {\tt color}. May also be spelt {\tt fillcolour}.
\item \indmodt{linetype} -- used to numerically select the type of line -- for example, solid, dotted, dashed, etc.\ -- which should be used by line-based plot styles. A complete list of Pyxplot's numbered line types can be found in Chapter~\ref{ch:linetypes_table}. May be abbreviated {\tt lt}.
\item \indmodt{linewidth} -- used to select the width of line which should be used by line-based plot styles, where unity represents the default width. May be abbreviated {\tt lw}.
\item \indmodt{pointlinewidth} -- used to select the width of line which should be used to stroke points in point-based plot styles, where unity represents the default width. May be abbreviated {\tt plw}.
\item \indmodt{pointsize} -- used to select the size of drawn points, where unity represents the default size. May be abbreviated {\tt ps}.
\item \indmodt{pointtype} -- used to numerically select the type of point -- for example, crosses, circles, etc.\ -- used by point-based plot styles. A complete list of Pyxplot's numbered point types can be found in Chapter~\ref{ch:linetypes_table}. May be abbreviated {\tt pt}.
\end{itemize}

Any number of these modifiers may be placed sequentially after the keyword {\tt
with}, as in the following examples:

\begin{verbatim}
plot 'datafile' using 1:2 with points pointsize 2
plot 'datafile' using 1:2 with lines color red linewidth 2
plot 'datafile' using 1:2 with lp col 1 lw 2 ps 3
\end{verbatim}

\noindent Where modifiers take numerical values, expressions of the form {\tt
\$2+1}, similar to those supplied to the {\tt using} modifier, may be used to
read numbers from the supplied data set. In this case, each datapoint will be
displayed in a different style or in a different color (in the example given,
depending on the values in the second column of the supplied data).

The following example would plot a \datafile\ with {\tt points}, drawing the
position of each point from the first two columns of the supplied \datafile\
and the size of each point from the third column:
\begin{verbatim}
plot 'datafile' using 1:2 with points pointsize $3
\end{verbatim}

Not all of these modifiers are applicable to all of Pyxplot's plot styles. For
example, the {\tt line\-width} modifier has no effect on plot styles which do
not draw lines between datapoints. Where modifiers are applied to plot styles
for which they have no defined effect, the modifier has no effect, but no error
results.  Table~\ref{tab:style_modifiers} lists which modifiers act on which
plot styles.

\begin{table}
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_plotstyletab}}
\caption{A list of the plot styles affected by each style modifiers.}
\label{tab:style_modifiers}
\end{table}

\subsection{The palette}
\label{sec:palette}
\index{palette}\index{colors!setting the palette}

Wherever Pyxplot takes a color as an input to a command, the user has three
options for how it may be specified.  A selection of widely-used colors may be
specified by name, for example {\tt red} and {\tt blue}. A complete list of
such colors may be found in Section~\ref{sec:color_names}. Alternatively, an
object of type {\tt color} may be provided, such as {\tt rgb(0,1,0)}, {\tt
hsb(0.5,0.5,0.5)}, {\tt gray(0.2)}, {\tt colors.green + colors.red}, or {\tt
colors.yellow - colors.green}.

The third option is to specify a numbered color from Pyxplot's {\it palette}.
By default, this contains a series of visually distinctive colors which are,
insofar as possible, also distinctive to users with most common forms of color
blindness:

\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_palettelist}}

The first color is number~1, the second number~2, and so forth. As
well as being accessible by number, these colors also form the default series
which Pyxplot chooses for successive datasets when their colors are not
individually specified.

The current palette may be queried using the \indcmdt{show palette}, and
changed using the \indcmdt{set palette}, which takes a comma-separated list of
colors, as in the example:

\begin{verbatim}
set palette brickRed, limeGreen, cadetBlue
\end{verbatim}

\noindent The palette is treated as a cyclic list, and so in the above example,
color number~4 would map to {\tt brickRed}, as would color numbers~1 and~8. The
default palette which Pyxplot uses on startup may be changed by setting up a
configuration file, as described in Chapter~\ref{ch:configuration}.

If a non-integer color is requested from the palette, for example color~1.5,
then a color is returned which is half-way in between colors~1 and~2 in RGB
space; in this case, brown. This can be used to produce custom color gradients,
as the following example demonstrates (the {\tt colormap} plot style will be
described in Section~\ref{sec:colormaps}):

\vspace{2mm}
\input{examples/tex/ex_colgradient_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=10cm]{examples/eps/ex_colgradient}}


\subsection{Default settings}

In addition to setting these parameters on a per-dataset basis, the {\tt
linewidth}, {\tt pointlinewidth} and {\tt pointsize} settings can also have
their default values changed for all datasets as in the following examples:
\begin{verbatim}
set linewidth 1
set pointlinewidth 2
set pointsize 3
plot "datafile"
\end{verbatim}
In each case, the normal default values of these settings are~1. The default
values of the {\tt color}, {\tt linetype} and {\tt pointtype} settings depend
whether the current graphic output device is set to produce color or
monochrome output (see Chapter~\ref{sec:set_terminal}).

In the case of color output, the colors of each of the comma-separated datasets
plotted on a graph are drawn sequentially from the currently-selected palette,
and all lines are drawn as solid lines ({\tt line\-type~1}). The symbols used
to draw each dataset are drawn sequentially from Pyxplot's available point
types. In the case of monochrome output, all datasets are plotted in black and
both the line types and point types used to draw each dataset are drawn
sequentially from Pyxplot's available options.

The following simple example demonstrates this:
\begin{verbatim}
set terminal color
plot [][6:0] 1 with lp, 2 with lp, 3 w lp, 4 w lp, 5 w lp
set terminal monochrome
replot
\end{verbatim}
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_col_vs_mono}}

\section{Pyxplot's plot styles}
\label{sec:list_of_plotstyles}

This section provides a complete list of Pyxplot's {\it plot styles}, arranged
into groups for clarity.  Table~\ref{tab:plot_style_columns} summarises the
columns of data expected by each plot style when used on two- and
three-dimensional plots. The following sections describe each of these plot
styles in turn.

\begin{table}
\begin{tabular}{|rll|}
\hline
{\bf Style} & {\bf Columns (2D plots)} & {\bf Columns (3D plots)} \\
\hline
{\tt arrows\_head} & $(x_1,y_1,x_2,y_2)$ & $(x_1,y_1,z_1,x_2,y_2,z_2)$ \\
{\tt arrows\_nohead} & $(x_1,y_1,x_2,y_2)$ & $(x_1,y_1,z_1,x_2,y_2,z_2)$ \\
{\tt arrows\_twohead} & $(x_1,y_1,x_2,y_2)$ & $(x_1,y_1,z_1,x_2,y_2,z_2)$ \\
{\tt boxes} & $(x,y)$ & $(x,y)$ \\
{\tt colormap} & $(x,y,c_1,\ldots)$ & $(x,y,c_1,\ldots)$ \\
{\tt contourmap} & $(x,y,c_1,\ldots)$ & $(x,y,c_1,\ldots)$ \\
{\tt dots} & $(x,y)$ & $(x,y,z)$ \\
{\tt FilledRegion} & $(x,y)$ & $(x,y)$ \\
{\tt fsteps} & $(x,y)$ & $(x,y)$ \\
{\tt histeps} & $(x,y)$ & $(x,y)$ \\
{\tt impulses} & $(x,y)$ & $(x,y,z)$ \\
{\tt lines} & $(x,y)$ & $(x,y,z)$ \\
{\tt LinesPoints} & $(x,y)$ & $(x,y,z)$ \\
{\tt LowerLimits} & $(x,y)$ & $(x,y,z)$ \\
{\tt points} & $(x,y)$ & $(x,y,z)$ \\
{\tt stars} & $(x,y)$ & $(x,y,z)$ \\
{\tt steps} & $(x,y)$ & $(x,y)$ \\
{\tt surface} & $(x,y,z)$ & $(x,y,z)$ \\
{\tt UpperLimits} & $(x,y)$ & $(x,y,z)$ \\
{\tt wboxes} & $(x,y,w)$ & $(x,y,w)$ \\
{\tt XErrorBars} & $(x,y,\sigma_x)$ & $(x,y,z,\sigma_x)$ \\
{\tt XErrorRange} & $(x,y,x_\mathrm{min},x_\mathrm{max})$ & $(x,y,z,x_\mathrm{min},x_\mathrm{max})$ \\
{\tt XYErrorBars} & $(x,y,\sigma_x,\sigma_y)$ & $(x,y,z,\sigma_x,\sigma_y)$ \\
{\tt XYErrorRange} & $(x,y,x_\mathrm{min},x_\mathrm{max},y_\mathrm{min},y_\mathrm{max})$ & $(x,y,z,x_\mathrm{min},x_\mathrm{max},y_\mathrm{min},y_\mathrm{max})$ \\
{\tt XYZErrorBars} & $(x,y,z,\sigma_x,\sigma_y,\sigma_z)$ & $(x,y,z,\sigma_x,\sigma_y,\sigma_z)$ \\
{\tt XYZErrorRange} & $(x,y,z,x_\mathrm{min},x_\mathrm{max},y_\mathrm{min},$ -- & $(x,y,z,x_\mathrm{min},x_\mathrm{max},y_\mathrm{min},$ -- \\
                    & -- $y_\mathrm{max},z_\mathrm{min},z_\mathrm{max})$ & -- $y_\mathrm{max},z_\mathrm{min},z_\mathrm{max})$ \\
{\tt XZErrorBars} & $(x,y,z,\sigma_x,\sigma_z)$ & $(x,y,z,\sigma_x,\sigma_z)$ \\
{\tt XZErrorRange} & $(x,y,z,x_\mathrm{min},x_\mathrm{max},z_\mathrm{min},z_\mathrm{max})$ & $(x,y,z,x_\mathrm{min},x_\mathrm{max},z_\mathrm{min},z_\mathrm{max})$ \\
{\tt YErrorBars} & $(x,y,\sigma_y)$ & $(x,y,z,\sigma_y)$ \\
{\tt YErrorRange} & $(x,y,y_\mathrm{min},y_\mathrm{max})$ & $(x,y,z,y_\mathrm{min},y_\mathrm{max})$ \\
{\tt YErrorShaded} & $(x,y_\mathrm{min},y_\mathrm{max})$ & $(x,y_\mathrm{min},y_\mathrm{max})$ \\
{\tt YZErrorBars} & $(x,y,z,\sigma_y,\sigma_z)$ & $(x,y,z,\sigma_y,\sigma_z)$ \\
{\tt YZErrorRange} & $(x,y,z,y_\mathrm{min},y_\mathrm{max},z_\mathrm{min},z_\mathrm{max})$ & $(x,y,z,y_\mathrm{min},y_\mathrm{max},z_\mathrm{min},z_\mathrm{max})$ \\
{\tt ZErrorBars} & $(x,y,z,\sigma_z)$ & $(x,y,z,\sigma_z)$ \\
{\tt ZErrorRange} & $(x,y,z,z_\mathrm{min},z_\mathrm{max})$ & $(x,y,z,z_\mathrm{min},z_\mathrm{max})$ \\
\hline
\end{tabular}
\caption{A summary of the columns of data expected by each of Pyxplot's plot styles when used on two- and three-dimensional plots.}
\label{tab:plot_style_columns}
\end{table}

\subsection{Lines and points}

The following is a list of Pyxplot's simplest plot styles, all of which take
two columns of input data on 2D plots (three columns on 3D plots), which
represent the $x$-, $y$- (and $z$-)coordinates of the positions of each point:
\begin{itemize}
\item \indpst{dots} -- places a small dot at each datum.
\item \indpst{lines} -- connects adjacent \datapoint s with straight lines.
\item \indpst{linespoints} -- a combination of both lines and points.
\item \indpst{lowerlimits} -- places a lower-limit sign (\includegraphics{examples/eps/ex_lowerlimit}) at each datum.\index{lower-limit datapoints}
\item \indpst{points} -- places a marker symbol at each datum.
\item \indpst{stars} -- similar to {\tt points}, but uses a different set of marker symbols, based on the stars drawn in Johann Bayer's highly ornate star atlas {\it Uranometria} of 1603.
\item \indpst{upperlimits} -- places an upper-limit sign (\includegraphics{examples/eps/ex_upperlimit}) at each datum.\index{upper-limit datapoints}
\end{itemize}

\example{ex:hrdiagram}{A Hertzsprung-Russell diagram}{
Hertzsprung-Russell (HR) diagrams are scatter-plots of the luminosities of
stars plotted against their colors, on which most normal stars lie
along a tight line called the main sequence, whilst unusual classes of stars --
giants and dwarfs -- can be readily identified on account of their not lying
along this main sequence. The principal difficulty in constructing accurate HR
diagrams is that the luminosities $L$ of stars can only be calculated from
their observed brightnesses $F$, using the relation $L=Fd^2$ if their distances
$d$ are known. In this example, we construct an HR diagram using observations
made by the European Space Agency's {\it Hipparcos} spacecraft, which
accurately measured the distances of over a million stars between 1989 and
1993.
\nlnp
The Hipparcos catalogue can be downloaded for free from
\url{ftp://cdsarc.u-strasbg.fr/pub/cats/I/239/hip_main.dat.gz}; a description
of the catalogue can be found at
\url{http://cdsarc.u-strasbg.fr/viz-bin/Cat?I/239}. In summary, though the data
is arranged in a non-standard format which Pyxplot cannot read without a
special input filter, the following Python script generates a text file with
four columns containing the magnitudes $m$, $B-V$ colors and parallaxes $p$ of
the stars, together with the uncertainties in the parallaxes. From these
values, the absolute magnitudes $M$ of the stars -- a measure of their
luminosities -- can be calculated using the expression
$M=m+5\log_{10}\left(10^{2}p\right)$, where $p$ is measured in
milli-arcseconds:
\nlscf
\noindent{\tt for line in open("hip\_main.dat"):}\newline
\noindent{\tt \phantom{x}try:}\newline
\noindent{\tt \phantom{xx}Vmag  = float(line[41:46])}\newline
\noindent{\tt \phantom{xx}BVcol = float(line[245:251])}\newline
\noindent{\tt \phantom{xx}parr  = float(line[79:86])}\newline
\noindent{\tt \phantom{xx}parre = float(line[119:125])}\newline
\noindent{\tt \phantom{xx}print "\%s,\%s,\%s,\%s"\%(Vmag, BVcol, parr, parre)}\newline
\noindent{\tt \phantom{x}except ValueError: pass}
\nlscf
The resultant four columns of data can then be plotted in the {\tt dots} style
using the following Pyxplot script. Because the catalogue is very large, and
many of the parallax datapoints have large errorbars producing large
uncertainties in their vertical positions on the plot, we use the {\tt select}
statement to pick out those datapoints with parallax signal-to-noise ratios of
better than~20.
\nlscf
\input{examples/tex/ex_hrdiagram_1.tex}
\nlscf
\centerline{\includegraphics[width=10cm]{examples/eps/ex_hrdiagram}}
}

\subsection{Error bars}
\index{errorbars}\label{sec:errorbars}

The following pair of plot styles allow datapoints to be plotted with errorbars
indicating the uncertainties in either their vertical or horizontal positions:
\begin{itemize}
\item \indpst{yerrorbars}
\item \indpst{xerrorbars}
\end{itemize}
Both of these take three columns of input data on 2D plots (or four on
3D plots). The first two (or three) of these represent the $x$-, $y$- (and
$z$-) coordinates of the central position of each errorbar, while the last
represents the uncertainty in either the $x$- and $y$-coordinate. The
plot style \indpst{errorbars} is an alias for \indpst{yerrorbars}.
Additionally, the following plot style allows datapoints to be plotted with
both horizontal and vertical errorbars:
\begin{itemize}
\item \indpst{xyerrorbars}
\end{itemize}
This plot style takes four (or five) columns of data as input, the first two
(or three) of which represent the $x$-, $y$- (and $z$-) coordinates of the
central position of each errorbar. The last but one column gives the
uncertainty in the $x$-coordinate, and the last column gives the uncertainty in
the $y$-coordinate.

Each of the plot styles listed above has a corresponding partner which takes
minimum and maximum limits for each errorbar, equivalent to writing
$5^{+2}_{-3}$, in place of a single symmetric uncertainty:
\begin{itemize}
\item \indpst{xerrorrange} -- takes four (or five) columns of data.
\item \indpst{yerrorrange} -- takes four (or five) columns of data.
\item \indpst{xyerrorrange} -- takes six (or seven) columns of data.
\end{itemize}
The plot style \indpst{errorrange} is an alias of \indpst{yerrorrange}.

Corresponding plot styles also exist to plot data with errorbars along the
$z$-axes of three-dimensional plots: {\tt zerrorbars}, {\tt zerrorrange}, {\tt
xzerrorbars}, {\tt xzerrorrange}, {\tt yzerrorbars}, {\tt yzerrorrange}, {\tt
xyzerrorbars}, {\tt xyzerrorrange}. Though it does not make sense to use these
on two-dimensional plots, it is not an error to do so; they expect the same
number of columns of input data on both two- and three-dimensional plots.

\subsection{Shaded regions}

The following plot styles allow regions of graphs to be shaded with color:

\begin{itemize}
\item \indpst{yerrorshaded}
\item \indpst{shadedregion}
\end{itemize}

Both fill specified regions of graphs with the selected
{\tt fillcolor} and draw a line around the boundary of the region with the
selected {\tt color}, {\tt linetype} and {\tt linewidth}.

They differ in the format in which they expect the input data to be arranged.
The \indpst{yerrorshaded} plot style is similar to the \indpst{yerrorrange}
plot style: it expects three columns of data, specifying the $x$-coordinate and
the minimum and maximum extremes of the vertical errorbar on each \datapoint.
The region contained between the upper and lower limits of these error bars is
filled with color.  Note that the \datapoint s must be sorted in order of
either increasing or decreasing $x$-coordinate for sensible behaviour.

The \indpst{shadedregion} plot style takes only two columns of input data,
specifying the $x$- and $y$-coordinates of a series of \datapoint s which are
to be joined in a join-the-dots fashion. At the end of each dataset, the drawn
path is closed and filled.

The use of these plot styles on three-dimensional graphs may produce unexpected
results.

\subsection{Barcharts and histograms}
\label{sec:barcharts}
\index{bar charts}

The following plot styles allow barcharts to be produced:
\begin{itemize}
\item \indpst{boxes}
\item \indpst{impulses}
\item \indpst{wboxes}
\end{itemize}
These styles differ in where the horizontal interfaces between the
bars are placed along the abscissa axis and how wide the bars are.  In the
\indpst{boxes} plot style, the interfaces between the bars are at the midpoints
between the specified \datapoint s by default (see, for example,
Figure~\ref{fig:ex_barchart2}a).  Alternatively, the widths of the bars may be
set using the {\tt set boxwidth} command. In this case, all of the bars will be
centered on their specified $x$-coordinates, and have total widths equalling
that specified in the \indcmdt{set boxwidth}. Consequently, there may be gaps
between them, or they may overlap, as seen in Figure~\ref{fig:ex_barchart2}(b).

\begin{figure}
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_barchart2}
\end{center}
\caption[A gallery of the various bar chart styles which Pyxplot can produce]
{A gallery of the various bar chart styles which Pyxplot can produce.
See the text for more details.}
\label{fig:ex_barchart2}
\end{figure}

Having set a fixed box width, the default behaviour of scaling box widths
automatically may be restored either with the {\tt unset boxwidth} command,
or by setting the boxwidth to a negative width.

In the \indpst{wboxes} plot style, the width of each bar is specified manually
as an additional column of the input \datafile.  This plot style expects three
columns of data to be provided: the $x$- and $y$-coordinates of each bar in the
first two, and the width of the bars in the third.
Figure~\ref{fig:ex_barchart2}(c) shows an example of this plot style in use.

Finally, in the \indpst{impulses} plot style, the bars all have zero width; see
Figure~\ref{fig:ex_barchart1}(c) for an example.

In all of these plot styles, the bars originate from the line $y=0$ by default,
as is normal for a histogram. However, should it be desired for the bars to
start from a different vertical line, this may be achieved by using the
\indcmdt{set boxfrom}, for example:

\begin{verbatim}
set boxfrom 5
\end{verbatim}

\noindent In this case, all of the bars would now originate from the line
$y=5$. Figure~\ref{fig:ex_barchart1}(b) shows the kind of effect that is
achieved; for comparison, Figure~\ref{fig:ex_barchart1}(a) shows the same bar
chart with the boxes starting from their default position of $y=0$.

\begin{figure}
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_barchart1}
\end{center}
\caption[A second gallery of the various bar chart styles which Pyxplot can
produce]
{A second gallery of the various bar chart styles which Pyxplot can
produce. See the text for more details.  The script and data file used to
produce this image are available on the Pyxplot website at
\protect\url{http://www.pyxplot.org.uk/examples/Manual/03barchart1/}.}
\label{fig:ex_barchart1}
\end{figure}

The bars may be filled using the {\tt with} \indmodt{fillcolor} modifier,
followed by the name of a color:

\begin{verbatim}
plot 'data.dat' with boxes fillcolor blue
plot 'data.dat' with boxes fc 4
\end{verbatim}

\noindent Figures~\ref{fig:ex_barchart2}(b) and (d) demonstrate the use of
filled bars.

The {\tt boxes} and {\tt wboxes} plot styles expect identically-formatted data
when used on two- and three-dimensional plots; in the latter case, all bars are
drawn in the plane $z=0$. The {\tt impulses} plot style takes an additional
column of data on three-dimensional plots, specifying the $z$-coordinate at
which each impulse should be drawn.

\subsubsection{Stacked bar charts}

If multiple \datapoint s are supplied to the \indpst{boxes} or \indpst{wboxes}
plot styles at a common $x$-coordinate, then the bars are stacked one above
another into a stacked barchart. Consider the following \datafile:

\begin{verbatim}
1 1
2 2
2 3
3 4
\end{verbatim}

\noindent The second bar at $x=2$ would be placed on top of the first, spanning
the range $2<y<5$, and having the same width as the first. If plot colors are
being automatically selected from the palette, then a different palette color
is used to plot the upper bar.

\subsection{Steps}

The following plot styles allow data to be plotted with a series of horizontal
steps associated with each supplied \datapoint:
\begin{itemize}
\item \indpst{steps}
\item \indpst{fsteps}
\item \indpst{histeps}
\end{itemize}
Each of these styles takes two columns of data, containing the $x$- and
$y$-coordinates of each \datapoint.  They expect identically-formatted data
regardless of whether they are used on two- and three-dimensional plots; in the
latter case, the steps are drawn in the plane $z=0$.

An example of their appearance  is shown in Figures~\ref{fig:ex_barchart1}(d),
(e) and (f); for clarity, the positions of each of the supplied \datapoint s
are marked by red crosses.

These plot styles differ in their placement of the edges of each of the
horizontal steps.  The \indpst{steps} plot style places the right-most edge of
each step on the \datapoint\ it represents.  The \indpst{fsteps} plot style
places the left-most edge of each step on the \datapoint\ it represents.  The
\indpst{histeps} plot style centers each step on the \datapoint\ it represents.

\subsection{Arrows}

The following plot styles allow arrows or lines to be drawn on graphs with
positions dictated by a series of \datapoint s:
\begin{itemize}
\item \indpst{arrows\_head}
\item \indpst{arrows\_nohead}
\item \indpst{arrows\_twohead}
\end{itemize}
The plot style of \indpst{arrows} is an alias for \indpst{arrows\_head}.  Each
of these plot styles take four columns of data on two-dimensional plots --
$x_1$, $y_1$, $x_2$ and $y_2$ -- or six columns of data on three-dimensional
plots with additional $z$-coordinates. Each \datapoint\ results in an arrow
being drawn from the point $(x_1,y_1,z_1)$ to the point $(x_2,y_2,z_2)$. The
three plot styles differ in the kinds of arrows that they draw:
\indpst{arrows\_head} draws an arrow head on each arrow at the point
$(x_2,y_2,z_2)$; \indpst{arrows\_nohead} draws simple lines without arrow heads
on either end; \indpst{arrows\_twohead} draws arrow heads on both ends of each
arrow.

\example{ex:vortex}{A diagram of fluid flow around a vortex}{
In this example we produce a velocity map of fluid circulating in a vortex. For
simplicity, we assume that the fluid in the core of the vortex, at radii $r<1$,
is undergoing solid body rotation with velocity $v\propto r$, and that the
fluid outside this core is behaving as a free vortex with velocity $v\propto
1/r$. First of all, we use a simple python script to generate a \datafile\ with
the four columns:
\nlscf
\noindent{\tt from math import *}\newline
\noindent{\tt for i in range(-19,20,2):}\newline
\noindent{\tt \phantom{x}for j in range(-19,20,2):}\newline
\noindent{\tt \phantom{xx}x = float(i)/2}\newline
\noindent{\tt \phantom{xx}y = float(j)/2}\newline
\noindent{\tt \phantom{xx}r = sqrt(x**2 + y**2) / 4}\newline
\noindent{\tt \phantom{xx}theta = atan2(y,x)}\newline
\noindent{\tt \phantom{xx}if (r $<$ 1.0): v = 1.3*r}\newline
\noindent{\tt \phantom{xx}else        : v = 1.3/r}\newline
\noindent{\tt \phantom{xx}vy = v *  cos(theta)}\newline
\noindent{\tt \phantom{xx}vx = v * -sin(theta)}\newline
\noindent{\tt \phantom{xx}print "\%7.3f \%7.3f \%7.3f \%7.3f"\%(x,y,vx,vy)}
\nlscf
This data can then be plotted using the following Pyxplot script:
\nlscf
\input{examples/tex/ex_vortex_1.tex}
\nlscf
\centerline{\includegraphics[width=10cm]{examples/eps/ex_vortex}}
}

\subsection{Color maps, contour maps and surface plots}

The following plot styles differ from those above in that, regardless of
whether a three-dimensional plot is being produced, they read in datapoints
with $x$, $y$ and $z$ coordinates in three columns. The first two are useful
for producing two-dimensional representations of $(x,y,z)$ surfaces using
colors or contours to show the magnitude of $z$, while the third is useful for
producing three-dimensional graphs of such surfaces:
\begin{itemize}
\item colormap
\item contourmap
\item surface
\end{itemize}
They are discussed in detail in Sections~\ref{sec:colormaps},
\ref{sec:contourmaps} and \ref{sec:surfaces} respectively.

\section{Labelling datapoints}

The {\tt label} modifier to the {\tt plot} command may be used to add text
labels next to datapoints, as in the following examples:
\begin{verbatim}
set samples 8
plot [2:5] x**2 label "$x=%.2f$"%($1) with points

plot 'datafile' using 1:2 label "%s"%($3)
\end{verbatim}

\noindent Note that if a particular column of a \datafile\ contains strings
which are to be used as labels, as in the second example above, syntax such as
{\tt "\%s"\%(\$3)} must be used to explicitly read the data as strings rather
than as numerical quantities.  As Pyxplot treats any whitespace as separating
columns of data, such labels cannot contain spaces, though \latexdcf's {\tt
$\sim$} character (a non-breaking space) can be used to achieve a space.

Data points can be labelled when plotted in any of the following plot styles:
{\tt arrows} (and similar styles), {\tt dots}, {\tt errorbars} (and similar
styles), {\tt errorrange} (and similar styles), {\tt impulses}, {\tt
linespoints}, {\tt lowerlimits}, {\tt points}, {\tt stars} and {\tt
upperlimits}. It is not possible to label datapoints plotted in other styles.
Labels are rendered in the same color as the datapoints with which they are
associated.

\section{The {\tt style} keyword}

At times, the string of style keywords placed after the {\tt with} modifier in
{\tt plot} commands can grow rather unwieldy in its length. For clarity,
frequently used plot styles can be stored as numbered plot {\it styles}.  The
syntax for setting a numbered plot style is:

\begin{verbatim}
set style 2 points pointtype 3
\end{verbatim}

\noindent where the {\tt 2} is the identification number of the style. In a
subsequent {\tt plot} statement, this style can be recalled as follows:

\begin{verbatim}
plot sin(x) with style 2
\end{verbatim}

\section{Plotting functions in exotic styles}

The use of plot styles which take more than two columns of input data to plot
functions requires more than one function to be supplied.  When functions are
plotted with syntax such as

\begin{verbatim}
plot sin(x) with lines
\end{verbatim}

\noindent two columns of data are generated: the first contains values of $x$
-- plotted against the horizontal axis -- and the second contains values of
$\sin(x)$ -- plotted against the vertical axis. Syntax such as

\begin{verbatim}
plot f(x):g(x) with yerrorbars
\end{verbatim}

\noindent generates three columns of data. As before, the first contains values
of $x$. The second and third contain samples from the colon-separated functions
$f(x)$ and $g(x)$. Specifically, in this example, $g(x)$ provides the
uncertainty in the value of $f(x)$.  The {\tt using} modifier may also be used
in combination with such syntax, as in

\begin{verbatim}
plot f(x):g(x) using 2:3
\end{verbatim}

\noindent though this example is not sensible. $g(x)$ would be plotted on the
{\tt y}-axis, against $f(x)$ on the {\tt x}-axis. However, this is unlikely to be
sensible because the range of values of $x$ substituting into these expressions
would correspond to the range of the plot's horizontal axis. The result might
be particularly unexpected if the above were attempted with an autoscaling
horizontal axis -- Pyxplot would find itself autoscaling the {\tt x}-axis range
to the spread of values of $f(x)$, but find that this itself changed depending
on the range of the {\tt x}-axis. In this case, the user should have used the
{\tt parametric} plot option described in the next section.

\section{Plotting parametric functions}
\label{sec:parametric_plotting}

Parametric functions are functions expressed in forms such as
\begin{eqnarray*}
x & = & r \sin(t)  \\
y & = & r \cos(t) ,
\end{eqnarray*}
where separate expressions are supplied for the ordinate and abscissa values as
a function of some free parameter $t$. The above example is a parametric
representation of a circle of radius $r$. Before Pyxplot can usefully plot
parametric functions, it is generally necessary to stipulate the range of
values of $t$ over which the function should be sampled. This may be done using
the \indcmdt{set trange}, as in the example
\begin{verbatim}
set trange [unit(0*rad):unit(2*pi*rad)]
\end{verbatim}
or in the {\tt plot} command itself. By default, values in the range $0\leq
t\leq1$ are used. Note that the \indcmdt{set trange} differs from other
commands for setting axis ranges in that auto-scaling is not an allowed
behaviour; an explicit range {\it must} be specified for $t$.

Having set an appropriate range for $t$, parametric functions may be plotted by
placing the keyword {\tt parametric} before the list of functions to be
plotted, as in the following simple example which plots a circle:
\begin{verbatim}
set trange [unit(0*rev):unit(1*rev)]
plot parametric sin(t):cos(t)
\end{verbatim}
Optionally, a range for $t$ can be specified on a plot-by-plot basis
immediately after the keyword {\tt parametric}, and thus the effect above could
also be achieved using:
\begin{verbatim}
plot parametric [unit(0*rev):unit(1*rev)] sin(t):cos(t)
\end{verbatim}
The only difference between parametric function plotting and ordinary function
plotting -- other than the change of dummy variable from {\tt x} to {\tt t} --
is that one fewer column of data is generated. Thus, whilst
\begin{verbatim}
plot f(x)
\end{verbatim}
generates two columns of data, with values of $x$ in the first column,
\begin{verbatim}
plot parametric f(t)
\end{verbatim}
generates only one column of data.

\example{ex:spirograph}{Spirograph patterns}{
Spirograph patterns are produced when a pen is tethered to the end of a rod
which rotates at some angular speed $\omega_1$ about the end of another rod,
which is itself rotating at some angular speed $\omega_2$ about a fixed central
point. Spirographs are commonly implemented mechanically as wheels within
wheels -- epicycles within deferents, mathematically speaking -- but in this
example we implement them using the parametric functions
\begin{eqnarray*}
x & = & r_1 \sin(t) + r_2 \sin(t r_1 / r_2) \\
y & = & r_1 \cos(t) + r_2 \cos(t r_1 / r_2) \\
\end{eqnarray*}
which are simply the sum of two circular motions with angular velocities
inversely proportional to their radii. The complexity of the resulting
spirograph pattern depends on how rapidly the rods return to their starting
configuration; if the two chosen angular speeds for the rods have a large
lowest common multiple, then a highly complicated pattern will result. In the
example below, we pick a ratio of $8:15$:
\nlscf
\input{examples/tex/ex_spirograph_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_spirograph}}
\nlscf
Other ratios of {\tt r1}:{\tt r2} such as $7:19$ and $5:19$ also produce
intricate patterns.
}

\subsection{Two-dimensional parametric surfaces}

Pyxplot can also plot datasets which can be parameterised in terms of two free
parameters $u$ and $v$. This is most often useful in conjunction with the {\tt
surface} plot style, allowing any $(u,v)$-surface to be plotted (see
Section~\ref{sec:surfaces} for details of the {\tt surface} plot style).
However, it also works in conjunction with any other plot style, allowing, for
example, $(u,v)$-grids of points to be constructed.

As in the case of parametric lines above, the range of values that each free
parameter should take must be specified. This can be done using the \indcmd{set
urange}{\tt set urange} and \indcmd{set vrange}{\tt set vrange} commands. These
commands also act to switch Pyxplot between one- and two-dimensional parametric
function evaluation; whilst the {\tt set trange} command indicates that the
next parametric function should be evaluated along a single raster of values of
$t$, the {\tt set urange} and {\tt set vrange} commands indicate that a grid of
$(u,v)$ values should be used. By default, the range of values used for $u$ and
$v$ is $0\to 1$.

The number of samples to be taken can be specified using a command of the
form\indcmd{set sample grid}
\begin{verbatim}
set sample grid 20x50
\end{verbatim}
which specifies that~20 different values of $u$ and~50 different values of $v$
should be used, yielding a total of~1000 datapoints. The following example uses
the {\tt lines} plot style to generate a sequence of cross-sections through a
two-dimensional Gaussian surface:

\vspace{2mm}
\input{examples/tex/ex_datagrid_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_datagrid}}

The ranges of values to use for $u$ and $v$ may alternatively be specified on a dataset-by-dataset
basis within the plot command, as in the example
\begin{verbatim}
plot parametric [0:1][0:1] u:v , \
     parametric [0:1] sin(t):cos(t)
\end{verbatim}

\example{ex:torus}{A three-dimensional view of a torus}{
In this example we plot a torus, which can be parametrised in terms of two
free parameters $u$ and $v$ as
\begin{eqnarray*}
x & = & (R + r\cos(v))\cos(u)  \\
y & = & (R + r\cos(v))\sin(u)  \\
z & = & r\sin(v)  ,
\end{eqnarray*}
where $u$ and $v$ both run in the range $[0:2\pi]$, $R$ is the distance of the
tube's center from the center of the torus, and $r$ is the radius of the tube.
\nlscf
\input{examples/tex/ex_torus_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_torus}}	
\nlscf
}

\example{ex:trefoil}{A three-dimensional view of a trefoil knot}{
In this example we plot a trefoil knot, which is the simplest non-trivial knot
in topology.  Simply put, this means that it is not possible to untie the knot
without cutting it.  The knot follows the line
\begin{eqnarray*}
x & = & (2 + \cos(3t))\cos(2t)  \\
y & = & (2 + \cos(3t))\sin(2t)  \\
z & = & \sin(3t)  ,
\end{eqnarray*}
but in this example we construct a tube around this line using the following
parameterisation:
\begin{eqnarray*}
x & = & \cos(2u)\cos(v) + r\cos(2u)(1.5+\sin(3u)/2)   \\
y & = & \sin(2u)\cos(v) + r\sin(2u)(1.5+\sin(3u)/2) \\
z & = & \sin(v)+R\cos(3u) ,
\end{eqnarray*}
where $u$ and $v$ run in the ranges $[0:2\pi]$ and $[-\pi:\pi]$ respectively,
and $r$ and $R$ determine the size and thickness of the knot as in an analogous
fashion to the previous example.
\nlscf
\input{examples/tex/ex_trefoil_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_trefoil}}
\nlscf
}

\section{Graph legends}
\index{keys}\index{legends}
\label{sec:legends}

By default, plots are displayed with legends in their top-right corners. The
textual description of each dataset is auto-generated from the command used
to plot it. Alternatively, the user may specify his own description for each
dataset by following the {\tt plot} command with the \indmodt{title} modifier,
as in the following examples:

\begin{verbatim}
plot sin(x) title 'A sine wave'
plot cos(x) title ''
\end{verbatim}

In the latter case a blank title is specified, which indicates to Pyxplot that
no entry should be made for the dataset in the legend. This allows for legends
which contain only a subset of the datasets on a plot. Alternatively, the
production of the legend can be completely turned off for all datasets using
the command \indcmdts{set nokey}. Having issued this command, the production of
keys can be resumed using the \indcmdt{set key}.

The \indcmdt{set key} can also be used to dictate how legends should be
positioned on graphs, using a syntax along the lines of:

\begin{verbatim}
set key top right
\end{verbatim}

The following recognised positional keywords are self-explanatory:
\indkeyt{top}, \indkeyt{bottom}, \indkeyt{left}, \indkeyt{right},
\indkeyt{xcenter} and \indkeyt{ycenter}. Any single instance of the
\indcmdt{set key} can be followed by one horizontal alignment keyword and one
vertical alignment keyword; these keywords also affect the justification of the
legend -- for example, the keyword \indkeyt{left} aligns the legend with its
left edge against the left edge of the plot.

Alternatively, the position of the legend can be indicated using one of the
keywords \indkeyt{outside}, \indkeyt{below} or \indkeyt{above}. These cannot be
combined with the horizontal and vertical alignment keywords above, and are
used to indicate that the legend should be placed, respectively, outside the
plot on its right side, centered beneath the plot, and centered above the plot.

Two comma-separated positional offset coordinates may be specified following
any of the named positions listed above to fine-tune the position of the legend
-- the first value is assumed to be a horizontal offset and the second a
vertical offset. Either may have units of length, or, if they are
dimensionless, are assumed to be measured in centimeters, as the following
examples demonstrate:

\begin{verbatim}
set key bottom left 0.0 -2
set key top xcenter 2*unit(mm),2*unit(mm)
\end{verbatim}

By default, entries in the legend are automatically sorted into an appropriate
number of columns. The number of columns to be used, can, instead, be
stipulated using the \indcmdt{set keycolumns}. This should be followed by
either the integer number of desired columns, or by the keyword {\tt auto} to
indicate that the default behaviour of automatic formatting should be resumed:

\begin{verbatim}
set keycolumns 2
set keycolumns auto
\end{verbatim}

\section{Configuring axes}

\subsection{Adding additional axes}
\label{sec:multiple_axes}

By default, plots have only one horizontal {\tt x}-axis and one vertical {\tt
y}-axis.  Additional axes may be added parallel to these and are referred to
as, for example, the {\tt x2} axis, the {\tt x3} axis, and so forth up to a
maximum of {\tt x127}.  In keeping with this nomenclature, the first axis in
each direction can be referred to interchangeably as, for example, {\tt x} or
{\tt x1}, or as {\tt y} or {\tt y1}.  Further axes are automatically generated
when statements such as the following are issued:

\begin{verbatim}
set x2label 'A second horizontal axis'
\end{verbatim}

\noindent Such axes may alternatively be created explicitly using the
\indcmdt{set axis}, as in the example

\begin{verbatim}
set axis x3
\end{verbatim}

\noindent or removed explicitly using the \indcmdt{unset axis}, as in the
example

\begin{verbatim}
unset axis x3
\end{verbatim}

\noindent In either case, multiple axes can be created or removed in a single
statement, as in the examples

\begin{verbatim}
unset axis x3x5x6 y2
set axis x2y2
\end{verbatim}

\noindent The first axes {\tt x1} and {\tt y1} -- and {\tt z1} on
three-dimensional plots -- are unique in that they cannot be removed; all plots
must have at least one axis in each perpendicular direction.  Thus, the command
{\tt unset axis x1} does not remove this first axis, but merely returns it to
its default configuration.  It should be noted that if the following two
commands are typed in succession, the second may not entirely negate the first:

\begin{verbatim}
set x3label 'foo'
unset x3label
\end{verbatim}

\noindent If an {\tt x3}-axis did not previously exist, then the first will
have implicitly created one. This would need to be removed with the {\tt unset
axis x3} command if it was not desired.

\subsection{Selecting which axes to plot against}

The axes against which data are plotted can be selected by passing the {\tt
axes} modifier to the {\tt plot} command. By default, data is plotted against
the first horizontal axis and the first vertical axis. In the following {\tt
plot} command the second horizontal axis and the third vertical axis would be
used:
\begin{verbatim}
plot f(x) axes x2y3
\end{verbatim}
It is also possible to plot data using a vertical axis as the abscissa axis
using syntax such as:
\begin{verbatim}
plot f(x) axes y3x2
\end{verbatim}
Similar syntax is used when plotting three-dimensional graphs, except that
three perpendicular axes should be specified.

\subsection{Plotting quantities with physical units}
\label{sec:set_axisunitstyle}

When data with non-dimensionless physical units are plotted against an axis,
for example using any of the statements
\begin{verbatim}
plot [0:10] x*unit(m)
plot [0:10] x using 1:$2*unit(m)
plot [0*unit(m):1*unit(m)] x**2

set unit angle nodimensionless ; plot [0:1] asin(x)
\end{verbatim}
the axis is set to share the particular physical dimensions of that unit, and
thereafter no data with any other physical dimensions may be plotted against
that axis. When the axis comes to be drawn, Pyxplot makes a decision about
which physical unit should be used to label the axis. For example, in the
default SI system and with no preferred unit of length set, axes with units of
length might be displayed in millimeters, meters or kilometers depending on
their scales.

The chosen unit is indicated in one of three styles in the axis label, selected
using the \indcmdt{set axisunitstyle}:
\begin{verbatim}
set axisunitstyle ratio
set axisunitstyle bracketed
set axisunitstyle squarebracketed
\end{verbatim}
The effect of these three options, respectively, is shown below for an axis
with units of momentum. In each case, the axis label was set simply using
\begin{verbatim}
set xlabel "Momentum"
\end{verbatim}
and the subsequent text was appended automatically by Pyxplot:

\vspace{3mm}
\centerline{\includegraphics[width=10cm]{examples/eps/ex_axisunits}}
\vspace{3mm}

When the \indcmdt{set xformat} is used (see Section~\ref{sec:set_xformat}), no
indication of the units associated with axes are appended to axis labels, as
the \indcmdt{set xformat} can be used to hard-code this information. The user
must include this information in the axis label manually if it is needed.

\subsection{Specifying the positioning of axes}

By default, the {\tt x1}-axis is placed along the bottom of graphs and the {\tt
y1}-axis is placed up the left-hand side of graphs. On three-dimensional plots,
the {\tt z1}-axis is placed at the front of the graph. The second set of axes
are placed opposite the first: the {\tt x2}-, {\tt y2}- and {\tt z2}-axes are
placed respectively along the top, right and back sides of graphs.
Higher-numbered axes are placed alongside the {\tt x1}-, {\tt y1}- and {\tt
z1}-axes.

However, the position of any axis can be explicitly set using syntax of the
form:
\begin{verbatim}
set axis x top
set axis y right
set axis z back
\end{verbatim}
Horizontal axes can be set to appear either at the {\tt top} or {\tt bottom};
vertical axes can be set to appear either at the {\tt left} or {\tt right}; and
$z$-axes can be set to appear either at the {\tt front} or {\tt back}.

\subsection{Configuring the appearance of axes}

The \indcmdt{set axis} also accepts the following keywords alongside the
positional keywords listed above, which specify how the axis should appear:
\begin{itemize}
\item {\tt arrow} -- Specifies that an arrowhead should be drawn on the right/top end of the axis. [{\bf Not default}].
\item {\tt atzero} -- Specifies that rather than being placed along an edge of the plot, the axis should mark the lines where the perpendicular axes {\tt x1}, {\tt y1} and/or {\tt z1} are zero. [{\bf Not default}].
\item {\tt automirrored} -- Specifies that an automatic decision should be made between the behaviour of {\tt mirrored} and {\tt nomirrored}. If there are no axes on the opposite side of the graph, a mirror axis is produced. If there are already axes on the opposite side of the graph, no mirror axis is produced. [{\bf Default}].
\item {\tt fullmirrored} -- Similar to {\tt mirrored}. Specifies that this axis should have a corresponding twin placed on the opposite side of the graph with mirroring ticks and labelling. [{\bf Not default}; see {\tt automirrored}].
\item {\tt invisible} -- Specifies that the axis should not be drawn; data can still be plotted against it, but the axis is unseen. See Example~\ref{ex:australia} for a plot where all of the axes are invisible.
\item {\tt linked} -- Specifies that the axis should be linked to another axis; see Section~\ref{sec:linked_axes}.
\item {\tt mirrored} -- Specifies that this axis should have a corresponding twin placed on the opposite side of the graph with mirroring ticks but with no labels on the ticks. [{\bf Not default}; see {\tt automirrored}].
\item {\tt noarrow} -- Specifies that no arrowheads should be drawn on the ends of the axis. [{\bf Default}].
\item {\tt nomirrored} -- Specifies that this axis should not have any corresponding twins. [{\bf Not default}; see {\tt automirrored}].
\item {\tt notatzero} -- Opposite of {\tt atzero}; the axis should be placed along an edge of the plot. [{\bf Default}].
\item {\tt notlinked} -- Specifies that the axis should no longer be linked to any other; see Section~\ref{sec:linked_axes}. [{\bf Default}].
\item {\tt reversearrow} -- Specifies that an arrowhead should be drawn on the left/bottom end of the axis. [{\bf Not default}].
\item {\tt twowayarrow} -- Specifies that arrowheads should be drawn on both ends of the axis. [{\bf Not default}].
\item {\tt visible} -- Specifies that the axis should be displayed; opposite of {\tt invisible}. [{\bf Default}].
\end{itemize}

The following simple examples demonstrate the use of some of these configuration options:
\begin{verbatim}
set axis x atzero twoway
set axis y atzero twoway
plot [-2:8][-10:10]
\end{verbatim}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_axisatzero}}

\begin{verbatim}
set axis x atzero arrow
set axis y atzero twoway
plot [0:10][-10:10]
\end{verbatim}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_axisatzero2}}

\begin{verbatim}
set axis x notatzero arrow nomirror
set axis y notatzero arrow nomirror
plot [0:10][0:20]
\end{verbatim}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_axisatzero3}}

\subsection{Setting the color of axes}

The colors of axes\index{axes!color}\index{colors!axes} can be controlled
via the \indcmdts{set axescolor}.  The following example would set axes to be
drawn in blue:

\begin{verbatim}
set axescolor blue
\end{verbatim}

\noindent Any of the color names listed in Section~\ref{sec:color_names} can be
used, as can any object of type {\tt color}, e.g.\ {\tt rgb(0.2,0.1,0.8)}.

\subsection{Specifying where ticks should appear along axes}

By default, Pyxplot places a series of tick marks at significant points along
each axis, with the most significant points being labelled.  Labelled tick
marks are termed {\it major} ticks, and unlabelled tick marks are termed {\it
minor} ticks.  The position and appearance of the major ticks along the {\tt
x}-axis can be configured using the \indcmdt{set xtics}, which has the
following syntax:

\begin{verbatim}
set xtics
    [ ( axis | border | inward | outward | both ) ]
    [ ( autofreq
          | [<minimum>,] <increment> [, <maximum>]
          | \( { '<label>' <position> } \)
         ] )
\end{verbatim}

The corresponding {\tt set mxtics} command, which has the same syntax as above,
configures the appearance of the minor ticks along the {\tt x}-axis. Analogous
commands such as {\tt set ytics} and {\tt set mx2tics} configure the major and
minor ticks along other axes.

The keywords \indkeyt{inward}, \indkeyt{outward} and \indkeyt{both} are used to
configure how the ticks appear -- whether they point inward, towards the plot,
as is default, or outwards towards the axis labels, or in both directions.  The
keyword \indkeyt{axis} is an alias for \indkeyt{inward}, and \indkeyt{border}
an alias for \indkeyt{outward}.

The remaining options are used to configure where along the axis ticks are
placed. If a series of comma-separated values {\tt <minimum>, <increment>,
<maximum>} are specified, then ticks are placed at evenly spaced intervals
between the specified limits. The {\tt <minimum>} and {\tt <maximum>} values
are optional; if only one value is specified then it is taken to be the step
size between ticks. If two values are specified, then the first is taken to be
{\tt <minimum>}. In the case of logarithmic axes, {\tt <increment>} is applied
as a multiplicative step size, and should be dimensionless. For example:
\begin{verbatim}
set xtics 0,1,10 # Ticks at 0,1,2,...,10
set log x
set xtics 2,2  # Ticks at 2,4,8,16 ...
\end{verbatim}

Alternatively, if a bracketed list of quoted tick labels and tick positions are
provided, then ticks can be placed on an axis manually and each given its own
textual label. The quoted tick labels may be omitted, in which case they are
automatically generated:
\begin{verbatim}
set xtics ("a" 1, "b" 2, "c" 3)
set xtics (1,2,3)
\end{verbatim}
The keyword \indkeyt{autofreq} overrides any manual selection of ticks which
may have been placed on an axis and resumes the automatic placement of ticks
along it. The \indcmdt{show xtics}, together with its companions such as {\tt
show x2tics} and {\tt show ytics}, may be used to query the current ticking
options. The \indcmdt{set noxtics} may be used to stipulate that no ticks
should appear along a particular axis:

\begin{verbatim}
set noxtics
show xtics
\end{verbatim}

\example{ex:axistics}{A plot of the function $\exp(x)\sin(1/x)$}{
In this example we produce a plot illustrating some of the zeroes of the
function $\exp(x)\sin(1/x)$.  We set the {\tt x}-axis to have tick marks at
$x=0.05$, $0.1$, $0.2$ and $0.4$.  The {\tt x2}-axis has custom labelled ticks
at $x=1/\pi, 2/\pi$, etc., pointing outwards from the plot.  The left-hand {\tt
y}-axis has tick marks placed automatically whereas the {\tt y2}-axis has no
tics at all.
\nlscf
\input{examples/tex/ex_axistics_1.tex}
\nlscf
\centerline{\includegraphics[width=9cm]{examples/eps/ex_axistics}}
}

\subsection{Configuring how tick marks are labelled}
\label{sec:set_xformat}

By default, the major tick marks along axes are labelled with representations
of the values represented at each point, each accurate to the number of
significant figures specified using the \indcmdt{set numerics sigfig}. These
labels may appear as decimals, such as $3.142$, in scientific notion, as in
$3\times10^8$, or, on logarithmic axes where a base has been specified for the
logarithms, using syntax such as\footnote{Note that the {\tt x} axis must be
referred to as {\tt x1} here to distinguish this statement from {\tt set log
x2}.}
\begin{verbatim}
set log x1 2
\end{verbatim}
in a format such as $1.5\times2^8$.

The \indcmdt{set xformat} -- together with its companions such as {\tt set
yformat}\footnote{There is no {\tt set mxformat} command since minor axis ticks
are never labelled unless labels are explicitly provided for them using the
syntax {\tt set mxtics (...)}.} -- is used to manually specify an explicit
format for the axis labels to take, as demonstrated by the following pair of
examples:
\begin{verbatim}
set xformat "%.2f"%(x)
set yformat "%s$^\prime$"%(y/unit(feet))
\end{verbatim}
The first example specifies that ordinate values should be displayed to two
decimal places along the {\tt x}-axis; the second specifies that distances should
be displayed in feet along the {\tt y}-axis. Note that the dummy variable used to
represent the ordinate value is {\tt x}, {\tt y} or {\tt z} depending on the
direction of the axis, but that the dummy variable used in the {\tt set
x2format} command is still {\tt x}. The following pair of examples both have
the equivalent effect of returning the {\tt x2}-axis to its default system of
tick labels:
\begin{verbatim}
set x2format auto
set x2format "%s"%(x)
\end{verbatim}

The following example specifies that ordinate values should be displayed as
multiples of $\pi$:
\begin{verbatim}
set xformat "%s$\pi$"%(x/pi)
plot [-pi:2*pi] sin(x)
\end{verbatim}

\noindent\centerline{\includegraphics[width=8cm]{examples/eps/ex_axistics2}}

Note that where possible, Pyxplot intelligently changes the positions along
axes where it places the ticks to reflect significant points in the chosen
labelling system.  The extent to which this is possible depends on the format
string supplied. It is generally easier when continuous-varying numerical
values are substituted into strings, rather than discretely-varying values or
strings. Thus, rather than

\begin{dontdo}
set xformat "\%d"\%(floor(x))
\end{dontdo}

\noindent the following is preferred

\begin{dodo}
set xformat "\%d"\%(x)
\end{dodo}

\noindent and rather than

\begin{dontdo}
set xformat "\%s"\%date.str()
\end{dontdo}

\noindent the following is preferred

\begin{dodo}
set xformat "\%d/\%02d/\%d"\%(date.toDayOfMonth(), $\backslash$\newline
date.toMonthNum(), date.toYear())
\end{dodo}

\subsubsection{Changing the slant of axis labels}

The \indcmdt{set xformat} and its companions may also be followed by keywords
which control the angle at which tick labels are drawn. By default, all tick
labels are written horizontally, a behaviour which may be reproduced by issuing
the command:
\begin{verbatim}
set xformat auto horizontal
\end{verbatim}
Alternatively, tick labels may be set to be written vertically, by issuing the command
\begin{verbatim}
set xformat auto vertical
\end{verbatim}
or to be written at any clockwise rotation angle from the horizontal using commands of the form
\begin{verbatim}
set xformat auto rotate 10
\end{verbatim}

Axis labels may also be made to appear at arbitrary rotations using commands such as
\begin{verbatim}
set unit angle nodimensionless
set xlabel "I'm upside down" rotate unit(0.5*revolution)
\end{verbatim}

\subsubsection{Removing axis tick labels}

Axes may be set to have no textual labels associated with the ticks along them
using the command:
\begin{verbatim}
set xformat ""
\end{verbatim}
This is particularly useful when compiling galleries of plots using linked axes
(see the next section) and the multiplot environment (see
Chapter~\ref{ch:vector_graphics}).

\subsection{Linked axes}
\label{sec:linked_axes}

Often it may be desired that multiple axes on a graph share a common range, or
be related to one another by some algebraic expression. For example, a plot
with wavelength $\lambda$ of light as one axis may usefully also have parallel
axes showing frequency of light $\nu=c/\lambda$ or photon energy
$E=hc/\lambda$. The following example sets the {\tt x2} axis to share a common
range with the {\tt x} axis:
\begin{verbatim}
set axis x2 linked x
\end{verbatim}
An algebraic relationship between two axes may be set by stating the algebraic
relationship after the keyword {\tt using}, as in the following example which
implement the formulae shown above for the frequency and energy of photons of
light as a function of their wavelength:
\begin{verbatim}
set xrange [200*unit(nm):unit(800*nm)]
set axis x2 linked x1 using phy.c/x
set axis x3 linked x2 using phy.h*x
\end{verbatim}
As in the {\tt set xformat} command, a dummy variable of {\tt x}, {\tt y} or
{\tt z} is used in the linkage expression depending on the direction of the
axis being linked to, but a dummy variable of {\tt x} is still used when
linking to, for example, the {\tt x2} axis.

As these examples demonstrate, the functions used to link axes need not be
linear. In fact, axes with any arbitrary mapping between position and value can
be produced by linked in a non-linear fashion to another linear axis, which, if
desired, can then be hidden using the {\tt set axis invisible} command.
Multi-valued mappings are also permitted. Any data plotted against the
following {\tt x2}-axis for a suitable range of {\tt x}-axis
\begin{verbatim}
set axis x2 linked x1 using x**2
\end{verbatim}
would appear twice, symmetrically on either side of $x=0$.

Insofar as is possible, linked axes autoscale intelligently when no range is
set.  Thus, if the {\tt x2}-axis is linked to the {\tt x}-axis, and no range to
set for the {\tt x}-axis, the {\tt x}-axis will autoscale to include all of the
data plotted against both itself and the {\tt x2}-axis. Similarly, if the {\tt
x2}-axis is linked to the {\tt x}-axis by means of some algebraic expression,
the {\tt x}-axis will attempt to autoscale to include the data plotted against
the {\tt x2}-axis, though in some cases -- especially with non-monotonic
linking functions -- this may prove too difficult. Where Pyxplot detects that
it has failed, a warning is issued recommending that a hard range be set for --
in this example -- the {\tt x}-axis.

\example{ex:multiaxes}{A plot of many blackbodies demonstrating the use of linked axes}{
In this example we produce a plot of blackbody spectra for five different
temperatures $T$, using the Planck formula
\begin{displaymath}
B_\nu(\nu,T)=\left(\frac{2h^3}{c^2}\right)\frac{\nu^3}{\exp(h\nu/kT)-1}
\end{displaymath}
which is evaluated in Pyxplot by the system-defined mathematical function {\tt
Bv(nu,T)}. We use the axis linkage commands listed as an example in the text of
Section~\ref{sec:linked_axes} to produce three parallel horizontal axes showing
wavelength of light, frequency of light and photon energy.
\nlscf
\input{examples/tex/ex_multiaxes_1.tex}
\nlscf
\centerline{\includegraphics[width=10cm]{examples/eps/ex_multiaxes}}
}

\example{ex:cmbrtemp}{A plot of the temperature of the CMBR as a function of redshift demonstrating non-linear axis linkage}{
In this example we produce a plot of the temperature of the cosmic microwave
background radiation (CMBR) as a function of time $t$ since the Big Bang, on
the {\tt x}-axis, and equivalently as a function of redshift $z$, on the {\tt
x2}-axis.  The specialist cosmology function
\indfunt{ast\_\-Lcdm\_\-z($t$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}
is used to make the highly non-linear conversion between time $t$ and redshift
$z$, adopting some standard values for the cosmological parameters $H_0$,
$\Omega_\mathrm{M}$ and $\Omega_\Uplambda$. Because the temperature of the CMBR
is most easily expressed as a function of redshift as $T=2.73\,\mathrm{K}/(1+z)$,
we plot this function against axis {\tt x2}.
\nlscf
\input{examples/tex/ex_cmbrtemp_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_cmbrtemp}}
}

\section{Gridlines}

Gridlines may be placed on a plot and subsequently removed via the statements:

\begin{verbatim}
set grid
set nogrid
\end{verbatim}

\noindent respectively. The following commands are also valid:

\begin{verbatim}
unset grid
unset nogrid
\end{verbatim}

\noindent By default, gridlines are drawn from the major and minor ticks of the
default horizontal and vertical axes (which are the first axes in each
direction unless set otherwise in the configuration file; see
Chapter~\ref{ch:configuration}).  However, the axes which should be used may be
specified after the \indcmdt{set grid}\index{grid}:

\begin{verbatim}
set grid x2y2
set grid x x2y2
\end{verbatim}

\noindent The top example would connect the gridlines to the ticks of the {\tt
x2}- and {\tt y2}-axes, whilst the lower would draw gridlines from both the
{\tt x}- and the {\tt x2}-axes.

If one of the specified axes does not exist, then no gridlines will be drawn in
that direction.  Gridlines can subsequently be removed selectively from some
axes via:

\begin{verbatim}
set nogrid x2x3
\end{verbatim}

\label{sec:set_colors}
The colors of gridlines\index{grid!color}\index{colors!grid} can be
controlled via the \indcmdts{set gridmajcolor} and \indcmdts{set
gridmincolor} commands, which control the gridlines emanating from major and
minor axis ticks respectively. The following example would set the minor grid
lines on a graph to be drawn in blue:

\begin{verbatim}
set gridmajcolor gray70
set gridmincolor blue
\end{verbatim}

\noindent Any of the color names listed in Section~\ref{sec:color_names} can
be used, as can any object of type {\tt color}.

\section{Clipping behaviour}

The treatment of datapoints close to the edges of plots may be specified using
the \indcmdt{set clip}, which provides two options. Either datapoints close to
the axes can be clipped and not allowed to overrun the axes -- specified by
{\tt set clip} -- or such datapoints may be allowed to extend over the lines of
the axes -- specified by {\tt set noclip} and the default behaviour.

\section{Labelling graphs}

The {\tt set arrow}\indcmd{set arrow} and \indcmdt{set label}s allow arrows and
text labels to be added to graphs to label significant points or to add simple
vector graphics to them.

\subsection{Arrows}

\label{sec:set_arrow}\index{arrows} The \indcmdt{set arrow} may be used to
draw arrows on top of graphs; its syntax is illustrated by the following simple
example:

\begin{verbatim}
set arrow 1 from 0,0 to 1,1
\end{verbatim}

\noindent Optionally, a third coordinate may be specified. On 2D plots, this is
ignored. If no third coordinate is supplied then a value of $z=0$ is
substituted when the arrow is plotted on 3D graphs. The number {\tt 1}
immediately following \indcmdts{set arrow} specifies an identification number
for the arrow, allowing it to be subsequently removed via the command

\begin{verbatim}
unset arrow 1
\end{verbatim}

\noindent or equivalently, via\indcmd{set noarrow}

\begin{verbatim}
set noarrow 1
\end{verbatim}

\noindent or to be replaced with a different arrow by issuing a new command of
the form {\tt set arrow 1~...}.  The {\tt set arrow} command may be followed by
the keyword {\tt with} to specify the style of the arrow. The keywords
\indkeyt{nohead}, \indkeyt{head} and \indkeyt{twohead}, placed after the
keyword {\tt with}, can be used to generate arrows with no arrow heads, normal
arrow heads, or with two arrow heads.  \indkeyt{twoway} is an alias for
\indkeyt{twohead}, as in the following example:

\begin{verbatim}
set arrow 1 from 0,0 to 1,1 with twoway
\end{verbatim}

\noindent Line types, line widths and colors can also be specified after the
keyword {\tt with}, as in the example:

\begin{verbatim}
set arrow 1 from 0,0 to 1,1 with nohead \
linetype 1 c blue
\end{verbatim}

The coordinates for the start and end points of the arrow can be specified in a
range of coordinate systems. The coordinate system to be used should be
specified immediately before the coordinate value. The default system,
\indcot{first} measures the graph using the {\tt x}- and {\tt y}-axes. The
\indcot{second} system uses the {\tt x2}- and {\tt y2}-axes. \indcot{axis<n>}
specifies that the position is to be measured along the $n\,$th horizontal or
vertical axis -- for example, {\tt axis3}.\indcmd{set arrow} This allows the
graph to be measured with reference to any arbitrary axis on plots which make
use of large numbers of parallel axes (see Section~\ref{sec:multiple_axes}).
The \indcot{page} and \indcot{graph} systems both measure in centimeters from
the origin of the graph. In the following example, we use these specifiers, and
specify coordinates using variables rather than doing so explicitly:

\begin{verbatim}
x0 = 0.0
y0 = 0.0
x1 = 1.0
y1 = 1.0
set arrow 1 from first  x0, first  y0 \
            to   screen x1, screen y1 \
            with nohead
\end{verbatim}

\subsection{Text labels}

Text labels may be placed on plots using the \indcmdt{set label}. As with all
textual labels in Pyxplot, these are rendered in \latexdcf:

\begin{verbatim}
set label 1 'Hello World' at 0,0
\end{verbatim}

As in the previous section, the number {\tt 1} is a reference number, which
allows the label to be removed by either of the following two commands:

\begin{verbatim}
set nolabel 1
unset label 1
\end{verbatim}

\noindent The positional coordinates for the text label, placed after the {\tt
at} keyword, can be specified in any of the coordinate systems described for
arrows above. As above, either two or three coordinates may be supplied. A
rotation angle may optionally be specified after the keyword \indkeyt{rotate},
to rotate text counter-clockwise by a given angle, measured in degrees. For
example, the following would produce upward-running text:

\begin{verbatim}
set label 1 'Hello World' at axis3 3.0, axis4 2.7 rotate 90
\end{verbatim}

A color can also be specified, if desired, using the {\tt with color}
modifier.  For example, the following would produce a green label at the origin:

\begin{verbatim}
set label 2 'This label is green' at 0, 0 with color green
\end{verbatim}

\index{fontsize}\index{text!size} The size of the text can be set using the {\tt with fontsize} modifier:

\begin{verbatim}
set label 3 'A Big Blue Label' at 0,0 with col blue fontsize 4
\end{verbatim}

\noindent
Alternatively, it may be set globally using the \indcmdt{set fontsize}. This
applies not only to the {\tt set label} command, but also to plot titles, axis
labels, keys, etc. The value supplied should be a multiplicative factor greater
than zero; a value of~{\tt 2} would cause text to be rendered at twice its
normal size, and a value of~{\tt 0.5} would cause text to be rendered at half
its normal size.

\index{text!color}\index{colors!text} The \indcmdt{set textcolor} can be
used to globally set the color of all text output, and applies to all of the
text that the {\tt set fontsize} command does. It is especially useful when
producing plots to be embedded in presentation slideshows, where bright text on
a dark background may be desired. It should be followed either by an integer,
to set a color from the present palette, or by a color name. A list of the
recognised color names can be found in Section~\ref{sec:color_names}.  For
example:

\begin{verbatim}
set textcolor 2
set textcolor blue
\end{verbatim}

\index{text!alignment}\index{alignment!text}By default, each label's specified
position corresponds to its bottom left corner. This alignment may be changed
with the \indcmdts{set texthalign} and \indcmdts{set textvalign} commands. The
former takes the options \indkeyt{left}, \indkeyt{center} or \indkeyt{right},
and the latter takes the options \indkeyt{bottom}, \indkeyt{center} or
\indkeyt{top}, for example:

\begin{verbatim}
set texthalign right
set textvalign top
\end{verbatim}

\example{ex:hlines}{A diagram of the atomic lines of hydrogen}{
The wavelengths of the spectral lines of atomic hydrogen are given by the Rydberg formula,
\begin{displaymath}
\frac{1}{\lambda} = R_\mathrm{H}\left(\frac{1}{n^2}-\frac{1}{m^2}\right),
\end{displaymath}
where $\lambda$ is wavelength, $R_\mathrm{H}$ is the Rydberg constant,
predefined in Pyxplot as the variable {\tt phy\_Ry}, and {\tt n} and {\tt m}
are positive non-zero integers such that {\tt m>n}. The first few series are
called the Lyman series ({\tt n}$=1$), the Balmer series ({\tt n}$=2$), the
Paschen series ({\tt n}$=3$) and the Brackett series ({\tt n}$=4$). Within each
series, the lines are given Greek letter designations -- $\alpha$ for {\tt
m}$=${\tt n}$+1$, $\beta$ for {\tt m}$=${\tt n}$+2$, and so forth.
\nlnp
In the following example, we produce a diagram of the lines in the first four
series, drawing the first~20 lines within each. At the bottom of the diagram,
we overlay indications of the wavelengths of ten color filters commonly used
by astronomers (data taken from Binney \& Merrifield, {\it Galactic Astronomy},
Princeton, 1998).
\nlscf
\input{examples/tex/ex_hlines_1.tex}
\nlscf
\begin{center}
\includegraphics[width=11cm]{examples/eps/ex_hlines}
\end{center}
}

\newpage
\example{ex:australia}{A map of Australia}{
In this example, we use Pyxplot to plot a map of Australia, using a coastal
outline obtained from \protect\url{http://www.maproom.psu.edu/dcw/}. We use the
{\tt set label} command to label the states and major cities. The files {\tt
ex\_\-map\_\-1.dat.gz} and {\tt ex\_\-map\_\-2.dat} can be found in the Pyxplot
installation tarball in the directory {\tt doc/\-examples/}.
\nlscf
\input{examples/tex/ex_map_1.tex}
\nlscf
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_map}
\end{center}
}

\section{Color maps}
\label{sec:colormaps}

Color maps provide a graphical means of producing two-dimensional
representations of $(x,y,z)$ surfaces, or equivalently of producing maps of the
values $z(x,y)$ of functions of two variables. Each point in the $(x,y)$ plane
is assigned a color which indicates the value $z$ associated with that point.
In this section, we refer to the third coordinate as $c_1$ rather than
$z$, to distinguish it from the third axes of three-dimensional
plots\footnote{When color maps are plotted on three-dimensional graphs, they
appear in a flat plane on one of the back faces of the plot selected using the
{\tt axes} modifier to the {\tt plot} command, and the $c_1$-axis associated
with each are entirely independent of the plot's $z$-axis.}.

In the following simple example, a color map of the complex argument of the
Riemann zeta function $\zeta(z)$ is produced, taking the $(x,y)$ plane to be an
Argand plane, with $x$ being the real axis, and $y$ being the imaginary axis.
Each point in the plane has an associated value of $c_1$.

\vspace{2mm}
\input{examples/tex/ex_zeta_arg_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_zeta_arg}}

The \indcmdt{set c1range} sets the range of values of $c_1$ to be assigned
colors between black and white. By default, the lowest and highest values of
$c_1$ found in the color map is assigned to black and white.

The \indcmdt{set c1format} controls the format of the axis labels placed along
the color scale bar on the right-hand side of the plot. In this case, they are
marked as multiples of $\pi$.

The \indcmdt{set samples grid} sets the dimensions of the grid of samples -- or
pixels -- used to render the color map. If either value is replaced with an
asterisk ({\tt *}) then the current number of samples set in the {\tt set
samples} command is substituted.

If a \datafile\ is supplied to the {\tt colormap} plot style, then the
datapoints need not lie on the specified regular grid, but are first re-sampled
onto this grid using the interpolation method specified using the \indcmdt{set
samples interpolate} (see Section~\ref{sec:spline_command}). Three methods are
available. {\tt nearest\-Neigh\-bor} uses the value of $c_1$
associated with the datapoint closest to each grid point, producing color maps
which look like Voronoi diagrams. {\tt inverse\-Square} interpolation returns a
weighted average of the supplied \datapoint s, using the inverse squares of
their distances from each grid point as weights. {\tt monag\-han\-Lattan\-zio}
interpolation uses the weighting function of Monaghan \& Lattanzio (1985) which
is described further in Section~\ref{sec:spline_command}).

In the following example, a color map of a quadrupole is produced using four
input datapoints:

\vspace{2mm}
\input{examples/tex/ex_quadrupole_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_quadrupole}}

\subsection{Custom color mappings}
\label{sec:colmap_custom}

The default mapping used between values of $c_1$ and color is a grayscale
mapping. This is scaled such that the smallest value of $c_1$ in the map
corresponds to black, and largest value corresponds to white.

Alternatively, the user can supply any algebraic expressions for converting
values of $c_1$ into colors.  Moreover, these custom color mappings need not be
one-parameter mappings depending only on a single variable $c_1$, but can
depend on up to four quantities $c_1$, $c_2$, $c_3$ and $c_4$. This makes it
possible, for example, to represent both the amplitude and complex phase of a
quantity in a single color map.

Pyxplot's \indpst{colormap} plot style takes between three and seven columns of
data, which may be supplied either from one or more function(s), or from a
\datafile. If data is read from a \datafile, then the first two columns of
output data are assumed to contain the respective positions of each datapoint
along the $x$-axis and the $y$-axis. The next column contains the value $c_1$,
and may be followed by up to three further optional values $c_2$, $c_3$ and
$c_4$.

In the case where one or more function(s) are supplied, they are assumed to be
functions of both $x$ and $y$, and are sampled at a grid of points in the
$(x,y)$ plane; the first supplied function returns the value $c_1$, and may be
followed by up to three further optional functions for $c_2$, $c_3$ and $c_4$..

The color mapping is set using the \indcmdt{set colormap}, which takes an
algebraic expression which should be a function of the variables {\tt c1}, {\tt
c2}, {\tt c3} and {\tt c4}. This should evaluate either to a color object or a
number (in which case a color is drawn from the current palette).

\begin{verbatim}
set colormap <expr> [ mask <expr> ]
\end{verbatim}

\noindent If the optional mask expression is supplied, then any areas in a
color map where this expression evaluates to false (e.g.\ zero) are made
transparent. The following color mapping, which is the default, produces a
grayscale color mapping of the third column of data supplied to the
\indpst{colormap} plot style; further columns of data, if supplied, are not
used:

\begin{verbatim}
set c1range [*:*] renormalise noreverse
set colormap gray(c1)
\end{verbatim}

The \indcmdt{set c<n>range} command specifies how the values of $c_n$ are
processed before being used in the expressions supplied to the \indcmdt{set
colormap}. It has the following syntax:

\begin{verbatim}
set c<n>range [ <range> ]
              [ reversed | noreversed ]
              [ renormalise | norenormalise ]
\end{verbatim}

\noindent If the {\tt renor\-malise} option is specified, then the values of
$c_n$ at each point in the data grid are first scaled into the range zero to
one. This is often useful, since the color components passed to the {\tt
rgb()}, {\tt gray()}, {\tt hsb()} and {\tt cmyk()} functions must be in this
range.  Thus, in the example given above, the lowest value of $c_1$ corresponds
to black (i.e.\ brightness 0), and the highest value corresponds to white
(i.e.\ brightness 1). If an explicit range is specified to the {\tt set
c<n>range} command, then the upper limit of this range maps to the value one,
and the lower limit maps to the value zero. An asterisk ({\tt *}) means that
the lowest or highest value found in the map is substituted. The mapping is
inverted if the {\tt reverse} option is specified, such that the upper limit
maps to zero, and the lower limit maps to one.  Intermediate values are scaled
either linearly or logarithmically, and these behaviours can be selected with
the following commands:
\begin{verbatim}
set logscale c1
set linearscale c1
\end{verbatim}

In the example below, a color map of the function $f(z)=3x^2/(x^3+1)$ is made,
using hue to represent the magnitude of $f(z)$ and saturation to represent the
complex argument of $f(z)$:

\vspace{2mm}
\input{examples/tex/ex_branch_cuts_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_branch_cuts}}

In the next example, three circular pools of red, green, and blue illumination are overlapped to show how colors mix together:

\vspace{2mm}
\input{examples/tex/ex_spectrum_colmix1_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_spectrum_colmix1}}

The same is possible with CMYK colors, to demonstrate how substractive color mixing works:

\vspace{2mm}
\input{examples/tex/ex_spectrum_colmix2_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_spectrum_colmix2}}

The function {\tt colors.wavelength(wlen,normalisation)} provides a color representation of any given wavelength of light, useful for producing representations of the electromagnetic spectrum:

\vspace{2mm}
\input{examples/tex/ex_spectrum_1_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_spectrum_1}}

The function {\tt colors.spectrum(spectrum,normalisation)} takes a function as its first input, which should return a spectral energy distribution (in arbitrary units) as a function of wavelength. In this example, we show the colors of blackbodies of different temperatures. We renormalise their brightnesses by $T^{-4}$ to avoid saturating hot blackbodies to white:

\vspace{2mm}
\input{examples/tex/ex_spectrum_bbcol_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_spectrum_bbcol}}

As a final example, we use this function to plot the interference pattern seen when a wedge of stressed plastic, a birefrigent material, is viewed between crossed polars:

\vspace{2mm}
\input{examples/tex/ex_spectrum_biref_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=8cm]{examples/eps/ex_spectrum_biref}}

\subsection{Color scale bars}

By default, plots with color maps with single-parameter color mappings are
accompanied by color scale bars, which appear by default on the right-hand
side of the plot. Such scale bars may be configured using the \indcmdt{set
colorkey}. Issuing the command

\begin{verbatim}
set colorkey
\end{verbatim}

\noindent by itself causes such a scale to be drawn on graphs in the default
position, usually along the right-hand edge of the graphs. The converse action
is achieved by:

\begin{verbatim}
set nocolorkey
\end{verbatim}

\noindent The command

\begin{verbatim}
unset colorkey
\end{verbatim}

\noindent causes Pyxplot to revert to its default behaviour, as specified in a
configuration file, if present. A position for the key may optionally be
specified after the {\tt set colorkey} command, as in the example:

\begin{verbatim}
set colorkey bottom
\end{verbatim}

Recognised positions are {\tt top}, {\tt bottom}, {\tt left} and {\tt right}.
{\tt above} is an alias for {\tt top}; {\tt below} is an alias for {\tt bottom}
and {\tt outside} is an alias for {\tt right}.

The format of the ticks along such scale bars may be set using the \indcmdt{set
c1format} command, which is similar in syntax to the {\tt set xformat} command
(see Section~\ref{sec:set_xformat}), but which uses {\tt c} as its dummy
variable.

The positions of the ticks along color scale bars may be set using the
\indcmdt{set c1tics} command, which has similar syntax to the {\tt set xtics}
command.

\example{ex:mandelbrot}{An image of the Mandelbrot set}{
The Mandelbrot set is a set of points in the complex plane whose boundary forms
a fractal with a Hausdorff dimension of two.  A point $c$ in the complex plane
is defined to lie within the Mandelbrot set if the complex sequence of numbers
\begin{displaymath}
z_{n+1} = z_n^2 + c,
\end{displaymath}
subject to the starting condition $z_0=0$, remains bounded.
\nlnp
The map of this set of points has become a widely-used image of the power of
chaos theory to produce complicated structure out of simple algorithms. To
produce a more pleasing image, points in the complex plane are often colored
differently, depending on how many iterations $n$ of the above series are
required for $|z_n|$ to exceed~2. This is the point of no return, beyond which
it can be shown that $|z_{n+1}|>|z_n|$ and that divergence is guaranteed. In
numerical implementations of the above iteration, in the absence of any better
way to prove that the iteration remains bounded for a certain value of $c$,
some maximum number of iterations $m$ is chosen, and the series is deemed to
have remained bounded if $|z_m|<2$.  This is implemented in Pyxplot by the
built-in mathematical function {\tt
fractal\_\-mandel\-brot(z,m)}\indfun{fractal\_mandelbrot($z$,$m$)}, which
returns an integer in the range $0\leq i\leq m$.
\nlscf
\input{examples/tex/ex_mandelbrot_1.tex}
\nlscf
\begin{center}
\includegraphics[width=8cm]{examples/eps/ex_mandelbrot}
\end{center}
}

\section{Contour maps}
\label{sec:contourmaps}

Contour maps are similar to color maps, but instead of coloring the whole
$(x,y)$ plane, lines are drawn to indicate paths of constant $c(x,y)$. The
number of contours drawn, and the values $c_1$ that they correspond to, is set
using the \indcmdt{set contour}, which has the following syntax:

\begin{verbatim}
set contours [ ( <number> |
               \( { <value> } \) ) ]
             [ (label | nolabel) ]
\end{verbatim}

If {\tt <number>} is specified, as in the example
\begin{verbatim}
set contours 8
\end{verbatim}
then the specified number of contours are drawn at evenly spaced intervals.
Whether the contours are linearly or logarithmically spaced can be changed
using the commands
\begin{verbatim}
set logscale c1
set linearscale c1
\end{verbatim}
By default, the range of values spanned by the contours is automatically scales
to the range of the data provided. However, it may also be set manually using
the \indcmdt{set c1range} as in the example
\begin{verbatim}
set c1range [0:10]
\end{verbatim}
The default autoscaling behaviour can be restored using the command
\begin{verbatim}
set c1range [*:*]
\end{verbatim}

Alternatively, an explicit list of the values of $c$ for which contours should
be drawn may be specified to the \indcmdt{set contour} as a ()-bracketed
comma-separated list. For example:
\begin{verbatim}
set contours (0,5,10,20,40)
\end{verbatim}

If the option {\tt label} is specified to the \indcmdt{set contour}, then each
contour is labelled with the value of $c$ that it corresponds to. If the option
{\tt nolabel} is specified, then the contours are left unlabelled.

In the following example, a contour map is overlaid on top of a color map of
the function $x^3/20+y^2$:

\vspace{2mm}
\input{examples/tex/ex_contourmap_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=10cm]{examples/eps/ex_contourmap}}
\vspace{2mm}

The {\tt contourmap} plot style differs from other plot styles in that it is
not permitted to take expressions such as {\tt \$2+1} for style modifiers such
as {\tt linetype} (see Section~\ref{sec:with_modifier}) which use additional
columns of input data to plot different points in different styles. However,
the variable {\tt c1} may be used in such expressions to define different
styles for different contours:

\begin{dontdo}
plot 'datafile' with contourmap linetype \$5
\end{dontdo}

\begin{dodo}
plot 'datafile' with contourmap linetype c1/10
\end{dodo}

\section{Three-dimensional plotting}
\label{sec:threedim}

Three-dimensional graphs may be produced by placing the modifier {\tt 3d}
immediately after the {\tt plot} command, as demonstrated by the following
simple example which draws a helix:

\vspace{2mm}
\input{examples/tex/ex_3d_helix_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=10cm]{examples/eps/ex_3d_helix}}
\vspace{2mm}

Many plot styles take additional columns of data when used on
three-dimen\-sional plots, reading in three values for the $x$, $y$ and $z$
coordinates of each datapoint, where previously only $x$ and $y$ coordinates
were required. In the above example, the {\tt lines} plot style is used, which
takes three columns of input data when used on three-dimensional plots, as
compared to two on two-dimensional plots.  The descriptions of each plot style
in Section~\ref{sec:list_of_plotstyles} includes information on the number of
columns of data required for two- and three-dimensional plots. 

The example above also demonstrates that the \indcmdt{set size} takes an
additional aspect ratio {\tt zratio} which affects three-dimensional plots;
whereas the aspect ratio {\tt ratio} determines the ratio of the lengths of the
$y$-axes of plots to their $x$-axes, the aspect ratio {\tt zratio} determines
the ratio of the lengths of the $z$-axes of plots to their $x$-axes.

The angle from which three-dimensional plots are viewed can be set using the
\indcmdt{set view}. This should be followed by two angles, which can either be
expressed in degrees, as dimensionless numbers, or as quantities with physical
units of angle:
\begin{verbatim}
set view 60,30

set unit angle nodimensionless
set view unit(0.1*rev),unit(2*rad)
\end{verbatim}
The orientation $(0,0)$ corresponds to having the $x$-axis horizontal, the
$z$-axis vertical, and the $y$-axis directed into the page. The first angle
supplied to the {\tt set view} command rotates the plot in the $(x,y)$ plane,
and the second angle tips the plot up in the plane containing the $z$-axis and
the normal to the user's two-dimensional display.

The \indcmdt{replot} command may be used to add additional datasets to
three-dimensional plots in an entirely analogous fashion to two-dimensional
plots.

\subsection{Surface plotting}
\label{sec:surfaces}

The {\tt surface} plot style is similar to the {\tt colormap} and {\tt
contourmap} plot styles, but produces maps of the values $z(x,y)$ of functions
of two variables using three-dimensional surfaces. The surface is displayed as
a grid of four-sided elements, whose number may be specified using the
\indcmdt{set samples}, as in the example
\begin{verbatim}
set samples grid 40x40
\end{verbatim}
If data is supplied from a \datafile, then it is first re-sampled onto a regular
grid using one of the methods described in Section~\ref{sec:colormaps}.

The example below plots a surface indicating the magnitude of the imaginary
part of $\log(x+iy)$:

\vspace{2mm}
\input{examples/tex/ex_surface_log_1.tex}
\vspace{2mm}

\centerline{\includegraphics[width=10cm]{examples/eps/ex_surface_log}}
\vspace{2mm}

\example{ex:surface-polynomial}{A surface plotted above a contour map}{
In this example, we plot a surface showing the value of the expression
$x^3/20+y^2$, and project below it a series of contours in the $(x,y)$ plane.
\nlscf
\input{examples/tex/ex_surface_polynomial_1.tex}
\nlscf
\begin{center}
\includegraphics[width=10cm]{examples/eps/ex_surface_polynomial}
\end{center}
}

\example{ex:surface-sinc}{The sinc($x$) function represented as a surface}{
In this example, we produce a surface showing the function $\mathrm{sinc}(r)$
where $r=\sqrt{x^2+y^2}$. To produce a prettier result, we vary the color of
the surface such that the hue of the surface varies with azimuthal position,
its saturation varies with radius $r$, and its brightness varies with height
$z$.
\nlscf
\input{examples/tex/ex_surface_sinc_1.tex}
\nlscf
\begin{center}
\includegraphics[width=10cm]{examples/eps/ex_surface_sinc}
\end{center}
}

% \section{Non-Flat Projections}