transformation example

[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 incompatibilities, for
example they are expected to happen for automatic axis ticking (which
will therefore not yet be covered within this manual). 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}

Additional axis types are likely to be added in the future.

\subsection{Axes properties}

Global properties of an axis are set as named parameters in the axis
constructor. Both predefined axis, 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 (its default value is 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 is 0.05\\
\texttt{datavmax}&as above, but for the maximum; default is 0.95\\
\texttt{tickvmin}&minimal graph coordinate for placing ticks to the axis; default is 0\\
\texttt{tickvmax}&as above, but for the maximum; default is 1\\
\texttt{part}&axis partitioning (described below)\\
\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|, \verb|labellevel|. If
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.

Although there is a rudimentary automatic axis partitioning, the
recommended solution at the moment is a manual axis partitioning,
because the manual axis partitioning will hopefully not break in
future versions, while the automatic axis breaking will change for
sure at least in the results it creates.

There are three different manual partition schemes, a manual
partition, another appropriate for linear axes and a third one for
logarithmic axes.

\subsubsection{Manual partitioning}

The class \verb|manualpart| creates a manual 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}&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.

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}

When no explicit axis partitioning is given, an automatic axis
partitioning is already available, but it is still considered to be
under development. A major feature is missing, namely the rating of
possible partitions does not yet attend the label texts, which is
important in order to avoid overlap of label texts. In order to
provide it, the rating of axis partitions has to be moved into the
axis painter. That has just to be done and is considered for the next
major release of \PyX.

\subsection{Painting of axes}

A major task of an axis is the painting of itself. It is done by
instances of \verb|axispainter|, provided to the constructor of an
axis as its painter. 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{((), tex.fontsize.footnotesize)}\\
\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{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.

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

\subsection{List of points}

Instances of the class \verb|data| link a \verb|datafile| and a
\verb|style| (see below; default is \verb|mark|). The link object is
needed in order to be able to plot several data from a singe file
without reading the file several times which would just be a bad
design. However, for easy usage, it is possible to provide a filename
instead of a datafile as the first argument to the constructor of the
class \verb|data| hiding the underlying \verb|datafile| instance
completely from view. This is the preverable 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 expressions, as the following table
will show by some examples.

\begin{center}
\begin{tabular}{ll}
selection method&example\\
\hline
as in \texttt{datafile.getcolumnno}&\texttt{data("test.dat", x=1,}\\
&\texttt{\hphantom{data(}y="result", dy="delta")}\\
by mathematical expressions&\texttt{data("test.dat", x="0.5*\$1",}\\
&\texttt{\hphantom{data(}y="0.5*result", dy="0.5*a", a=3)}\\
\end{tabular}
\end{center}

Note that mathematical expressions get evaluated by
\verb|datafile.addcolumn| and thus the same column identifications
become available.

\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 may use the string format syntax to insert
external parameters, \textit{e.g.} \verb|"y=sin(%f*x)" % a| where
\verb|a| is a float variable.

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\\
\end{tabularx}
\medskip

The expression evaluation takes place at a linear raster of 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 two named parameters \verb|points| and \verb|parser|
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 marker types available and the possibility
to introduce other styles opens even more prospects.

On the other hand there is not yet any support for bar graphs. This is
due to the fact that it might be better implemented together with some
specialized axes. It will be shown in the future, what solution will
arise out of that idea instead of an disposable implementation right
now.

\subsection{Marks}

The class \verb|mark| can be used to plot markers, 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{mark}&\texttt{changemark.cross()}&marker to be used (see below)\\
\texttt{size}&\texttt{"0.2 cm"}&size of the marker (visual length)\\
\texttt{markattrs}&\texttt{canvas.stroked()}&draw attributes for the marker\\
\texttt{errorscale}&\texttt{0.5}&size of the errorbar caps (relative to the marker size)\\
\texttt{errorbarattrs}&\texttt{()}&stroke attributes for the errorbars\\
\texttt{lineattrs}&\texttt{None}&stroke attributes for the line\\
\end{tabularx}
\medskip

The parameter \verb|mark| has to be a routine, which returns a path to
be drawn (e.g. stoked or filled). There are several those routines
already available in the class \verb|mark|, 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|changemark.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 markers 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 marker\\
\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 \verb|mark| and is restricted
to line drawing. The constructor takes only \verb|lineattrs| and its
default is set to \verb|changelinestyle()|. The other features of the
mark 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|mark|.
Indeed, the class \verb|mark| reuses most of the marker code by
inheritance, while modifying the errorbar look into a colored filled
rectangle and turing off the marker itself.

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

\subsection{Texts}

Another style to be used within graphs is the class \verb|text|, which
adds the output of text to the class \verb|mark|. The text
position relative to the markers 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|tex.halign.center|. Furthermore the constructor of this class
allows all other attributes of the class \verb|mark|.

\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 mark 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{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 gradient. Applying this attribute to a style and using this style at
a sequence of data, the color will get changed lineary along the
gradient from one end to the other. The class \verb|colorchange|
includes inherited classes as class variables, which are called like
the color gradients shown in appendix~\ref{gradientname}. For them the
default gradient is set to the appropriate color gradient.

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|changemark| can be used to cycle throu markers and it
provides already various specialized classes as class variables. To
loop over all available markers (cross, plus, square, triangle,
circle, and diamond) the equal named class variables can be used. They
start at that marker they are named of. Thus \verb|changemark.cross()|
cycles throu the sequence starting at the cross marker. Furthermore
there are four class variables called \verb|squaretwice|,
\verb|triangletwice|, \verb|circletwice|, and \verb|diamondtwice|.
They cycle throu the four fillable markers, but returning the markers
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}
Sorry, there is not yet any support for graph keys.

\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, namely first of
all a tex canvas. (This ugly construction is likely to be ommited in
future versions of \PyX{} once a new \TeX{} binding becomes
available.) Other parameters are named and 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)\\
\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 style (or a list of styles when a data
list was provided) which was used for plotting. Just as an example you
can thus access the path of a line and fill areas with it and so on.

After the plot method was called once or several times, you should
call the method \verb|finish|. (This is actually needed as long as a
tex canvas gets used for text output and the tex canvas is inserted
into the main canvas before the graph gets inserted.) Finishing a
graph allows for the access to positioning routines which can be quite
usefull to plot additional information into a graph.

Sometimes it is also nice to partly finish a graph. By that you can
even modify the order in which a graph performs its drawing process.
By default the four methods \verb|dolayout|, \verb|dobackground|,
\verb|doaxis|, and \verb|dodata| 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 named parameters \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 gridpath for a
given position at the axis.

\section{Examples}

\subsection{A minimal example: plot data from a file}

We plot data from the file \verb|"graph.dat"|:

\begin{quote}
\begin{verbatim}
1   2
2   3
3   8
4  13
5  18
6  21
\end{verbatim}
\end{quote}

The following script creates the file \verb|"graph.eps"|:

\begin{quote}
\begin{verbatim}
from pyx import *

c = canvas.canvas()
t = c.insert(tex.tex())
g = c.insert(graph.graphxy(t, width=10))
g.plot(graph.data("graph.dat", x=1, y=2))
g.finish()
c.writetofile("graph")
\end{verbatim}
\end{quote}

The result looks like:
\begin{quote}
\includegraphics{graph1}
\end{quote}

\subsection{A more advanced function plot}

\begin{quote}
\begin{verbatim}
from pyx import *
from pyx.graph import *

c = canvas.canvas()
t = tex.tex()

a, b = 2, 9

mypainter=axispainter(baselineattrs=canvas.earrow.normal)

g = c.insert(graphxy(t, width=10, x2=None, y2=None,
                     x=linaxis(min=0, max=10,
                               part=manualpart(ticks=(frac(a, 1),
                                                      frac(b, 1)),
                                               texts=("a", "b")),
                               painter=mypainter),
                     y=linaxis(painter=mypainter,
                               part=manualpart())))

line = g.plot(function("y=(x-3)*(x-5)*(x-7)"))
g.finish()

pa = path.path(g.axes["x"].gridpath(a))
pb = path.path(g.axes["x"].gridpath(b))
(splita,), (splitpa,) = line.path.intersect(pa)
(splitb,), (splitpb,) = line.path.intersect(pb)
area = (pa.split(splitpa)[0] <<
        line.path.split(splita, splitb)[1] <<
        pb.split(splitpb)[0].reversed())
area.append(path.closepath())
g.stroke(area, canvas.linewidth.THick,
         canvas.filled(color.gray(0.8)))
t.text(g.pos(0.5*(a+b), 0)[0], 1,
       r"\int_a^b f(x) {\rm d}x", tex.halign.center, tex.style.math)

c.insert(t)
c.writetofile("graph2")
\end{verbatim}
\end{quote}

The result looks like:
\begin{quote}
\includegraphics{graph2}
\end{quote}