\documentclass[11pt]{article}

\usepackage[toc]{multitoc}

\usepackage{booktabs}
\usepackage{multirow}

\usepackage{amssymb}

\usepackage{fontspec}
% Libertine
\setmainfont[Ligatures={Common,TeX}]{Linux Libertine O}
\setsansfont{Linux Biolinum O}
\setmonofont{Inconsolata}

\usepackage{minted}
\newminted{julia}{}

\usepackage{geometry}
\geometry{
	xetex,
	textwidth=410pt
}

\hyphenpenalty 300

\newcommand{\cm}{$\checkmark$}

\title{Gaston \\[0.8cm] \large A plotting utility for Julia \\[0.8cm] v. 0.5.5}
\author{M. Bazdresch}
\date{\today}

\newcommand{\cmd}[1]{\texttt{#1}}

\begin{document}
\maketitle

\textbf{Please note:} Gaston is currently under heavy development, and all
functions and definitions are subject to change from one version to the next,
as we figure out the best way to organize the code. Gaston has been tested on
Linux, with gnuplot 4.6, and Julia v0.1.

\tableofcontents

\section{Introduction}

Gaston provides a way to plot scientific and numeric data using the Julia
programming language. It accomplishes this by harnessing gnuplot, a versatile
and time-tested plotting utility. Gaston also relies on gnuplot for interacting
with plots (zooming and rotating a plot with the mouse, for instance).

The primary purpose of Gaston is to provide easy-to-use functions to quickly
and conveniently plot the most common kinds of scientific and numeric data. It
is concerned mainly with screen output, although it also supports exporting
figures to SVG, PDF, PNG and GIF files (see section \ref{s:print} for more on
printing).

Gaston offers two sets of plotting functions. The first, called "high-level",
is similar to some of the functions offered by programs such as Octave. These
functions may be used to create 2-D plots (including histograms), 3-D surfaces,
and for plotting images. See section \ref{hilevel} for more information on
these functions.

The second set, called "mid-level", offers more flexibility at the cost of
being a bit more cumbersome. With these functions, figures are built step by
step by adding sets of coordinates with associated properties. These functions
allow creation of some kinds of plots not supported by the high-level
interface. For example, plotting a histogram and a curve on the same plot is
only possible with mid-level functions. See section \ref{midlevel} for more
information.

At the lowest level, Gaston provides a function called \cmd{gnuplot\_send()}.
It takes a string argument, which is sent to a gnuplot process through a
pipe. While certainly not user-friendly, this function may be used to
ultimately access any gnuplot feature from Julia, even if not supported by
Gaston.

Gaston has a layered design: high-level plot functions use the mid-level
functions to build and specify plots, which are translated to gnuplot commands
and sent to gnuplot using \cmd{gnuplot\_send()}.

\section{Installation}

To use Gaston, install the package from Julia's command prompt:

\begin{juliacode}
Pkg.add("Gaston")
\end{juliacode}

Then, load the package with

\begin{juliacode}
using Gaston
\end{juliacode}

To run a demo, do

\begin{juliacode}
gaston_demo()
\end{juliacode}

This will create a series of figures that illustrate the current capabilities
of the program. The same file may also serve as a guide on how to create
different types of plots.

To run the tests (see section \ref{tests}), do

\begin{juliacode}
gaston_tests()
\end{juliacode}

All tests should pass.

\section{Definitions}

A \textbf{figure} is an independent window, which contains a set of axes, on
which one or more \textbf{curves} are plotted. A figure may contain
\textbf{labels} (for instance, on each coordinate axis), a \textbf{title}, and a
\textbf{legend box} which identifies each curve. Gaston supports having any
number of figures open at the same time; however, gnuplot requires that only
one figure is able to offer mouse interactivity at a given time. Each figure is
identified by a unique \textbf{handle}. Handles are natural numbers.

A \textbf{curve} is defined by a set of coordinates. Two-dimensional curves
have \textbf{x} and \textbf{y} coordinates; in three dimensions, an additional
\textbf{z} coordinate must be specified. A curve also has several
\textbf{properties} that specify a plotting configuration (for instance, it may
have a \textbf{plotstyle}, a \textbf{linewidth}, a \textbf{linecolor}, etc),
which define how the curve is to be plotted.

\section{Plotting}
\label{hilevel}

\subsection{Figures}

A figure may be created by the function \cmd{figure()}. Many plotting functions
create or reuse an existing figure, as needed (see each function's
documentation). Called with no arguments, \cmd{figure()} creates a new figure
with the smallest available handle. Called with an argument (which must be a
natural number), it will create a figure with that handle if no such figure
exists, or will select it (make it current) if it exists.

Selecting an existing figure may be useful, for instance, to interact with it
using mouse and keyboard, or to overwrite it with the next plotting command.

Handles may be created in any numerical order.

This function always returns the handle of the current figure.

\subsection{Terminals}

Gaston supports plotting to the screen as well as printing the plots to files.
Three screen terminals are supported: \cmd{wxt}, \cmd{x11} and
\cmd{aqua}\footnote{Gnuplot provides the \cmd{aqua} terminal on Mac OS X
systems only. It is included in Gaston for convenience of users of that system.
However, the author does not have access to any Mac computers and, in
consequence, this terminal should be considered as unsupported. Bug reports,
patches and comments are welcome, as always.}. The \cmd{x11} terminal is faster
than \cmd{wxt}, but it offers lower plot quality; it is provided for use in
systems with lower performance or that don't support WxWindows.

For printing to files, terminals \cmd{svg}, \cmd{pdf}, \cmd{png}, \cmd{eps} and
\cmd{gif} are supported. For more details on printing, see section
\ref{s:print} below.

To set the terminal type, use the command
\begin{juliacode}
set_terminal(term)
\end{juliacode}
where \cmd{term} is a string.

\subsection{2-D plotting}

There are two commands for two-dimensional plotting: \cmd{plot()} and
\cmd{histogram()}.

\subsubsection{plot()}

The \cmd{plot()} function takes at least one argument, with the following
format:

\cmd{plot(\{h,\} \{x,\} y \{, property, value...\} \{...\})}

\begin{itemize}
	\item If the optional argument \cmd{h} is provided, it is assumed to be the
		figure handle in which to plot.
		\begin{itemize}
			\item If the handle doesn't exist, a new figure is created.
			\item If it exists, the figure will be overwritten.
			\item If it is 0, then a new figure to plot in will be created,
				using the next handle available.
		\end{itemize}
		If it is not provided, then the current figure will be used and
		overwritten.
	\item The \cmd{x} and \cmd{y} arguments specify coordinates (they must be ranges, vectors, or
		two-dimensional arrays with a singleton dimension). If only \cmd{y} is
		provided, it is assumed to be the ordinate. If \cmd{x} and \cmd{y} are provided, they
		are assumed to be the abscissa and the ordinate, in that order.
	\item The coordinates may be followed by any number of
		\cmd{property}, \cmd{value} pairs. These are used to set the value of
		any of the curve's or the axes' properties (see section Reference,
		below). \cmd{property}s are always strings. The \cmd{value}s must be of
		the appropriate type.
	\item The pattern \cmd{\{x,\} y \{, property, value...\}} may be repeated
		any number of times.
		\begin{itemize}
			\item Curve settings are always set for the immediately
				preceding curve.
			\item Axes settings may be specified at any time,
				and in the case of repeated properties, the last one set is the
				one that is used.
		\end{itemize}
	\item Properties may take the following values: \cmd{plotstyle},
		\cmd{legend}, \cmd{color},
		\cmd{marker}, \cmd{linewidth}, \cmd{pointsize}, \cmd{title},
		\cmd{xlabel}, \cmd{ylabel}, \cmd{box}, \cmd{axis}.
	\item Supported plotstyles are \cmd{lines}, \cmd{linespoints},
		\cmd{points}, \cmd{impulses}, \cmd{dots} and \cmd{boxes}.
	\item plot() returns the handle of the figure that was plotted.
\end{itemize}

As an example, to plot an amplitude modulated signal and its envelope, we may
run the following code:

\begin{juliacode}
t = 0:0.0001:.15
carrier = cos(2pi*t*200)
modulator = 0.7+0.5*cos(2pi*t*15)
am = carrier.*modulator
plot(t,am,"color","blue","legend","AM DSB-SC","linewidth",1.5,
    t,modulator,"color","black","legend","Envelope",
    t,-modulator,"color","black","title","AM DSB-SC example",
    "xlabel","Time (s)","ylabel","Amplitude",
    "box","horizontal top left")
\end{juliacode}

\noindent which produces this plot:

\begin{center}
\includegraphics[width=12cm]{plotex}
\end{center}

\subsubsection{histogram()}

The \cmd{histogram()} function plots a single histogram in a figure. It has the
following format:

\cmd{histogram(\{h,\} y \{, "bins", bins\} \{, "norm", norm\}
\{, property, value...\})}

\begin{itemize}
	\item The optional argument \cmd{h} has the same meaning as in
		\cmd{plot()}.
	\item The histogram consists of boxes, where the height of each box is
		given by the number of elements of \cmd{y} that fall in a given range.
	\item \cmd{bins} specify the number of bins (boxes) that will be plotted
		(\cmd{bins} must be an integer larger than zero).
	\item If \cmd{norm} is specified, the histogram will be normalized, so that
		the area under the histogram is equal to \cmd{norm} (\cmd{norm} must be
		a real number larger than zero).
	\item The pairs \cmd{\{, property, value...\}} have the same meaning as in
		\cmd{plot()}.
	\item Properties may take the following values: \cmd{legend}, \cmd{color},
		\cmd{linewidth}, \cmd{title}, \cmd{xlabel}, \cmd{ylabel}, \cmd{box}.
	\item \cmd{histogram()} returns the handle of the figure that was plotted.
\end{itemize}

As an example, to plot an approximation of a Rayleigh density, we may run the
following code:

\begin{juliacode}
y = sqrt( randn(1000).^2 + randn(1000).^2 )
histogram(y,"bins",25,"norm",1,"color","blue","title","Rayleigh density (25 bins)")
\end{juliacode}

which produces this plot:

\begin{center}
	\includegraphics[width=12cm]{histoex}
\end{center}

\subsection{3-D plotting}

There is one 3-D plotting command, \cmd{surf()}. This command is intended for
plotting surfaces. Its format is as follows:

\cmd{surf(\{h,\} \{y, \{x,\}\} \{f|Z\} \{, property, value...\} \{...\})}

\begin{itemize}
	\item The optional argument \cmd{h} has the same meaning as in
		\cmd{plot()}.
	\item The \cmd{x} and \cmd{y} arguments have the same meaning as in
		\cmd{plot()}.
	\item The argument \cmd{f|Z} may be either a 2-D matrix \cmd{Z} or a
		function of \cmd{(x,y)}. If \cmd{Z} is provided, then its element
		\cmd{i,j} is assumed to be the z-coordinate associated with
		\cmd{(x[i],y[j])}. If \cmd{f} is provided, then \cmd{x} and \cmd{y} must
		be provided too, and the function \cmd{meshgrid()} will be used to
		calculate matrix \cmd{Z}.
	\item The pairs \cmd{\{, property, value...\}} have the same meaning as in
		\cmd{plot()}.
	\item Properties may take the following values: \cmd{plotstyle},
		\cmd{legend}, \cmd{color}, \cmd{marker}, \cmd{linewidth},
		\cmd{pointsize}, \cmd{title}, \cmd{xlabel}, \cmd{ylabel}, \cmd{zlabel},
		\cmd{box}.
	\item Supported plotstyles are \cmd{lines}, \cmd{linespoints},
		\cmd{points}, \cmd{impulses}, \cmd{dots} and \cmd{pm3d}.
\end{itemize}

As an example, to plot \cmd{f(x,y)=cos(x)*sin(y)} using points, one may use the
following code:

\begin{juliacode}
gnuplot_send("set view 67,25")
surf(-3:.1:3,-3:0.1:3,(x,y)->cos(x)*sin(y),"plotstyle","points",
"xlabel","coord 1","ylabel","coord 2","zlabel","coord 3",
"title","surf demo","color","blue")
\end{juliacode}

\noindent which produces this plot:

\begin{center}
\includegraphics[width=12cm]{surfex}
\end{center}

Note the use of \cmd{gnuplot\_send()} to set the view, which is something Gaston
doesn't support natively yet.

\subsection{Plotting images}

The command to plot images is \cmd{imagesc()}. This command plots a matrix as an
image. The format of the arguments is the following:

\cmd{imagesc(\{h,\} \{y, \{x,\}\} Z \{, "clim", clim\} \{, property, value...\})}

\begin{itemize}
	\item The optional argument \cmd{h} has the same meaning as in
		\cmd{plot()}.
	\item The \cmd{x} and \cmd{y} arguments have the same meaning as in
		\cmd{plot()}.
	\item \cmd{Z} is a matrix. If it is two-dimensional, then gnuplot's
		\cmd{image} plot style is used. In this case, gnuplot
		automatically adjusts the values in \cmd{Z} to fit the current palette. If it is three-dimensional, then
		the plotstyle \cmd{rgbimage} is used; in this case, all matrix elements
		are assumed to be between 0 and 255. \cmd{Z[:,:,1]} is assumed to be
		the image's red component, \cmd{Z[:,:,2]} the blue, and \cmd{Z[:,:,3]}
		the green.
	\item If the optional \cmd{clim} property is specified, then it must be
		followed by a two-element
		array \cmd{clim=[cmin cmax]}. The values of Z
		are scaled to the range \cmd{0:255} using the following logic:
		\begin{juliacode}
Z -= cmin
Z[Z<0] = 0
Z *= 255/(cmax-cmin)
Z[Z>255] = 255
		\end{juliacode}
	\item The pairs \cmd{\{, property, value...\}} have the same meaning as in
		\cmd{plot()}.
	\item Properties may take the following values:
		\cmd{title}, \cmd{xlabel}, \cmd{ylabel}.
	\item \cmd{imagesc()} returns the handle of the figure that was plotted.
\end{itemize}

It is important to understand how \cmd{imagesc()} interprets matrix \cmd{Z}.
The matrix is plotted such that the resulting image resembles the matrix as it
would normally be printed on screen. That is, element \cmd{Z[1,1]} (or
\cmd{Z[1,1,:]} for an RGB image) is plotted on the upper left-hand corner, and
matrix columns are plotted as image columns.

As an example, the following code:

\begin{juliacode}
z = zeros(10,10,3)
z[:,:,1] = 255*rand(10,10)
z[:,:,2] = 128*rand(10,10)+40
z[:,:,3] = 64*rand(10,10)+190
imagesc(z,"title","imagesc demo")
\end{juliacode}

produces a plot similar to this:

\begin{center}
	\includegraphics[width=12cm]{imagescex}
\end{center}

\section{Plotting with mid-level functions}
\label{midlevel}

In addition to the plotting functions described in the section above, Gaston
offers a ``mid-level'' set of functions that allow plots to be created
step-by-step.

Having this mid-level layer has two benefits. One is that this layer is more
flexible and allows direct control over all aspects of the plot. For instance,
using high-level functions it is not currently possible to plot more than one
histogram, or a histogram and another curve, on the same figure. The mid-level
layer allows such combinations. Another example is an algorithm that builds
figures step-by-step as data becomes available, instead of waiting until all
the data needed has been produced.

A second benefit is that this layer abstracts Gaston's internal graphics
representation from the high-level layer. This means Gaston's whole back-end
may change without affecting the high-level functions; only the mid-level layer
would have to be adapted.

Also, much of Gaston's error checking and argument validation is performed in
this layer.

Please note that there is a single mid-level plot command, which is
\cmd{llplot()}. According to the type of coordinates and plotstyle, it will
figure out how to plot a figure.

\subsection{2-D plotting}

Plotting proceeds in steps:
\begin{enumerate}
	\item Create or select a figure with \cmd{figure()} or \cmd{figure(i)},
		where \cmd{i} is a positive integer.
	\item Add a curve (a set of coordinates plus a plot configuration), with
		\cmd{addcoords(x,y,conf)}. Here, \cmd{x} and \cmd{y} are vectors, and
		\cmd{conf} configures the plot and line styles, markers, legend, color,
		etc. Repeat this step for each curve you wish to include
		in the figure.
	\item Add a configuration for the entire figure (axis), with
		\cmd{addconf(conf)}, where \cmd{conf} contains the figure
		configuration.
	\item Issue the \cmd{llplot()} command.
\end{enumerate}

A curve configuration is created as follows:
\begin{enumerate}
	\item Create a default configuration with \cmd{c = CurveConf()}.
	\item \cmd{c} is a structure, each of whose fields controls one aspect of
		the curve's configuration. These fields may be set individually.
		Available fields are: \cmd{legend}, \cmd{plotstyle}, \cmd{color},
		\cmd{marker}, \cmd{linewidth}, and \cmd{pointsize}. For instance, to
		change a curve's color, do\footnote{Directly changing a structure's
		fields, instead of using setter functions, may be seen as non-idiomatic
		or inelegant. In this case we have decided to do the simplest thing
		that might possibly work.}

\begin{juliacode}
c.color = "blue"
\end{juliacode}

See gnuplot's documentation and this manual's section \ref{refer} to see the
range of valid options.

\end{enumerate}

A figure (axis) configuration is created as follows:
\begin{enumerate}
	\item Create a default configuration with \cmd{a = AxesConf()}
	\item Just as in the case of a curve configuration, \cmd{a} is a structure
		whose fields may be modified. Available fields are: \cmd{title},
		\cmd{xlabel}, \cmd{ylabel}, \cmd{zlabel}, \cmd{box}, \cmd{axis}.
\end{enumerate}

Several rules apply:
\begin{itemize}
	\item You can create as many figures, each with as many curves, as desired.
	\item Whenever possible, missing coordinate data will be inferred. For
		example, calling \cmd{addcoords()} with a single vector \cmd{y}
		will assume the \cmd{x} coordinate is \cmd{1:length(y)} and set up the
		default plot configuration.
	\item If you call \cmd{addcoords()} with matrix arguments, each column will
		be interpreted as a different plot.
	\item Calling \cmd{addcoords()} will create a new figure if none have been
		created yet.
	\item Calling \cmd{llplot()} without an axis configuration will just use one
		by default.
	\item Gnuplot only provides mouse interaction support for the current
		figure. To use the mouse in a previously created figure \cmd{i}, just
		issue command \cmd{figure(i)}. This will also bring the figure to the
		front.
\end{itemize}

\subsubsection{2-D plotting styles}

Besides simply plotting a set of \cmd{x} and \cmd{y} coordinates, Gaston
supports other kinds of plots.

\textbf{Error bars and lines.} Gaston supports gnuplot's \cmd{errorbars} and
\cmd{errorlines} plot styles. To add error bars or lines, follow
\cmd{addcoords()} with a call to \cmd{adderror()} with one or two extra
coordinates. If two coordinates are provided, they are interpreted as \cmd{ylow}
and \cmd{yhigh} (following gnuplot's terminology). If only one is provided, it
is interpreted as \cmd{ydelta}. Remember to configure the plotstyle
accordingly.

\textbf{Histograms.} To plot the histogram of a data vector \cmd{data} with
\cmd{b} bins, first use the auxiliary function \cmd{(x,y) = histdata(data,b)}
to create \cmd{x} and \cmd{y} coordinates that may be plotted with the
\cmd{boxes} plotstyle.

\subsection{3-D plotting}

The same rules apply, except that \cmd{addcoords()} should be called as
\cmd{addcoords(x,y,Z)}, where \cmd{Z} is a matrix whose element \cmd{j,k}
corresponds to some function of \cmd{x[j],y[k]}.

For convenience, a function \cmd{Z = meshgrid(x,y,f)} is provided. Called with
\cmd{x}, \cmd{y} coordinates and a function \cmd{f}, it will return a matrix
that may be used to plot \cmd{f}.

\subsection{Image plotting}

Two image plotstyles are supported: \cmd{image} and \cmd{rbgimage}. Plotting
images is very similar to 3-D plotting, the only differences being the
plotstyle and the way the coordinate data is interpreted.

\textbf{Scalar image.} To plot a 2-D matrix \cmd{Z} as an image, set the
plotstyle to \cmd{image}. The color of each image element is given by the
matrix values and the current colormap.

\textbf{RGB image.} To plot an RGB image, the matrix \cmd{Z} must be three
dimensional, and the plotstyle must be set to \cmd{rgbimage}.  \cmd{Z[:,:,1]}
is assumed to be the image's red component, \cmd{Z[:,:,2]} the blue, and
\cmd{Z[:,:,3]} the green.

\section{Printing to a file}
\label{s:print}

Gaston supports plotting a figure to a file instead of the screen
(\textit{printing} a figure). Currently supported are PDF, PNG,  SVG and GIF
files. There are two ways to print figures.

\subsection{Printing a single figure}

If you have a figure on screen that you want to print, you may use the
\cmd{printfigure()} command. The following example shows hows to print a figure
to a PNG file:

\begin{juliacode}
plot(sin(-pi:0.01:pi))
set_filename("test.png")
printfigure("png")
\end{juliacode}

If the filename is not set, output will be sent to the screen.

Some properties of the printed figures can be controlled using the following
functions:

\cmd{set\_print\_color()}: Use \cmd{"mono"} for printing monochromatic figures,
and \cmd{"color"} for color figures.

\cmd{set\_print\_fontface()}: Name of font to use for all text in the figure. Use
\cmd{fc-list} to find fonts installed on your system.

\cmd{set\_print\_fontsize()}: Font size.

\cmd{set\_print\_fontscale()}: Gnuplot scales the fonts by this factor (even
if the font size has been specified).

\cmd{set\_print\_linewidth()}: Controls the plot's linewidth. This is useful
because in most cases, gnuplot's default linewidth is too thin.

\cmd{set\_print\_size()}: Sets the plot size. The size is specified differently
for various terminals, see table below.

The following table provides more details on each function.

\begin{center}
\begin{tabular}{lp{4cm}ll}
	\toprule
	\textbf{Command} & \textbf{Values} & \textbf{Default} & \textbf{File types}
	\\
	\midrule
	\cmd{set\_print\_color()} & \cmd{"mono"}, \cmd{"color"} & \cmd{"color"} &
	PDF, PNG \\
	\cmd{set\_print\_fontface()} & Font name (a string); font must be present
	in the system & \cmd{Sans} & All \\
	\cmd{set\_print\_fontsize} & Positive number & 12 & All \\
	\cmd{set\_print\_fontscale} & Positive number & 0.5 & PDF, PNG, GIF \\
	\cmd{set\_print\_linewidth} & Positive number & 1 & All \\
	\cmd{set\_print\_size()} & For GIF, SVG, PNG, EPS and PDF: \cmd{"X,Y"}
	specifies a plot of
	\cmd{X} times \cmd{Y} pixels. In addition, for PNG, EPS and PDF, dimensions
	may be specified as \cmd{"Xin,Yin"} or \cmd{"Xcm,Ycm"} & \cmd{"5in,3in"} &
	All \\
	\bottomrule
\end{tabular}
\end{center}

\subsection{Always print to files}

If you want regular plot commands to print to files instead of showing the
plots on the screen, just set the terminal type and filename at the start of
your session. For example, Gaston may be used in a webserver that reads SVG
plots from a pipe; this may be set up as follows:
\begin{juliacode}
set_terminal("svg")
set_filename("|serverpipe")
plot(sin(-3:0.01:3),"title","SVG test")
\end{juliacode}
The plot command in the last line will cause the SVG data representing the
figure to be sent to the pipe \cmd{serverpipe}.

\section{Reference}
\label{refer}

Note: In this section, at least superficial knowledge of Julia and gnuplot is
assumed. Please refer to the respective documentation for more details.

\subsection{Curve configuration}

A given curve's configuration is stored in a structure of type \cmd{CurveConf}.
This structure has the following fields:

{\small
\begin{center}
\begin{tabular}{lll}
	\toprule
	\textbf{Field} & \multicolumn{1}{c}{\textbf{Notes}} &
	\multicolumn{1}{c}{\textbf{Meaning in gnuplot}} \\
	\midrule
	\cmd{legend} & The text that appears in the legend box. & Argument of
	\cmd{title}. \\
	\cmd{plotstyle} & How the curve will be plotted. & Argument of \cmd{with}.
	\\
	\cmd{color} & The curve color. & Argument of \cmd{linecolor rgb}. \\
	\cmd{marker} & The marker name. & Argument of \cmd{pointtype}. \\
	\cmd{linewidth} & The curve line width; must be a positive number. &
	Argument of \cmd{linewidth}. \\
	\cmd{pointsize} & The marker size; must be a positive number. & Argument
	of \cmd{pointsize}. \\
	\bottomrule
\end{tabular}
\end{center}}

The types, default and valid values for each field are given in the following
table.

{\small
\begin{center}
	\begin{tabular}{lp{1.5cm}p{2cm}p{7.5cm}}
	\toprule
	\textbf{Field} & \textbf{Type} & \textbf{Default value} & \textbf{Valid values} \\
	\midrule
	\cmd{legend} & \cmd{String} & \cmd{""} & Any string. \\
	\cmd{plotstyle} & \cmd{String} & \cmd{lines} & \cmd{lines}, \cmd{linespoints},
	\cmd{points}, \cmd{impulses}, \cmd{errorbars}, \cmd{errorlines},
	\cmd{pm3d}, \cmd{boxes}, \cmd{image}, \cmd{rgbimage}. \\
	\cmd{color} & \cmd{String} & \cmd{""} & \cmd{""}, any gnuplot color name,
	or a color specified in a string in the format \cmd{"\#RRGGBB"}. \\
	\cmd{marker} & \cmd{String} & \cmd{""} & \cmd{""}, \cmd{+}, \cmd{x}, \cmd{*}, \cmd{esquare},
	\cmd{fsquare}, \cmd{ecircle}, \cmd{fcircle}, \cmd{etrianup},
	\cmd{ftrianup}, \cmd{etriandn}, \cmd{ftriandn}, \cmd{edmd}, \cmd{fdmd} (run
	\cmd{test} in gnuplot terminal). \\
	\cmd{linewidth} & \cmd{Real} & 1 & Any real number \\
	\cmd{pointsize} & \cmd{Real} & 0.5 & Any real number \\
	\bottomrule
\end{tabular}
\end{center}}

Notes: When \cmd{color} or \cmd{marker} are set to the empty string, gnuplot will use
its own default values. Gaston does not verify that the color name provided is
valid. You can see a list of valid color names running \cmd{show colornames} in
a gnuplot terminal.

The following table lists the marker names and corresponding symbols.

{\small
\begin{center}
\begin{tabular}{lc}
	\toprule
	\textbf{Marker name} & \textbf{Symbol} \\
	\midrule
	\cmd{+} & + \\
	\cmd{x} & $\times$ \\
	\cmd{*} & $\ast$ \\
	\cmd{esquare} & $\square$ \\
	\cmd{fsquare} & $\blacksquare$ \\
	\cmd{ecircle} & $\circ$ \\
	\cmd{fcircle} & ● \\
	\cmd{etrianup} & △ \\
	\cmd{ftrianup} & ▲ \\
	\cmd{etriandn} & ▽ \\
	\cmd{ftriandn} & ▼ \\
	\cmd{edmd} & ◇ \\
	\cmd{fdmd} & ◆ \\
	\bottomrule
\end{tabular}
\end{center}}

\subsection{Axes configuration}

There may be only one configuration per figure. This configuration is stored in
a structure of type \cmd{AxesConf}, which has the following fields:

{\small
\begin{center}
\begin{tabular}{lll}
	\toprule
	\textbf{Field} & \multicolumn{1}{c}{\textbf{Notes}} &
	\multicolumn{1}{c}{\textbf{Meaning in gnuplot}} \\
	\midrule
	\cmd{title} & The figure's title & \cmd{title-spec} \\
	\cmd{xlabel} & Abscissa's label & Argument to \cmd{set xlabel} \\
	\cmd{ylabel} & Ordinate's label & Argument to \cmd{set ylabel} \\
	\cmd{zlabel} & Z-axis label & Argument to \cmd{set zlabel} \\
	\cmd{box} & Legend box configuration & Argument to \cmd{set key} \\
	\cmd{axis} & Axis scale & Argument to \cmd{set logscale} \\
	\bottomrule
\end{tabular}
\end{center}}

The types, default and valid values for each field are given in the following
table.

{\small
\begin{center}
	\begin{tabular}{lp{1.5cm}p{2cm}p{7.5cm}}
	\toprule
	\textbf{Field} & \textbf{Type} & \textbf{Default value} & \textbf{Valid values} \\
	\midrule
	\cmd{title} & \cmd{String} & \cmd{"Untitled"} & Any string \\
	\cmd{xlabel} & \cmd{String} & \cmd{"x"} & Any string \\
	\cmd{ylabel} & \cmd{String} & \cmd{"y"} & Any string \\
	\cmd{zlabel} & \cmd{String} & \cmd{"z"} & Any string \\
	\cmd{box} & \cmd{String} & \cmd{"inside vertical right top"} & Any valid
	string \\
	\cmd{axis} & \cmd{String} & \cmd{""} & \cmd{""}, \cmd{normal},
	\cmd{semilogx}, \cmd{semilogy}, \cmd{loglog}  \\
	\bottomrule
\end{tabular}
\end{center}}

Notes: Gaston does not verify that \cmd{box} contains a valid \cmd{set key}
argument. The \cmd{axis} values follow Matlab's conventions for logscale axes;
Gaston translates them to gnuplot's equivalents.

\subsection{Changing default configuration}

Gaston provides functions to change the default values listed above. There is
one function per each property, both for curves and for axes. For example, a
Spanish speaker may wish to change the default value for figure titles from
``Untitled'' to ``Sin título''. This is achieved by
\begin{juliacode}
set_default_title("Sin título")
\end{juliacode}
and, from that point on, any figure with an unspecified title will be titled
thus.

Functions to change the defaults have the form \cmd{set\_default\_*(arg)},
where \texttt{*} is the property name and \cmd{arg} is the new default
value (must be of the appropriate type).

\subsection{Plot types}

In this section, we describe how Gaston decides which kind of plot to produce
(2-d, 3-d, or image), based on the available coordinates and specified plot
style.

In the following table, a check mark (\cm) means that the coordinate has been
specified by the user in either a mid-level or high-level command (\cmd{x}
coordinates, if not specified, are calculated by Gaston, and are not included
in the following table. The same applies to \cmd{yhigh}).

{\small
\begin{center}
	\begin{tabular}{lcccl}
	\toprule
	\textbf{plotstyle} & \textbf{y} & \textbf{Z} & \textbf{ylow} &
	\textbf{Gnuplot command} \\
	\midrule
	\multirow{2}{*}{\cmd{lines}}
	& \cm &     &  & \cmd{plot with lines} \\
	& \cm & \cm &  & \cmd{splot with lines} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{linespoints}}
	& \cm &     &  & \cmd{plot with linespoints} \\
	& \cm & \cm &  & \cmd{splot with linespoints} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{points}}
	& \cm &     &  & \cmd{plot with points} \\
	& \cm & \cm &  & \cmd{splot with points} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{impulses}}
	& \cm &     &  & \cmd{plot with impulses} \\
	& \cm & \cm &  & \cmd{splot with impulses} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{dots}}
	& \cm &     &  & \cmd{plot with dots} \\
	& \cm & \cm &  & \cmd{splot with dots} \\
	\cmidrule(r){2-5}
	\cmd{boxes}       & \cm &  &     & \cmd{plot with boxes} \\
	\cmd{errorbars}   & \cm &  & \cm & \cmd{plot with errorbars} \\
	\cmd{errorlines}  & \cm &  & \cm & \cmd{plot with errorlines} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{pm3d}}
	&     & \cm &  & \cmd{splot with pm3d} \\
	& \cm & \cm &  & \cmd{splot with pm3d} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{image}}
	&     & \cm &  & \cmd{plot with image} \\
	& \cm & \cm &  & \cmd{plot with image} \\
	\cmidrule(r){2-5}
	\multirow{2}{*}{\cmd{rgbimage}}
	&     & \cm &  & \cmd{plot with rgbimage} \\
	& \cm & \cm &  & \cmd{plot with rgbimage} \\
	\bottomrule
\end{tabular}
\end{center}}

Any other combination of coordinates and plotstyle produces undefined behavior
-- we try to identify invalid combinations and produce an error, but this is
not guaranteed. Please note that mixing 2-d and 3-d plots on the same figure
also produces undefined behavior.

\subsection{Types}

Gaston defines several new types. All types are defined in file
\cmd{gaston\_types.jl}.

\begin{center}
	\begin{tabular}{lp{8cm}}
		\toprule
		\textbf{Name} & \textbf{Purpose} \\
		\midrule
		GnuplotState & Structure that stores the state of gnuplot process. \\
		GastonConfig & Structure that stores Gaston's configuration. \\
		CurveConf & Configuration of a single curve. \\
		AxesConf & Configuration of a figure. \\
		CurveData & A set of coordinates and its configuration. \\
		Figure & Structure that stores a set of curves, a configuration and a
		handle. \\
		Coord & A variable of this type may be used as an abscissa or ordinate. \\
		\bottomrule
	\end{tabular}
\end{center}

\section{Notes to the user}

This section gathers some notes that may be useful to Gaston users and don't
fit anywhere else on this document.

\subsection{Scripting}
When including Gaston plotting commands in a script, it is necessary to take
steps to avoid race conditions between Gaston and Gnuplot. These race
conditions arise for the following reasons.

Gaston writes the data to be plotted to a file, and then issues plot commands
that point Gnuplot to the correct file. However, communication between Gaston
and Gnuplot occurs asynchronously. This means that, when Gaston communicates a
command to Gnuplot, it writes the command to a pipe and then continues with its
normal execution.  If two consecutive (or near) plot commands write plot data
to the same file, it is possible that the file will be overwritten while
Gnuplot was still reading it.

When this happens, the plot command will apparently succeed, but no plot will
be produced, and Gnuplot will issue error messages that appear on the screen.
If this happens, it may be necessary to insert \cmd{sleep(x)} commands between
the plotting commands. Here, \cmd{x} is the number of seconds to wait; this
number will change depending on the particular system's speed. A value
of 0.1 could be more than enough on modern machines.

A solution to this problem is under investigation.

\section{Testing}
\label{tests}

Gaston includes a unit test framework that verifies the program's
functionality. To run all tests, run:
\begin{juliacode}
gaston_tests()
\end{juliacode}
This function will run all tests and print a summary to the screen.

There is a peculiarity to the tests that must be taken into account. When
plotting a figure, Gaston will write the relevant data to a file and then issue
commands to gnuplot through a pipe. These two actions are sequential but
asynchronous. When plotting many figures in quick succession, it may happen
that a data file is updated before gnuplot has processed it. In this case, the
commands that gnuplot receives are no longer correlated with the data file, and
the commands may fail.

When running tests, this is exactly what may happen. This is prevented by
inserting a delay between tests, using a system call to \cmd{sleep} (see macros
\cmd{test\_success} and \cmd{test\_error} in file \cmd{gaston\_test.jl}). The
sleep amounts may have to be increased for more complex tests or for slower
computers.  A more robust solution may be implemented in future versions of
Gaston.

\subsection{Adding tests}

New tests are easy to add. To test code that should complete successfully,
use the macro \cmd{@test\_success}, as in this example:
\begin{juliacode}
@test_success plot(-3:3,"title","test")
\end{juliacode}
This code should be added to function \cmd{run\_tests\_success()}. To test code
that should produce an error, use the macro \cmd{@test\_error} inside function
\cmd{run\_tests\_error()}.

\end{document}
