late evaluation of source range in function

[PyX/mjg.git] / manual / graph.tex

\chapter{Module graph: graph plotting}
\label{graph}
\section{Introductory notes}

The graph module is considered to be in constant, gradual development.
For the moment we concentrate ourself on standard 2d xy-graphs taking
all kind of possible specialties into account like any number of axes.
Architectural decisions play the most substantial role at the moment
and have hopefully already been done that way, that their flexibility
will suffice for future usage in quite different graph applications,
\emph{e.g.} circular 2d graphs or even 3d graphs. We will describe
those parts of the graph module here, which are in a totally usable
state already and are hopefully not to be changed later on. However,
future developments certainly will cause some incompatibilities. At
least be warned: Nobody knows the hole list of things that will break.
At the moment, keeping backwards compatibility in the graph module is
not at all an issue. Although we do not yet claim any backwards
compatibility for the future at all, the graph module is certainly one
of the biggest construction sites within \PyX.

The task of drawing graphs is splitted in quite some subtasks, which
are implemented by classes of its own. We tried to make those
components as independend as it is usefull and possible in order to
make them reuseable for different graph types. They are also
replaceable by the user to get more specialized graph drawing tasks
done without needing to implement a hole graph system. A major
abstraction layer are the so-called graph coordinates. Their range is
generally fixed to $[0;1]$. Only the graph does know about the
conversion between these coordinates and the position at the canvas
(the graph itself is its canvas, that can be inserted into another
canvas). By that, all other components can be reused for different
graph geometries. The interfaces between the components are documented
in docstrings of interface classes in the source. The interface
technique is used for documentation purposes only. For the user, the
most important informations (as described in the following) are the
parameters of the constructors of the various implementations of those
interface. They are documented in docstrings of the constructors of
the classes. While effort of clearing and documenting is still in
progress, some parts are already nicely documented as you may see by
using \verb|pydoc|.

\section{Axes}
\label{graph:axes}

A common feature of a graph are axes. An axis is responsible for the
conversion of values to graph coordinates. There are predefined axis
types, namely:
\begin{center}
\begin{tabular}{ll}
axis type&description\\
\hline
\texttt{linaxis}&linear axis\\
\texttt{logaxis}&logarithmic axis\\
\end{tabular}
\end{center}

Further axes types are available to support axes splitting and bar
graphs (other axes types might be added in the future as well), but
they behave quite different from the generic case and are thus
described separately below.

You may use axes even without a graph, but drawing them along an
arbitrary path using the \verb|pathaxis| function. This function takes
an path and an axis as its first two arguments and the result can be
inserted into a canvas. The optional keyword argument \verb|direction|
can be set to \verb|1|(default) or \verb|-1| to place the labels to
the right (default) or left side of the path, respectively.

\subsection{Axes properties}

Global properties of an axis are set as named parameters in the axis
constructor. Both, the \verb|linaxis| and the \verb|logaxis|, have the
same set of named parameters listed in the following table:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
\texttt{title}&axis title\\
\texttt{min}&fixes axis minimum; if not set, it is automatically determined, but this might fail, for example for the $x$-range of functions, when it is not specified there\\
\texttt{max}&as above, but for the maximum\\
\texttt{reverse}&boolean; exchange minimum and maximum (might be used without setting minimum and maximum); if min>max and reverse is set, they cancel each other\\
\texttt{divisor}&numerical divisor for the axis partitioning; default: \texttt{1}\\
\texttt{suffix}&a suffix to indicate the divisor within an automatic axis labeling\\
\texttt{density}&density parameter for the axis partition rating\\
\texttt{maxworse}&number of trials with worse tick rating before giving up; default: \texttt{2}\\
\texttt{manualticks}&a list of ticks (described below)\\
\texttt{painter}&axis painter (described below)\\
\texttt{texter}&texter for the axis labels (described below)\\
\texttt{parter}&axis partitioner (described below)\\
\texttt{rater}&partition rater (described below)\\
\end{tabularx}
\medskip

\subsection{Partitioning of axes}

The definition of ticks and labels appropriate to an axis range is
called partitioning. The axis partioning within \PyX{} uses rational
arithmetics, which avoids any kind of rounding problems to the cost of
performance. The class \verb|frac| supplies a rational number. It can
be initialized by another \verb|frac| instance, a tuple of integers
(called enumerator and denominator), a float (which gets converted
into a frac with a finite resolution \verb|floatprecision| of 10
digits per default) or a string with infinite precision (like
"1.2345e-100" or even "1/3"). However, a partitioning is composed out
of a sorted list of ticks, where the class \verb|tick| is derived from
\verb|frac| and has additional properties called \verb|ticklevel|,
\verb|labellevel|, \verb|label|, and \verb|labelattrs|. When the
\verb|ticklevel| or the \verb|labellevel| is \verb|None|, it just
means not present, \verb|0| means tick or label, respectively,
\verb|1| means subtick or sublevel and so on. When \verb|labellevel|
is not \verb|None|, a \verb|label| might be explicitly given, which
will get used as the text of that label. Otherwise the axis painter
has to create an appropriate text for the label. The \verb|labelattrs|
might specify some attributes for the label to be used by the
\verb|text| method of an \verb|texrunner| instance.

You can pass a list of \verb|tick| instance to the \verb|manualticks|
argument of an axis. By that you can place ticks whereever you want.
Additionally you can use a partitioner to create ticks appropriate to
the axis range. This can be done by manually specifying distances
between ticks, subticks and so on. Alternatively there are automatic
axis partitioners available, which provide different partitions and
the rating of those different partitions by the \verb|rater| become
crucial. Note, that you can combine manually set ticks and a
partitioner.

\subsubsection{Partitioning of linear axes}

The class \verb|linpart| creates a linear partition as described by
named parameters of the constructor:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{tickdist}&\texttt{None}&distance between ticks, subticks, etc. (see comment below); when the parameter is \texttt{None}, ticks will get placed at labels\\
\texttt{labeldist}&\texttt{None}&distance between labels, sublabels, etc. (see comment below); when the parameter is \texttt{None}, labels will get placed at ticks\\
\texttt{labels}&\texttt{None}&set the text for the labels manually\\
\texttt{extendtick}&\texttt{0}&allow for a range extention to include the next tick of the given level\\
\texttt{extendlabel}&\texttt{None}&as above, but for labels\\
\texttt{epsilon}&\texttt{1e-10}&allow for exceeding the range by that relative value\\
\end{tabularx}
\medskip

The \verb|ticks| and \verb|labels| can either be a list or just a
single entry. When a list is provided, the first entry stands for
the tick or label, respectively, the second for the subtick or
sublabel, and so on. The entries are passed to the constructor of a
frac instance, e.g. there can be tuples (enumerator, denominator),
strings, floats, etc.

\subsubsection{Partitioning of logarithmic axes}

The class \verb|logpart| create a logarithmic partition. The
parameters of the constructor of the class \verb|logpart| are quite
simular to the parameters of \verb|linpart| discussed above. Instead
of the parameters \verb|tickdist| and \verb|labeldist| the parameters
\verb|tickpos| and \verb|labelpos| are present. All other parameters
of \verb|logpart| do not differ in comparision to \verb|linpart|. The
\verb|tickdist| and \verb|labeldist| parameters take either a single
\verb|preexp| instance or a list of \verb|preexp| instances, where the
first stands for the ticks (labels), the second for subticks
(sublabels) and so on. A \verb|preexp| instance contains a list of
\verb|pres|, which are \verb|frac| instances defining some positions,
say $p_i$. Furthermore there is a \verb|frac| instance called
\verb|exp|, say $e$. Valid tick and label positions are then given by
$s^np_i$, where $n$ is an integer.

\begin{center}
\begin{tabular}{ll}
name&values it descibes\\
\hline
\texttt{pre1exp5}&1 and multiple of $10^5$\\
\texttt{pre1exp4}&1 and multiple of $10^4$\\
\texttt{pre1exp3}&1 and multiple of $10^3$\\
\texttt{pre1exp2}&1 and multiple of $10^2$\\
\texttt{pre1exp}&1 and multiple of $10$\\
\texttt{pre125exp}&1, 2, 5 and multiple of $10$\\
\texttt{pre1to9exp}&1, 2, \dots, 9 and multiple of $10$\\
\end{tabular}
\end{center}

\subsubsection{Automatic partitioning of linear axes}

When no explicit axis partitioner is given in the constructor argument
\verb|part| of an linear axis, it is initialized with an automatic
partitioning scheme for linear axes. This scheme is provided by the
class \verb|autolinpart|, where the constructor takes the following
arguments:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{variants}&\texttt{defaultvariants}&list of possible values for the ticks parameter of \texttt{linpart} (labels are placed at the position of ticks)\\
\texttt{extendtick}&\texttt{0}&allow for a range extention to include the next tick of the given level\\
\texttt{epsilon}&\texttt{1e-10}&allow for exceeding the range by that relative value\\
\end{tabularx}
\medskip

The default value for the argument \verb|variants|, namely
\verb|defaultvariants|, is defined as a class variable of
\verb|autolinpart| and has the value \texttt{((frac(1, 1), frac(1,
2)), (frac(2, 1), frac(1, 1)), (frac(5, 2), frac(5, 4)), (frac(5, 1),
frac(5, 2)))}. This implies, that the automatic axis partitioning
scheme allows for partitions using (ticks, subticks) with at distances
(1, 1/2), (2, 1), (5/2, 5/4), (5, 5/2). This list must be sorted by
the number of ticks the entries will lead to. The given fractions are
automatically multiplied or divided by 10 in order to fit better to
the axis range. Therefore those additional partitioning possibilities
(infinte possibilities) must not be given explicitly.

\subsubsection{Automatic partitioning of logarithmic axes}

When no explicit axis partitioning is given in the constructor
argument \verb|part| of an logarithmic axis, it is initialized with an
automatic partitioning schemes for logarithmic axes. This scheme is
provided by the class \verb|autologpart|, where the constructor takes
the following arguments:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{variants}&\texttt{defaultvariants}&list of pairs with possible values for the ticks and labels parameters of \texttt{logpart}\\
\texttt{extendtick}&\texttt{0}&allow for a range extention to include the next tick of the given level\\
\texttt{extendlabel}&\texttt{None}&as above, but for labels\\
\texttt{epsilon}&\texttt{1e-10}&allow for exceeding the range by that relative value\\
\end{tabularx}
\medskip

The default value for the argument \verb|variants|, namely
\verb|defaultvariants|, is defined as a class variable of
\verb|autologpart| and has the value:
\begin{verbatim}
(((pre1exp, pre1to9exp),        # ticks & subticks,
         (pre1exp, pre125exp)), # labels & sublevels
 ((pre1exp, pre1to9exp), None), # ticks & subticks, labels=ticks
 ((pre1exp2, pre1exp), None),   # ticks & subticks, labels=ticks
 ((pre1exp3, pre1exp), None),   # ticks & subticks, labels=ticks
 ((pre1exp4, pre1exp), None),   # ticks & subticks, labels=ticks
 ((pre1exp5, pre1exp), None))   # ticks & subticks, labels=ticks
\end{verbatim}
As for the \verb|autolinaxis|, this list must be sorted by the number
of ticks the entries will lead to.

\subsubsection{Rating of axes partitionings}

When an axis partitioning scheme returns several partitioning
possibilities, the partitions are rated by an instance of a rater
class provided as the parameter \verb|rater| at the axis constructor.
It is used to calculate a positive rating number for a given axis
partitioning. In the end, the lowest rated axis partitioning gets
used.

The rating consists of two steps. The first takes into account only
the number of ticks, subticks, labels and so on in comparison to an
optimal number. Additionally, the transgression of the axis range by
ticks and labels is taken into account. This rating leads to a
preselection of possible partitions. In the second step the layout of
a partition gets acknowledged by rating the distance of the labels to
each other. Thereby partitions with overlapping labels get quashed
out.

The class \verb|axisrater| implements a rating with quite some
parameters specifically adjusted to linear and logarithmic axes. A
detailed description of the hole system goes beyond the scope of that
manual. Take your freedom and have a look at the \PyX{} source code if
you wish to adopt the rating to personal preferences.

The overall optimal partition properties, namely the density of ticks
and labels, can be easily adjusted by the single parameter
\verb|density| of the axis constructor. The rating is
adjusted to the default densitiy value of \verb|1|, but modifications
of this parameter in the range of 0.5 (for less ticks) to 2 or even 3
(for more ticks) might be usefull.

\subsection{Creating label text}

When a partition is created, the typical situation is that some of the
ticks have a \verb|labellevel| not equal to \verb|None| but there is
no \verb|label| (a string) defined to be printed at this tick. The
task of a \verb|texter| is to create those label strings for a given
list of ticks. There are different \verb|texter| classes creating
different label strings.

\subsubsection{Decimal numbers}

The class \verb|decimaltexter| creates decimal labels. The format of
the labels can be configured by numerous arguments of the constructor
listed in the following table:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{prefix}&\texttt{""}&string to be inserted in front of the number\\
\texttt{infix}&\texttt{""}&string to be inserted between the plus or minus sign and the number\\
\texttt{suffix}&\texttt{""}&string to be inserted after the number\\
\texttt{equalprecision}&\texttt{0}&forces a common number of digits after the comma\\
\texttt{decimalsep}&\texttt{"."}&decimal separator\\
\texttt{thousandsep}&\texttt{""}&thousand separator\\
\texttt{thousandthpartsep}&\texttt{""}&thousandth part separator\\
\texttt{plus}&\texttt{""}&plus sign\\
\texttt{minus}&\texttt{"-"}&minus sign\\
\texttt{period}&\texttt{r"\textbackslash overline\{\%s\}"}&format string to indicate a period\\
\texttt{labelattrs}&\texttt{text.mathmode}&a single attribute or a list of attributes to be added to the labelattrs\\
\end{tabularx}
\medskip

\subsubsection{Decimal numbers with an exponential}

The class \verb|exponentialtexter| creates decimal labels with an
exponent. The format of the labels can be configured by numerous
arguments of the constructor listed in the following table:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{plus}&\texttt{""}&plus sign for the exponent\\
\texttt{minus}&\texttt{"-"}&minus sign for the exponent\\
\texttt{mantissaexp}&\texttt{r"\{\{\%s\}\textbackslash cdot10\textasciicircum\{\%s\}\}"}&format string for manissa and exponent\\
\texttt{skipexp0}&\texttt{r"\{\%s\}}&format string for manissa, when exponent is \texttt{0}; use \texttt{None} to turn off this feature\\
\texttt{skipexp1}&\texttt{None}&as \texttt{skipexp0}, but for exponent \texttt{1}\\
\texttt{nomantissaexp}&\texttt{r"\{10\textbackslash\{\%s\}\}"}&format string when skipping a manissa equals 1\\
\texttt{minusnomantissaexp}&\texttt{r"\{-1\textbackslash\{\%s\}\}"}&format string when skipping a manstissa equals -1\\
\texttt{mantissamin}&\texttt{frac((1, 1))}&minimal value for the mantissa\\
\texttt{mantissamax}&\texttt{frac((10, 1))}&maximal value for the mantissa\\
\texttt{skipmantissa1}&\texttt{0}&skip mantissa equals 1\\
\texttt{skipallmantissa1}&\texttt{1}&skip mantissa when its always 1\\
\texttt{mantissatexter}&\texttt{decimaltexter()}&texter for the mantissa\\
\end{tabularx}
\medskip

\subsubsection{Decimal numbers without or with an exponential}

The class \verb|defaulttexter| creates decimal labels without or
with an exponent. As the name says, its used as the default texter.
The texter splits the tick list into two lists, one to be passed to a
decimal texter and another to be passed to an exponential texter. This
splitting is based on the two properties \verb|smallestdecimal| and
\verb|biggestdecimal|. See the following table for all available
arguments:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{smallestdecimal}&\texttt{frac((1, 1000))}&the smallest number (ignoring the sign) where the decimal texter should be used\\
\texttt{biggestdecimal}&\texttt{frac((9999, 1))}&as above, but for the biggest number\\
\texttt{equaldecision}&\texttt{1}&either use the \texttt{decimaltexter} or the \texttt{exponentialtexter}\\
\texttt{decimaltexter}&\texttt{decimaltexter()}&texter withoud an exponential\\
\texttt{exponentialtexter}&\texttt{exponentialtexter()}&exponential with an exponential\\
\end{tabularx}
\medskip

\subsubsection{Rational numbers}

The class \verb|rationaltexter| creates rational labels. The format of
the labels can be configured by numerous arguments of the constructor
listed in the following table:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{prefix}&\texttt{""}&string to be inserted in front of the rational\\
\texttt{infix}&\texttt{""}&string to be inserted between the plus or minus sign and the rational\\
\texttt{suffix}&\texttt{""}&string to be inserted after the rational\\
\texttt{enumprefix}&\texttt{""}&as \texttt{prefix} but for the enumerator\\
\texttt{enuminfix}&\texttt{""}&as \texttt{infix} but for the enumerator\\
\texttt{enumsuffix}&\texttt{""}&as \texttt{suffix} but for the enumerator\\
\texttt{denomprefix}&\texttt{""}&as \texttt{prefix} but for the denominator\\
\texttt{denominfix}&\texttt{""}&as \texttt{infix} but for the denominator\\
\texttt{denomsuffix}&\texttt{""}&as \texttt{suffix} but for the denominator\\
\texttt{plus}&\texttt{""}&plus sign\\
\texttt{minus}&\texttt{"-"}&minus sign\\
\texttt{minuspos}&\texttt{0}&position of the minus: \texttt{0} -- in front of the fraction, \texttt{1} -- in front of the enumerator, \texttt{-1} -- in front of the denominator\\
\texttt{over}&\texttt{r"\{\{\%s\}\textbackslash over\{\%s\}\}"}&format string for the fraction\\
\texttt{equaldenom}&\texttt{0}&usually, the enumerator and the denominator are canceled; if set, take the least common multiple of all denominators\\
\texttt{skip1}&\texttt{1}&skip printing the fraction for \texttt{1} when there is a \texttt{prefix}, \texttt{infix}, or \texttt{suffix}\\
\texttt{skipenum0}&\texttt{1}&print \texttt{0} instead of a fraction when the enumerator is 0\\
\texttt{skipenum1}&\texttt{1}&as \texttt{skip1} but for the enumerator\\
\texttt{skipdenom1}&\texttt{1}&skip the denominator when it is \texttt{1} and there is no \texttt{denomprefix}, \texttt{denominfix}, or \texttt{denomsuffix}\\
\texttt{labelattrs}&\texttt{text.mathmode}&a single attribute or a list of attributes to be added to the labelattrs\\
\end{tabularx}
\medskip

\subsection{Painting of axes}

A major task for an axis is its painting. It is done by instances of
\verb|axispainter|, provided to the constructor of an axis as its
\verb|painter| argument. The constructor of the axis painter receives
a numerous list of named parameters to modify the axis look. A list of
parameters is provided in the following table:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
\texttt{innerticklengths}$^{1,4}$&tick length of inner ticks (visual length);\newline default: \texttt{axispainter.defaultticklengths}\\
\texttt{outerticklengths}$^{1,4}$&as before, but for outer ticks; default: \texttt{None}\\
\texttt{tickattrs}$^{2,4}$&stroke attributes for ticks; default: \texttt{()}\\
\texttt{gridattrs}$^{2,4}$&stroke attributes for grid paths; default: \texttt{None}\\
\texttt{zeropathattrs}$^{3,4}$&stroke attributes for a grid path at axis value 0; default: \texttt{()}\\
\texttt{basepathattrs}$^{3,4}$&stroke attributes for the axis base path;\newline default: \texttt{canvas.linecap.square}\\
\texttt{labeldist}&label distance from axis (visual length); default: \texttt{"0.3 cm"}\\
\texttt{labelattrs}$^{2,4}$&text attributes for labels;\newline default: \texttt{(text.halign.center, text.vshift.mathaxis)}\\
\texttt{labeldirection}$^4$&relative label direction (see below); default: \texttt{None}\\
\texttt{labelhequalize}&set width of labels to its maximum (boolean); default: \texttt{0}\\
\texttt{labelvequalize}&set height and depth of labels to their maxima (boolean); default: \texttt{1}\\
\texttt{titledist}&title distance from labels (visual length); default: \texttt{"0.3 cm"}\\
\texttt{titleattrs}$^{3,4}$&text attributes for title; default: \texttt{(text.halign.center, text.vshift.mathaxis)}\\
\texttt{titledirection}$^4$&relative title direction (see below);\newline default: \texttt{paralleltext}\\
\texttt{titlepos}&title position in graph coordinates; default: \texttt{0.5}\\
\end{tabularx}
\medskip

$^1$
The parameter should be a list, where the entries are attributes
for the different levels. When the level is larger then the list
length, \verb|None| is assumed. When the parameter is not a list,
it is applied to all levels.\\
$^2$
The parameter should be a list of lists, where the entries are
attributes for the different levels. When the level is larger then the
list length, \verb|None| is assumed. When the parameter is not a
list of lists, it is applied to all levels.\\
$^3$
The parameter should be a list. When the parameter is not a
list, the parameter is interpreted as a list with a single
entry.\\
$^4$
The feature can be turned off by the value \verb|None|. Within
lists or lists of lists, the value \verb|None| might be
used to turn off the feature for some levels selectively.
\medskip

Relative directions for labels (\verb|labeldirection|) and titles
(\verb|titledirection|) are instances of \verb|rotatetext|. By that
the text direction is calculated relatively to the tick direction of
the axis and is added as an attribute of the text. The relative
direction provided by instances of the class \verb|rotatetext| prevent
upside down text by flipping it by 180 degrees. For convenience, the
two self-explanatory values \verb|rotatetext.parallel| and
\verb|rotatetext.orthogonal| are available, which are just instances of
rotatetext initializes by \verb|-90| degree and \verb|0|,
respectively.

\subsection{Linked axes}

Linked axes can be used whenever an axis should be repeated within a
single graph or even between different graphs although the intrinsic
meaning is to have only one axis plotted several times. Almost all
properties of a linked axis are supplied by the axis it is linked to
(you may call it the base axis), but some properties and methods might
be different. For the typical case (implemented by \verb|linkaxis|)
only the painter of the axis is exchanged together with some
simplified behaviour when finishing the axis (there is no need to
recalculate the axis partition etc.). The constructor of
\verb|linkaxis| takes the axis to be linked to as the first parameter
and in the named parameter \verb|painter| a new painter for the axis.
By default, \verb|linkaxispainter| is used, which differs from the
standard \verb|axispainter| by some default values for the arguments
only. Namely, the arguments \verb|zeropathattrs|, \verb|labelattrs|,
and \verb|titleattrs| are set to \verb|None| turing off these
features.

The standard \verb|linkaxis| can be used for a \verb|linaxis| or
\verb|logaxis|, other axes might have different \verb|linkaxis|
classes, \emph{e.g. \texttt{linksplitaxis} and \texttt{linkbaraxis}}.
While those linked axes might be used by graphs to plot the same axis
at both sides of the graph (when appropriate), every axis has a
\verb|createlinkaxis| method, which returns a standard linked axis.

\subsection{Special purpose axes}

\subsubsection{Splitable axes}

Axes with breaks are created by instances of the class
\verb|splitaxis|. Its constructor takes the following parameters:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
(axis list)&a list of axes to be used as subaxes (this is the first parameter of the constructor; it has no name)\\
\texttt{splitlist}&a single number or a list split points of the possitions of the axis breaks in graph coordinates; the value \texttt{None} forces \texttt{relsizesplitdist} to be used; default: \texttt{0.5}\\
\texttt{splitdist}&gap of the axis break; default: \texttt{0.1}\\
\texttt{relsizesplitdist}&used when \texttt{splitlist} entries are \texttt{None}; gap of the axis break in values of the surrounding axes (on logarithmic axes, a decade corresponds to 1); the split position is adjusted to give both surrounding axes the same scale (thus, their range must be completely fixed); default: \texttt{1}\\
\texttt{title}&axis title\\
\texttt{painter}&axis painter; default: \texttt{splitaxispainter()} (described below)\\
\end{tabularx}
\medskip

A split axis is build up from a list of ``subaxes''. Those subaxes
have to provide some range information needed to identify the subaxis
to be used out of a plain number (thus all axes minima and maxima has
to be set except for the two subaxes at the egde, where for the first
only the maximum is needed, while for the last only the minimum is
needed). The only point left is the description of the specialized
\verb|splitaxispainter|, where the constructor takes the following
parameters:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
\texttt{breaklinesdist}&(visual) distance between the break lines; default: \texttt{0.05}\\
\texttt{breaklineslength}&(visual) length of break lines; default: \texttt{0.5}\\
\texttt{breaklinesangle}&angle of the breakline with respect to the axis; default: \texttt{-60}\\
\texttt{breaklinesattrs}&stroke attributes for the break lines (\texttt{None} to turn off the break lines, otherwise a single value or a tuple); default: \texttt{()}\\
\end{tabularx}

Additionally, the painter takes parameters for the axis title
formatting like the standard axis painter class \verb|axispainter|.
(There is a common base class \verb|titleaxispainter| for that.) The
parameters are \verb|titledist|, \verb|titleattrs|,
\verb|titledirection|, and \verb|titlepos|.

\subsubsection{Bar axes}

Axes appropriate for bar graphs are created by instances of the class
\verb|baraxis|. Its constructor takes the following parameters:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
\texttt{subaxis}&baraxis can be recursive by having another axis as its subaxis; default: \texttt{None}\\
\texttt{multisubaxis}&contains another baraxis instance to be used to construct a new subaxes for each item (by that a nested bar axis with a different number of subbars at each bar can be created) ; default: \texttt{None}\\
\texttt{title}&axis title\\
\texttt{dist}&distance between bars (relative to the bar width); default: \texttt{0.5}\\
\texttt{firstdist}&distance of the first bar to the border; default: \texttt{0.5*dist}\\
\texttt{lastdist}&as before but for the last bar\\
\texttt{names}&tuple of name identifiers for bars; when set, no other identifiers are allowed; default: \texttt{None}\\
\texttt{texts}&dictionary translating names into label texts (otherwise just the names are used); default: \texttt{\{\}}\\
\texttt{painter}&axis painter; default: \texttt{baraxispainter} (described below)\\
\end{tabularx}
\medskip

In contrast to other axes, a bar axis uses name identifiers to
calculate a position at the axis. Usually, a style appropriate to a
bar axis (this is right now just the bar style) set those names out of
the data it recieves. However, the names can be forced and fixed.

Bar axes can be recursive. Thus for a given value, an appropriate
subaxis is choosen (usually another bar axis). Usually only a single
subaxis is needed, because it doesn't need to be painted and for each
value the same recursive subaxis transformation has to be applied.
This is achieved by using the parameter \verb|subaxis|. Alternatively
you may use the \verb|multisubaxis|. Here only a bar axis can be used.
Then the subaxes (note axes instead of axis) are painted as well
(however their painter can be set to not paint anything). For that,
duplications of the subaxis are created for each name. By that, each
subaxis can have different names, in particular different number of
names.

The only point left is the description of the specialized
\verb|baraxispainter|. It works quite similar to the
\verb|axispainter|. Thus the constructors have quite some parameters
in common, namely \verb|titledist|, \verb|titleattrs|,
\verb|titledirection|, \verb|titlepos|, and \verb|basepathattrs|.
Furthermore the parameters \verb|innerticklength| and
\verb|outerticklength| work like their counterparts in the
\verb|axispainter|, but only plain values are allowed there (no
lists). However, they are both \verb|None| by default and no ticks
get plotted. Then there is a hole bunch of name
attribute identifiers, namely \verb|namedist|, \verb|nameattrs|,
\verb|namedirection|, \verb|namehequalize|, \verb|namevequalize| which
are identical to their counterparts called \verb|label...| instead of
\verb|name...|. Last but not least, there is a parameter \verb|namepos|
which is analogous to \verb|titlepos| and set to \verb|0.5| by
default.

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

\subsection{List of points}

Instances of the class \verb|data| link together a \verb|datafile| (or
another instance of a class from the module \verb|data|) and a
\verb|style| (see below; default is \verb|symbol|). The link object is
needed in order to be able to plot several data from a singe file
without reading the file several times. However, for easy usage, it is
possible to provide just a filename instead of a \verb|datafile|
instance as the first argument to the constructor of the class
\verb|data| thus hiding the underlying \verb|datafile| instance
completely from view. This is the preferable solution as long as the
datafile gets used only once.

The additional parameters of the constructor of the class \verb|data|
are named parameters. The values of those parameters describe data
columns which are linked to the names of the parameters within the
style. The data columns can be identified directly via their number or
title, or by means of mathematical expression (as in the addcolumn
method of the class \verb|data| in the module \verb|data|; see
chapter~\ref{module:data}; indeed a addcolumn call takes place to
evaluate mathematical expressions once and for all).

The constructors keyword argument \verb|title| however does not
refer to a parameter of a style, but instead sets the title to be used
in the graph key. It might be set to \verb|None| to exclude the data
and style from the the graph key.

\subsection{Functions}

The class \verb|function| provides data generation out of a functional
expression. The default style for function plotting is \verb|line|.
The constructor of \verb|function| takes an expression as the first
parameter. The expression must be a string with exactly one equal sign
(\verb|=|). At the left side the result axis identifier must be placed
and at the right side the expression must depend on exactly one
variable axis identifier. Hence, a valid expression looks like
\verb|"y=sin(x)"|. You can access own variables and functions by
providing them as a dictionary to the constructors \verb|context|
keyword argument.

Additional named parameters of the constructor are:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{min}&\texttt{None}&minimal value for the variable parameter; when \texttt{None}, the axis data range will be used\\
\texttt{max}&\texttt{None}&as above, but for the maximum\\
\texttt{points}&\texttt{100}&number of points to be calculated\\
\texttt{parser}&\texttt{mathtree.parser()}&parser for the mathematical expression\\
\texttt{context}&\texttt{None}&dictionary of extern variables and functions\\
\texttt{title}&equal to the expression&title to be used in the graph key\\
\end{tabularx}
\medskip

The expression evaluation takes place at a linear raster on the
variable axis. More advanced methods (detection of rapidely changing
functions, handling of divergencies) are likely to be added in future
releases.

\subsection{Parametric functions}

The class \verb|paramfunction| provides data generation out of a
parametric representation of a function. The default style for
parametric function plotting is \verb|line|. The parameter list of the
constructor of \verb|paramfunction| starts with three parameters
describing the function parameter. The first parameter is a string,
namely the variable name. It is followed by a minimal and maximal
value to be used for that parameter. The next parameter contains an
expression assigning functions to the axis identifiers in a quite
pythonic tuple notation. As an example, such an expression could look
like \verb|"x, y = sin(k), cos(3*k)"|.

Additionally, the named parameters \verb|points|, \verb|parser|,
\verb|context|, and \verb|title| behave like their equally named
counterparts in \verb|function|.

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

Styles are used to draw data at a graph. A style determines what is
painted and how it is painted. Due to this powerfull approach there
are already some different styles available and the possibility to
introduce other styles opens even more prospects.

\subsection{Symbols}

The class \verb|symbol| can be used to plot symbols, errorbars and lines
configurable by parameters of the constructor. Providing \verb|None|
to attributes hides the according component.

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{symbol}&\texttt{changesymbol.cross()}&symbol to be used (see below)\\
\texttt{size}&\texttt{"0.2 cm"}&size of the symbol (visual length)\\
\texttt{symbolattrs}&\texttt{deco.stroked}&draw attributes for the symbol\\
\texttt{errorscale}&\texttt{0.5}&size of the errorbar caps (relative to the symbol size)\\
\texttt{errorbarattrs}&\texttt{()}&stroke attributes for the errorbars\\
\texttt{lineattrs}&\texttt{None}&stroke attributes for the line\\
\end{tabularx}
\medskip

The parameter \verb|symbol| has to be a routine, which returns a path to
be drawn (e.g. stroked or filled). There are several such routines
already available in the class \verb|symbol|, namely \verb|cross|,
\verb|plus|, \verb|square|, \verb|triangle|, \verb|circle|, and
\verb|diamond|. Furthermore, changeable attributes might be used here
(like the default value \verb|changesymbol.cross|), see
section~\ref{graph:changeattrs} for details.

The attributes are available as class variables after plotting the
style for outside usage. Additionally, the variable \verb|path|
contains the path of the line (even when it wasn't plotted), which
might be used to get crossing points, fill areas, etc.

Valid data names to be used when providing data to symbols are listed
in the following table. The character \verb|X| stands for axis names
like \verb|x|, \verb|x2|, \verb|y|, etc.

\begin{center}
\begin{tabular}{ll}
data name&description\\
\hline
\texttt{X}&position of the symbol\\
\texttt{Xmin}&minimum for the errorbar\\
\texttt{Xmax}&maximum for the errorbar\\
\texttt{dX}&relative size of the errorbar: \texttt{Xmin, Xmax = X-dX, X+Xd}\\
\texttt{dXmin}&relative minimum \texttt{Xmin = X-dXmin}\\
\texttt{dXmax}&relative maximum \texttt{Xmax = X+dXmax}\\
\end{tabular}
\end{center}

\subsection{Lines}

The class \verb|line| is inherited from the class \verb|symbol| and
restricted itself to line drawing. The constructor takes only the
\verb|lineattrs| keyword argment, which is by default set to
\verb|(changelinestyle(), style.linejoin.round)|. The other features
of the symbol style are turned off.

\subsection{Rectangles}

The class \verb|rect| draws filled rectangles into a graph. The size
and the position of the rectangles to be plotted can be provided by
the same data names like for the errorbars of the class \verb|symbol|.
Indeed, the class \verb|symbol| reuses most of the symbol code by
inheritance, while modifying the errorbar look into a colored filled
rectangle and turing off the symbol itself.

The color to be used for the filling of the rectangles is taken from a
palette provided to the constructor by the named parameter
\verb|palette| (default is \verb|color.palette.Gray|). The data
name \verb|color| is used to select the color out of this palette.

\subsection{Texts}

Another style to be used within graphs is the class \verb|text|, which
adds the output of text to the class \verb|symbol|. The text
position relative to the symbol is defined by the two named
parameters \verb|textdx| and \verb|textdy| having a default of
\verb|"0 cm"| and \verb|"0.3 cm"|, respectively, which are by default
interpreted as visual length. A further named parameter
\verb|textattrs| may contain a list of text attributes (or just a
single attribute). The default for this parameter is
\verb|text.halign.center|. Furthermore the constructor of this class
allows all other attributes of the class \verb|symbol|.

\subsection{Arrows}

The class \verb|arrow| can be used to plot small arrows into a graph
where the size and direction of the arrows has to be given within the
data. The constructor of the class takes the following parameters:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{linelength}&\texttt{"0.2 cm"}&length of a the arrow line (visual length)\\
\texttt{arrowattrs}&\texttt{()}&stroke attributes\\
\texttt{arrowsize}&\texttt{"0.1 cm"}&size of the arrow (visual length)\\
\texttt{arrowdict}&\texttt{\{\}}&attributes to be used in the \texttt{earrow} constructor\\
\texttt{epsilon}&1e-10&smallest allowed arrow size factor for a arrow to become plotted (avoid numerical instabilities)\\
\end{tabularx}
\medskip

The arrow allows for data names like the symbol and introduces
additionally the data names \verb|size| for the arrow size (as an
multiplicator for the sizes provided to the constructor) and
\verb|angle| for the arrow direction (in degree).

\subsection{Bars}

The class \verb|bar| must be used in combination with an
\verb|baraxis| in order to create bar plots. The constructor takes the
following parameters:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
\texttt{fromzero}&bars start at zero (boolean); default: \texttt{1}\\
\texttt{stacked}&stack bars (boolean/integer); for values bigger than 1 it is the number of bars to be stacked; default: \texttt{0}\\
\texttt{skipmissing}&skip entries in the bar axis, when datapoints are missing; default: \texttt{1}\\
\texttt{xbar}&bars parallel to the graphs x-direction (boolean); default: \texttt{0}\\
\texttt{barattrs}&fill attributes; default: \texttt{(deco.stroked(color.gray.black), changecolor.Rainbow())}\\
\end{tabularx}

Additionally, the bar style takes two data names appropriate to the
graph (like \verb|x|, \verb|x2|, and \verb|y|).

\subsection{Iterateable style attributes}
\label{graph:changeattrs}

The attributes provided to the constructors of styles can usually
handle so called iterateable attributes, which are changing itself
when plotting several data sets. Iterateable attributes can be easily
written, but there are already some iterateable attributes available
for the most common cases. For example a color change is done by
instances of the class \verb|colorchange|, where the constructor takes
a palette. Applying this attribute to a style and using this style at
a list of data, the color will get changed lineary along the
palette from one end to the other. The class \verb|colorchange|
includes inherited classes as class variables, which are called like
the color palettes shown in appendix~\ref{palettename}. For them the
default palette is set to the appropriate color palette.

Another attribute changer is called \verb|changesequence|. The
constructor takes a list of attributes and the attribute changer
cycles through this list whenever a new attribute is requested.
This attribute changer is used to implement the following attribute
changers:

\begin{center}
\begin{tabular}{ll}
attribute changer&description\\
\hline
\texttt{changelinestyle}&iterates linestyles solid, dashed, dotted, dashdotted\\
\texttt{changestrokedfilled}&iterates \texttt{(deco.stroked, deco.filled)}\\
\texttt{changefilledstroked}&iterates \texttt{(deco.filled, deco.stroked)}\\
\end{tabular}
\end{center}

The class \verb|changesymbol| can be used to cycle throu symbols and it
provides already various specialized classes as class variables. To
loop over all available symbols (cross, plus, square, triangle,
circle, and diamond) the equal named class variables can be used. They
start at that symbol they are named of. Thus \verb|changesymbol.cross()|
cycles throu the list starting at the cross symbol. Furthermore
there are four class variables called \verb|squaretwice|,
\verb|triangletwice|, \verb|circletwice|, and \verb|diamondtwice|.
They cycle throu the four fillable symbols, but returning the symbols
twice before they go on to the next one. They are intented to be used
in combination with \verb|changestrokedfilled| and
\verb|changefilledstroked|.

\section{Keys}

Graph keys can be created by instances of the class \verb|key|. Its
constructor takes the following keyword arguments:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
argument name&description\\
\hline
\texttt{dist}&(vertical) distance between the key entries (visual length); default: \texttt{"0.2 cm"}\\
\texttt{pos}&\texttt{"tr"} (top right; default), \texttt{"br"} (bottom right), \texttt{"tl"} (top left), \texttt{"bl"} (bottom left)\\
\texttt{hdist}&horizontal distance of the key (visual length); default: \texttt{"0.6 cm"}\\
\texttt{vdist}&vertical distance of the key (visual length); default: \texttt{"0.4 cm"}\\
\texttt{hinside}&align horizonally inside to the graph (boolean); default: \texttt{1}\\
\texttt{vinside}&align vertically inside to the graph (boolean); default: \texttt{1}\\
\texttt{symbolwidth}&width reserved for the symbol (visual length); default: \texttt{"0.5 cm"}\\
\texttt{symbolheight}&height reserved for the symbol (visual length); default: \texttt{"0.25 cm"}\\
\texttt{symbolspace}&distance between symbol and text (visual length); default: \texttt{"0.2 cm"}\\
\texttt{textattrs}&text attributes (a list or a single entry); default: \texttt{text.vshift.mathaxis}\\
\end{tabularx}
\medskip

The data description to be printed in the graph key is given by the
title of the data drawn.

\section{X-Y-Graph}

The class \verb|graphxy| draws standard x-y-graphs. It is a subcanvas
and can thus be just inserted into a canvas. The x-axes are named
\verb|x|, \verb|x2|, \verb|x3|, \dots and equally the y-axes. The
number of axes is not limited. All odd numbered axes are plotted at
the bottom (for x axes) and at the left (for y axes) and all even
numbered axes are plotted opposite to them. The lower numbers are
closer to the graph.

The constructor of \verb|graphxy| takes axes as named parameters where
the parameter name is an axis name as just described. Those parameters
refer to an axis instance as they where described in
section~\ref{graph:axes}. When no \verb|x| or \verb|y| is provided,
they are automatically set to instances of \verb|linaxis|. When no
\verb|x2| or \verb|y2| axes are given they are initialized as standard
linkaxis to the axis \verb|x| and \verb|y|. However, you can turn off
the automatism by setting those axes explicitly to \verb|None|.

However, the constructor takes some more attributes listed in the
following table:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{xpos}&\texttt{"0"}&x position of the graph (user length)\\
\texttt{ypos}&\texttt{"0"}&y position of the graph (user length)\\
\texttt{width}&\texttt{None}&width of the graph area (axes are outside of that range)\\
\texttt{height}&\texttt{None}&as abovem, but for the height\\
\texttt{ratio}&\texttt{goldenrule}&width/height ratio when only a width or height is provided\\
\texttt{backgroundattrs}&\texttt{None}&background attributes for the graph area\\
\texttt{axisdist}&\texttt{"0.8 cm"}&distance between axis (visual length)\\
\texttt{key}&\texttt{None}&\texttt{key} instance for an automatic graph key\\
\end{tabularx}
\medskip

After a graph is constructed, data can be plotted via the \verb|plot|
method. The first argument should be an instance of the data providing
classes described in section~\ref{graph:data}. This first parameter
can also be a list of those instances when you want to iterate the
style you explicitly provide as a second parameter to the plot method.
The plot method returns the plotinfo instance (or a list of plotinfo
instances when a data list was provided). The plotinfo class has
attributes \verb|data| and \verb|style|, which provide access to the
plotted data and the style, respectively. Just as an example, from the
style you can access the path of the drawed line, fill areas with it
etc.

After the plot method was called once or several times, you may
explicitly call the method \verb|finish|. Most of the graphs
functionallity becomes available just after (partially) finishing the
graph. A partial finish can even modify the order in which a graph
performs its drawing process. By default the five methods
\verb|dolayout|, \verb|dobackground|, \verb|doaxis|, \verb|dodata|,
and \verb|dokey| are called in that order. The method \verb|dolayout|
must always be called first, but this is internally ensured once you
call any of the routines yourself. After \verb|dolayout| gets called,
the method \verb|plot| can not be used anymore.

To get a position within a graph as a tuple out of some axes values,
the method \verb|pos| can be used. It takes two values for a position
at the x and y axis. By default, the axes named \verb|x| or \verb|y|
are used, but this is changed when the keyword arguments \verb|xaxis|
and \verb|yaxis| are set to other axes. The graph axes are available
by their name using the dictionary \verb|axes|. There is also an
dictionary \verb|axespos|, which contains \verb|lineaxespos| instances
for all axes. They implement the \verb|_Iaxispos| interface, thus
having the following methods:

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
method name&description\\
\hline
\texttt{basepath(x1=None, x2=None)}&returns the base path for the range \texttt{x1} to \texttt{x2}, (hole range, when omitting the parameters)\\
\texttt{vbasepath(x1=None, x2=None)}&as above but for graph coordinates\\
\texttt{gridpath(x)}&returns the grid path\\
\texttt{vgridpath(x)}&as above but for graph coordinates\\
\texttt{tickpoint(x)}&returns the position of a tick\\
\texttt{vtickpoint(x)}&as above but for graph coordinates\\
\texttt{tickdirection(x)}&returns the direction, a tick should be drawn (towards inside of the graph)\\
\texttt{vtickdirection(x)}&as above but for graph coordinates\\
\end{tabularx}
\medskip

Its likely, that this interface will change to contain local
transformation for the tick position/direction in a future release.
For the axes named \verb|x| and \verb|y|, the methods are available
within the graph (like the \verb|pos| method), where the method name
is prefixed by \verb|x| or \verb|y|, respectively.

To manually add a graph key, use the \verb|addkey| method, which takes
a \verb|key| instance first followed by several \verb|plotinfo|
instances.