test trafo application in draw

[PyX/mjg.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 simple 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 then 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 list of graph styles to be used to plot the data. When no styles are
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 styles might make use of
(\emph{e.g.} data for error bars to be used by the errorbar 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}
The result \file{graph.eps} is 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, other data source are available
as well. For example function data is created and placed into
\method{plot()} by the following line:
\begin{verbatim}
g.plot(graph.data.function("y=x**2"))
\end{verbatim}
You can plot different data in a single graph by calling
\method{plot()} several times before \method{writeEPSfile()}. Note
that a calling \method{plot()} will fail once a graph was forced to
``finish'' itself. This happens automatically, when the graph is
written to a file. 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}

While the axes ranges got adjusted automatically in the previous
example, they might be fixed by keyword options in axes constructors.
Plotting only a function will need such a setting at least in the
variable coordinate. The following code also shows how to set a
logathmic axis in y-direction:

\verbatiminput{graph3.py}

The result is shown in figure~\ref{fig:graph3}.

\begin{figure}[ht]
\centerline{\includegraphics{graph3}}
\caption{Plotting a function for a given axis range and use a
logarithmic y-axis.}
\label{fig:graph3}
\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
well-defined interfaces. They certainly have to be completed and
stabilized in their 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 prepares data to be plotted in graphs.
\term{style}
  Performs the plotting of the data into the graph. It gets data,
  converts 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 themselves and
  other things, this task is splitted into several independent
  subtasks. Axes are discussed separately in chapter~\ref{axis}.
\end{definitions}

\section{Module \code{graph/graph}: 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 an x-y-graph. A graph instance is also a fully
  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 is
  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} receives 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 an \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{x} axes) and
  right (\code{y} axes) while the others are plotted at the bottom
  (\code{x} axes) and left (\code{y} axes) in ascending order each.
  Axes instances should only be used once.
\end{classdesc}

Some instance attributes might be useful 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, styles=None}
  Adds \var{data} to the list of data to be plotted. Sets \var{styles}
  to be used for plotting the data. When \var{styles} is \code{None},
  the default styles 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 only be used once.

  When the same combination of styles (\emph{i.e.} the same
  references) are used several times within the same graph instance,
  the styles are kindly asked by the graph to iterate their
  appearence. Its up to the styles 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, sometimes position
methods (described below) are nice to be accessible. For that, at
least the layout of the graph must have been finished. By calling the
\method{do}-methods yourself you can also alter the order in which the
graph components are plotted. Multiple calls to 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
  adjust themselves 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}

\begin{methoddesc}{finish}{}
  Finishes the graph by calling all pending \method{do}-methods. This
  is done automatically, when the output is created.
\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{vx2}, \var{vy2} 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}

% dirty hack to add a whole list of methods to the index:
\index{xbasepath()@\texttt{xbasepath()} (graphxy method)}
\index{xvbasepath()@\texttt{xvbasepath()} (graphxy method)}
\index{xgridpath()@\texttt{xgridpath()} (graphxy method)}
\index{xvgridpath()@\texttt{xvgridpath()} (graphxy method)}
\index{xtickpoint()@\texttt{xtickpoint()} (graphxy method)}
\index{xvtickpoint()@\texttt{xvtickpoint()} (graphxy method)}
\index{xtickdirection()@\texttt{xtickdirection()} (graphxy method)}
\index{xvtickdirection()@\texttt{xvtickdirection()} (graphxy method)}
\index{ybasepath()@\texttt{ybasepath()} (graphxy method)}
\index{yvbasepath()@\texttt{yvbasepath()} (graphxy method)}
\index{ygridpath()@\texttt{ygridpath()} (graphxy method)}
\index{yvgridpath()@\texttt{yvgridpath()} (graphxy method)}
\index{ytickpoint()@\texttt{ytickpoint()} (graphxy method)}
\index{yvtickpoint()@\texttt{yvtickpoint()} (graphxy method)}
\index{ytickdirection()@\texttt{ytickdirection()} (graphxy method)}
\index{yvtickdirection()@\texttt{yvtickdirection()} (graphxy method)}

Further geometry information is available by the \member{axespos}
instance variable. Shortcuts to the \class{axispos} methods for the
\code{x}- and \code{y}-axis become available after \method{dolayout()}
as \class{graphxy} methods \code{Xbasepath}, \code{Xvbasepath},
\code{Xgridpath}, \code{Xvgridpath}, \code{Xtickpoint},
\code{Xvtickpoint}, \code{Xtickdirection}, and \code{Xvtickdirection}
where the prefix \code{X} stands for \code{x} and \code{y}.

\section{Module \code{graph/data}: 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{!} as well
  as an empty line is treated as a comment.

  A non-comment line is analysed by repeatedly 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{skiptail} 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 expressions 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 keys of the dictionary \var{**columns}.
  Only the later, the data column names, are valid identifiers for the
  data columns at later usage (by the graph styles).

  File column names occur when the data file contains a comment line
  immediately in front of the data (except for empty or empty comment
  lines). This line will be parsed skipping the matched comment
  identifier as if the line would be regular data, but it will not be
  converted to floats even if it would be possible to convert the
  items. The result is taken as file column names, \emph{i.e.} a
  string representation for the columns in the file.

  The values of \var{**columns} can refer to column numbers in the
  file starting at \code{1}. The column \code{0} is also available
  and contains the line number starting from \code{1} not counting
  comment lines, but lines skiped by \var{skiphead}, \var{skiptail},
  and \var{every}. Furthermore values of \var{**columns} can be
  strings: file column names or complex 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. In
  those mathematical expressions the \var{context} is available, but
  data from other columns are not. 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 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 we list 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 whole 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 choosen linearly 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: In principle, it is 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 expressions. 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}{data, title="user provided list",
                        addlinenumbers=1, **columns}
  This class creates graph data from externally provided data.
  \var{data} 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.

  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 added to
  contain a line number in that case), 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 parameters work like the equally
  called parameters in \class{graph.data.file}. Indeed, the latter is
  built 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.
\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{Module \code{graph/style}: Styles}
\label{graph:style}

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

Please note that we are 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 plotting symbols, lines and errorbars into a
  graph. \var{symbol} refers to a (changeable) 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{dX}}{minimal and maximal delta}
    \lineii{\code{dXmin}}{minimal delta}
    \lineii{\code{dXmax}}{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 mutually
  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 useful 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 line style 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}{lineattrs=[]}
  This class is a style to stroke lines into a 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 to be provided in the additional data column named
  \code{text}. \var{textdx} and \var{textdy} are the position of the
  text with respect to 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 axis 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 horizontal line. The
  \code{angle} is taken in degrees and used in mathematically 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 positions of the rectangles are given by four
  data columns named \code{Xmin} and \code{Xmax} where \code{X} stands
  for two axis 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 is 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 has the name of 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{Module \code{graph/key}: 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} are 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}