pyxplot-0.8.1/0000755000175000017500000000000011401470460011614 5ustar dcf21dcf21pyxplot-0.8.1/AUTHORS0000644000175000017500000000006211401470334012662 0ustar dcf21dcf21Dominic Ford, Ross Church
pyxplot-0.8.1/manpage_pyxplot_watch.py0000644000175000017500000000547411401470334016575 0ustar dcf21dcf21# MANPAGE_PYXPLOT_WATCH.PY
#
# The code in this file is part of PyXPlot
#
#
# Copyright (C) 2006-2010 Dominic Ford
# 2008-2010 Ross Church
#
# $Id: manpage_pyxplot_watch.py 814 2010-05-28 15:14:41Z 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
# ----------------------------------------------------------------------------
# Generate manpage for PyXPlot watcher
import sys
docpath = sys.argv[1]
author = open("AUTHORS","r").read()
description = ""
sys.stdout.write(r"""
.\" pyxplot_watch.1
.\"
.\" The manpage in this file is part of PyXPlot
.\"
.\"
.\" Copyright (C) 2006-2010 Dominic Ford
.\" 2008-2010 Ross Church
.\"
.\" $Id: manpage_pyxplot_watch.py 814 2010-05-28 15:14:41Z 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
.\"
.\" ----------------------------------------------------------------------------
.\" Man page for pyxplot_watch
.TH PYXPLOT_WATCH 1
.SH NAME
pyxplot_watch \- a tool which monitors a collection of PyXPlot command scripts
and executes them whenever they are modified.
.SH SYNOPSIS
.B pyxplot_watch
[file ...]
.SH DESCRIPTION
pyxplot_watch is a part of the PyXPlot plotting package; it is a simple tool
for watching PyXPlot command script files, and executing them whenever they are
modified. It is should be followed on the commandline by a list of command
scripts which are to be watched. Full documentation can be found in:
%s
.SH COMMAND LINE OPTIONS
\-v, \-\-verbose: Verbose mode; output full activity log to terminal
\-q, \-\-quiet : Quiet mode; only output PyXPlot error messages to terminal
\-h, \-\-help : Display this help
\-V, \-\-version: Display version number
.SH AUTHORS
%s.
.SH CREDITS
Thanks to Dave Ansell, Rachel Holdforth, Stuart Prescott, Michael Rutter and
Matthew Smith, all of whom have made substantial contributions to the
development of PyXPlot.
.SH "SEE ALSO"
.BR pyxplot (1), gnuplot (1)
"""%(docpath,author))
pyxplot-0.8.1/doc/0000755000175000017500000000000011401470524012362 5ustar dcf21dcf21pyxplot-0.8.1/doc/papersizes.tex0000644000175000017500000001665511401470334015305 0ustar dcf21dcf21% PAPERSIZES.TEX
%
% The documentation in this file is part of PyXPlot
%
%
% Copyright (C) 2006-2010 Dominic Ford
% 2008-2010 Ross Church
%
% $Id: papersizes.tex 760 2010-05-10 16:24:57Z 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{List of Paper Sizes}
\label{ch:paper_sizes}
The following table lists all of the named paper sizes which PyXPlot recognises:
{\twocolumn
\begin{supertabular}{|lll|}
\shrinkheight{5mm}
\hline
\tabletail{\hline}
\tablehead{\hline
{\bf Name} & {\bf $h$/mm} & {\bf $w$/mm} \\ \hline}
{\bf Name} & {\bf $h$/mm} & {\bf $w$/mm} \\ \hline
2a0 & 1681 & 1189 \\
4a0 & 2378 & 1681 \\
a0 & 1189 & 840 \\
a1 & 840 & 594 \\
a10 & 37 & 26 \\
a2 & 594 & 420 \\
a3 & 420 & 297 \\
a4 & 297 & 210 \\
a5 & 210 & 148 \\
a6 & 148 & 105 \\
a7 & 105 & 74 \\
a8 & 74 & 52 \\
a9 & 52 & 37 \\
b0 & 1414 & 999 \\
b1 & 999 & 707 \\
b10 & 44 & 31 \\
b2 & 707 & 499 \\
b3 & 499 & 353 \\
b4 & 353 & 249 \\
b5 & 249 & 176 \\
b6 & 176 & 124 \\
b7 & 124 & 88 \\
b8 & 88 & 62 \\
b9 & 62 & 44 \\
c0 & 1296 & 917 \\
c1 & 917 & 648 \\
c10 & 40 & 28 \\
c2 & 648 & 458 \\
c3 & 458 & 324 \\
c4 & 324 & 229 \\
c5 & 229 & 162 \\
c6 & 162 & 114 \\
c7 & 114 & 81 \\
c8 & 81 & 57 \\
c9 & 57 & 40 \\
crown & 508 & 381 \\
demy & 572 & 445 \\
double\_demy & 889 & 597\\
elephant & 711 & 584 \\
envelope\_dl & 110 & 220\\
executive & 267 & 184 \\
foolscap & 330 & 203\\
government\_ & 267 & 203\\
\hfill letter & & \\
international\_ & 85 & 53\\
\hfill businesscard & & \\
japanese\_b0 & 1435 & 1015\\
japanese\_b1 & 1015 & 717\\
japanese\_b10 & 44 & 31\\
japanese\_b2 & 717 & 507\\
japanese\_b3 & 507 & 358\\
japanese\_b4 & 358 & 253\\
japanese\_b5 & 253 & 179\\
japanese\_b6 & 179 & 126\\
japanese\_b7 & 126 & 89\\
japanese\_b8 & 89 & 63\\
japanese\_b9 & 63 & 44\\ \shrinkheight{5mm}
japanese\_kiku4 & 306 & 227\\
japanese\_kiku5 & 227 & 151\\
japanese\_shiroku4 & 379 & 264\\
japanese\_shiroku5 & 262 & 189\\
japanese\_shiroku6 & 188 & 127\\
large\_post & 533 & 419\\
ledger & 432 & 279 \\
legal & 356 & 216 \\
letter & 279 & 216 \\
medium & 584 & 457 \\
monarch & 267 & 184 \\
post & 489 & 394 \\
quad\_demy & 1143 & 889 \\
quarto & 254 & 203 \\
royal & 635 & 508 \\
statement & 216 & 140 \\
swedish\_d0 & 1542 & 1090 \\
swedish\_d1 & 1090 & 771 \\
swedish\_d10 & 48 & 34 \\
swedish\_d2 & 771 & 545 \\
swedish\_d3 & 545 & 385 \\
swedish\_d4 & 385 & 272 \\
swedish\_d5 & 272 & 192 \\
swedish\_d6 & 192 & 136 \\
swedish\_d7 & 136 & 96 \\
swedish\_d8 & 96 & 68 \\
swedish\_d9 & 68 & 48 \\
swedish\_e0 & 1241 & 878 \\
swedish\_e1 & 878 & 620 \\
swedish\_e10 & 38 & 27 \\
swedish\_e2 & 620 & 439 \\
swedish\_e3 & 439 & 310 \\
swedish\_e4 & 310 & 219 \\
swedish\_e5 & 219 & 155 \\
swedish\_e6 & 155 & 109 \\
swedish\_e7 & 109 & 77 \\
swedish\_e8 & 77 & 54 \\
swedish\_e9 & 54 & 38 \\
swedish\_f0 & 1476 & 1044 \\
swedish\_f1 & 1044 & 738 \\
swedish\_f10 & 46 & 32 \\
swedish\_f2 & 738 & 522 \\
swedish\_f3 & 522 & 369 \\ \shrinkheight{5mm}
swedish\_f4 & 369 & 261 \\
swedish\_f5 & 261 & 184 \\
swedish\_f6 & 184 & 130 \\
swedish\_f7 & 130 & 92 \\
swedish\_f8 & 92 & 65 \\
swedish\_f9 & 65 & 46 \\
swedish\_g0 & 1354 & 957 \\
swedish\_g1 & 957 & 677 \\
swedish\_g10 & 42 & 29 \\
swedish\_g2 & 677 & 478 \\
swedish\_g3 & 478 & 338 \\
swedish\_g4 & 338 & 239 \\
swedish\_g5 & 239 & 169 \\
swedish\_g6 & 169 & 119 \\
swedish\_g7 & 119 & 84 \\
swedish\_g8 & 84 & 59 \\
swedish\_g9 & 59 & 42 \\
swedish\_h0 & 1610 & 1138 \\
swedish\_h1 & 1138 & 805 \\
swedish\_h10 & 50 & 35 \\
swedish\_h2 & 805 & 569 \\
swedish\_h3 & 569 & 402 \\
swedish\_h4 & 402 & 284 \\
swedish\_h5 & 284 & 201 \\
swedish\_h6 & 201 & 142 \\
swedish\_h7 & 142 & 100 \\
swedish\_h8 & 100 & 71 \\
swedish\_h9 & 71 & 50 \\
tabloid & 432 & 279 \\
us\_businesscard & 89 & 51 \\
\end{supertabular}
}\onecolumn
pyxplot-0.8.1/doc/data.tex0000644000175000017500000011123311401470334014015 0ustar dcf21dcf21% DATA.TEX
%
% The documentation in this file is part of PyXPlot
%
%
% Copyright (C) 2006-2010 Dominic Ford
% 2008-2010 Ross Church
%
% $Id: data.tex 768 2010-05-15 20:26:07Z 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{Working with Data}
\label{ch:numerics}
In this chapter, we return to PyXPlot's commands for acting upon data stored in
files. First, we review some of the features which are common to all of the
commands which act upon \datafile s, and then we move on to introduce each
command in turn. We leave the {\tt plot} command, which was introduced in
Chapter~\ref{ch:first_steps}, to be described in more detail in
Chapter~\ref{ch:plotting}.
\section{Input Filters}
\label{sec:filters}
By default, PyXPlot expects \datafile s to be in a simple plaintext format
which is described in Section~\ref{sec:plot_datafiles}. Input filters provide a
mechanism by which \datafile s in arbitrary formats can be read into PyXPlot.
For each filter, a filename wildcard is supplied, and the filter is then applied to
all \datafile s whose filenames match this wildcard. For example, by default
PyXPlot has five input filters installed, as the {\tt show filters} command
reveals:
\begin{verbatim}
set filter "*.fits" "/usr/local/lib/pyxplot/pyxplot_fitshelper"
set filter "*.gz" "/bin/gunzip -c"
set filter "*.log" "/usr/local/lib/pyxplot/pyxplot_timehelper"
set filter "ftp://*" "/usr/bin/wget -O -"
set filter "http://*" "/usr/bin/wget -O -"
\end{verbatim}
Each filter takes the form of a program which is launched by PyXPlot whenever a
\datafile\ with matching filename is read. The program is passed the filename of
the \datafile\ as a command line argument immediately following any arguments
specified in the filter's definition. It is then expected to return the data
contained in the file to PyXPlot in plaintext format using its {\tt stdout}
stream. Any errors which such a program returns to {\tt stderr} are passed to
the user as error messages.
The above set of filters allows PyXPlot to read data from gzipped plaintext
\datafile s, data tables in FITS format\index{FITS format}, and from \datafile
s available over the web via HTTP\index{HTTP} or FTP\index{FTP}. Finally, a
filter is provided for converting textual dates in log files into numbers
representing days, months and years. To add to this list of filters, it is
necessary to write a short program or shell script, and the simple filters
provided in PyXPlot's source code for {\tt .log} and {.fits} files may provide
a useful model.
\section{Reading Data from a Pipe}
PyXPlot usually reads data from files, but it is also possible to read data
from pipes from other processes if these are directed to PyXPlot's standard
input stream. To do this, one uses the magic filename {\tt -}:
\begin{verbatim}
plot '-' with lines
\end{verbatim}
This makes it possible to call PyXPlot from within another program and pass it
data to plot without ever storing the data on disk. Whilst this facility has
great power, the authors would urge caution in this practice. Whilst it is
tempting to write programs which both perform calculations and plot the results
immediately, this can make it difficult to replot graphs later. A few months
after the event, when the need arises to replot the same data in a different
form or in a different style, remembering how to use a sizeable program can
prove tricky -- especially if the person struggling to do so is not you! But a
simple \datafile\ is quite straightforward to plot time and again.
\section{Including Data within Command Scripts}
It is also possible to embed data directly within PyXPlot scripts, which may be
useful when a small number of markers are wanted at particular pre-defined
positions on a graph, or when it is desirable to roll a PyXPlot script and the
data it takes into a single file for easy storage or transmission. To do this,
one uses the magic filename {\tt --} and terminates the data with the string
{\tt END}:
\begin{verbatim}
plot '--' with lines
0 0
1 1
2 0
3 1
END
print "More PyXPlot commands can be placed after END"
\end{verbatim}
\section{Special Comment Lines in Datafiles}
\label{sec:special_comments}
\index{comment lines!in datafiles}
Whilst most comment lines in \datafile s -- those lines which begin with a hash
character -- are ignored by PyXPlot, lines which begin with any of the
following four strings are parsed:
\begin{verbatim}
# Columns:
# ColumnUnits:
# Rows:
# RowUnits:
\end{verbatim}
The first pair of special comments affect the behaviour of PyXPlot when
plotting {\tt using columns}, while the second pair affect the behaviour of
PyXPlot when plotting {\tt using rows} (see
Section~\ref{sec:horizontal_datafiles}). Within each pair, the first may be
used to tell PyXPlot the names of each of the columns/rows in the \datafile,
while the second may be used to tell PyXPlot the physical units of the values
in each of the columns/rows. These special comments may appear multiple times
throughout a single \datafile\ to indicate changes to the format of the data.
For example, a \datafile\ prefixed with the lines
\begin{verbatim}
# Columns: Time Distance
# ColumnUnits: s 10*m
\end{verbatim}
contains two columns of data, the first containing times measured in seconds
and the second containing distances measured in tens of metres. Note that
because the entries on each of these lines are whitespace-separated, spaces are
not allowed in column names or within units such as {\tt 10*m}. This \datafile\
could be plotted using any of the following forms equivalently
\begin{verbatim}
plot 'data' using Time:Distance
plot 'data' using $Time:$Distance
plot 'data' using 1:2
\end{verbatim}
and the axes of the graph would indicate the units of the data (see
Section~\ref{sec:set_axisunitstyle}).
\section{Tabulating Functions and Slicing Data Files}
\label{sec:tabulate}
PyXPlot's \indcmdt{tabulate} is similar to its {\tt plot} command, but instead
of plotting a series of \datapoint s onto a graph, it writes them to \datafile
s. This can be used to produce text files containing samples of functions, to
rearrange/filter the columns in \datafile s, to change the units in which data
are expressed in \datafile s, and so forth. The following example would produce
a \datafile\ called {\tt gamma.dat} containing a list of values of the gamma
function:
\begin{verbatim}
set output 'gamma.dat'
tabulate [1:5] gamma(x)
\end{verbatim}
\noindent Multiple functions may be tabulated into the same file, either by
using the \indmodt{using} modifier, as in the example
\begin{verbatim}
tabulate [0:2*pi] sin(x):cos(x):tan(x) using 1:2:3:4
\end{verbatim}
\noindent or by placing them in a comma-separated list, as in the {\tt plot}
command:
\begin{verbatim}
tabulate [0:2*pi] sin(x), cos(x), tan(x)
\end{verbatim}
In the former case, the functions are tabulated horizontally alongside one
another in a series of columns. In the latter case, the functions are tabulated
one after another in a series of index blocks separated by double linefeeds
(see Section~\ref{sec:plot_datafiles}).
The {\tt samples} setting can be used to control the number of points that are
produced when tabulating functions, in the same way that it controls the {\tt
plot} command:\indcmd{set samples}
\begin{verbatim}
set samples 200
\end{verbatim}
\noindent If the abscissa axis is set to be logarithmic then the points at which
functions are evaluated are spaced logarithmically, otherwise they are spaced
linearly.
The \indmodt{select}, \indmodt{using} and \indmodt{every} modifiers operate in
the same manner in the {\tt tabulate} command as in the {\tt plot} command.
Thus the following example would write out the third, sixth and ninth columns
of the \datafile\ {\tt input.dat}, but only when the arcsine of the value in the
fourth column is positive:
\begin{verbatim}
set output 'filtered.dat'
tabulate 'input.dat' using 3:6:9 select (asin($4)>0)
\end{verbatim}
The numerical display format used in each column of the output file is chosen
automatically to preserve accuracy whilst simultaneously being as easily human
readable as possible. Thus, columns which contain only integers are displayed
as such, and scientific notation is only used in columns which contain very
large or very small values. If desired, however, a format statement may be
specified using the {\tt with format} specifier. The syntax for this is similar
to that expected by the string substitution operator ({\tt \%}; see
Section~\ref{sec:stringsubop}). As an example, to tabulate the values of $x^2$
to very many significant figures with some additional text, one could use:
\begin{verbatim}
tabulate x**2 with format "x = %f ; x**2 = %27.20e"
\end{verbatim}
\noindent This might produce the following output:
\begin{verbatim}
x = 0.000000 ; x**2 = 0.00000000000000000000e+00
x = 0.833333 ; x**2 = 6.94444444444442421371e-01
x = 1.666667 ; x**2 = 2.77777777777778167589e+00
\end{verbatim}
The data produced by the {\tt tabulate} command can be sorted in order of any
arbitrary metric by supplying an expression after the {\tt sortby} modifier;
where such expressions are supplied, the data are sorted in order from the
smallest value of the expression to the largest.
\section{Function Fitting}
\label{sec:fit_command}
The \indcmdt{fit} can be used to fit arbitrary functional forms to \datapoint s
read from files. It can be used to produce best-fit lines\index{best fit
lines}\footnote{Another way of producing best-fit lines is to use a cubic
spline; more details are given in Section~\ref{sec:spline_command}} for
datasets, or to determine gradients and other mathematical properties of data
by looking at the parameters associated with the best-fitting functional form.
The following simple example fits a straight line to data in a file called {\tt
data.dat}:
\begin{verbatim}
f(x) = a*x+b
fit f() 'data.dat' index 1 using 2:3 via a,b
\end{verbatim}
\noindent The first line specifies the functional form which is to be used.
The coefficients within this function, {\tt a} and {\tt b}, which are to be
varied during the fitting process, are listed after the keyword \indkeyt{via}
in the {\tt fit} command. The modifiers \indmodt{index}, \indmodt{every},
\indmodt{select} and \indmodt{using} have the same meanings in the {\tt fit}
command as in the {\tt plot} command. For example, given the following
\datafile, entitled {\tt square.dat}, which contains a sampled square wave, the
script below fits the first three terms of a truncated Fourier series to it:
\begin{verbatim}
0.314159 1
0.942478 1
1.570796 1
2.199115 1
2.827433 1
3.455752 -1
4.084070 -1
4.712389 -1
5.340708 -1
5.969026 -1
\end{verbatim}
\begin{verbatim}
f(x) = a1*sin(x) + a3*sin(3*x) + a5*sin(5*x)
fit f() 'square.dat' via a1, a3, a5
set xlabel '$x$' ; set ylabel '$y$'
plot 'square.dat' title 'data' with points pointsize 2, \
f(x) title 'Fitted function' with lines
\end{verbatim}
\begin{center}
\includegraphics[width=8cm]{examples/eps/ex_fitting}
\end{center}
As the \indcmdt{fit} works, it displays statistics including the best-fit
values of each of the fitting parameters, the uncertainties in each of them,
and the covariance matrix. These can be useful for analysing the security of
the fit achieved, but calculating the uncertainties in the best-fit parameters
and the covariance matrix can be time consuming, especially when many
parameters are being fitted simultaneously. The optional word {\tt
withouterrors} can be included immediately before the filename of the input
\datafile\ to substantially speed up cases where this information is not
required.
A few points are worth noting:
\begin{itemize}
\item When fitting a function of $n$ variables, at least $n+1$ columns (or
rows -- see Section~\ref{sec:horizontal_datafiles}) must be specified after the
{\tt using} modifier. By default, the first $n+1$ columns are used. These
correspond to the values of each of the $n$ inputs to the function, plus
finally the value which the output from the function is aiming to match.
\item If an additional column is specified, then this is taken to contain the
standard error in the value that the output from the function is aiming to
match, and can be used to weight the \datapoint s which are being used to
constrain the fit.
\item By default, the starting values for each of the fitting parameters is
$1.0$. However, if the variables to be used in the fitting process are already
set before the {\tt fit} command is called, these initial values are used
instead. For example, the following would use the initial values
$\{a=100,b=50\}$:
\begin{verbatim}
f(x) = a*x+b
a = 100
b = 50
fit f() 'data.dat' index 1 using 2:3 via a,b
\end{verbatim}
\item As with all numerical fitting procedures, the {\tt fit} command comes
with caveats. It uses a generic fitting algorithm, and may not work well with
poorly behaved or ill-constrained problems. It works best when all of the
values it is attempting to fit are of order unity. For example, in a problem
where $a$ was of order $10^{10}$, the following might fail:
\begin{verbatim}
f(x) = a*x
fit f() 'data.dat' via a
\end{verbatim}
However, better results might be achieved if $a$ were artificially made of
order unity, as in the following script:
\begin{verbatim}
f(x) = 1e10*a*x
fit f() 'data.dat' via a
\end{verbatim}
\item A series of ranges may be specified after the {\tt fit} command, using
the same syntax as in the {\tt plot} command, as described in
Section~\ref{sec:plot_ranges}. If ranges are specified then only \datapoint s
falling within these ranges are used in the fitting process; the ranges refer
to each of the $n$ variables of the fitted function in order:
\begin{verbatim}
fit [0:10] f() 'data.dat' via a
\end{verbatim}
\item For those interested in the mathematical details, the workings of the
{\tt fit} command are discussed in more detail in Appendix~\ref{ch:fit_maths}.
\end{itemize}
\section{Datafile Interpolation}
\label{sec:spline_command}
\index{best fit lines}
The \indcmdt{interpolate} can be used to generate a special function within
PyXPlot's mathematical environment which interpolates a set of \datapoint s
supplied from a \datafile. Various different types of interpolation are
supported: linear interpolation, power-law interpolation\footnote{Power-law
interpolation is equivalent to linear interpolation in log-log space.},
polynomial interpolation, cubic-spline interpolation and akima-spline
interpolation. The use of polynomial interpolation with large datasets is
strongly discouraged, as polynomial fits tend to show severe oscillations
between \datapoint s. Extrapolation is not permitted; if an attempt is made to
evaluate an interpolated function beyond the limits of the \datapoint s which
it interpolates, PyXPlot returns an error or value of not-a-number.
The \indcmdt{interpolate} has similar syntax to the \indcmdt{fit}:
\begin{verbatim}
interpolate ( akima | linear | loglinear | polynomial | spline )
[] "()"
''
[ every {: ]
[ select ]
[ using {:\nicefrac{1}{2}\end{array}\right. ,
\end{displaymath}
the Fourier transform $F(\omega)$ of $f(x)$ is
\begin{eqnarray*}
F(\omega) & = & \int_0^\infty f(x) \exp \left(-2\pi ix\omega\right) \,\mathrm{d}x
= \int_{-\nicefrac{1}{2}}^{\nicefrac{1}{2}} \exp\left(-2\pi ix\omega\right) \,\mathrm{d}x
\\ & = & \frac{1}{2\pi\omega}\left[ \exp\left(\pi i\omega\right) - \exp\left(-\pi i\omega\right) \right]
= \frac{\sin(\pi\omega)}{\pi\omega}
= \sinc(\pi\omega).
\end{eqnarray*}
\nlnp
In this example, we demonstrate this numerically by taking the Fourier
transform of such a step function, and comparing the result against the
function {\tt sinc(x)} which is pre-defined within PyXPlot:
\nlscf
\noindent{\tt set numerics complex}\newline
\noindent{\tt step(x) = tophat(x,0.5)}\newline
\noindent{\tt fft [-1:1:0.01] f() of step()}\newline
\noindent{\tt plot [-10:10] Re(f(x)), sinc(pi*x)}
\nlscf
Note that the function {\tt Re(x)} is needed in the {\tt plot} statement here,
since although the Fourier transform of a symmetric function is in theory real,
in practice any numerical Fourier transform will yield a small imaginary
component at the level of the accuracy of the numerical method used. Although
the calculated numerical Fourier transform is defined throughout the range
$-50\leq x<50$, discretised with steps of size $\Updelta x=0.5$, we only plot
the central region in order to show clearly the stepping of the function:
\nlscf
\begin{center}
\includegraphics{examples/eps/ex_fft}
\end{center}
\nlscf
In the following steps, we take the square of the function $\sinc(\pi x)$ just
calculated, and then plot the numerical inverse Fourier transform of the
result:
\nlscf
\noindent{\tt g(x) = f(x)**2}\newline
\noindent{\tt ifft [-50:49.5:0.5] h(x) of g(x)}\newline
\noindent{\tt plot [-2:2] Re(h(x))}
\nlscf
\begin{center}
\includegraphics{examples/eps/ex_fft2}
\end{center}
\nlscf
As can be seen, the result is a triangle function. This is the result which
would be expected from the convolution theorem, which states that when the
Fourier transforms of two functions are multiplied together and then inverse
transformed, the result is the convolution of the two original functions. The
convolution of a top-hat function with itself is, indeed, a triangle function.
}
\subsection{Window Functions}
\index{window functions}
A range of commonly-used window functions may automatically be applied to data
as it is read into the {\tt fft} and {\tt ifft} commands; these are listed
together with their algebraic forms in Table~\ref{tab:windowfuncs} and shown in
Figure~\ref{fig:windowfuncs}. In each case, the window functions are given for
sample number $n$, which ranges between $0$ and $N_x$. The window functions may
be invoked using the following syntax:
\begin{verbatim}
fft [...] () of () window
\end{verbatim}
\noindent Where multi-dimensional FFTs are performed, window functions are
applied to each dimension in turn. Other arbitrary window functions may be
implemented by pre-multiplying data before entry to the {\tt fft} and {\tt
ifft} commands.
\begin{table}
\newlength{\wfgap}
\setlength{\wfgap}{30pt}
\begin{center}
\begin{tabular}{|>{\columncolor{LightGrey}}l>{\columncolor{LightGrey}}l|}
\hline
{\bf Window Name} & {\bf Algebraic Definition} \\
\hline
Bartlett & $\displaystyle w(n) = \left( \frac{2}{N_x-1} \right) \left( \frac{N_x-1}{2} - \left| n - \frac{N_x-1}{2} \right| \right)$ \vphantom{\rule{0pt}{20pt}}\\
BartlettHann & $\displaystyle w(n) = a_0 - a_1\left|\frac{n}{N_x-1}-\frac{1}{2}\right| - a_2\cos\left(\frac{2\pi n}{N_x-1}\right),\;\textrm{for}$ \vphantom{\rule{0pt}{\wfgap}}\\
& $a_0=0.62,\; a_1=0.48,\; a_2=0.38.$ \vphantom{\rule{0pt}{20pt}}\\
Cosine & $\displaystyle w(n) = \cos\left(\frac{\pi n}{N_x-1} - \frac{\pi}{2} \right)$ \vphantom{\rule{0pt}{\wfgap}}\\
Gauss & $\displaystyle w(n) = \exp \left\{ -\frac{1}{2}\left[ \frac{n-(N_x-1)/2}{\sigma(N_x-1)/2} \right]^2 \right\},\;\textrm{for}\;\sigma=0.5$ \vphantom{\rule{0pt}{\wfgap}}\\
Hamming & $\displaystyle w(n) = 0.54 - 0.46\cos\left(\frac{2\pi n}{N_x-1}\right)$ \vphantom{\rule{0pt}{\wfgap}}\\
Hann & $\displaystyle w(n) = 0.5 \left[ 1 - \cos\left(\frac{2\pi n}{N_x-1}\right) \right]$ \vphantom{\rule{0pt}{\wfgap}}\\
Lanczos & $\displaystyle w(n) = \mathrm{sinc}\left( \frac{2n}{N_x-1} - 1 \right)$ \vphantom{\rule{0pt}{\wfgap}}\\
Rectangular & $\displaystyle w(n) = 1$ \vphantom{\rule{0pt}{\wfgap}}\\
Triangular & $\displaystyle w(n) = \left( \frac{2}{N_x} \right) \left( \frac{N_x}{2} - \left| n - \frac{N_x-1}{2} \right| \right)$ \vphantom{\rule{0pt}{\wfgap}}\\
\hline
\end{tabular}
\end{center}
\caption{Window functions available in the {\tt fft} and {\tt ifft} commands.}
\label{tab:windowfuncs}
\end{table}
\begin{figure}
\begin{center}
\includegraphics{examples/eps/ex_windowfuncs}
\end{center}
\caption{Window functions available in the {\tt fft} and {\tt ifft} commands.}
\label{fig:windowfuncs}
\end{figure}
\section{Histograms}
\label{sec:histogram}
The \indcmdt{histogram} takes a single column of data from a file and produces
a function that represents the frequency distribution of the supplied data
values. The output function consists of a series of discrete intervals which we
term {\it bins}. Within each interval the output function has a constant value,
determined such that the area under each interval -- i.e.\ the integral of the
function over each interval -- is equal to the number of datapoints found
within that interval. The following simple example
\begin{verbatim}
histogram f() 'input.dat'
\end{verbatim}
\noindent produces a frequency distribution of the data values found in the
first column of the file {\tt input.dat}, which it stores in the function
$f(x)$. The value of this function at any given point is equal to the number of
items in the bin at that point, divided by the width of the bins used. If the
input datapoints are not dimensionless then the output frequency distribution
adopts appropriate units, thus a histogram of data with units of length has
units of one over length.
The number and arrangement of bins used by the \indcmdt{histogram} can be
controlled by means of various modifiers. The \indmodt{binwidth} modifier sets
the width of the bins used. The \indmodt{binorigin} modifier controls where
their boundaries lie; the \indcmdt{histogram} selects a system of bins which,
if extended to infinity in both directions, would put a bin boundary at the
value specified in the {\tt binorigin} modifier. Thus, if {\tt binorigin 0.1}
were specified, together with a bin width of~20, bin boundaries might lie
at~$20.1$, $40.1$, $60.1$, and so on. Alternatively global defaults for the bin
width and the bin origin can be specified using the {\tt set binwidth} and {\tt
set binorigin} commands respectively. The example
\begin{verbatim}
histogram h() 'input.dat' binorigin 0.5 binwidth 2
\end{verbatim}
\noindent would bin data into bins between $0.5$ and $2.5$, between $2.5$ and
$4.5$, and so forth.
Alternatively the set of bins to be used can be controlled more precisely using
the \indmodt{bins} modifier, which allows an arbitrary set of bins to be
specified. The example
\begin{verbatim}
histogram g() 'input.dat' bins (1, 2, 4)
\end{verbatim}
\noindent would bin the data into two bins, $x=1\to 2$ and $x=2\to 4$.
A range can be supplied immediately following the {\tt histogram} command,
using the same syntax as in the {\tt plot} and {\tt fit} commands; if such a
range is supplied, only points that fall within that range will be binned. In
the same way as in the {\tt plot} command, the \indmodt{index},
\indmodt{every}, \indmodt{using} and \indmodt{select} modifiers can be used to
specify which subsets of a \datafile\ should be used.
Two points about the {\tt histogram} command are worthy of note. First,
although histograms are similar to bar charts, they are not the same. A bar
chart conventionally has the height of each bar equal to the number of points
that it represents, whereas a histogram is a continuous function in which the
area underneath each interval is equal to the number of points within it.
Thus, to produce a bar chart using the {\tt histogram} command, the end result
should be multiplied by the bin width used.
Second, if the function produced by the {\tt histogram} command is plotted
using the {\tt plot} command, samples are automatically taken not at evenly
spaced intervals along the abscissa axis, but at the centres of each bin. If
the \indpst{boxes} plot style is used, the box boundaries are conveniently
drawn to coincide with the bins into which the data were sorted.
\section{Random Data Generation}
PyXPlot has a range of mathematical functions which draw random samples from a
variety of probability distibutions. These are:
\begin{itemize}
\item {\tt random()} -- returns a random real number between 0 and~1.
\indfun{random()}
\item {\tt random\_binomial($p,n$)} -- returns a random sample from a binomial distribution with $n$ independent trials and a success probability $p$.
\indfun{random\_\-binomial($p,n$)}
\item {\tt random\_chisq($\nu$)} -- returns a random sample from a $\chi$-squared distribution with $\nu$ degrees of freedom.
\indfun{random\_\-chisq($\nu$)}
\item {\tt random\_gaussian($\sigma$)} -- returns a random sample from a Gaussian (normal) distribution of standard deviation $\sigma$ and centred upon zero.
\indfun{random\_\-gaussian($\sigma$)}
\item {\tt random\_lognormal($\zeta,\sigma$)} -- returns a random sample from the log normal distribution centred on $\zeta$, and of width $\sigma$.
\indfun{random\_\-lognormal($\zeta,\sigma$)}
\item {\tt random\_poisson($n$)} -- returns a random integer from a Poisson distribution with mean $n$.
\indfun{random\_\-poisson($n$)}
\item {\tt random\_tdist($\nu$)} -- returns a random sample from a $t$-distribution with $\nu$ degrees of freedom.
\indfun{random\_\-tdist($\nu$)}
\end{itemize}
\noindent These functions all rely upon a common underlying random number
generator, whose seed may be set using the \indcmdt{set seed}, which should be
followed by any integer.
\example{ex:random}{Using random numbers to estimate the value of $\pi$}{
PyXPlot's functions for generating random numbers are most commonly used for
adding noise to artificially-generated data. In this example, however, we use
them to implement a rather inefficient algorithm for estimating the value of
the mathematical constant $\pi$. The algorithm works by spreading
randomly-placed samples in the square $\left\{ -1
%
% Copyright (C) 2006-2010 Dominic Ford
% 2008-2010 Ross Church
%
% $Id: functions.tex 809 2010-05-21 15:28:01Z 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{List of Mathematical Functions}
\label{ch:function_list}
The following is a complete list of the mathematical functions which are defined by default within PyXPlot.
\newcommand{\funcdef}[2]{
\vspace{5mm}
\begin{samepage}
\noindent
{\large \bf #1}
\newline
\indfun{#1}
The #1 function #2
\end{samepage}
}
\funcdef{abs($z$)}{returns the absolute magnitude of $z$, where $z$ may be any general complex number. The output shares the physical dimensions of $z$, if any.}
\funcdef{acos($z$)}{returns the arccosine of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{acosh($z$)}{returns the hyperbolic arccosine of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{acot($z$)}{returns the arccotangent of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{acoth($z$)}{returns the hyperbolic arccotangent of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{acsc($z$)}{returns the arccosecant of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{acsch($z$)}{returns the hyperbolic arccosecant of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{airy\_\-ai($z$)}{returns the Airy function Ai evaluated at $z$, where $z$ may be any dimensionless complex number.}
\funcdef{airy\_\-ai\_\-diff($z$)}{returns the first derivative of the Airy function Ai evaluated at $z$, where $z$ may be any dimensionless complex number.}
\funcdef{airy\_\-bi($z$)}{returns the Airy function Bi evaluated at $z$, where $z$ may be any dimensionless complex number.}
\funcdef{airy\_\-bi\_\-diff($z$)}{returns the first derivative of the Airy function Bi evaluated at $z$, where $z$ may be any dimensionless complex number.}
\funcdef{arg($z$)}{returns the argument of the complex number $z$, which may have any physical dimensions. The output has physical dimensions of angle.}
\funcdef{asec($z$)}{returns the arcsecant of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{asech($z$)}{returns the hyperbolic arcsecant of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{asin($z$)}{returns the arcsine of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{asinh($z$)}{returns the hyperbolic arcsine of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{ast\_\-Lcdm\_\-age($H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the current age of the Universe in a standard $\Uplambda_\mathrm{CDM}$ cosmology with specified values for Hubble's constant, $\Omega_\mathrm{M}$ and $\Omega_\Uplambda$. Hubble's constant should be specified either with physical units of recession velocity per unit distance, or as a dimensionless number, assumed to have implicit units of km/s/Mpc. Suitable input values for a standard cosmology are: $H_0=70$, $\Omega_\mathrm{M}=0.27$ and $\Omega_\Uplambda=0.73$. For more details, see David W.\ Hogg's short article {\it Distance measures in cosmology}, available online at:\newline\url{http://arxiv.org/abs/astro-ph/9905116}.}
\funcdef{ast\_\-Lcdm\_\-angscale($z$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the angular scale of the sky at a redshift of $z$ in a standard $\Uplambda_\mathrm{CDM}$ cosmology. For details, see the {\tt ast\_Lcdm\_age()} function above. The returned value has dimensions of distance per unit angle.}
\funcdef{ast\_\-Lcdm\_\-DA($z$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the angular size distance of objects at a redshift of $z$ in a standard $\Uplambda_\mathrm{CDM}$ cosmology. For details, see the {\tt ast\_Lcdm\_age()} function above. The returned value has dimensions of distance.}
\funcdef{ast\_\-Lcdm\_\-DL($z$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the luminosity distance of objects at a redshift of $z$ in a standard $\Uplambda_\mathrm{CDM}$ cosmology. For details, see the {\tt ast\_Lcdm\_age()} function above. The returned value has dimensions of distance.}
\funcdef{ast\_\-Lcdm\_\-DM($z$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the proper motion distance of objects at a redshift of $z$ in a standard $\Uplambda_\mathrm{CDM}$ cosmology. For details, see the {\tt ast\_Lcdm\_age()} function above. The returned value has dimensions of distance.}
\funcdef{ast\_\-Lcdm\_\-t($z$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the lookback time to objects at a redshift of $z$ in a standard $\Uplambda_\mathrm{CDM}$ cosmology. For details, see the {\tt ast\_Lcdm\_age()} function above. The returned value has dimensions of time. To find the age of the Universe at a redshift of $z$, this value should be subtracted from the output of the {\tt ast\_Lcdm\_age()} function.}
\funcdef{ast\_\-Lcdm\_\-z($t$,\-$H_0$,\-$\Omega_\mathrm{M}$,\-$\Omega_\Uplambda$)}{is a specialist cosmology function. It returns the redshift corresponding to a lookback time of $t$ in a standard $\Uplambda_\mathrm{CDM}$ cosmology. For details, see the {\tt ast\_Lcdm\_age()} function above. The returned value is dimensionless.}
\funcdef{ast\_\-moonphase($JD$)}{returns the phase of the Moon, with dimensions of angle, at the time corresponding to the supplied Julian Day number.}
\funcdef{ast\_\-sidereal\_\-time($JD$)}{returns the sidereal time at Greenwich, with dimensions of angle, at the time corresponding to the supplied Julian Day number. This is equal to the right ascension of the stars which are transiting the Greenwich meridian at that time. This function uses the expression for sidereal time adopted in 1982 by the International Astronomical Union (IAU), and which is reproduced in Chapter~12 of Jean Meeus' book {\it Astronomical Algorithms} (1998).}
\funcdef{atan($z$)}{returns the arctangent of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{atanh($z$)}{returns the hyperbolic arctangent of $z$, where $z$ may be any general dimensionless complex number. The output has physical dimensions of angle.}
\funcdef{atan2($x,y$)}{returns the arctangent of $x/y$. Unlike atan($y/x$), atan2($x,y$) takes account of the signs of both $x$ and $y$ to remove the degeneracy between $(1,1)$ and $(-1,-1)$. $x$ and $y$ must be real numbers, and must have matching physical dimensions.}
\funcdef{besseli($l,x$)}{evaluates the $l$th regular modified spherical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{besselI($l,x$)}{evaluates the $l$th regular modified cylindrical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{besselj($l,x$)}{evaluates the $l$th regular spherical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{besselJ($l,x$)}{evaluates the $l$th regular cylindrical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{besselk($l,x$)}{evaluates the $l$th irregular modified spherical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{besselK($l,x$)}{evaluates the $l$th irregular modified cylindrical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{bessely($l,x$)}{evaluates the $l$th irregular spherical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{besselY($l,x$)}{evaluates the $l$th irregular cylindrical Bessel function at $x$. $l$ must be a positive dimensionless real integer. $x$ must be a real dimensionless number.}
\funcdef{beta($a,b$)}{evaluates the beta function $B(a,b)$, where $a$ and $b$ must be dimensionless real numbers.}
\funcdef{binomialCDF($k,p,n$)}{evaulates the probability of getting fewer than or exactly $k$ successes out of $n$ trials in a binomial distribution with success probability $p$. $k$ and $n$ must be positive real integers. $p$ must be a real number in the range $0\leq p \leq 1$.}
\funcdef{binomialPDF($k,p,n$)}{evaulates the probability of getting $k$ successes out of $n$ trials in a binomial distribution with success probability $p$. $k$ and $n$ must be positive real integers. $p$ must be a real number in the range $0\leq p \leq 1$.}
\funcdef{Bv($\nu,T$)}{returns the power emitted by a blackbody of temperature $T$ at frequency $\nu$ per unit area, per unit solid angle, per unit frequency. $T$ should have physical dimensions of temperature, or be a dimensionless number, in which case it is understood to be a temperature in Kelvin. $\nu$ should have physical dimensions of frequency, or be a dimensionless number, in which case it is understood to be a frequency measured in Hertz. The output has physical dimensions of power per unit area per unit solid angle per unit frequency.}
\funcdef{Bvmax($T$)}{returns the frequency at which the function Bv($\nu,T$) reaches its maximum, as calculated by the Wien Displacement Law. The inputs are subject to the same constraints as above.}
\funcdef{ceil($x$)}{returns the smallest integer value greater than or equal to $x$, where $x$ must be a dimensionless real number.}
\funcdef{chisqCDF($x,nu$)}{returns the cumulative probability density at $x$ in a $\chi$-squared distribution with $\nu$ degrees of freedom. $\nu$ must be a positive real dimensionless integer. $x$ must be a positive real dimensionless number.}
\funcdef{chisqCDFi($P,nu$)}{returns the point $x$ at which the cumulative probability density in a $\chi$-squared distribution with $\nu$ degrees of freedom is $P$. $\nu$ must be a positive real dimensionless integer. $P$ must be a real number in the range $0\leq p \leq 1$.}
\funcdef{chisqPDF($x,nu$)}{returns the probability density at $x$ in a $\chi$-squared distribution with $\nu$ degrees of freedom. $\nu$ must be a positive real dimensionless integer. $x$ must be a positive real dimensionless number.}
\funcdef{conditionalN($a,b,c$)}{returns either $b$, if $a$ is true, or $c$ otherwise. Arguments $b$ and $c$ may be complex and may have any physical dimensions, but may not be strings. Argument $a$ must be a dimensionless real number.}
\funcdef{conditionalS($a,b,c$)}{returns either $b$, if $a$ is true, or $c$ otherwise. Arguments $b$ and $c$ should be string variables or expressions. Argument $a$ must be a dimensionless real number.}
\funcdef{conjugate($z$)}{returns the complex conjugate of the complex number $z$, which may have any physical dimensions.}
\funcdef{cos($z$)}{returns the cosine of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{cosh($z$)}{returns the hyperbolic cosine of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{cot($z$)}{returns the cotangent of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{coth($z$)}{returns the hyperbolic cotangent of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{csc($z$)}{returns the cosecant of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{csch($z$)}{returns the hyperbolic cosecant of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{degrees($x$)}{takes a real input which should either have physical units of angle, or be dimensionless, in which case it is assumed to be measured in radians. The output is the dimensionless number of degrees in $x$.}
\funcdef{diff\_dx($e,x,step$)}{numerically differentiates an expression $e$ with respect to $a$ at $x$, using a step size of $step$. `{\tt x}' can be replaced by any variable name of fewer than 16 characters, and so, for example, the {\tt diff\_dfoobar()} function differentiates an expression with respect to the variable {\tt foobar}. The expression $e$ may optionally be enclosed in quotes. Both $x$, and the output differential, may be complex numbers with any physical unit. The step size may optionally be omitted, in which case a value of $10^{-6}$ is used. The following example would differentiate the expression $x^2$ with respect to $x$:\newline{\tt print diff\_dx("x**2", 1, 1e-6)}.}
\funcdef{ellipticintE($k$)}{evaluates the following complete elliptic integral: \begin{displaymath} E(k) = \int_0^1 \sqrt{\frac{1-k^2 t^2}{1-t^2}}\,\mathrm{d}t. \end{displaymath} }
\funcdef{ellipticintK($k$)}{evaluates the following complete elliptic integral: \begin{displaymath} K(k) = \int_0^1 \frac{\mathrm{d}t}{\sqrt{(1-t^2)(1-k^2 t^2)}}. \end{displaymath} }
\funcdef{ellipticintP($k,n$)}{evaluates the following complete elliptic integral: \begin{displaymath} P(k,n) = \int_0^{\nicefrac{\pi}{2}} \frac{\mathrm{d}\theta}{(1+n\sin^2\theta)(1-k^2\sin^2\theta)}.\end{displaymath} }
\funcdef{erf($x$)}{evaluates the error function at $x$, where $x$ must be a dimensionless real number.}
\funcdef{erfc($x$)}{evaluates the complementary error function at $x$, where $x$ must be a dimensionless real number.}
\funcdef{exp($z$)}{returns $e^z$, where $z$ can be a complex number but must either be dimensionless or be an angle.}
\funcdef{expint($n,x$)}{evaluates the following integral: \begin{displaymath} \int_{t=1}^{t=\infty} \exp(-xt)/t^n \, \mathrm{d}t. \end{displaymath} $n$ must be a positive real dimensionless integer and $x$ must be a real dimensionless number.}
\funcdef{expm1($x$)}{accurately evaluates $\exp(x)-1$, where $x$ must be a dimensionless real number.}
\funcdef{floor($x$)}{returns the largest integer value smaller than or equal to $x$, where $x$ must be a dimensionless real number.}
\funcdef{gamma($x$)}{evaluates the gamma function $\Gamma(x)$, where $x$ must be a dimensionless real number.}
\funcdef{gaussianCDF($x,\sigma$)}{evaluates the Gaussian cumulative distribution function of standard deviation $\sigma$ at $x$. The distribution is centred upon $x=0$. $x$ and $\sigma$ must both be real, but may have any physical dimensions so long as they match.}
\funcdef{gaussianCDFi($x,\sigma$)}{evaluates the inverse Gaussian cumulative distribution function of standard deviation $\sigma$ at $x$. The distribution is centred upon $x=0$. $x$ and $\sigma$ must both be real, but may have any physical dimensions so long as they match.}
\funcdef{gaussianPDF($x,\sigma$)}{evaluates the Gaussian probability density function of standard deviation $\sigma$ at $x$. The distribution is centred upon $x=0$. $x$ and $\sigma$ must both be real, but may have any physical dimensions so long as they match.}
\funcdef{heaviside($x$)}{returns the Heaviside function, defined to be one for $x\geq0$ and zero otherwise. $x$ must be a dimensionless real number.}
\funcdef{hyperg\_0F1($c,x$)}{evaluates the hypergeometric function $_0F_1(c,x)$. All inputs must be dimensionless real numbers. For reference, the implementation used is GSL's {\tt gsl\_sf\_hyperg\_0F1} function.}
\funcdef{hyperg\_1F1($a,b,x$)}{evaluates the hypergeometric function $_1F_1(a,b,x)$. All inputs must be dimensionless real numbers. For reference, the implementation used is GSL's {\tt gsl\_sf\_hyperg\_1F1} function.}
\funcdef{hyperg\_2F0($a,b,x$)}{evaluates the hypergeometric function $_2F_0(a,b,x)$. All inputs must be dimensionless real numbers.For reference, the implementation used is GSL's {\tt gsl\_sf\_hyperg\_2F0} function.}
\funcdef{hyperg\_2F1($a,b,x$)}{evaluates the hypergeometric function $_2F_1(a,b,x)$. All inputs must be dimensionless real numbers. For reference, the implementation used is GSL's {\tt gsl\_sf\_hyperg\_2F1} function. This implementation cannot evaluate the region $|x|<1$.}
\funcdef{hyperg\_U($a,b,x$)}{evaluates the hypergeometric function $U(a,b,x)$. All inputs must be dimensionless real numbers. For reference, the implementation used is GSL's {\tt gsl\_sf\_hyperg\_U} function.}
\funcdef{hypot($x,y$)}{returns the quadrature sum of $x$ and $y$, $\sqrt{x^2+y^2}$, where $x$ and $y$ may have any physical dimensions so long as they match, and can be complex numbers.}
\funcdef{Im($z$)}{returns the imaginary part of the complex number $z$, which may have any physical units. The number returned shares the same physical units as $z$.}
\funcdef{int\_dx($e,min,max$)}{numerically integrates an expression $e$ with respect to $x$ between $min$ and $max$. `{\tt x}' can be replaced by any variable name of fewer than 16 characters, and so, for example, the {\tt int\_dfoobar()} function integrates an expression with respect to the variable {\tt foobar}. The expression $e$ may optionally be enclosed in quotes. $min$ and $max$ may have any physical units, so long as they match, but must be real numbers. The output integral may be a complex number, and may have any physical dimensions. The following example would integrate the expression $x^2$ with respect to $x$ between $1$\,m and $2$\,m:\newline{\tt print int\_dx("x**2", 1*unit(m), 2*unit(m))}.}
\funcdef{jacobi\_cn($u,m$)}{evaluates a Jacobi elliptic function; it returns the value $\cos\phi$ where $\phi$ is defined by the integral \begin{displaymath} \int_{0}^{\phi}\frac{\mathrm{d}\theta}{\sqrt{1-m\sin^2\theta}}.\end{displaymath}}
\funcdef{jacobi\_dn($u,m$)}{evaluates a Jacobi elliptic function; it returns the value $\sqrt{1-m\sin^2\theta}$ where $\phi$ is defined by the integral \begin{displaymath} \int_{0}^{\phi}\frac{\mathrm{d}\theta}{\sqrt{1-m\sin^2\theta}}.\end{displaymath}}
\funcdef{jacobi\_sn($u,m$)}{evaluates a Jacobi elliptic function; it returns the value $\sin\phi$ where $\phi$ is defined by the integral \begin{displaymath} \int_{0}^{\phi}\frac{\mathrm{d}\theta}{\sqrt{1-m\sin^2\theta}}.\end{displaymath}}
\funcdef{lambert\_W0($x$)}{evaluates the principal real branch of the Lambert~W function, for which $W>-1$ when $x<0$.}
\funcdef{lambert\_W1($x$)}{evaluates the secondary real branch of the Lambert~W function, for which $W<-1$ when $x<0$.}
\funcdef{ldexp($x,y$)}{returns $x$ times $2^y$ for integer y, where both $x$ and $y$ must be real.}
\funcdef{legendreP($l,x$)}{evaluates the $l$th Legendre polynomial at $x$, where $l$ must be a positive dimensionless real integer and $x$ must be a real dimensionless number.}
\funcdef{legendreQ($l,x$)}{evaluates the $l$th Legendre function at $x$, where $l$ must be a positive dimensionless real integer and $x$ must be a real dimensionless number.}
\funcdef{log($z$)}{returns the natural logarithm of $z$, where $z$ may be any complex dimensionless number.}
\funcdef{log10($z$)}{returns the logarithm to base~10 of $z$, where $z$ may be any complex dimensionless number.}
\funcdef{lognormalCDF($x,\zeta,\sigma$)}{evaluates the log normal cumulative distribution function of standard deviation $\sigma$, centred upon $\zeta$, at $x$. $\sigma$ must be real, positive and dimenionless. $x$ and $\zeta$ must both be real, but may have any physical dimensions so long as they match.}
\funcdef{lognormalCDFi($x,\zeta,\sigma$)}{evaluates the inverse log normal cumulative distribution function of standard deviation $\sigma$, centred upon $\zeta$, at $x$. $\sigma$ must be real, positive and dimenionless. $x$ and $\zeta$ must both be real, but may have any physical dimensions so long as they match.}
\funcdef{lognormalPDF($x,\zeta,\sigma$)}{evaluates the log normal probability density function of standard deviation $\sigma$, centred upon $\zeta$, at $x$. $\sigma$ must be real, positive and dimenionless. $x$ and $\zeta$ must both be real, but may have any physical dimensions so long as they match.}
\funcdef{max($x,y$)}{returns the greater of the two values $x$ and $y$, where $x$ and $y$ may have any physical dimensions so long as they match. If either input is complex, the input with the larger magnitude is returned.}
\funcdef{min($x,y$)}{returns the lesser of the two values $x$ and $y$, where $x$ and $y$ may have any physical dimensions so long as they match. If either input is complex, the input with the smaller magnitude is returned.}
\funcdef{mod($x,y$)}{returns the remainder of $x/y$, where $x$ and $y$ may have any physical dimensions so long as they match but must both be real.}
\funcdef{ordinal($x$)}{returns an ordinal string, for example, ``1st'', ``2nd'' or ``3rd'', for any positive dimensionless real number $x$.}
\funcdef{poissonCDF($x,\mu$)}{returns the probability of getting $\leq x$ from a Poisson distribution with mean $\mu$, where $\mu$ must be real, positive and dimensionless and $x$ must be real and dimensionless.}
\funcdef{poissonPDF($x,\mu$)}{returns the probability of getting $x$ from a Poisson distribution with mean $\mu$, where $\mu$ must be real, positive and dimensionless and $x$ must be a real dimensionless integer.}
\funcdef{pow($x,y$)}{returns $x$ to the power of $y$, where $x$ and $y$ may both be complex numbers and $x$ may have any physical dimensions but $y$ must be dimensionless. It not not permitted for $y$ to be complex if $x$ is not dimensionless, since this would lead to an output with complex physical dimensions.}
\funcdef{radians($x$)}{takes a real input which should either have physical units of angle, or be dimensionless, in which case it is assumed to be measured in degrees. The output is the dimensionless number of radians in $x$.}
\funcdef{random()}{returns a random real number between 0 and~1.}
\funcdef{random\_\-binomial($p,n$)}{returns a random sample from a binomial distribution with $n$ independent trials and a success probability $p$. $n$ must be a real positive dimensionless integer. $p$ must be a dimensionless number in the range $0\leq p\leq 1$.}
\funcdef{random\_\-chisq($\nu$)}{returns a random sample from a $\chi$-squared distribution with $\nu$ degrees of freedom, where $\nu$ must be a real positive dimensionless integer.}
\funcdef{random\_\-gaussian($\sigma$)}{returns a random sample from a Gaussian (normal) distribution of standard deviation $\sigma$ and centred upon zero. $\sigma$ must be real, but may have any physical units. The returned random sample shares the physical units of $\sigma$.}
\funcdef{random\_\-lognormal($\zeta,\sigma$)}{returns a random sample from the log normal distribution centred on $\zeta$, and of width $\sigma$. $\sigma$ must be a real positive dimensionless number. $\zeta$ must be real, but may have any physical units. The returned random sample shares the physical units of $\zeta$.}
\funcdef{random\_\-poisson($n$)}{returns a random integer from a Poisson distribution with mean $n$, where $n$ must be a real positive dimensionless number.}
\funcdef{random\_\-tdist($\nu$)}{returns a random sample from a $t$-distribution with $\nu$ degrees of freedom, where $\nu$ must be a real positive dimensionless integer.}
\funcdef{Re($z$)}{returns the real part of the complex number $z$, which may have any physical units. The number returned shares the same physical units as $z$.}
\funcdef{root($z,n$)}{returns the $n$th root of $z$. $z$ may be any complex number, and may have any physical dimensions. $n$ must be a dimensionless integer. When complex arithmetic is enabled, and whenever $z$ is positive, this function is entirely equivalent to {\tt pow(z,1/n)}. However, when $z$ is negative and complex arithmetic is disabled, the expression {\tt pow(z,1/n)} may not be evaluated, since it will in general have a small imaginary part for any finite-precision floating-point representation of $1/n$. The expression {\tt root(z,n)}, on the other hand, may be evaluated under such conditions, providing that $n$ is an odd integer.}
\funcdef{sec($z$)}{returns the secant of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{sech($z$)}{returns the hyperbolic secant of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{sin($z$)}{returns the sine of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{sinc($z$)}{returns the sinc function $\sin(z)/z$ for any complex number $z$, which may either be dimensionless, in which case it is understood to be measured in radians, or have physical dimensions of angle. The result is dimensionless.}
\funcdef{sinh($z$)}{returns the hyperbolic sine of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{sqrt($z$)}{returns the square root of $z$, which may be any complex number and may have any physical dimensions.}
\funcdef{strcmp($s1,s2$)}{returns zero if the strings $s1$ and $s2$ are the same, one if $s1$ should be placed after $s2$ in alphabetical sequence, minus one if $s1$ should be placed before $s2$ in alphabetical sequence.}
\funcdef{strlen($s$)}{returns the length of the string $s$.}
\funcdef{strlower($s$)}{returns a version of the string $s$ in which all alphabetic characters are converted to lowercase.}
\funcdef{strrange($s,i,j$)}{returns a slice of the string $s$ containing only the $i$th through until the $j$th characters of the string. If either $i$ or $j$ are negative, they are counted from the end of the string; for example, $-1$ refers to the last character of the string.}
\funcdef{strupper($s$)}{returns a version of the string $s$ in which all alphabetic characters are converted to uppercase.}
\funcdef{tan($z$)}{returns the tangent of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{tanh($z$)}{returns the hyperbolic tangent of $z$, where $z$ may be any complex number and must either have physical dimensions of angle or be a dimensionless number, in which case it is understood to be measured in radians.}
\funcdef{tdistCDF($x,nu$)}{returns the cumulative probability density at $x$ in a $t$-distribution with $\nu$ degrees of freedom. $\nu$ must be a positive real dimensionless integer. $x$ must be a positive real dimensionless number.}
\funcdef{tdistCDFi($P,nu$)}{returns the point $x$ at which the cumulative probability density in a $t$-distribution with $\nu$ degrees of freedom is $P$. $\nu$ must be a positive real dimensionless integer. $P$ must be a real number in the range $0\leq p \leq 1$.}
\funcdef{tdistPDF($x,nu$)}{returns the probability density at $x$ in a $t$-distribution with $\nu$ degrees of freedom. $\nu$ must be a positive real dimensionless integer. $x$ must be a positive real dimensionless number.}
\funcdef{texify(\ldots)}{returns a string of \LaTeX\ text corresponding to the algebraic expression or string supplied between the brackets.}
\funcdef{time\_\-daymonth({\it JD})}{returns the number of the day of the month on which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-dayweekname({\it JD})}{returns as a string the name of the day of the week on which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-dayweeknum({\it JD})}{returns the number, in the range 1~(Sunday) to 7~(Saturday), of the day of the week on which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-diff({\it JD}$_1$,\-{\it JD}$_2$)}{returns the time interval elapsed between the first and second supplied Julian Day numbers. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-diff\_\-string({\it JD}$_1$,\-{\it JD}$_2$,\-{\it format})}{returns a string representation of the time interval elapsed between the first and second supplied Julian Day numbers. For more details about Julian Day numbers, see the {\tt time\_\-julianday()} function. The third input is used to control the format of the output, with the following tokens being substituted for:
\begin{longtable}{|>{\columncolor{LightGrey}}l|>{\columncolor{LightGrey}}l|}
\hline \endfoot
\hline
Token & Value \\
\hline \endhead
{\tt \%\%} & A literal \% sign.\\
{\tt \%d} & The number of days elapsed, modulo 365.\\
{\tt \%D} & The number of days elapsed. \\
{\tt \%h} & The number of hours elapsed, modulo 24.\\
{\tt \%H} & The number of hours elapsed.\\
{\tt \%m} & The number of minutes elapsed, modulo 60.\\
{\tt \%M} & The number of minutes elapsed.\\
{\tt \%s} & The number of seconds elapsed, modulo 60.\\
{\tt \%S} & The number of seconds elapsed.\\
{\tt \%Y} & The number of years elapsed.\\
\end{longtable}}
\funcdef{time\_\-fromunix({\it u})}{returns the Julian Day number corresponding to the specified Unix time $u$.}
\funcdef{time\_\-hour({\it JD})}{returns the integer hour of the day, in the range 0-23, in which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-julianday({\it year},\-{\it month},\-{\it day},\-{\it hour},\-{\it min},\-{\it sec})}{returns the Julian Day number corresponding to the supplied time and date. Each field should be supplied numerically as an integer: for example, the {\it month} argument should be an integer in the range 1-12. In the default British calendar, the {\it year} argument should be the number of years elapsed since the Christian epoch. To enter dates before {\footnotesize AD\,1}, $0$ should be passed to indicate the year 1\,{\footnotesize BC}, $-1$ should be passed to indicate the year 2\,{\footnotesize BC}, and so forth. Dates may be entered in other calendars using the {\tt set calendar} command.
Julian Day numbers are defined to be the number of days elapsed since noon on 1st January, 4713\,{\footnotesize BC} in the Julian Calendar. Consequently, Julian Day numbers are rather large numbers: for example, midnight on 1st January 2000 corresponds to the Julian Day number 2451544.5. The hour of the day is indicated by the fractional part of the Julian Day number.
Julian Day numbers provide a useful means for analysing time-series data because they are not subject to the complicated non-decimal units in which time is conventionally measured. The task of calculating the time interval elapsed between two calendar dates is in general rather difficult, especially when leap years need be considered. However, the number of 24-hour periods elapsed between two Julian Day numbers is simply the numerical difference between the two day numbers.
PyXPlot's implementation of the {\tt time\_\-julianday()} function includes a consideration of the transition which was made from the Julian calendar to the Gregorian calendar on various dates in various countries. By default the transition is made at midnight on 14th~September 1752 (Gregorian calendar), when Britain and the British Empire adopted the Gregorian calendar. However, this may be changed using the {\tt set calendar} command.}
\funcdef{time\_\-min({\it JD})}{returns the integer number of minutes elapsed within the hour when the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-monthname({\it JD})}{returns as a string the English name of the calendar month in which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-monthnum({\it JD})}{returns the number, in the range 1-12, of the calendar month in which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-now()}{returns the Julian Day number corresponding to the present epoch. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-sec({\it JD})}{returns the number of seconds elapsed within the minute when the supplied Julian Day number falls. The number of seconds includes the fractional part. For more details see the {\tt time\_\-julianday()} function.}
\funcdef{time\_\-string({\it JD},\-{\it format})}{returns a string representation of the date and time corresponding to the supplied Julian Day number. For more details about Julian Day numbers, see the {\tt time\_\-julianday()} function. The second input is optional, and may be used to control the format of the output. If no format string is provided, then the format \newline\noindent{\tt "\%a \%Y \%b \%d \%H:\%M:\%S"}\newline\noindent is used. In such format strings, the following tokens are substituted for various parts of the date:
\begin{longtable}{|>{\columncolor{LightGrey}}l|>{\columncolor{LightGrey}}l|}
\hline \endfoot
\hline
Token & Value \\
\hline \endhead
{\tt \%\%} & A literal \% sign.\\
{\tt \%a} & Three-letter abbreviated weekday name.\\
{\tt \%A} & Full weekday name.\\
{\tt \%b} & Three-letter abbreviated month name.\\
{\tt \%B} & Full month name.\\
{\tt \%C} & Century number, e.g. 21 for the years 2000-2100.\\
{\tt \%d} & Day of month.\\
{\tt \%H} & Hour of day, in range~00-23.\\
{\tt \%I} & Hour of day, in range~01-12.\\
{\tt \%k} & Hour of day, in range~0-23.\\
{\tt \%l} & Hour of day, in range~1-12.\\
{\tt \%m} & Month number, in range~01-12.\\
{\tt \%M} & Minute, in range~00-59.\\
{\tt \%p} & Either {\tt am} or {\tt pm}.\\
{\tt \%S} & Second, in range~00-59.\\
{\tt \%y} & Last two digits of year number.\\
{\tt \%Y} & Year number.\\
\end{longtable}}
\funcdef{time\_\-unix({\it JD})}{returns the Unix time corresponding to the specified Julian Day number.}
\funcdef{time\_\-year({\it JD})}{returns the year in which the supplied Julian Day number falls. For more details see the {\tt time\_\-julianday()} function. The returned value is a dimensionless integer. A value of $0$ corresponds to the year 1\,{\footnotesize BC}; a value of $-1$ corresponds to the year 2\,{\footnotesize BC}, and so forth.}
\funcdef{tophat($x,\sigma$)}{returns one if $|x| \leq |\sigma|$, and zero otherwise. Both inputs must be real, but may have any physical dimensions so long as they match.}
\funcdef{unit(\ldots)}{multiplies a number by a physical unit. The string inside the brackets should consist of a string of the names of physical units, multiplied together with the {\tt *} operator, divided using the {\tt /} operator, or raised by numeric powers using the {\tt \^{}} operator. The list may be commenced with a numeric constant, for example: {\tt unit(2*m\^{}2/s)}.}
\funcdef{zernike($n,m,r,\phi$)}{evaluates the Zernike polynomial $Z^m_n(r,\phi)$, where $m$ and $n$ are non-negative integers with $n\geq m$, $r$ is the radial coordinate in the range $0
%
% Copyright (C) 2006-2010 Dominic Ford
% 2008-2010 Ross Church
%
% $Id: plotting.tex 814 2010-05-28 15:14:41Z 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 Detailed Survey}
\label{ch:plotting}
Having described PyXPlot's mathematical environment and data-processing
facilities in detail, this part of the manual returns to the subject of how
PyXPlot may be used to produce graphs and other vector graphics. In this
chapter we provide a systematic survey of how the appearance of plots can be
configured, continuing from the brief overview of the \indcmdt{plot} given in
Chapter~\ref{ch:first_steps}. In the subsequent chapters of this part, we will
go on to describe how to produce graphical output in a range of image formats
(Chapter~\ref{ch:image_formats}) and how to produce galleries of multiple plots
side-by-side together with more sophisticated vector graphics
(Chapter~\ref{ch:vector_graphics}).
\section{The {\tt with} modifier}
Chapter~\ref{ch:first_steps} provided an overview of the syntax of the
\indcmdt{plot}, including the {\tt every}, {\tt index}, {\tt select} and {\tt
using} modifiers which can be used to control {\it which} data, read from a
\datafile\ or sampled from a function, 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 using lines connecting each \datapoint\ to
its neighbours. More generally, the {\tt with} modifier can be followed by a
range of settings which fine-tune the manner in which the data are displayed;
for example, the statement
\begin{verbatim}
plot "data.dat" with lines linewidth 2.0
\end{verbatim}
would use twice the default width of line.
In the following section, a complete list of all of PyXPlot's plot styles --
i.e.\ all of the words which may be used in place of {\tt lines} -- will be
given. In this section, we list all of the modifiers such as {\tt line\-width}
which may be used to alter the exact appearance of these plot styles, which are
as follows:
\begin{itemize}
\item \indmodt{colour} -- used to select the colour in which each dataset is to be plotted. It should be followed either by an integer, to set a colour from the present palette (see Section~\ref{sec:palette}), or by a recognised colour name, a complete list of which can be found in Section~\ref{sec:colour_names}. Alternatively, arbitrary colours may be specified by using one of the forms {\tt rgb0.1:\-0.2:\-0.3}, {\tt hsb0.1:\-0.2:\-0.3} or {\tt cmyk0.4:\-0.3:\-0.2:\-0.1}, where the colon-separated values indicate the RGB, HSB or CMYK components of the desired colour in the range~0 to~1. This modifier may also be spelt {\tt color}.\index{colours!setting for datasets}
\item \indmodt{fillcolour} -- used to select the colour in which each dataset is filled. This is not applicable to any of the plot styles listed above, but is included here for completeness. The colour may be specified using any of the styles listed for {\tt colour}. 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 in 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 in 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 colour 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
indicate that each datapoint should be displayed in a different style or in a
different colour. 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 upon 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{colours!setting the palette} As indicated above, colours
may be referred to either specifically by name or RGB components, or by their
locations in the current palette. By default, PyXPlot's palette contains a series
of visually distinctive colours which are insofar as possible are also
distinctive to users with most common forms of colour blindness. 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 colours, 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,
colour number~4 would map to {\tt BrickRed}, as would colour number~0. A list
of all of the named colours which PyXPlot recognises is given in
Section~\ref{sec:colour_names}. The default palette which PyXPlot uses upon
startup may be changed by setting up a configuration file, as described in
Chapter~\ref{ch:configuration}.
\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 colour}, {\tt linetype} and {\tt pointtype} settings depend
upon whether the current graphic output device is set to produce colour or
monochrome output (see Chapter~\ref{sec:set_terminal}). In the former case
(colour output), the colours of each of the comma-separated datasets plotted on
a graph are drawn sequentially from the currently-selected palette, all lines
are drawn as solid lines ({\tt line\-type~1}), and the symbols used to draw
each dataset are drawn sequentially from PyXPlot's available point types. In
the latter case (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 colour
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 an exhaustive list of all of PyXPlot's {\it plot styles},
which we place into a series of groups for clarity.
\subsection{Lines and Points}
The following is a list of PyXPlot's simplest plot styles, all of which take as
input two columns of data, representing the $x$- and $y$-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 upon 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 colours which reveal that 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$ colours 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
\noindent{\tt set nokey}\newline
\noindent{\tt set size square}\newline
\noindent{\tt set xlabel '\$B-V\$ colour'}\newline
\noindent{\tt set ylabel 'Absolute magnitude \$M\$'}\newline
\noindent{\tt plot [-0.4:2][14:-4] 'hr\_data.dat' $\backslash$}\newline
\noindent{\tt \phantom{xxxxx}using \$2:(\$1+5*log10(1e2*\$3)) $\backslash$}\newline
\noindent{\tt \phantom{xxxxx}select (\$4/\$3<0.05) $\backslash$}\newline
\noindent{\tt \phantom{xxxxx}with dots ps 3}
\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 plot styles take three columns of input data, the first two of
which represent the $x$- and $y$-coordinates of the positions of each point,
and the last of which 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 columns of data as input, the first two of which
represent the $x$- and $y$-coordinates of the positions of each point, the
third of which gives the uncertainty in the $x$-coordinate, and the last of
which gives the uncertainty in the $y$-coordinate.
Each of the plot styles listed above has a corresponding partner which takes
minimum and maximum limit in place of each uncertainty, equivalent to writing
$5^{+2}_{-3}$ instead of $5\pm2$, except that the limits of~2 and~7 should be
given in place of $5-3$ and $5+2$:
\begin{itemize}
\item \indpst{xerrorrange} -- takes four columns of data.
\item \indpst{yerrorrange} -- takes four columns of data.
\item \indpst{xyerrorrange} -- takes six 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\footnote{These plot styles are currently
present for future expansion purposes only, as PyXPlot~0.8.0 cannot produce
three-dimensional plots.}: {\tt zerrorbars}, {\tt zerrorrange}, {\tt
xzerrorbars}, {\tt xzerrorrange}, {\tt yzerrorbars}, {\tt yzerrorrange}, {\tt
xyzerrorbars}, {\tt xyzerrorrange}.
\subsection{Shaded Regions}
The following plot styles allow regions of graphs to be shaded with colour:
\begin{itemize}
\item \indpst{yerrorshaded}
\item \indpst{shadedregion}
\end{itemize}
Both of these plot styles fill specified regions of graphs with the selected
{\tt fillcolour} and draw a line around the boundary of the region with the
selected {\tt colour}, {\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 expects data to be arranged in the same format
as the \indpst{yerrorrange} plot style, specifying the $x$- and $y$-coordinates
of a series of \datapoint s in the first two columns, together with the minimum
and maximum extremes of the vertical errorbar on each \datapoint in the third
and fourth columns. The region contained between the upper and lower limits of
the error bars is filled with colour; the $y$-coordinate specified in the
second column is unused. This plot style provides easy conversion between plots
drawn with errorbars and with shaded error regions. 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.
\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}
\noindent These styles differ in where the horizontal interfaces between the
bars are placed along the ordinate 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
centred upon 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. 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/04barchart2/}.}
\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}(1) shows the kind of effect that is
achieved; for comparison, Figure~\ref{fig:ex_barchart1}(b) 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{fillcolour} modifier,
followed by the name of a colour:
\begin{verbatim}
plot 'data.dat' with boxes fillcolour 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.
\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
| { , } { , }
| ( {"label"}
{ , {"label"} } .... )
}
\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 , ,
} are specified, then ticks are placed at evenly spaced intervals
between the specified limits. The {\tt } and {\tt } 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 }. In the case of logarithmic axes, {\tt } is applied
as a multiplicative step size.
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 crossing points 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
\noindent{\tt set log x1x2}\newline
\noindent{\tt set xrange [0.05:0.5]}\newline
\noindent{\tt set axis x2 top linked x}\newline
\noindent{\tt set xtics 0.05, 2, 0.4}\newline
\noindent{\tt set x2tics border $\backslash$}\newline
\noindent{\tt \phantom{xxxxx}("\$$\backslash$frac\{1\}\{$\backslash$pi\}\$" 1/pi, "\$$\backslash$frac\{1\}\{2$\backslash$pi\}\$" 1/(2*pi), $\backslash$}\newline
\noindent{\tt \phantom{xxxxxx}"\$$\backslash$frac\{1\}\{3$\backslash$pi\}\$" 1/(3*pi), "\$$\backslash$frac\{1\}\{4$\backslash$pi\}\$" 1/(4*pi), $\backslash$}\newline
\noindent{\tt \phantom{xxxxxx}"\$$\backslash$frac\{1\}\{5$\backslash$pi\}\$" 1/(5*pi), "\$$\backslash$frac\{1\}\{6$\backslash$pi\}\$" 1/(6*pi))}\newline
\noindent{\tt set grid x2}\newline
\noindent{\tt set nokey}\newline
\noindent{\tt set xlabel '\$x\$'}\newline
\noindent{\tt set ylabel '\$$\backslash$exp(x)$\backslash$sin(1/x)\$'}\newline
\noindent{\tt plot exp(x)*sin(1/x), 0}
\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 ordinate values 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 upon 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 upon 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"\%time\_string(x)
\end{dontdo}
\noindent the following is preferred
\begin{dodo}
set xformat "\%d/\%02d/\%d"\%(time\_day(x), $\backslash$\newline time\_monthnum(x),time\_daymonth(x))
\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 horizontal
\end{verbatim}
Alternatively, tick labels may be set to be written vertically, by issuing the command
\begin{verbatim}
set xformat vertical
\end{verbatim}
or to be written at any clockwise rotation angle from the horizontal using commands of the form
\begin{verbatim}
set xformat rotate unit(10*deg)
\end{verbatim}
Axis labels may also be made to appear at arbitrary rotations using commands such as
\begin{verbatim}
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 upon 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 distance and ordinate
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
\noindent{\tt set numeric display latex}\newline
\noindent{\tt set log x y}\newline
\noindent{\tt set key bottom right}\newline
\noindent{\tt set ylabel "Flux density / W/Hz/m\$\^{}2\$/sterad"}\newline
\noindent{\tt set x1label "Wavelength"}\newline
\noindent{\tt set x2label "Frequency"~~~~~; set unit of frequency Hz}\newline
\noindent{\tt set x3label "Photon Energy" ; set unit of energy eV}\newline
\noindent{\tt set axis x2 linked x1 using phy\_c/x}\newline
\noindent{\tt set axis x3 linked x2 using phy\_h*x}\newline
\\
\noindent{\tt bb(wlen,T) = Bv(phy\_c/wlen,T)/unit(W/Hz/m\^{}2/sterad)}\newline
\\
\noindent{\tt plot [80*unit(nm):unit(mm)][1e-20:] $\backslash$}\newline
\noindent{\tt \phantom{xx}bb(x,~~30) title "\$T=~~30\$$\backslash$,K", $\backslash$}\newline
\noindent{\tt \phantom{xx}bb(x, 100) title "\$T= 100\$$\backslash$,K", $\backslash$}\newline
\noindent{\tt \phantom{xx}bb(x, 300) title "\$T= 300\$$\backslash$,K", $\backslash$}\newline
\noindent{\tt \phantom{xx}bb(x,1000) title "\$T=1000\$$\backslash$,K", $\backslash$}\newline
\noindent{\tt \phantom{xx}bb(x,3000) title "\$T=3000\$$\backslash$,K"}
\nlscf
\centerline{\includegraphics[width=10cm]{examples/eps/ex_multiaxes}}
}
\example{ex:cmbrtemp}{A plot of the temperature of the CMB 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
\noindent{\tt h0 = 70}\newline
\noindent{\tt omega\_m = 0.27}\newline
\noindent{\tt omega\_l = 0.73}\newline
\noindent{\tt age = ast\_Lcdm\_age(h0,omega\_m,omega\_l)}\newline
\noindent{\tt set xrange [0.01*age:0.99*age]}\newline
\noindent{\tt set unit of time Gyr}\newline
\noindent{\tt set axis x2 linked x using ast\_Lcdm\_z(age-x,h0,omega\_m,omega\_l)}\newline
\noindent{\tt set xlabel "Time since Big Bang \$t\$"}\newline
\noindent{\tt set ylabel "CMB Temperature \$T\$"}\newline
\noindent{\tt set x2label "Redshift \$z\$"}\newline
\noindent{\tt plot unit(2.73*K)*(1+x) axes x2y1}
\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}
The colours of gridlines\index{grid!colour}\index{colours!grid} can be
controlled via the \indcmdts{set gridmajcolour} and \indcmdts{set
gridmincolour} commands, which control the gridlines emanating from major and
minor axis ticks respectively. An example would be:
\begin{verbatim}
set gridmincolour blue
\end{verbatim}
\noindent Any of the colour names listed in Section~\ref{sec:colour_names} can
be used.
A related command\index{axes!colour}\index{colours!axes} is \indcmdts{set
axescolour}, which has a syntax similar to that above, and sets the colour of
the graph's axes.\label{sec:set_colours}
\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 \indcmdt{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 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 and colours 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. The
\indcot{screen} and \indcot{graph} systems both measure in centimetres 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}
In addition to these four options, \indcot{axis} 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}).
\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 \LaTeX:
\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. 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 colour can also be specified, if desired, using the {\tt with colour}
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 colour green
\end{verbatim}
\index{fontsize}\index{text!size} The size of the text in such labels can 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!colour}\index{colours!text} The \indcmdt{set textcolour} can be
used to globally set the colour 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 colour from the present palette, or by a colour name. A list of the
recognised colour names can be found in Section~\ref{sec:colour_names}. For
example:
\begin{verbatim}
set textcolour 2
set textcolour 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{centre} or \indkeyt{right},
and the latter takes the options \indkeyt{bottom}, \indkeyt{centre} 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 colour filters commonly used
by astronomers (data taken from Binney \& Merrifield, {\it Galactic Astronomy},
Princeton, 1998).
\nlscf
{\footnotesize
\noindent{\tt set numeric display latex}\newline
\noindent{\tt set width 20}\newline
\noindent{\tt set size ratio 0.4}\newline
\noindent{\tt set numerics sf 4}\newline
\noindent{\tt set log x}\newline
\noindent{\tt set x1label "Wavelength"}\newline
\noindent{\tt set x2label "Frequency" ; set unit of frequency Hz}\newline
\noindent{\tt set x3label "Photon Energy" ; set unit of energy eV}\newline
\noindent{\tt set axis x2 linked x1 using phy\_c/x}\newline
\noindent{\tt set axis x3 linked x2 using phy\_h*x}\newline
\noindent{\tt set noytics ; set nomytics}\newline
}\\{\footnotesize
\noindent{\tt \# Draw lines of first four series of hydrogen lines}\newline
\noindent{\tt an=2}\newline
\noindent{\tt n=1}\newline
\noindent{\tt foreach SeriesName in ("Ly","Ba","Pa","Br")}\newline
\noindent{\tt \phantom{x}\{}\newline
\noindent{\tt \phantom{xx}for m=n+1 to n+21}\newline
\noindent{\tt \phantom{xxx}\{}\newline
\noindent{\tt \phantom{xxxx}wl = 1/(phy\_Ry*(1/n**2-1/m**2))}\newline
\noindent{\tt \phantom{xxxx}set arrow an from wl,0.3 to wl,0.6 with nohead col n}\newline
\noindent{\tt \phantom{xxxx}if (m-n==1) \{ ; GreekLetter = "$\backslash$$\backslash$alpha" ; \}}\newline
\noindent{\tt \phantom{xxxx}if (m-n==2) \{ ; GreekLetter = "$\backslash$$\backslash$beta" ; \}}\newline
\noindent{\tt \phantom{xxxx}if (m-n==3) \{ ; GreekLetter = "$\backslash$$\backslash$gamma" ; \}}\newline
\noindent{\tt \phantom{xxxx}if (m-n$<$4)}\newline
\noindent{\tt \phantom{xxxxx}\{}\newline
\noindent{\tt \phantom{xxxxxx}set label an "$\backslash$parbox\{5cm\}\{$\backslash$footnotesize$\backslash$center\{$\backslash$}\newline
\noindent{\tt \phantom{xxxxxxxx}\%s-\$\%s\$$\backslash$$\backslash$newline \$\%d$\backslash$to\%d\$$\backslash$$\backslash$newline \%s$\backslash$$\backslash$newline\}\}" $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxxx}\%(SeriesName,GreekLetter,n,m,wl) at wl,0.55+0.2*(m-n) $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxxx}hal centre val centre}\newline
\noindent{\tt \phantom{xxxxx}\}}\newline
\noindent{\tt \phantom{xxxx}an = an+1}\newline
\noindent{\tt \phantom{xxx}\}}\newline
\noindent{\tt \phantom{xx}n=n+1}\newline
\noindent{\tt \phantom{x}\}}\newline
}\\{\footnotesize
\noindent{\tt \# Label astronomical photometric colours}\newline
\noindent{\tt foreach datum i,name,wl\_c,wl\_w in "--" using $\backslash$}\newline
\noindent{\tt \phantom{xxxx}1:"\%s"\%(\$2):(\$3*unit(nm)):(\$4*unit(nm))}\newline
\noindent{\tt \phantom{x}\{}\newline
\noindent{\tt \phantom{xx}arry = 0.12+0.1*(i\%2) \# Vertical positions for arrows}\newline
\noindent{\tt \phantom{xx}laby = 0.07+0.1*(i\%2) \# Vertical positions for labels}\newline
\noindent{\tt \phantom{xx}x0 = (wl\_c-wl\_w/2) \# Shortward end of passband}\newline
\noindent{\tt \phantom{xx}x1 = wl\_c \# Centre of passband}\newline
\noindent{\tt \phantom{xx}x2 = (wl\_c+wl\_w/2) \# Longward end of passband}\newline
\noindent{\tt \phantom{xx}set arrow an from x0,arry to x2,arry with nohead}\newline
\noindent{\tt \phantom{xx}set label an name at x1,laby hal centre val centre}\newline
\noindent{\tt \phantom{xx}an = an+1}\newline
\noindent{\tt \phantom{x}\}}\newline
\noindent{\tt \phantom{x}1 U 365 66}\newline
\noindent{\tt \phantom{x}2 B 445 94}\newline
\noindent{\tt \phantom{x}3 V 551 88}\newline
\noindent{\tt \phantom{x}4 R 658 138}\newline
\noindent{\tt \phantom{x}5 I 806 149}\newline
\noindent{\tt \phantom{x}6 J 1220 213}\newline
\noindent{\tt \phantom{x}7 H 1630 307}\newline
\noindent{\tt \phantom{x}8 K 2190 390}\newline
\noindent{\tt \phantom{x}9 L 3450 472}\newline
\noindent{\tt 10 M 4750 460}\newline
\noindent{\tt END}\newline
}\\{\footnotesize
\noindent{\tt \# Draw a marker for the Lyman limit}\newline
\noindent{\tt ll = 91.1267*unit(nm)}\newline
\noindent{\tt set arrow 1 from ll,0.12 to ll,0.22}\newline
\noindent{\tt set label 1 "Lyman Limit: \%s"\%(ll) at 95*unit(nm),0.17 $\backslash$}\newline
\noindent{\tt \phantom{xxxxx}hal left val centre}\newline
}\\{\footnotesize
\noindent{\tt \# Finally produce plot}\newline
\noindent{\tt plot [80*unit(nm):5500*unit(nm)][0:1.25]}\newline
}
\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
{\footnotesize
\noindent{\tt set width 20}\newline
}\\{\footnotesize
\noindent{\tt \# We want a plot without axes or key}\newline
\noindent{\tt set nokey}\newline
\noindent{\tt set axis x invisible}\newline
\noindent{\tt set axis y invisible}\newline
}\\{\footnotesize
\noindent{\tt \# Labels for the states}\newline
\noindent{\tt set label 1 '\{$\backslash$large $\backslash$sf $\backslash$slshape Western Australia\}' 117, -28}\newline
\noindent{\tt set label 2 '\{$\backslash$large $\backslash$sf $\backslash$slshape South Australia\}' 130, -29.5}\newline
\noindent{\tt set label 3 '\{$\backslash$large $\backslash$sf $\backslash$slshape Northern Territory\}' 129.5, -20.5}\newline
\noindent{\tt set label 4 '\{$\backslash$large $\backslash$sf $\backslash$slshape Queensland\}' 141,-24}\newline
\noindent{\tt set label 5 '\{$\backslash$large $\backslash$sf $\backslash$slshape New South Wales\}' 142,-32.5}\newline
\noindent{\tt set label 6 '\{$\backslash$large $\backslash$sf $\backslash$slshape Victoria\}' 139,-41}\newline
\noindent{\tt set arrow 6 from 141,-40 to 142, -37 with nohead}\newline
\noindent{\tt set label 7 '\{$\backslash$large $\backslash$sf $\backslash$slshape Tasmania\}' 149,-42}\newline
\noindent{\tt set arrow 7 from 149, -41.5 to 146.5, -41.75 with nohead}\newline
\noindent{\tt set label 8 '\{$\backslash$large $\backslash$sf $\backslash$slshape Capital Territory\}' 151,-37}\newline
\noindent{\tt set arrow 8 from 151, -36.25 to 149, -36 with nohead}\newline
}\\{\footnotesize
\noindent{\tt \# Labels for the cities}\newline
\noindent{\tt set label 10 '\{$\backslash$sf Perth\}' 116.5, -32.4}\newline
\noindent{\tt set label 11 '\{$\backslash$sf Adelaide\}' 136, -38}\newline
\noindent{\tt set arrow 11 from 137.5,-37.2 to 138.601, -34.929}\newline
\noindent{\tt set label 12 '\{$\backslash$sf Darwin\}' 131, -13.5}\newline
\noindent{\tt set label 13 '\{$\backslash$sf Brisbane\}' 149, -27.5}\newline
\noindent{\tt set label 14 '\{$\backslash$sf Sydney\}' 151.5, -34.5}\newline
\noindent{\tt set label 15 '\{$\backslash$sf Melbourne\}' 143, -37.3}\newline
\noindent{\tt set label 16 '\{$\backslash$sf Hobart\}' 147.5, -44.25}\newline
\noindent{\tt set label 17 '\{$\backslash$sf Canberra\}' 145, -35.25}\newline
}\\{\footnotesize
\noindent{\tt \# A big label saying "Australia"}\newline
\noindent{\tt set label 20 '\{$\backslash$Huge $\backslash$sf $\backslash$slshape Australia\}' 117,-42}\newline
}\\{\footnotesize
\noindent{\tt \# Plot the coastline and cities}\newline
\noindent{\tt plot [][-45:] 'ex\_map\_1.dat.gz' every ::1 with lines, $\backslash$}\newline
\noindent{\tt \phantom{xxxxx}'ex\_map\_2.dat' with points pointtype 10 pointsize 2}
}
\nlscf
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_map}
\end{center}
}
% \section{Non-Flat Projections}
\section{Three-Dimensional Plotting}
PyXPlot 0.8.1 has no facilities for three-dimensional plotting. The ability to
configure axes such as {\tt z} and {\tt z2}, together with various references
to three-dimensional plotting in this manual, are provided for future
expansion only.
pyxplot-0.8.1/doc/vector_graphics.tex0000644000175000017500000014740011401470334016273 0ustar dcf21dcf21% VECTOR_GRAPHICS.TEX
%
% The documentation in this file is part of PyXPlot
%
%
% Copyright (C) 2006-2010 Dominic Ford
% 2008-2010 Ross Church
%
% $Id: vector_graphics.tex 779 2010-05-17 14:25:15Z 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{Producing Vector Graphics}
\label{ch:vector_graphics}
In the previous two chapters, we have seen how the \indcmdt{plot} may be used
to produce single graphs of functions and \datafile s, how the \indcmdt{set
terminal} can be used to produce graphical output in a wide range of different
image formats (see Section~\ref{sec:set_terminal}), and how the \indcmdt{set
papersize} can be used to produce PostScript output to fit on different sizes
of paper (see Section~\ref{sec:set_papersize}). Often, however, there is a need
to produce more sophisticated vector graphics. For example, several plots may
be wanted side-by-side, or some line-art annotations may be wanted on top of a
graph. Additionally, PyXPlot can also produce technical diagrams as well as
graphs. In this chapter, we turn our attention to such cases.
Several of the vector graphics commands described in this chapter take rotation
angles as one of their inputs. It should be stressed that PyXPlot has two
modes for handling angles: they can either be treated as dimensionless numbers
or as being an additional base unit within the SI system (see
Section~\ref{sec:angles}). Where the vector graphics commands described in
this chapter take rotation angles, a choice is always provided between
expressing the angles as dimensionless numbers, measured in degrees, or as
quantities with physical dimensions of angle. Thus, the following ways of
specifying angles are all valid:
\begin{dodo}
set unit angle nodimensionless\newline
text "foo" rotate unit(pi*rad)\newline
text "foo" rotate 180\newline
text "foo" rotate unit(0.25*revolution)
\end{dodo}
\noindent as are these ways:
\begin{dodo}
set unit angle dimensionless\newline
text "foo" rotate 180\newline
text "foo" rotate degrees(pi)
\end{dodo}
\noindent The following is {\it not} valid, because the angle of $180^\circ$ is
passed to the {\tt text} command in radians:
\begin{dontdo}
set unit angle dimensionless\newline
text "foo" rotate unit(180*deg)
\end{dontdo}
\section{Multiplot Mode}
\label{sec:multiplot}
\index{multiplot}
PyXPlot has two modes in which it can produce graphical output. In {\it
singleplot} mode, the default, each time the {\tt plot} command is issued, the
canvas is wiped clean and the new plot is placed alone on a blank page. In {\it
multiplot} mode, vector graphics objects accumulate on the canvas. Each time
the {\tt plot} command is issued, the new graph is placed on top of any other
objects which were already on the canvas, and many plots can be placed
side-by-side.
The user can switch between these two modes of operation by issuing the
commands \indcmdts{set multiplot} and \indcmdts{set nomultiplot}. The
\indcmdt{set origin} is required for multiplot mode to be useful when placing
plots side-by-side: it sets the position on the page of the lower-left corner
of the next plot. It takes a comma-separated $(x,y)$ coordinate pair, which may
have units of length, or, if dimensionless, are assumed to be measured in
centimetres. The following example plots a graph of $\sin(x)$ to the left of a
plot of $\cos(x)$:
\begin{verbatim}
set multiplot
set width 8
plot sin(x)
set origin 10,0
plot cos(x)
\end{verbatim}
All objects on a multiplot canvas have a unique identification number. By
default, these count up from one, such that the first item placed on the canvas
is number one, the next is number two, and so forth. Alternatively, the user
may specify a particular number for a particular object by supplying the
modifier {\tt item} to the {\tt plot} command, followed by an integer
identification number, as in the following example:
\begin{verbatim}
plot item 6 'data.dat'
\end{verbatim}
If there were already an object on the canvas with identification number~6,
this object would be deleted and replaced with the new object.
A list of all of the objects on the current multiplot canvas can be obtained
using the \indcmdt{list}, which produces output in the following format:
\begin{verbatim}
# ID Command
1 plot item 1 'data1.dat'
2 plot item 2 'data2.dat'
3 [deleted] plot item 3 'data3.dat'
\end{verbatim}
A multiplot canvas can be wiped clean by issuing the \indcmdt{clear}, which
removes all items currently on the canvas. Alternatively, individual items may
be removed using the \indcmdt{delete}, which should be followed by a
comma-separated list of the identification numbers of the objects to be
deleted. Deleted items may be restored using the \indcmdt{undelete}, which
likewise takes a comma-separated list of the identification numbers of the
objects to be restored, e.g.:
\begin{verbatim}
delete 1,2
undelete 2
\end{verbatim}
Once a canvas has been cleared using the \indcmdt{clear}, however, there is no
way to restore it. Objects may be moved around on the canvas using the
\indcmdt{move}. For example, the following would move item 23 to position
$(8,8)$ measured in inches:
\begin{verbatim}
move 23 to 8*unit(in), 8*unit(in)
\end{verbatim}
\subsection{Settings Associated with Multiplot Items}
Of the settings which can be set with the \indcmdt{set}, some refer to
PyXPlot's global environment and whole multiplot canvases. Others, such as {\tt
set width} and {\tt set origin} refer specifically to individual graphs and
vector graphics items. For this reason, whenever a new multiplot graphics item
is produced, it takes a copy of the settings which are specific to it, allowing
these settings to be changed by the user before producing other multiplot
items, without affecting previous items. The settings associated with a
particular multiplot item can be queried by passing the modifier {\tt item} to
the \indcmdt{show}, followed by the integer identification number of the item,
as in the examples:
\begin{verbatim}
show item 3 width # Shows the width of item 3
show item 3 settings # Shows all settings associated with item 3
\end{verbatim}
The settings associated with a particular multiplot item can be changed by
passing the same {\tt item} modifier to the \indcmdt{set}, as in the example,
which sets the width of item~3 to be $10\,\mathrm{cm}$:
\begin{verbatim}
set item 3 width 10*unit(cm)
\end{verbatim}
After making such changes, the \indcmdt{refresh} is useful: it produces a new
graphical image of the current multiplot to reflect any settings which have
been changed. The following example would produce a pair of plots, and then
change the colour of the text on the first plot:
\begin{verbatim}
set multiplot
plot f(x)
set origin 10,0
plot g(x)
set item 1 textcolour red
refresh
\end{verbatim}
Another common use of the \indcmdt{refresh} is to produce multiple
copies of an image in different graphical formats. For example, having just
developed a multiplot canvas interactively in the {\tt X11\_singlewindow},
copies can be produced as {\tt eps} and {\tt jpeg} images using the following
commands:
\begin{verbatim}
set terminal eps
set output 'figure.eps'
refresh
set terminal jpeg
set output 'figure.jpg'
refresh
\end{verbatim}
\subsection{Reordering Multiplot Items}
Items on multiplot canvases are drawn in order of increasing identification
number, and thus items with low identification numbers are drawn first, at the
back of the multiplot, and items with higher identification numbers are later,
towards the front of the multiplot. When new items are added, they are given
higher identification numbers than previous items and appear at the front of
the multiplot.
If this is not the desired ordering, then the \indcmdt{swap} may be used to
rearrange items. It takes the identification numbers of two multiplot items and
swaps their identification numbers and hence their positions in the ordered
sequence. Thus, if, for example, the corner of item~3 disappears behind the
corner of item~5, when the converse effect is actually desired, the following
command should be issued:
\begin{verbatim}
swap 3 5
\end{verbatim}
\subsection{The Construction of Large Multiplots}
\label{sec:set_display}
By default, whenever an item is added to a multiplot, or an existing item moved
or replotted, the whole multiplot is replotted to show the change. This can be
a time consuming process on large and complex multiplots. For this reason, the
\indcmdt{set nodisplay} is provided, which stops PyXPlot from producing any
output. The \indcmdt{set display} can subsequently be issued to return to
normal behaviour.
This can be especially useful in scripts which produce large multiplots. There
is no point in producing output at each step in the construction of a large
multiplot, and a great speed increase can be achieved by wrapping the script
with:
\begin{verbatim}
set nodisplay
[...prepare large multiplot...]
set display
refresh
\end{verbatim}
\section{Linked Axes and Galleries of Plots}
In the previous chapter (Section~\ref{sec:linked_axes}), linked axes were
introduced as a mechanism by which several axes on a single plot could be set
to have the same range, or to be algebraically related to one another. Another
common use for them is to make several plots on a multiplot canvas share common
axes. Just as the following statement links two axes on a single plot to one
another
\begin{verbatim}
set axis x2 linked x
\end{verbatim}
axes on the current plot can be linked to those of previous plots which are
already on the multiplot canvas using syntax of the form:
\begin{verbatim}
set axis x2 linked item 2 x
\end{verbatim}
A common reason for doing this is to produce galleries of side-by-side plots.
The following series of commands would produce a $2\times2$ grid of plots, with
axes only labelled along the bottom and left sides of the grid:
\vspace{3mm}
{\footnotesize
\noindent{\tt set multiplot}\newline
\noindent{\tt set nodisplay}\newline
\noindent{\tt width=5.4}\newline
}\\{\footnotesize
\noindent{\tt set width width}\newline
\noindent{\tt set xrange [0:23.999]}\newline
\noindent{\tt set yrange [0:0.11]}\newline
\noindent{\tt set nokey}\newline
\noindent{\tt set texthalign left}\newline
\noindent{\tt set textvalign centre}\newline
}\\{\footnotesize
\noindent{\tt \# Plot 1 (bottom left)}\newline
\noindent{\tt set xlabel "\$x\$"}\newline
\noindent{\tt set ylabel ""}\newline
\noindent{\tt set label 1 "(c) fsteps" at graph width*0.03 , graph width*gold\_ratio*0.9}\newline
\noindent{\tt plot "examples/ex\_barchart1.dat" with fsteps, "" with points}\newline
}\\{\footnotesize
\noindent{\tt set axis x linked item 1 x}\newline
\noindent{\tt set axis y linked item 1 y}\newline
}\\{\footnotesize
\noindent{\tt \# Plot 2 (bottom right)}\newline
\noindent{\tt set origin 1*width, 0*width*gold\_ratio}\newline
\noindent{\tt set yformat ""}\newline
\noindent{\tt set label 1 "(d) histeps" at graph width*0.03 , graph width*gold\_ratio*0.9}\newline
\noindent{\tt plot "examples/ex\_barchart1.dat" with histeps, "" with points}\newline
}\\{\footnotesize
\noindent{\tt \# Plot 3 (top left)}\newline
\noindent{\tt set origin 0*width, 1*width*gold\_ratio}\newline
\noindent{\tt set xformat "" ; set xlabel ""}\newline
\noindent{\tt unset yformat ; set ylabel texify(poissonPDF(x,18))}\newline
\noindent{\tt set label 1 "(a) impulses" at graph width*0.03 , graph width*gold\_ratio*0.9}\newline
\noindent{\tt plot "examples/ex\_barchart1.dat" with impulses, "" with points}\newline
}\\{\footnotesize
\noindent{\tt \# Plot 4 (top right)}\newline
\noindent{\tt set origin 1*width, 1*width*gold\_ratio}\newline
\noindent{\tt set yformat "" ; set ylabel ""}\newline
\noindent{\tt set label 1 "(b) steps" at graph width*0.03 , graph width*gold\_ratio*0.9}\newline
\noindent{\tt plot "examples/ex\_barchart1.dat" with steps, "" with points}\newline
}\\{\footnotesize
\noindent{\tt \# Now that we are finished preparing multiplot, turn display on}\newline
\noindent{\tt set display}\newline
\noindent{\tt refresh}
}\vspace{3mm}
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_gallery}}
\section{The {\tt replot} Command Revisited}
In multiplot mode, the \indcmdt{replot} can be used to modify the last plot
added to the page. For example, the following would change the title of the
latest plot to `foo', and add a plot of the function $g(x)$ to it:
\begin{verbatim}
set title 'foo'
replot cos(x)
\end{verbatim}
Additionally, it is possible to modify any plot on the page by adding an {\tt
item} modifier to the {\tt replot} statement to specify which plot should be
replotted. The following example would produce two plots, and then add an
additional function to the first plot:
\begin{verbatim}
set multiplot
plot f(x)
set origin 10,0
plot g(x)
replot item 1 h(x)
\end{verbatim}
If no {\tt item} number is specified, then the \indcmdt{replot} acts by default
upon the most recent plot to have been added to the multiplot canvas.
\section{Adding Other Vector Graphics Objects}
In addition to graphs, a range of other objects can be placed on multiplot
canvases:
\begin{itemize}
\item Arcs of circles (the \indcmdt{arc}).
\item Arrows (the \indcmdt{arrow}).
\item Rectangular boxes (the \indcmdt{box}).
\item Circles (the \indcmdt{circle}).
\item Ellipses (the \indcmdt{ellipse}).
\item Encapsulated PostScript images (the \indcmdt{eps}).
\item Graphical images in {\tt bmp}, {\tt gif}, {\tt jpeg} or {\tt png} formats (the \indcmdt{image}).
\item Lines (the \indcmdt{line}).
\item Piecharts (the \indcmdt{piechart}).
\item Points labelled by crosses and other symbols (the \indcmdt{point}).
\item Text labels (the \indcmdt{text}).
\end{itemize}
Put together, these commands can be used to produce a wide range of vector
graphics. In the remainder of this chapter, we describe these commands in turn,
providing a variety of examples of their use.
\subsection{The {\tt text} Command}
Text labels may be added to multiplot canvases using the \indcmdt{text}. This
has the following syntax:
\begin{verbatim}
text 'This is some text' at x,y
\end{verbatim}
In this case, the string `This is some text' would be rendered at position
$(x,y)$ on the multiplot. As with the \indcmdt{set label}, a colour may
optionally be specified with the {\tt with colour} modifier, as well as a
rotation angle to rotate text labels through any given angle, measured in
degrees counter-clockwise. For example:\indkey{rotate}
\begin{verbatim}
text 'This is some text' at x,y rotate r with colour red
\end{verbatim}
The commands \indcmdts{set textcolour}, \indcmdts{set texthalign} and
\indcmdts{set textvalign} can be used to set the colour and alignment of the
text produced with the \indcmdt{text}. Alternatively, the \indcmdt{text} takes
three modifiers to control the alignment of the text which override these {\tt
set} commands. The {\tt halign} and {\tt valign} modifiers may be followed by
any of the settings which may follow the {\tt set texthalign} and {\tt set
textvalign} commands respectively, as in the following examples:
\begin{verbatim}
text 'This is some text' at 0,0 halign left valign top
text 'This is some text' at 0,0 halign right valign centre
\end{verbatim}
\noindent The {\tt gap} modifier allows a gap to be inserted in the alignment
of the text. For example, the string {\tt halign left gap 3*unit(mm)} would
cause text to be rendered with its left side $3\,\mathrm{mm}$ to the right of
the position specified for the text. This is useful for labelling points on
diagrams, where the labels should be slightly offset from the points that they
are associated with. If the {\tt gap} modifier is followed by a dimensionless
number, rather than one with dimensions of lengths, then it is assumed to be
measured in centimetres.
It should be noted that the \indcmdt{text} can also be used outside of the
multiplot environment, to render a single piece of short text instead of a
graph. One obvious application is to produce equations rendered as graphical
files which can subsequently be imported into documents, slideshows or
webpages.\index{presentations}
\subsection{The {\tt arrow} and {\tt line} Commands}
Arrows may also be added to multiplot canvases using the \indcmdt{arrow}, which
has syntax:
\begin{verbatim}
arrow from x,y to x,y
\end{verbatim}
The \indcmdt{arrow} may be followed by the \indmodt{with} keyword to specify to
style of the arrow. The line type, line width and colour of the arrow, may be
specified using the same syntax as used in the plot command, using the {\tt
linetype}, {\tt linewidth} and {\tt colour} modifiers after the word {\tt
with}, as in the example:
\begin{verbatim}
arrow from 0,0 to 10,10 \
with linetype 2 linewidth 5 colour red
\end{verbatim}
\noindent The style of the arrow may also be specified after the word {\tt
with}, and three options are available: {\tt head} (the default), {\tt nohead},
which produces line segments with no arrowheads on them, and {\tt twoway},
which produces bidirectional arrows with heads on both ends.
The \indcmdt{arrow} has a twin, the \indcmdt{line}, which has the same syntax
but with a different style setting of {\tt nohead}.
\example{ex:notice}{A simple notice generated with the {\tt text} and {\tt arrow} commands}{
In this example script, we use PyXPlot's {\tt arrow} and {\tt text} commands to
produce a simple notice advertising that a lecture has moved to a different
seminar room:
\nlscf
\noindent {\tt \# Turn on multiplot mode }\newline
\noindent {\tt set multiplot ; set nodisplay }\newline
\\
\noindent {\tt \# Set the dimensions of the notice }\newline
\noindent {\tt w = 20~~~~~~~~\# Width of notice / cm }\newline
\noindent {\tt h = w/sqrt(2)~\# Height of notice / cm }\newline
\\
\noindent {\tt \# Put a rectangular box around the notice }\newline
\noindent {\tt line from 0,0 to w,0 with linewidth 5 }\newline
\noindent {\tt line from w,0 to w,h with linewidth 5 }\newline
\noindent {\tt line from w,h to 0,h with linewidth 5 }\newline
\noindent {\tt line from 0,h to 0,0 with linewidth 5 }\newline
\\
\noindent {\tt \# Write the text of the notice in big letters }\newline
\noindent {\tt set texthalign centre ; set fontsize 3 }\newline
\noindent {\tt text "$\backslash$bf Astrophysical Fluids Lecture" at w/2,3/4*h }\newline
\noindent {\tt text "$\backslash$bf MOVED to Seminar Room 3" at w/2, h/2 }\newline
\noindent {\tt arrow from w/4, h/4 to 3/4*w, h/4 with linewidth 8 }\newline
\\
\noindent {\tt \# Display the notice }\newline
\noindent {\tt set display ; refresh }\newline
\nlfcf
The resulting notice is shown below:
\nlscf
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_notice}}
}
\example{ex:euclid}{A diagram from Euclid's {\it Elements}}{
In this more extended example script, we use PyXPlot's {\tt arrow} and {\tt
text} commands to reproduce a diagram illustrating the 47th Proposition from
Euclid's First Book of {\it Elements}, better known as Pythagoras' Theorem. A
full text of the proof which accompanies this diagram can be found at
\url{http://www.gutenberg.org/etext/21076}.
\nlscf
{\footnotesize
\noindent {\tt set multiplot ; set nodisplay}\newline
}\\{\footnotesize
\noindent {\tt \# Lengths of three sides of triangle}\newline
\noindent {\tt AB = 2*unit(cm)}\newline
\noindent {\tt AC = 4*unit(cm)}\newline
\noindent {\tt BC = hypot(AC, AB) \# Hypotenuse}\newline
\noindent {\tt CBA = atan2(AC, AB) \# Angle CBA}\newline
}\\{\footnotesize
\noindent {\tt \# Positions of three corners of triangle}\newline
\noindent {\tt Bx = 0*unit(cm)~~~~~~~; By = 0*unit(cm) \# The origin}\newline
\noindent {\tt Cx = Bx + BC~~~~~~~~~~; Cy = By}\newline
\noindent {\tt Ax = Bx + AB*cos(CBA) ; Ay = By + AB*sin(CBA)}\newline
}\\{\footnotesize
\noindent {\tt \# Positions of constructed points}\newline
\noindent {\tt Dx = Bx~~~~~~~~~~~~~~~; Dy = -BC}\newline
\noindent {\tt Lx = Ax~~~~~~~~~~~~~~~; Ly = Dy}\newline
\noindent {\tt Ex = Cx~~~~~~~~~~~~~~~; Ey = Dy}\newline
}\\{\footnotesize
\noindent {\tt Hx = Bx + (AB + AC) * cos(CBA)}\newline
\noindent {\tt Hy = By + (AB + AC) * sin(CBA)}\newline
\noindent {\tt Kx = Cx + (~~~~~AC) * cos(CBA)}\newline
\noindent {\tt Ky = Cy + (~~~~~AC) * sin(CBA)}\newline
}\\{\footnotesize
\noindent {\tt Fx = Bx + AB*cos(CBA+90*unit(deg))}\newline
\noindent {\tt Fy = By + AB*sin(CBA+90*unit(deg))}\newline
\noindent {\tt Gx = Ax + AB*cos(CBA+90*unit(deg))}\newline
\noindent {\tt Gy = Ay + AB*sin(CBA+90*unit(deg))}\newline
}\\{\footnotesize
\noindent {\tt \# Construct diagram}\newline
\noindent {\tt box from Dx,Dy to Cx,Cy with fillcol grey80}\newline
\noindent {\tt box at Ax,Ay width AC height AC rot CBA-90*unit(deg) with fillcol grey80}\newline
\noindent {\tt box at Bx,By width AB height AB rot CBA with fillcol grey80}\newline
\noindent {\tt line from Bx,By to Kx,Ky}\newline
\noindent {\tt line from Fx,Fy to Cx,Cy}\newline
\noindent {\tt line from Ax,Ay to Dx,Dy}\newline
\noindent {\tt line from Ax,Ay to Lx,Ly}\newline
\noindent {\tt line from Ax,Ay to Ex,Ey}\newline
}\\{\footnotesize
\noindent {\tt \# Label diagram}\newline
\noindent {\tt set fontsize 1.3}\newline
\noindent {\tt TG = 0.5*unit(mm) \# Gap left between labels and figure}\newline
\noindent {\tt text "A" at Ax,Ay gap TG*5 hal c val b}\newline
\noindent {\tt text "B" at Bx,By gap TG~~~hal r val t}\newline
\noindent {\tt text "C" at Cx,Cy gap TG~~~hal l val t}\newline
\noindent {\tt text "D" at Dx,Dy gap TG~~~hal c val t}\newline
\noindent {\tt text "E" at Ex,Ey gap TG~~~hal c val t}\newline
\noindent {\tt text "F" at Fx,Fy gap TG~~~hal r val c}\newline
\noindent {\tt text "G" at Gx,Gy gap TG~~~hal c val b}\newline
\noindent {\tt text "H" at Hx,Hy gap TG~~~hal c val b}\newline
\noindent {\tt text "K" at Kx,Ky gap TG~~~hal l val c}\newline
\noindent {\tt text "L" at Lx,Ly gap TG~~~hal c val t}\newline
}\\{\footnotesize
\noindent {\tt \# Display diagram}\newline
\noindent {\tt set display ; refresh}\newline
}
\nlfcf
The resulting diagram is shown below:
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_euclid_I_47}}
}
\example{ex:nanotubes}{A diagram of the conductivity of nanotubes}{
In this example we produce a diagram of the {\it irreducible wedge} of possible
carbon nanotube configurations, highlighting those configurations which are
electrically conductive. We use PyXPlot's loop constructs to automate the
production of the hexagonal grid which forms the basis of the diagram.
\nlscf
{\footnotesize
\noindent{\tt BASIS\_ANGLE\_X = (0 )*unit(deg)}\newline
\noindent{\tt BASIS\_ANGLE\_Y = (120)*unit(deg)}\newline
\noindent{\tt LINELEN = unit(5*mm)}\newline
}\\{\footnotesize
\noindent{\tt subroutine line(x1,y1,x2,y2,lw)}\newline
\noindent{\tt \phantom{x}\{}\newline
\noindent{\tt \phantom{xx}line from (x1*sin(BASIS\_ANGLE\_X)+y1*sin(BASIS\_ANGLE\_Y))*LINELEN, $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxxxxxxx}(x1*cos(BASIS\_ANGLE\_X)+y1*cos(BASIS\_ANGLE\_Y))*LINELEN $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxx}to (x2*sin(BASIS\_ANGLE\_X)+y2*sin(BASIS\_ANGLE\_Y))*LINELEN, $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxxxxxxx}(x2*cos(BASIS\_ANGLE\_X)+y2*cos(BASIS\_ANGLE\_Y))*LINELEN $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxx}with linewidth lw}\newline
\noindent{\tt \phantom{x}\}}\newline
}\\{\footnotesize
\noindent{\tt subroutine hexagon(x,y,lw)}\newline
\noindent{\tt \phantom{x}\{}\newline
\noindent{\tt \phantom{xx}call line(x ,y ,x ,y-1,lw)}\newline
\noindent{\tt \phantom{xx}call line(x ,y-1,x+1,y-1,lw)}\newline
\noindent{\tt \phantom{xx}call line(x+1,y-1,x+2,y ,lw)}\newline
\noindent{\tt \phantom{xx}call line(x+2,y ,x+2,y+1,lw)}\newline
\noindent{\tt \phantom{xx}call line(x+2,y+1,x+1,y+1,lw)}\newline
\noindent{\tt \phantom{xx}call line(x+1,y+1,x ,y ,lw)}\newline
\noindent{\tt \phantom{x}\}}\newline
}\\{\footnotesize
\noindent{\tt set multiplot}\newline
\noindent{\tt set nodisplay}\newline
}\\{\footnotesize
\noindent{\tt for XPOS=0 to 10}\newline
\noindent{\tt \phantom{x}\{}\newline
\noindent{\tt \phantom{xx}for YPOS=0 to XPOS+1}\newline
\noindent{\tt \phantom{xxx}\{}\newline
\noindent{\tt \phantom{xxxx}x = 1*XPOS + 2*YPOS}\newline
\noindent{\tt \phantom{xxxx}y = 2*XPOS + 1*YPOS}\newline
\noindent{\tt \phantom{xxxx}call hexagon(x,y, conditionalN((XPOS-YPOS)\%3==0,4,1))}\newline
\noindent{\tt \phantom{xxxx}text '\%d,\%d'\%(XPOS,YPOS) $\backslash$}\newline
\noindent{\tt \phantom{xxxxxx}at ((x+1)*sin(BASIS\_ANGLE\_X)+y*sin(BASIS\_ANGLE\_Y))*LINELEN, $\backslash$}\newline
\noindent{\tt \phantom{xxxxxxxxx}((x+1)*cos(BASIS\_ANGLE\_X)+y*cos(BASIS\_ANGLE\_Y))*LINELEN $\backslash$}\newline
\noindent{\tt \phantom{xxxxxx}hal cen val cen}\newline
\noindent{\tt \phantom{xxx}\}}\newline
\noindent{\tt \phantom{x}\}}\newline
}\\{\footnotesize
\noindent{\tt set display}\newline
\noindent{\tt refresh}}
\nlscf
\centerline{\includegraphics[width=9cm]{examples/eps/ex_nanotubes}}
}
\subsection{The {\tt image} Command}
Graphical images in {\tt bmp}, {\tt gif}, {\tt jpeg} or {\tt png} format may be
placed on multiplot canvases using the \indcmdt{image}\footnote{To maintain
compatibility with historic versions of PyXPlot, the {\tt image} command may
also be spelt {\tt jpeg}, with the identical syntax thereafter.}. In its
simplest form, this has the syntax:
\begin{verbatim}
image 'filename' at x,y width w
\end{verbatim}
As an alternative to the \indkeyt{width} keyword the height of the image can be
specified, using the analogous \indkeyt{height} keyword. An optional angle can
also be specified using the \indkeyt{rotate} keyword; this causes the included
image to be rotated counter-clockwise by a specified angle, measured in
degrees. The keyword {\tt smooth} may optionally be supplied to cause the
pixels of the image to be interpolated\footnote{Many commonly-used PostScript
display engines, including Ghostscript, do not support this functionality.}.
Images which include transparency are supported. The optional keyword {\tt
notransparent} may be supplied to the \indcmdt{image} to cause transparent
regions to be filled with the image's default background colour. Alternatively,
an RGB colour may be specified in the form {\tt rgb::} after the
keyword {\tt transparent} to cause that particular colour to become
transparent; the three components of the RGB colour should be in the range~0
to~255.
\subsection{The {\tt eps} Command}
Vector graphic images in eps format may be placed on multiplot canvases
using the \indcmdt{eps}, which has a syntax analogous to the {\tt image}
command. However neither height nor width need be specified; in this case the
image will be included at its native size. For example:
\begin{verbatim}
eps 'filename' at 3,2 rotate 5
\end{verbatim}
\noindent will place the eps file with its bottom-left corner at position
$(3,2)$\,cm from the origin, rotated counter-clockwise through 5 degrees.
\subsection{The {\tt box} and {\tt circle} Commands}
\label{sec:rectangle}
Rectangular boxes and circles may be placed on multiplot canvases
using the {\tt box} and {\tt circle} commands\indcmd{box}\indcmd{circle}, as
in:
\begin{verbatim}
box from 0*unit(mm),0*unit(mm) to 25*unit(mm),70*unit(mm)
circle at 0*unit(mm),0*unit(mm) radius 70*unit(mm)
\end{verbatim}
\noindent In the former case, two corners of the rectangle are specified,
meanwhile in the latter case the centre of the circle and its radius are
specified. The \indcmdt{box} may also be invoked by the synonym {\tt
rectangle}\indcmd{rectangle}. Boxes may be rotated using an optional {\tt
rotate} modifier, which may be followed by a counter-clockwise rotational angle
which may either have dimensions of angle, or is assumed to be in degrees if
dimensionless. The rotation is performed about the centre of the rectangle:
\begin{verbatim}
box from 0,0 to 10,3 rotate 45
\end{verbatim}
The positions and dimensions of boxes may also be specified by giving the
position of one of the corners of the box, together with its width and height.
The specified corner is assumed to be the bottom-left corner if both the
specified width and height are positive; other corners may be specified if the
supplied width and/or height are negative. If such boxes are rotated, the
rotation is about the specified corner:
\begin{verbatim}
box at 0,0 width 10 height 3 rotate 45
\end{verbatim}
The line type, line width, and colour of line with which the outlines of boxes
and circles are drawn may be specified as in the {\tt arrow} command, for
example:
\begin{verbatim}
circle at 0,0 radius 5 with linetype 1 linewidth 2 colour red
\end{verbatim}
\noindent The shapes may be filled by specifying a {\tt fillcolour}:
\begin{verbatim}
circle at 0,0 radius 5 with lw 10 colour red fillcolour yellow
\end{verbatim}
\example{ex:noentry}{A simple no-entry sign}{
In this example script, we use PyXPlot's {\tt box} and {\tt circle} commands to
produce a no-entry sign warning passers by that code monkeys can turn nasty
when interrupted from their work.
\nlscf
\noindent {\tt set multiplot ; set nodisplay}\newline
\noindent {\tt }\newline
\noindent {\tt w = 10 \# Width of sign / cm}\newline
\\
\noindent {\tt \# Make no-entry sign}\newline
\noindent {\tt circle at 0,0 radius w with col null fillcol red}\newline
\noindent {\tt box from -(0.8*w),-(0.2*w) to (0.8*w),(0.2*w) $\backslash$}\newline
\noindent {\tt \phantom{xxxx}with col null fillcol white}\newline
\\
\noindent {\tt \# Put a warning beneath the sign}\newline
\noindent {\tt set fontsize 3}\newline
\noindent {\tt set texthalign centre ; set textvalign centre}\newline
\noindent {\tt text "$\backslash$bf Keep Out! Code Monkey at work!"}\newline
\\
\noindent {\tt \# Display sign}\newline
\noindent {\tt set display ; refresh}\newline
\vspace{2mm}\\
\nlfcf
The resulting sign is shown below:
\nlscf
\centerline{\includegraphics[width=5cm]{examples/eps/ex_noentry}}
}
\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. It is an iconic image of the power of chaos theory to produce
complicated structure out of simple algorithms, which we implement in this
example using PyXPlot's loop constructs.
\nlnp
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. In practice, the
sequence is certain to diverge if $|z_n|$ ever exceeds~2. It cannot generally
be proven not to diverge at any particular point, but is considered to remain
bounded in our algorithm if $|z_n|$ has not exceeded~2 within a certain number
{\tt StepsMax} of steps. To increase the aesthetic appeal of the fractal,
pixels outside of the fractal are assigned different colours depending upon how
many iterations were required before the sequence moved outside the circle
$|z_n|=2$.
\nlnp
This script makes use of the \indcmdt{rectangle} to paint each pixel of the
fractal one by one, which is highly inefficient, but demonstrates PyXPlot's
versatility.
\nlscf
\noindent {\tt set~multiplot }\newline
\noindent {\tt set~nodisplay }\newline
\noindent {\tt set~numerics~complex }\newline
\noindent {\tt StepsMax=10 }\newline
\noindent {\tt yn=0 }\newline
\noindent {\tt for~y=2~to~-2~step~-0.05 }\newline
\noindent {\tt \phantom{x}\{ }\newline
\noindent {\tt \phantom{xx}xn=0 }\newline
\noindent {\tt \phantom{xx}for~x=-2~to~2~step~0.05 }\newline
\noindent {\tt \phantom{xxx}\{ }\newline
\noindent {\tt \phantom{xxxx}zi~=~x+i*y;~z=zi;~iter=0; }\newline
\noindent {\tt \phantom{xxxx}while~(abs(z)<2)~and~(iter$ Centre}\newline
}\\{\footnotesize
\noindent {\tt \# Label ellipse }\newline
\noindent {\tt set texthalign centre ; set textvalign centre}\newline
\noindent {\tt text '\$ae\$' at -fd/2,-0.3}\newline
\noindent {\tt text '\$a\$' at a/2,+0.3}\newline
\noindent {\tt text '\$b\$' at 0.3,b/2}\newline
\noindent {\tt set texthalign left ; set textvalign centre}\newline
\noindent {\tt text '\$L=a(1-e\^{}2)\$' at 0.2-fd,slr/2}\newline
}\\{\footnotesize
\noindent {\tt \# Display diagram }\newline
\noindent {\tt set display ; refresh }\newline
}
\nlfcf
The resulting diagram is shown below:
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_ellipse}}
}
\subsection{The {\tt piechart} Command}
\label{sec:piechart}
The \indcmdt{piechart} produces piecharts based upon single columns of data
read from \datafile s, which are taken to indicate the sizes of the pie wedges.
The \indcmdt{piechart} has the following syntax:
\begin{verbatim}
piechart (''|)
[using ]
[select