updates to the manual, some comments on TODOs for 0.6

[PyX.git] / manual / graph.tex

\chapter{Graphs\label{graph}}
\section{Introduction}
\PyX{} can be used for data and function plotting. At present only
x-y-graphs are supported. However, the component architecture of the
graph system described in section \ref{graph:components} allows for
additional graph geometries while reusing most of the existing
components.

Creating a graph splits into two basic steps. First you have to create
a graph instance. The most simples form would look like:
\begin{verbatim}
from pyx import *
g = graph.graphxy(width=8)
\end{verbatim}
The graph instance \code{g} created in this example can than be used
to actually plot something into the graph. Suppose you have some data
in a file \file{graph.dat} you want to plot. The content of the file
could look like:
\verbatiminput{graph.dat}
To plot these data into the graph \code{g} you must perform:
\begin{verbatim}
g.plot(graph.data.file("graph.dat", x=1, y=2))
\end{verbatim}
The method \method{plot()} takes the data to be plotted and optionally
a graph style to be used to plot the data. When no style is provided,
a default style defined by the data instance is used. For data read
from a file by an instance of \class{graph.data.file}, the default are
symbols. When instantiating \class{graph.data.file}, you not only
specify the file name, but also a mapping from columns to axis names
and other information the style might use (\emph{e.g.} data for error
bars for the symbol style).

While the graph is already created by that, we still need to perform a
write of the result into a file. Since the graph instance is a canvas,
we can just call its \method{writeEPSfile()} method.
\begin{verbatim}
g.writeEPSfile("graph")
\end{verbatim}
will create the file \file{graph.eps} as shown in
figure~\ref{fig:graph}.

\begin{figure}[ht]
\centerline{\includegraphics{graph}}
\caption{A minimalistic plot for the data from file \file{graph.dat}.}
\label{fig:graph}
\end{figure}

Instead of plotting data from a file, we could also use other data
sources like functions. The procedure would be as before, but we would
place different data into \method{plot()}:
\begin{verbatim}
g.plot(graph.data.function("y=x**2"))
\end{verbatim}
You can plot different data into a single graph by calling the
\method{plot()} several times. Thus the command above might just be
inserted before \method{writeEPSfile()} of the original example.
Note that a call to \method{plot()} will fail once you forced the
graph to ``finish'' itself. This happens automatically, when you
write the output. Thus it is not an option to call \method{plot()}
after \method{writeEPSfile()}. The topic of the finalization of a
graph is addressed in more detail in section~\ref{graph:graph}. As
you can see in figure~\ref{fig:graph2}, a function is plotted as a
line by default.
\begin{figure}[ht]
\centerline{\includegraphics{graph2}}
\caption{Plotting data from a file together with a function.}
\label{fig:graph2}
\end{figure}

\section{Component architecture \label{graph:components}}

Creating a graph involves a variety of tasks, which thus can be
separated into components without significant additional costs.
This structure manifests itself also in the \PyX{} source, where there
are different modules for the different tasks. They interact by some
welldefined interfaces. They certainly has to be completed and
stabilized in its details, but the basic structure came up in the
continuous development quite clearly. The basic parts of a graph are:

\begin{definitions}
\term{graph}
  Defines the geometry of the graph by means of graph coordinates with
  range [0:1]. Keeps lists of plotted data, axes \emph{etc.}
\term{data}
  Produces or prepare data to be plotted in graphs.
\term{style}
  Performs the plotting of the data into the graph. It get data,
  convert them via the axes into graph coordinates and uses the graph
  to finally plot the data with respect to the graph geometry methods.
\term{key}
  Responsible for the graph keys.
\term{axis}
  Creates axes for the graph, which take care of the mapping from data
  values to graph coordinates. Because axes are also responsible for
  creating ticks and labels, showing up in the graph themselfs and
  other things, this task is splitted into several independend
  subtasks. Axes are discussed separately in chapter~\ref{axis}.
\end{definitions}

\section{X-Y-Graphs\label{graph:graph}}

\declaremodule{}{graph.graph}
\modulesynopsis{Graph geometry}

The class \class{graphxy} is part of the module \module{graph.graph}.
However, there is a shortcut to access this class via
\code{graph.graphxy}.

\begin{classdesc}{graphxy}{xpos=0, ypos=0, width=None, height=None,
ratio=goldenmean, key=None, backgroundattrs=None, axesdist="0.8 cm",
**axes}
  This class provides a x-y-graph. A graph instance is also a full
  functional canvas.

  The position of the graph on its own canvas is specified by
  \var{xpos} and \var{ypos}. The size of the graph is specified by
  \var{width}, \var{height}, and \var{ratio}. These parameters define
  the size of the graph area not taking into account the additional
  space needed for the axes. Note that you have to specify at least
  \var{width} or \var{height}. \var{ratio} will be used as the ratio
  between \var{width} and \var{height} when only one of these are
  provided.

  \var{key} can be set to a \class{graph.key.key} instance to create
  an automatic graph key. \code{None} omits the graph key.

  \var{backgroundattrs} is a list of attributes for drawing the
  background of the graph. Allowed are decorators, strokestyles, and
  fillstyles. \code{None} disables background drawing.

  \var{axisdist} is the distance between axes drawn at the same side
  of a graph.

  \var{**axes} recieves axes instances. Allowed keywords (axes names)
  are \code{x}, \code{x2}, \code{x3}, \emph{etc.} and \code{y},
  \code{y2}, \code{y3}, \emph{etc.} When not providing a \code{x} or
  \code{y} axis, linear axes instances will be used automatically.
  When not providing a \code{x2} or \code{y2} axis, linked axes to the
  \code{x} and \code{y} axes are created automatically. You may set
  those axes to \code{None} to disable the automatic creation of axes.
  The even numbered axes are plotted at the top (\code{y} axes) and
  right (\code{x} axes) while the others are plotted at the bottom
  (\code{x} axes) and left (\code{y} axes) in ascending order each.
  Axes instances should be used once only.
\end{classdesc}

Some instance attributes might be usefull for outside read-access.
Those are:

\begin{memberdesc}{axes}
  A dictionary mapping axes names to the \class{axis} instances.
\end{memberdesc}

\begin{memberdesc}{axespos}
  A dictionary mapping axes names to the \class{axispos} instances.
\end{memberdesc}

To actually plot something into the graph, the following instance
method \method{plot()} is provided:

\begin{methoddesc}{plot}{data, style=None}
  Adds \var{data} to the list of data to be plotted. Sets \var{style}
  the be used for plotting the data. When \var{style} is \code{None},
  the default style for the data as provided by \var{data} is used.

  \var{data} should be an instance of any of the data described in
  section~\ref{graph:data}. This instance should used once only.

  When a style is used several times within the same graph instance,
  it is kindly asked by the graph to iterate its appearence. Its up
  to the style how this is performed.

  Instead of calling the plot method several times with different
  \var{data} but the same style, you can use a list (or something
  iterateable) for \var{data}.
\end{methoddesc}

While a graph instance only collects data initially, at a certain
point it must create the whole plot. Once this is done, further calls
of \method{plot()} will fail. Usually you do not need to take care
about the finalization of the graph, because it happens automatically
once you write the plot into a file. However, sometime position
methods (described below) are nice to be accessable. For that, at
least the layout of the graph must be done. By calling the
\method{do}-methods yourself you can also alter the order in which
the graph is plotted. Multiple calls the any of the
\method{do}-methods have no effect (only the first call counts). The
orginal order in which the \method{do}-methods are called is:

\begin{methoddesc}{dolayout}{}
  Fixes the layout of the graph. As part of this work, the ranges of
  the axes are fitted to the data when the axes ranges are allowed to
  addjust themselfs to the data ranges. The other \method{do}-methods
  ensure, that this method is always called first.
\end{methoddesc}

\begin{methoddesc}{dobackground}{}
  Draws the background.
\end{methoddesc}

\begin{methoddesc}{doaxes}{}
  Inserts the axes.
\end{methoddesc}

\begin{methoddesc}{dodata}{}
  Plots the data.
\end{methoddesc}

\begin{methoddesc}{dokey}{}
  Inserts the graph key.
\end{methoddesc}

The graph provides some methods to access its geometry:

\begin{methoddesc}{pos}{x, y, xaxis=None, yaxis=None}
  Returns the given point at \var{x} and \var{y} as a tuple
  \code{(xpos, ypos)} at the graph canvas. \var{x} and \var{y} are
  axis data values for the two axes \var{xaxis} and \var{yaxis}. When
  \var{xaxis} or \var{yaxis} are \code{None}, the axes with names
  \code{x} and \code{y} are used. This method fails if called before
  \method{dolayout()}.
\end{methoddesc}

\begin{methoddesc}{vpos}{vx, vy}
  Returns the given point at \var{vx} and \var{vy} as a tuple
  \code{(xpos, ypos)} at the graph canvas. \var{vx} and \var{vy} are
  graph coordinates with range [0:1].
\end{methoddesc}

\begin{methoddesc}{vgeodesic}{vx1, vy1, vx2, vy2}
  Returns the geodesic between points \var{vx1}, \var{vy1} and
  \var{vx1}, \var{vy1} as a path. All parameters are in graph
  coordinates with range [0:1]. For \class{graphxy} this is a straight
  line.
\end{methoddesc}

\begin{methoddesc}{vgeodesic\_el}{vx1, vy1, vx2, vy2}
  Like \method{vgeodesic()} but this method returns the path element to
  connect the two points.
\end{methoddesc}

\section{Data\label{graph:data}}

\declaremodule{}{graph.data}
\modulesynopsis{Graph data}

The following classes provide data for the \method{plot()} method of a
graph. The classes are implemented in \module{graph.data}.

\begin{classdesc}{file}{filename,
                        commentpattern=defaultcommentpattern,
                        columnpattern=defaultcolumnpattern,
                        stringpattern=defaultstringpattern,
                        skiphead=0, skiptail=0, every=1, title=notitle,
                        parser=dataparser(), context=\{\}, **columns}
  This class reads data from a file and makes them available to the
  graph system. \var{filename} is the name of the file to be read.
  The data should be organized in columns.

  The arguments \var{commentpattern}, \var{columnpattern}, and
  \var{stringpattern} are responsible for identifying the data in each
  line of the file. Lines matching \var{commentpattern} are ignored
  except for the column name search of the last non-emtpy comment line
  before the data. By default a line starting with one of the
  characters \character{\#}, \character{\%}, or \character{!} are
  treated as comments. A line is analysed by repeatingly matching
  \var{stringpattern} and, whenever the stringpattern does not match
  by \var{columnpattern}. When the \var{stringpattern} matches, the
  result is taken as the value for the next column without further
  transformations. When \var{columnpattern} matches, it is tried to
  convert the result to a float. When this fails the result is taken
  as a string as well. By default, you can write strings with spaces
  surrounded by \character{\textquotedbl} immediately surrounded by
  spaces or begin/end of line in the data file. Otherwise
  \character{\textquotedbl} is not taken to be special.

  \var{skiphead} and \var{skipfoot} are numbers of data lines to be
  ignored at the beginning and end of the file while \var{every}
  selects only every \var{every} line from the data.

  \var{title} is the title of the data to be used in the graph key. A
  default title is constructed out of \var{filename} and
  \var{**columns}. You may set \var{title} to \code{None} to disable
  the title.

  \var{parser} is the parser for mathematical expression provided in
  \var{**columns}. When in doubt, this is probably uninteresting for
  you. \var{context} allows for accessing external variables and
  functions when evaluating mathematical expressions for columns. As
  an example you may use \code{context=locals()} or something similar.

  Finally, \var{columns} defines the data columns. To make it a bit
  more complicated, there are file column names and new created data
  column names, namely the keywords of \var{**columns}. File column
  names occure when the data file contains a comment line immediately
  in front of the data. This line will be parsed skipping the comment
  character (even if it occures multiple times) as if it would be
  regular data, but it will not be converted to floats even if it
  would be possible to convert them. The values of \var{**columns} can
  refer to column numbers in the file (starting with \code{1}). The
  column \code{0} is also available and contains the line number
  starting from \code{1} not counting comment lines. Furthermore
  values of \var{**columns} can be strings: file column names or
  mathematical expressions. To refer to columns within mathematical
  expressions you can also use file column names when they are valid
  variable names or by the syntax \code{\$\textless
  number\textgreater} or even \code{\$(\textless
  expression\textgreater)}, where \code{\textless number\textgreater}
  is a non-negative integer and \code{\textless
  expression\textgreater} a valid mathematical expression itself. For
  the later negative numbers count the columns from the end.
  Example:
  \begin{verbatim}
graph.data.file("test.dat", a=1, b="B", c="2*B+$3")
  \end{verbatim}
  with \file{test.dat} looking like:
  \begin{verbatim}
# A   B C
1.234 1 2
5.678 3 4
  \end{verbatim}
  The columns with name \samp{a}, \samp{b}, \samp{c} will become
  \samp{[1.234, 5.678]}, \samp{[1.0, 3.0]}, and \samp{[4.0, 10.0]},
  respectively.

  When creating the several data instances accessing the same file,
  the file is read only once. There is an inherent caching of the
  file contents.
\end{classdesc}

For the sake of completeness the default patterns:

\begin{memberdesc}{defaultcommentpattern}
  \code{re.compile(r\textquotedbl (\#+|!+|\%+)\e s*\textquotedbl)}
\end{memberdesc}

\begin{memberdesc}{defaultcolumnpattern}
  \code{re.compile(r\textquotedbl\e \textquotedbl(.*?)\e \textquotedbl(\e s+|\$)\textquotedbl)}
\end{memberdesc}

\begin{memberdesc}{defaultstringpattern}
  \code{re.compile(r\textquotedbl(.*?)(\e s+|\$)\textquotedbl)}
\end{memberdesc}

\begin{classdesc}{function}{expression, title=notitle,
                            min=None, max=None, points=100,
                            parser=mathtree.parser(),
                            context=\{\}}
  This class creates graph data from a function. \var{expression} is
  the mathematical expression of the function. It must also contain
  the result variable name by assignment. Thus a typical example looks
  like \samp{y=sin(x)}.

  \var{title} is the title of the data to be used in the graph key. By
  default \var{expression} is used. You may set \var{title} to
  \code{None} to disable the title.

  \var{min} and \var{max} give the range of the variable. If not set
  the range spans the hole axis range. The axis range might be set
  explicitly or implicitly by ranges of other data. \var{points} is
  the number of points for which the function is calculated. The
  points are lineary choosen in terms of graph coordinates.

  \var{parser} is the parser for the mathematical expression. When in
  doubt, this is probably uninteresting for you. \var{context} allows
  for accessing external variables and functions. As an example you
  may use \code{context=locals()} or something similar.

  Note when accessing external variables: When doing so, at first it
  renders unclear, which of the variables should be used as the
  dependent variable. The solution is, that there should be exactly
  one variable, which is a valid and used axis name.
  Example:
  \begin{verbatim}
  [graph.data.function("y=x**i", context=locals()) for i in range(1, 5)]
  \end{verbatim}
  The result of this expression could just be passed to a graphs
  \method{plot()} method, since not only data instances but also lists
  of data instances are allowed.
\end{classdesc}

\begin{classdesc}{paramfunction}{varname, min, max, expression,
                                 title=notitle, points=100,
                                 parser=mathtree.parser(),
                                 context=\{\}}
  This class creates graph data from a parametric function.
  \var{varname} is the parameter of the function. \var{min} and
  \var{max} give the range for that variable. \var{points} is the
  number of points for which the function is calculated. The points
  are choosen lineary in terms of the parameter.

  \var{expression} is the mathematical expression for the parametric
  function. It contains an assignment of a tuple of functions to a
  tuple of variables.

  \var{title} is the title of the data to be used in the graph key. By
  default \var{expression} is used. You may set \var{title} to
  \code{None} to disable the title.

  \var{parser} is the parser for mathematical expression. When in
  doubt, this is probably uninteresting for you. \var{context} allows
  for accessing external variables and functions. As an example you
  may use \code{context=locals()} or something similar.
\end{classdesc}

\begin{classdesc}{list}{points, title="user provided list",
                        maxcolumns=None, addlinenumbers=1, **columns}
  This class creates graph data from external provided data.
  \var{points} is a list of lines, where each line is a list of data
  values for the columns.

  \var{title} is the title of the data to be used in the graph key.

  \var{maxcolumn} is the number of columns in the points list. If set
  to \code{None}, the number of columns will be calculated by cycling
  through the points. Each element of \var{points}, \emph{i.e.} each
  line, will be checked and adjusted to the number of columns.

  \var{addlinenumbers} is a boolean indicating whether line numbers
  should be added or not. Note that the line numbers are storred in
  column \code{0}. A transformation (see \class{data} below) will
  always keep the first column. When not adding line numbers, you
  should be aware, that the numbering in \var{**columns} becomes
  different form the usual case, where the first column containing
  data (not the line number) has column number \code{1}.

  The keywords of \var{**columns} become the data column names. The
  values are the column numbers starting from one, when
  \var{addlinenumbers} is turned on (the zeroth column is the line
  number then), while the column numbers starts from zero, when
  \var{addlinenumbers} is switched off.
\end{classdesc}

\begin{classdesc}{data}{data, title=notitle, parser=dataparser(),
                        context={}, **columns}
  This class provides graph data out of other graph data. \var{data}
  is the source of the data. All other paramters work like the equally
  called parameters in \class{graph.data.file}. Indeed, the later is
  build on top of this class by reading the file and caching its
  contents in a \class{graph.data.list} instance. The columns are then
  selected by creating new data out of the existing data. Note that
  the data itself is not copied as long as no new columns need to be
  calculated.
\end{classdesc}

\begin{classdesc}{conffile}{filename, title=notitle,
                            parser=dataparser(), context={},
                            **columns}
  This class reads data from a config file with the file name
  \var{filename}. The format of a config file is described within the
  documentation of the \module{ConfigParser} module of the Python
  Standard Library.

  Each section of the config file becomes a data line. The options in
  a section are the columns. The name of the options will be used as
  file column names. All other parameters work as in
  \var{graph.data.file} and \var{graph.data.data} since they all use
  the same code.
\end{classdesc}

\section{Styles\label{graph:style}}

\declaremodule{}{graph.style}
\modulesynopsis{Graph style}

Please note that we're talking about graph styles here. Those are
responsible for plotting symbols, lines, bars and whatever else into a
graph. Do not mix it up with path styles like the line width, the line
style (solid, dashed, dotted \emph{etc.}) and others.

The following classes provide styles to be used at the \method{plot()}
method of a graph. The classes are implemented in \module{graph.style}.

\begin{classdesc}{symbolline}{symbol=changecross, size="0.2 cm",
                              errorscale=0.5, symbolattrs=[],
                              errorbarattrs=[], lineattrs=[],
                              epsilon=1e-10}
  This class is a style for plot symbols, lines and errorbars into a
  graph. \var{symbol} refers to a (changable) symbol method (see
  below). The symbol is drawn at size \var{size} (a visual \PyX{}
  length; also changeable) using \var{symbolattrs}. \var{symbolattrs}
  are merged with the decorator \class{deco.stroked}. \var{errorscale}
  is the size of the error bars compared to the symbol size.
  \var{errorbarattrs} and \var{lineattrs} are strokestyles for
  stroking the errorbars and lines, respecively. \var{lineattrs} are
  merged with \var{changelinestyle} (see below). \var{epsilon} is used
  to determine, when a symbol is outside of the graph (in graph
  coordinates).

  \var{symbolline} is useable on graphs with arbitrary dimension and
  geometry. It needs one data column for each graph dimension. The
  data names must be equal to an axis name. Furthermore there can be
  data names constructed out of the axis names for identifying data
  for the error bars. Suppose \code{X} is an axis name. Then
  \class{symbolline} allows for the following data names as well:

  \begin{tableii}{l|l}{}{data name}{description}
    \lineii{\code{Xmin}}{minimal value}
    \lineii{\code{Xmax}}{maximal value}
    \lineii{\code{Xd}}{minimal and maximal delta}
    \lineii{\code{Xdmin}}{minimal delta}
    \lineii{\code{Xdmax}}{maximal delta}
  \end{tableii}

  Minimal and maximal values are calculated from delta by subtracting
  and adding it to the value itself. Most of the data names are mutal
  exclusive (whenever a minimal or maximal value would be set twice).
\end{classdesc}

\class{symbolline} provides some symbol methods, namely:

\begin{methoddesc}{cross}{x_pt, y_pt, size_pt}
  A cross. Should be used for stroking only.
\end{methoddesc}

\begin{methoddesc}{plus}{x_pt, y_pt, size_pt}
  A plus. Should be used for stroking only.
\end{methoddesc}

\begin{methoddesc}{square}{x_pt, y_pt, size_pt}
  A square. Might be stroked or filled or both.
\end{methoddesc}

\begin{methoddesc}{triangle}{x_pt, y_pt, size_pt}
  A triangle. Might be stroked or filled or both.
\end{methoddesc}

\begin{methoddesc}{circle}{x_pt, y_pt, size_pt}
  A circle. Might be stroked or filled or both.
\end{methoddesc}

\begin{methoddesc}{diamond}{x_pt, y_pt, size_pt}
  A diamond. Might be stroked or filled or both.
\end{methoddesc}

\class{symbolline} provides some changeable symbol methods as class
variables, namely:

\begin{memberdesc}{changecross}
  attr.changelist([cross, plus, square, triangle, circle, diamond])
\end{memberdesc}

\begin{memberdesc}{changeplus}
  attr.changelist([plus, square, triangle, circle, diamond, cross])
\end{memberdesc}

\begin{memberdesc}{changesquare}
  attr.changelist([square, triangle, circle, diamond, cross, plus])
\end{memberdesc}

\begin{memberdesc}{changetriangle}
  attr.changelist([triangle, circle, diamond, cross, plus, square])
\end{memberdesc}

\begin{memberdesc}{changecircle}
  attr.changelist([circle, diamond, cross, plus, square, triangle])
\end{memberdesc}

\begin{memberdesc}{changediamond}
  attr.changelist([diamond, cross, plus, square, triangle, circle])
\end{memberdesc}

\begin{memberdesc}{changesquaretwice}
  attr.changelist([square, square, triangle, triangle, circle, circle, diamond, diamond])
\end{memberdesc}

\begin{memberdesc}{changetriangletwice}
  attr.changelist([triangle, triangle, circle, circle, diamond, diamond, square, square])
\end{memberdesc}

\begin{memberdesc}{changecircletwice}
  attr.changelist([circle, circle, diamond, diamond, square, square, triangle, triangle])
\end{memberdesc}

\begin{memberdesc}{changediamondtwice}
  attr.changelist([diamond, diamond, square, square, triangle, triangle, circle, circle])
\end{memberdesc}

\class{symbolline} provides two changeable decorators for alternated filling
and stroking. Those are especially usefull in combination with the
\method{change}-\method{twice}-symbol methods above. They are:

\begin{memberdesc}{changestrokedfilled}
  attr.changelist([deco.stroked, deco.filled])
\end{memberdesc}

\begin{memberdesc}{changefilledstroked}
  attr.changelist([deco.filled, deco.stroked])
\end{memberdesc}

Finally, there is a changeable linestyle used by default. It is
defined as:

\begin{memberdesc}{changelinestyle}
  attr.changelist([style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted])
\end{memberdesc}

\begin{classdesc}{symbol}{symbol=changecross, size="0.2 cm",
                          errorscale=0.5, symbolattrs=[],
                          errorbarattrs=[], epsilon=1e-10}
  This class is a style to plot symbols and errorbars into a graph. It
  is equivalent to \class{symbollines} except that it does not allow
  for lines. An instance of \class{symbol} is the default style for
  all data classes described in section~\ref{graph:data} except for
  \class{function} and \class{paramfunction}.
\end{classdesc}

\begin{classdesc}{line}{errorbarattrs=[]}
  This class is a style to stroke lines into graph. It is equivalent
  to \class{symbollines} except that it does not allow for symbols and
  errorbars. Thus it also does not accept data names for error bars.
  Instances of \class{line} are the default style for the data classes
  \class{function} and \class{paramfunction}.
\end{classdesc}

\begin{classdesc}{text}{textdx="0", textdy="0.3 cm", textattrs=[],
                        symbol=changecross, size="0.2 cm",
                        errorscale=0.5, symbolattrs=[],
                        errorbarattrs=[], epsilon=1e-10}
  This class enhances \class{symbol} by adding text to the symbol. The
  text to be written has provided in the additional data column named
  \code{text}. \var{textdx} and \var{textdy} are the position of the
  text with respect of the symbol. \var{textattrs} are text
  attributes for the output of the text. All other parameters have the
  same meaning as in the \class{symbol} class.
\end{classdesc}

\begin{classdesc}{arrow}{linelength="0.25 cm", arrowsize="0.15 cm",
                         lineattrs=[], arrowattrs=[], epsilon=1e-10}
  This class is a style to plot short lines with arrows into a
  two-dimensional graph. The position of the arrow is defined by two
  data columns named like an axes for each graph dimension. Two
  additional data columns named \code{size} and \code{angle} define
  the size and angle for each arrow. \code{size} is taken as a factor
  to \var{arrowsize} and \var{linelength}, the size of the arrow and
  the length of the line the arrow is plotted at. \code{angle} is the
  angle the arrow points to with respect to a horizonal lines. The
  \code{angle} is taken in degree and use in mathematical positive
  sense. \var{lineattrs} and \var{arrowattrs} are styles for the arrow
  line and arrow head respectively. \var{epsilon} is used to
  determine, when the arrow is outside of the graph (in graph
  coordinates).
\end{classdesc}

\begin{classdesc}{rect}{palette=color.palette.Gray}
  This class is a style to plot coloured rectangles into a
  two-dimensional graph. The position of the rectangles are given by 4
  data columns named \code{Xmin} and \code{Xmax} where \code{X} stands
  for two axes names, one for each graph dimension. The additional
  data column named \code{color} specifies the color of the rectangle
  defined by \var{palette}. Thus the valid color range is [0:1].

  \begin{note}
    Although this style can be used for plotting coloured surfaces, it
    will lead to a huge memory footprint of \PyX together with a
    long running time and large outputs. Improved support for coloured
    surfaces are planned for the future.
  \end{note}
\end{classdesc}

\begin{classdesc}{bar}{fromvalue=None, frompathattrs=[], barattrs=[],
                       subnames=None, epsilon=1e-10}
  This class is a style to plot bars into a two-dimensional graph. The
  bars are plotted on top of a specialized axis, namely a bar axis.
  The data column for this bar axis is named \code{Xname} where
  \code{X} is an axis name. The bar value have a name an axis of the
  other graph dimension. Suppose the name of this value axis is
  \code{Y} than you can stack further bars on top of this bar by
  providing additional data columns consecutively named
  \code{Ystack1}, \code{Ystack2}, \code{Ystack3}, \emph{etc.}
  When plotting several bars in a single graph, those bars are placed
  side by side (at the same value of \code{Xname}). The name axis, a
  bar axis, must then be a nested bar axis. The names used for the
  subaxis can be set by \var{subnames}. When not set, integer numbers
  starting from zero will be used.

  The bars start at \var{fromvalue} when provided. The \var{fromvalue}
  is marked by a gridline stroked using \var{frompathattrs}. The bars
  are filled using \var{barattrs}. \var{barattrs} is merged with
  \samp{[color.palette.Rainbow, deco.stroked([color.gray.black])]} and
  iterated independently when several bars are plotted side by side
  and when several bars are plotted on top of each other. When mixing
  both possibilities, you may use nested changeable styles.
\end{classdesc}

\section{Keys\label{graph:key}}

\declaremodule{}{graph.key}
\modulesynopsis{Graph keys}

The following class provides a key, whose instances can be passed to
the constructor keyword argument \code{key} of a graph. The class is
implemented in \module{graph.key}.

\begin{classdesc}{key}{dist="0.2 cm", pos="tr", hinside=1, vinside=1,
                       hdist="0.6 cm", vdist="0.4 cm",
                       symbolwidth="0.5 cm", symbolheight="0.25 cm",
                       symbolspace="0.2 cm", textattrs=[]}
  This class writes the title of the data in a plot together with a
  small illustration of the style. The style is responsible for its
  illustration.

  \var{dist} is a visual length and a distance between the key
  entries. \var{pos} is the position of the key with respect to the
  graph. Allowed values are combinations of \samp{t} (top) and
  \samp{b} (bottom) with \samp{l} (left) and \samp{r} (right).
  \var{hdist} and \var{vdist} are the distances from the specified
  corner of the graph. \var{hinside} and \var{vinside} are booleans to
  define whether the key should be placed horizontally and vertically
  inside of the graph or not.

  \var{symbolwidth} and \var{symbolheight} is passed to the style to
  control the size of the style illustration. \var{symbolspace} is the
  space between the illustration and the text. \var{textattrs} are
  attributes for the text creation. They are merged with
  \samp{[text.vshift.mathaxis]}.
\end{classdesc}