chmod

[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.
By that, all other components can be reused for different graph
geometries.

\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.

\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{datavmin}&minimal graph coordinate when adjusting the axis minima to the graph data; default: \texttt{0.05} (or \texttt{0}, when min is present)\\
\texttt{datavmax}&as above, but for the maximum; default: \texttt{0.95} (or \texttt{1}, when max is present)\\
\texttt{tickvmin}&minimal graph coordinate for placing ticks to the axis; default: \texttt{0}\\
\texttt{tickvmax}&as above, but for the maximum; default: \texttt{1}\\
\texttt{part}&axis partitioning (described below)\\
\texttt{rate}&axis partition rating (described below)\\
\texttt{dense}&dense parameter for the axis partition rating; if not set, the dense value for the graph is used\\
\texttt{painter}&axis painter (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.
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| and \verb|labellevel|.
When those values are \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|text|
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.

We will first discuss manual partitioning schemes, namely a plain
manual partition, another appropriate for linear axes and a third one
for logarithmic axes. These partition schemes might be used directly
or indirectly via automatic axis partioning schemes.

\subsubsection{Manual partitioning}

The class \verb|manualpart| creates a manual partition where every
single tick, label etc. is set independendly from each other as
described by named parameters of the constructor:

\medskip
\begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X}
argument name&default&description\\
\hline
\texttt{ticks}&\texttt{None}&position of ticks, subticks, etc. (see below)\\
\texttt{labels}&\texttt{None}&position of labels, sublabels, etc. (see below)\\
\texttt{texts}&\texttt{None}&force text at labels, sublabels, etc. (see below)\\
\texttt{mix}&\texttt{()}&ordered tick list to be merged into the result\\
\end{tabularx}
\medskip

The parameters \verb|ticks|, \verb|labels|, and \verb|texts| can
either be a sequence, or a sequence of sequences. (When it is not a
sequence at all, it is converted to a sequence with a single entry.)
When it is a sequence of sequences, than the first sequence stands for
the ticks, labels, and texts of the labels, the second sequence stands
for the subticks, sublabels, and texts of the sublabels, and so on.
When it is just a sequence, it stands for the ticks, labels and texts
of the labels and no subticks, sublabels and subtexts will be created.

The single entries of \verb|ticks| and \verb|labels| can either be a
frac or a string, which will be converted to a frac. However, a float
is not valid in order to avoid a conversion from a float to a frac.
Valid strings are just numbers like \verb|"0.1"|, or fractions like
\verb|"1/10"|.

\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{ticks}&\texttt{None}&distance between ticks, subticks, etc. (see comment below); when the parameter is \texttt{None}, ticks will get placed at labels\\
\texttt{labels}&\texttt{None}&distance between labels, sublabels, etc. (see comment below); when the parameter is \texttt{None}, labels will get placed at ticks\\
\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\\
\texttt{texts}&\texttt{None}&as in manualpart\\
\texttt{mix}&\texttt{()}&as in manualpart\\
\end{tabularx}
\medskip

The \verb|ticks| and \verb|labels| can either be a sequence or just a
single entry. When a sequence is provided, the first entry stands for
the tick or label, respectively, the second for the subtick or
sublabel, and so on. The entries can either be a frac or a string,
as in \verb|manualpart|.

\subsubsection{Partitioning of logarithmic axes}

The class \verb|logpart| create a logarithmic partition. The class has
the same arguments as \verb|linpart| upto the interpretation of two
arguments \verb|ticks| and \verb|labels|. Both parameters can contain
just a single entry or a sequence --- the interpretation of those
possibilities is the same as it was for \verb|linpart|. The entries
have to be \verb|shiftfracs|, which contains a \verb|frac| for the
shift, say $s$, and a list of \verb|frac| for the positions, say
$p_i$. Valid positions are then $s^np_i$, where $n$ can be any integer
number. Within \verb|logpart| there are numerous predefined
\verb|shiftfracs|, namely:

\begin{center}
\begin{tabular}{ll}
name&values it descibes\\
\hline
\texttt{shift5fracs1}&1 and multiple of $10^5$\\
\texttt{shift4fracs1}&1 and multiple of $10^4$\\
\texttt{shift3fracs1}&1 and multiple of $10^3$\\
\texttt{shift2fracs1}&1 and multiple of $10^2$\\
\texttt{shiftfracs1}&1 and multiple of $10$\\
\texttt{shiftfracs125}&1, 2, 5 and multiple of $10$\\
\texttt{shiftfracs1to9}&1, 2, \dots, 9 and multiple of $10$\\
\end{tabular}
\end{center}

\subsubsection{Automatic partitioning of linear axes}

When no explicit axis partitioning is given in the constructor of an
linear axis, it is initialized with an automatic partitioning schemes
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{list}&\texttt{defaultlist}&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\\
\texttt{mix}&\texttt{()}&as in manualpart\\
\end{tabularx}
\medskip

The default value for the argument \verb|list|, namely
\verb|defaultlist|, 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. Additionally, as most
likely already from the default value of the argument \verb|list|, the
given fractions are automatically multiplied or divided by 10 in order
to fit better to the axis range. Therefore these additional
partitioning possibilities must not be given explicitly.

\subsubsection{Automatic partitioning of logarithmic axes}

When no explicit axis partitioning is given in the constructor 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{list}&\texttt{defaultlist}&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\\
\texttt{mix}&\texttt{()}&as in manualpart\\
\end{tabularx}
\medskip

The default value for the argument \verb|list|, namely
\verb|defaultlist|, is defined as a class variable of
\verb|autologpart| and has the value:
\begin{verbatim}
(((shiftfracs1, shiftfracs1to9),        # ticks & subticks,
         (shiftfracs1, shiftfracs125)), # labels & sublevels
 ((shiftfracs1, shiftfracs1to9), None), # ticks & subticks, labels=ticks
 ((shift2fracs1, shiftfracs1), None),   # ticks & subticks, labels=ticks
 ((shift3fracs1, shiftfracs1), None),   # ticks & subticks, labels=ticks
 ((shift4fracs1, shiftfracs1), None),   # ticks & subticks, labels=ticks
 ((shift5fracs1, shiftfracs1), 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|rate| 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|dense| of the axis (or graph) 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. This parameter was taken out of the
rating class for easier access.

\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 lines; default: \texttt{None}\\
\texttt{zerolineattrs}$^{3,4}$&stroke attributes for a grid line at axis value 0; default: \texttt{()}\\
\texttt{baselineattrs}$^{3,4}$&stroke attributes for the axis baseline;\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{((textmodule.halign.center, textmodule.vshift.mathaxis), (textmodule.size.footnotesize, textmodule.halign.center, textmodule.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{()}\\
\texttt{titledirection}$^4$&relative title direction (see below);\newline default: \texttt{axispainter.paralleltext}\\
\texttt{titlepos}&title position in graph coordinates; default: \texttt{0.5}\\
\texttt{fractype}&text creation for labels (see below);\newline default: \texttt{axispainter.fractypeauto}\\
\texttt{ratfracsuffixenum}&write suffix at the enumerator (boolean); default: \texttt{1}\\
\texttt{ratfracover}&text for fraction line; default: \texttt{r"\textbackslash over"}\\
\texttt{decfracpoint}&decimal point; default: \texttt{"."}\\
\texttt{decfracequal}&equalize number of decimal digits (boolean); default: \texttt{0}\\
\texttt{expfractimes}&text between factor and decimal power; default: \texttt{r"\textbackslash cdot"}\\
\texttt{expfracpre1}&allow factor 1 before a decimal power (boolean); default: \texttt{0}\\
\texttt{expfracminexp}&minimal exponent for decimal power; default: \texttt{4}\\
\texttt{suffix0}&when a suffix is \texttt{x} write \texttt{0x} instead of \texttt{0} (boolean); default: \texttt{0}\\
\texttt{suffix1}&when a suffix is \texttt{x} write \texttt{1x} instead of \texttt{x} (boolean); default: \texttt{0}\\
\end{tabularx}
\medskip

$^1$
The parameter should be a sequence, where the entries are attributes
for the different levels. When the level is larger then the sequence
length, \verb|None| is assumed. When the parameter is not a sequence,
it is applied to all levels.\\
$^2$
The parameter should be a sequence of sequences, where the entries are
attributes for the different levels. When the level is larger then the
sequence length, \verb|None| is assumed. When the parameter is not a
sequence of sequences, it is applied to all levels.\\
$^3$
The parameter should be a sequence. When the parameter is not a
sequence, the parameter is interpreted as a sequence with a single
entry.\\
$^4$
The feature can be turned off by the value \verb|None|. Within
sequences or sequences of sequences, 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 basically a float number in degree. The
text direction is calculated relatively to the baseline of the axis
and is added as an attribute of the text, when no direction was
already provided. The relative direction prevents upside down text by
flipping it by 180 degrees. For convenience, the two self-explanatory
values \verb|axispainter.paralleltext| and
\verb|axispainter.orthogonaltext| are available.

The \verb|fractype| parameter determines the creation of label texts.
There are three types available, which can be forced by providing them
to the \verb|fractype| parameter. The possibilities are listed in the
following table.

\begin{center}
\begin{tabular}{lll}
\texttt{fractype}&description&example\\
\hline
\texttt{axispainter.fractypedec}&decimal&$0.1$\\
\texttt{axispainter.fractypeexp}&decimal with exponent&$2\cdot 10^4$\\
\texttt{axispainter.fractyperat}&rational&$\displaystyle{{1}\over{2}}$\\
\texttt{axispainter.fractypeauto}&automatic (see below)&\\
\end{tabular}
\end{center}

For the default \verb|axispainter.fractypeauto| the three
possibilities are selected depending on some simple rules:
\verb|axispainter.fractyperat| is used, when the axis provides a
suffix, \verb|axispainter.fractypeexp| is used, when the exponent
exceed \verb|expfracminexp|, and \verb|axispainter.fractypedec| is
used otherwise.

\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. The
constructor of \verb|linkaxis| receives the axis it is linked to as
its first parameter. Additionally, the named parameter \verb|title|
contains an axis title (default is \verb|None|) and the named
parameter \verb|painter| refers to an axispainter (default is
\verb|linkaxispainter|). This \verb|linkedaxispainter| is a slightly
modified version of the standard \verb|axispainter|. Hence it can
receive all the parameters as the \verb|axispainter| and only the
default value of the parameter \verb|zerolineattrs| is changed to
\verb|None| compared to the \verb|axispainter| previously discussed.
Additionally, two parameters are added, namely \verb|skipticklevel|
and \verb|skiplabellevel|. They are used to build the tick list to be
plotted at the linked axis. Ticks and labels at levels equal or higher
as the provided values get ignored. The default is \verb|None| (do not
ignore any ticks) for the ticks and \verb|0| (ignore all labels) for
the labels.

\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|.
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}&allow for multiple subaxis (boolean); default: \texttt{0}\\
\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 possition 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 for each value the same recursive subaxis
transformation has to be applied. However, this prevents the subaxis
to be painted, but as soon as multisubaxis is turned on, 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 (right now, this is only available
for the bar axis). 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|baselineattrs|.
Furthermore the parameters \verb|innerticklength| and
\verb|outerticklength| work like their counterparts in the
\verb|axispainter|, but only plain values are allowed there (no
tuples). 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 an axis 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{canvas.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(), canvas.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 sequence 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{(canvas.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 sequence 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, dasheddotted\\
\texttt{changestrokedfilled}&iterates \texttt{(canvas.stroked(), canvas.filled())}\\
\texttt{changefilledstroked}&iterates \texttt{(canvas.filled(), canvas.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 sequence 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|. Each axis has a method
\verb|gridpath| which is set by the graph. It returns a path of a grid
line for a given position at the axis.

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