reencoding->recompression

[PyX.git] / manual / axis.tex

\chapter{Axes}
\label{axis}
\section{Component architecture} % {{{

Axes are a fundamental component of graphs although there might be
applications outside of the graph system. Internally axes are
constructed out of components, which handle different tasks axes need
to fulfill:

\begin{definitions}
\term{axis}
  Implements the conversion of a data value to a graph coordinate of
  range [0:1]. It does also handle the proper usage of the components
  in complicated tasks (\emph{i.e.} combine the partitioner, texter,
  painter and rater to find the best partitioning).

  An anchoredaxis is a container to combine an axis with an positioner
  and provide a storage area for all kind of axis data. That way axis
  instances are reusable (they do not store any data locally). The
  anchoredaxis and the positioner are created by a graph corresponding
  to its geometry.
\term{tick}
  Ticks are plotted along the axis. They might be labeled with text as
  well.
\term{partitioner, we use ``parter'' as a short form}
  Creates one or several choices of tick lists suitable to a certain
  axis range.
\term{texter}
  Creates labels for ticks when they are not set manually.
\term{painter}
  Responsible for painting the axis.
\term{rater}
  Calculate ratings, which can be used to select the best suitable
  partitioning.
\term{positioner}
  Defines the position of an axis.
\end{definitions}

The names above map directly to modules which are provided in the
directory \file{graph/axis} except for the anchoredaxis, which is part
of the axis module as well. Sometimes it might be convenient to import
the axis directory directly rather than to access iit through the
graph. This would look like:
\begin{verbatim}
  from pyx import *
  graph.axis.painter() # and the like

  from pyx.graph import axis
  axis.painter() # this is shorter ...
\end{verbatim}

In most cases different implementations are available through
different classes, which can be combined in various ways. There are
various axis examples distributed with \PyX{}, where you can see some
of the features of the axis with a few lines of code each. Hence we
can here directly come to the reference of the available
components. % }}}

\section{Module \module{graph.axis.axis}: Axes} % {{{

\declaremodule{}{graph.axis.axis}
\modulesynopsis{Axes}

The following classes are part of the module \module{graph.axis.axis}.
However, there is a shortcut to access those classes via
\code{graph.axis} directly.

Instances of the following classes can be passed to the \var{**axes}
keyword arguments of a graph. Those instances should only be used once.

\begin{classdesc}{linear}{min=None, max=None, reverse=0, divisor=None, title=None,
                          parter=parter.autolinear(), manualticks=[],
                          density=1, maxworse=2, rater=rater.linear(),
                          texter=texter.mixed(), painter=painter.regular(),
                          linkpainter=painter.linked()}
  This class provides a linear axis. \var{min} and \var{max} define the
  axis range. When not set, they are adjusted automatically by the
  data to be plotted in the graph. Note, that some data might want to
  access the range of an axis (\emph{e.g.} the \class{function} class
  when no range was provided there) or you need to specify a range
  when using the axis without plugging it into a graph (\emph{e.g.}
  when drawing an axis along a path).

  \var{reverse} can be set to indicate a reversed axis starting with
  bigger values first. Alternatively you can fix the axis range by
  \var{min} and \var{max} accordingly. When divisor is set, it is
  taken to divide all data range and position informations while
  creating ticks. You can create ticks not taking into account a
  factor by that. \var{title} is the title of the axis.

  \var{parter} is a partitioner instance, which creates suitable ticks
  for the axis range. Those ticks are merged with ticks manually given 
  by \var{manualticks} before proceeding with rating, painting
  \emph{etc.} Manually placed ticks win against those created by the
  partitioner. For automatic partitioners, which are able to calculate
  several possible tick lists for a given axis range, the
  \var{density} is a (linear) factor to favour more or less ticks. It
  should not be stressed to much (its likely, that the result would be
  unappropriate or not at all valid in terms of rating label
  distances). But within a range of say 0.5 to 2 (even bigger for
  large graphs) it can help to get less or more ticks than the default
  would lead to. \var{maxworse} is the number of trials with more
  and less ticks when a better rating was already found. \var{rater}
  is a rater instance, which rates the ticks and the label distances
  for being best suitable. It also takes into account \var{density}.
  The rater is only needed, when the partitioner creates several tick
  lists.

  \var{texter} is a texter instance. It creates labels for those
  ticks, which claim to have a label, but do not have a label string
  set already. Ticks created by partitioners typically receive their
  label strings by texters. The \var{painter} is finally used to
  construct the output. Note, that usually several output
  constructions are needed, since the rater is also used to rate the
  distances between the labels for an optimum. The \var{linkedpainter}
  is used as the axis painter, when automatic link axes are created by
  the \method{createlinked()} method.
\end{classdesc}

\begin{classdesc}{lin}{...}
  This class is an abbreviation of \class{linear} described above.
\end{classdesc}

\begin{classdesc}{logarithmic}{min=None, max=None, reverse=0, divisor=None, title=None,
                               parter=parter.autologarithmic(), manualticks=[],
                               density=1, maxworse=2, rater=rater.logarithmic(),
                               texter=texter.mixed(), painter=painter.regular(),
                               linkpainter=painter.linked()}
  This class provides a logarithmic axis. All parameters work like
  \class{linear}. Only two parameters have a different default:
  \var{parter} and \var{rater}. Furthermore and most importantly, the
  mapping between data and graph coordinates is logarithmic.
\end{classdesc}

\begin{classdesc}{log}{...}
This class is an abbreviation of \class{logarithmic} described above.
\end{classdesc}

\begin{classdesc}{bar}{subaxes=None,
                       defaultsubaxis=linear(painter=None,
                                             linkpainter=None,
                                             parter=None,
                                             texter=None),
                       dist=0.5, firstdist=None, lastdist=None,
                       title=None, reverse=0,
                       painter=painter.bar(),
                       linkpainter=painter.linkedbar()}
  This class provides an axis suitable for a bar style. It handles a
  discrete set of values and maps them to distinct ranges in graph
  coordinates. For that, the axis gets a tuple of two values.

  The first item is taken to be one of the discrete values valid on
  this axis. The discrete values can be any hashable type and the
  order of the subaxes is defined by the order the data is recieved or
  the inverse of that when \var{reverse} is set.

  The second item is passed to the corresponding subaxis. The result
  of the conversion done by the subaxis is mapped to the graph
  coordinate range reserved for this subaxis. This range is defined by
  a size attribute of the subaxis, which can be added to any axis.
  (see the sized linear axes described below for some axes already
  having a size argument). When no size information is available for a
  subaxis, a size value of 1 is used. The baraxis itself calculates
  its size by suming up the sizes of its subaxes plus \var{firstdist},
  \var{lastdist} and \var{dist} times the number of subaxes minus 1.

  \var{subaxes} should be a list or a dictionary mapping a discrete
  value of the bar axis to the corresponding subaxis. When no subaxes
  are set or data is recieved for a unknown descrete axis value,
  instances of defaultsubaxis are used as the subaxis for this
  discrete value.

  \var{dist} is used as the spacing between the ranges for each
  distinct value. It is measured in the same units as the subaxis
  results, thus the default value of \code{0.5} means half the width
  between the distinct values as the width for each distinct value.
  \var{firstdist} and \var{lastdist} are used before the first and
  after the last value. When set to \code{None}, half of \var{dist}
  is used.

  \var{title} is the title of the split axes and \var{painter} is a
  specialized painter for an bar axis and \var{linkpainter} is used as
  the painter, when automatic link axes are created by the
  \method{createlinked()} method.
\end{classdesc}

\begin{classdesc}{nestedbar}{subaxes=None,
                             defaultsubaxis=bar(dist=0, painter=None, linkpainter=None),
                             dist=0.5, firstdist=None, lastdist=None,
                             title=None, reverse=0,
                             painter=painter.bar(),
                             linkpainter=painter.linkedbar()}
   This class is identical to the bar axis except for the different
   default value for defaultsubaxis.
\end{classdesc}

\begin{classdesc}{split}{subaxes=None,
                         defaultsubaxis=linear(),
                         dist=0.5, firstdist=0, lastdist=0,
                         title=None, reverse=0,
                         painter=painter.split(),
                         linkpainter=painter.linkedsplit()}
   This class is identical to the bar axis except for the different
   default value for defaultsubaxis, firstdist, lastdist, painter, and
   linkedpainter.
\end{classdesc}

Sometimes you want to alter the default size of 1 of the subaxes. For
that you have to add a size attribute to the axis data. The two
classes \class{sizedlinear} and \class{autosizedlinear} do that for
linear axes. Their short names are \class{sizedlin} and
\class{autosizedlin}. \class{sizedlinear} extends the usual linear
axis by an first argument \var{size}. \class{autosizedlinear} creates
the size out of its data range automatically but sets an
\class{autolinear} parter with \var{extendtick} being \code{None} in
order to disable automatic range modifications while painting the
axis.

The \module{axis} has two classes implementing so called anchored
axes, which combine an axis with an positioner and a storage place for
axis related data. Since these features are not interesting for the
average \PyX{} user, we'll not go into the details of their paramters
and except for some handy axis position methods:

\begin{methoddesc}[anchoredaxis]{basepath}{x1=None, x2=None}
  Returns a path instance for the base path. \var{x1} and \var{x2}
  define the axis range, the base path should cover. For \code{None}
  the beginning and end of the path is taken, which might cover a
  longer range, when the axis is embedded as a subaxis. For that case,
  a \code{None} value extends the range to the point of the middle
  between two subaxes or the beginning or end of the whole axis, when
  the subaxis is the first or last of the subaxes.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{vbasepath}{v1=None, v2=None}
  Like \method{basepath} but in graph coordinates.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{gridpath}{x}
  Returns a path instance for the grid path at position \var{x}.
  Might return \code{None} when no grid path is available.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{vgridpath}{v}
  Like \method{gridpath} but in graph coordinates.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{tickpoint}{x}
  Returns the position of \var{x} as a tuple \samp{(x, y)}.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{vtickpoint}{v}
  Like \method{tickpoint} but in graph coordinates.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{tickdirection}{x}
  Returns the direction of a tick at \var{x} as a tuple \samp{(dx, dy)}.
  The tick direction points inside of the graph.
\end{methoddesc}

\begin{methoddesc}[anchoredaxis]{vtickdirection}{v}
  Like \method{tickdirection} but in graph coordinates.
\end{methoddesc}

Finally in the axis module there is an easy to use
\class{anchoredpathaxis} class to create an anchored axis along an
arbitrary path:

\begin{classdesc}{anchoredpathaxis}{path, axis, direction=1}
  This class implements an anchored axis the path \var{path}.
  \var{direction} defines the direction of the ticks. Allowed values
  are \code{1} (left) and \code{-1} (right).
\end{classdesc}

The \class{anchoredpathaxis} contains the painted axis in the
\member{canvas} member attribute. The function \function{pathaxis} has
the same signature like the \class{anchoredpathaxis} class, but
directly returns the painted axis. % }}}

\section{Module \module{graph.axis.tick}: Ticks} % {{{

\declaremodule{}{graph.axis.tick}
\modulesynopsis{Axes ticks}

The following classes are part of the module \module{graph.axis.tick}.

\begin{classdesc}{rational}{x, power=1, floatprecision=10}
  This class implements a rational number with infinite precision. For
  that it stores two integers, the numerator \code{num} and a
  denominator \code{denom}. Note that the implementation of rational
  number arithmetics is not at all complete and designed for its
  special use case of axis partitioning in \PyX{} preventing any
  roundoff errors.

  \var{x} is the value of the rational created by a conversion from
  one of the following input values:
  \begin{itemize}
  \item A float. It is converted to a rational with finite precision
    determined by \var{floatprecision}.
  \item A string, which is parsed to a rational number with full
    precision. It is also allowed to provide a fraction like
    \code{\textquotedbl{}1/3\textquotedbl}.
  \item A sequence of two integers. Those integers are taken as
    numerator and denominator of the rational.
  \item An instance defining instance variables \code{num} and
  \code{denom} like \class{rational} itself.
  \end{itemize}

  \var{power} is an integer to calculate \code{\var{x}**\var{power}}.
  This is useful at certain places in partitioners.
\end{classdesc}

\begin{classdesc}{tick}{x, ticklevel=0, labellevel=0, label=None,
                        labelattrs=[], power=1, floatprecision=10}
  This class implements ticks based on rational numbers. Instances of
  this class can be passed to the \code{manualticks} parameter of a
  regular axis.

  The parameters \var{x}, \var{power}, and \var{floatprecision} share
  its meaning with \class{rational}.

  A tick has a tick level (\emph{i.e.} markers at the axis path) and a
  label lavel (\emph{e.i.} place text at the axis path),
  \var{ticklevel} and \var{labellevel}. These are non-negative
  integers or \var{None}. A value of \code{0} means a regular tick or
  label, \code{1} stands for a subtick or sublabel, \code{2} for
  subsubtick or subsublabel and so on. \code{None} means omitting the
  tick or label. \var{label} is the text of the label. When not set,
  it can be created automatically by a texter. \var{labelattrs} are
  the attributes for the labels.
\end{classdesc} % }}}

\section{Module \module{graph.axis.parter}: Partitioners} % {{{

\declaremodule{}{graph.axis.parter}
\modulesynopsis{Axes partitioners}

The following classes are part of the module \module{graph.axis.parter}.
Instances of the classes can be passed to the parter keyword argument
of regular axes.

\begin{classdesc}{linear}{tickdists=None, labeldists=None,
                          extendtick=0, extendlabel=None,
                          epsilon=1e-10}
  Instances of this class creates equally spaced tick lists. The
  distances between the ticks, subticks, subsubticks \emph{etc.}
  starting from a tick at zero are given as first, second, third
  \emph{etc.} item of the list \var{tickdists}. For a tick position,
  the lowest level wins, \emph{i.e.} for \code{[2, 1]} even numbers
  will have ticks whereas subticks are placed at odd integer. The
  items of \var{tickdists} might be strings, floats or tuples as
  described for the \var{pos} parameter of class \class{tick}.

  \var{labeldists} works equally for placing labels. When
  \var{labeldists} is kept \code{None}, labels will be placed at each
  tick position, but sublabels \emph{etc.} will not be used. This copy
  behaviour is also available \emph{vice versa} and can be disabled by
  an empty list.

  \var{extendtick} can be set to a tick level for including the next
  tick of that level when the data exceed the range covered by the
  ticks by more then \var{epsilon}. \var{epsilon} is taken relative
  to the axis range. \var{extendtick} is disabled when set to
  \code{None} or for fixed range axes. \var{extendlabel} works similar
  to \var{extendtick} but for labels.
\end{classdesc}

\begin{classdesc}{lin}{...}
This class is an abbreviation of \class{linear} described above.
\end{classdesc}

\begin{classdesc}{autolinear}{variants=defaultvariants,
                              extendtick=0,
                              epsilon=1e-10}
  Instances of this class creates equally spaced tick lists, where the
  distance between the ticks is adjusted to the range of the axis
  automatically. Variants are a list of possible choices for
  \var{tickdists} of \class{linear}. Further variants are build out of
  these by multiplying or dividing all the values by multiples of
  \code{10}. \var{variants} should be ordered that way, that the
  number of ticks for a given range will decrease, hence the distances
  between the ticks should increase within the \var{variants} list.
  \var{extendtick} and \var{epsilon} have the same meaning as in
  \class{linear}.
\end{classdesc}

\begin{memberdesc}{defaultvariants}
  \code{[[tick.rational((1, 1)),
  tick.rational((1, 2))], [tick.rational((2, 1)), tick.rational((1,
  1))], [tick.rational((5, 2)), tick.rational((5, 4))],
  [tick.rational((5, 1)), tick.rational((5, 2))]]}
\end{memberdesc}

\begin{classdesc}{autolin}{...}
This class is an abbreviation of \class{autolinear} described above.
\end{classdesc}

\begin{classdesc}{preexp}{pres, exp}
  This is a storage class defining positions of ticks on a
  logarithmic scale. It contains a list \var{pres} of positions $p_i$
  and \var{exp}, a multiplicator $m$. Valid tick positions are defined
  by $p_im^n$ for any integer $n$.
\end{classdesc}

\begin{classdesc}{logarithmic}{tickpreexps=None, labelpreexps=None,
                               extendtick=0, extendlabel=None,
                               epsilon=1e-10}
  Instances of this class creates tick lists suitable to logarithmic
  axes. The positions of the ticks, subticks, subsubticks \emph{etc.}
  are defined by the first, second, third \emph{etc.} item of the list
  \var{tickpreexps}, which are all \class{preexp} instances.

  \var{labelpreexps} works equally for placing labels. When \var{labelpreexps}
  is kept \code{None}, labels will be placed at each tick position,
  but sublabels \emph{etc.} will not be used. This copy behaviour is
  also available \emph{vice versa} and can be disabled by an empty
  list.

  \var{extendtick}, \var{extendlabel} and \var{epsilon} have the same
  meaning as in \class{linear}.
\end{classdesc}

Some \class{preexp} instances for the use in \class{logarithmic} are
available as instance variables (should be used read-only):

\begin{memberdesc}{pre1exp5}
  \code{preexp([tick.rational((1, 1))], 100000)}
\end{memberdesc}

\begin{memberdesc}{pre1exp4}
  \code{preexp([tick.rational((1, 1))], 10000)}
\end{memberdesc}

\begin{memberdesc}{pre1exp3}
  \code{preexp([tick.rational((1, 1))], 1000)}
\end{memberdesc}

\begin{memberdesc}{pre1exp2}
  \code{preexp([tick.rational((1, 1))], 100)}
\end{memberdesc}

\begin{memberdesc}{pre1exp}
  \code{preexp([tick.rational((1, 1))], 10)}
\end{memberdesc}

\begin{memberdesc}{pre125exp}
  \code{preexp([tick.rational((1, 1)), tick.rational((2, 1)), tick.rational((5, 1))], 10)}
\end{memberdesc}

\begin{memberdesc}{pre1to9exp}
  \code{preexp([tick.rational((1, 1)) for x in range(1, 10)], 10)}
\end{memberdesc}

\begin{classdesc}{log}{...}
This class is an abbreviation of \class{logarithmic} described above.
\end{classdesc}

\begin{classdesc}{autologarithmic}{variants=defaultvariants,
                                   extendtick=0, extendlabel=None,
                                   epsilon=1e-10}
  Instances of this class creates tick lists suitable to logarithmic
  axes, where the distance between the ticks is adjusted to the range
  of the axis automatically. Variants are a list of tuples with
  possible choices for \var{tickpreexps} and \var{labelpreexps} of
  \class{logarithmic}. \var{variants} should be ordered that way, that
  the number of ticks for a given range will decrease within the
  \var{variants} list.

  \var{extendtick}, \var{extendlabel} and \var{epsilon} have the same
  meaning as in \class{linear}.
\end{classdesc}

\begin{memberdesc}{defaultvariants}
  \code{[([log.pre1exp, log.pre1to9exp], [log.pre1exp,
  log.pre125exp]), ([log.pre1exp, log.pre1to9exp], None),
  ([log.pre1exp2, log.pre1exp], None), ([log.pre1exp3,
  log.pre1exp], None), ([log.pre1exp4, log.pre1exp], None),
  ([log.pre1exp5, log.pre1exp], None)]}
\end{memberdesc}

\begin{classdesc}{autolog}{...}
This class is an abbreviation of \class{autologarithmic} described above.
\end{classdesc} % }}}

\section{Module \module{graph.axis.texter}: Texter} % {{{

\declaremodule{}{graph.axis.texter}
\modulesynopsis{Axes texters}

The following classes are part of the module \module{graph.axis.texter}.
Instances of the classes can be passed to the texter keyword argument
of regular axes. Texters are used to define the label text for ticks,
which request to have a label, but for which no label text has been specified
so far. A typical case are ticks created by partitioners described
above.

\begin{classdesc}{decimal}{prefix="", infix="", suffix="", equalprecision=0,
                           decimalsep=".", thousandsep="", thousandthpartsep="",
                           plus="", minus="-", period=r"\textbackslash overline\{\%s\}",
                           labelattrs=[text.mathmode]}
  Instances of this class create decimal formatted labels.

  The strings \var{prefix}, \var{infix}, and \var{suffix} are added to
  the label at the beginning, immediately after the plus or minus, and at
  the end, respectively. \var{decimalsep}, \var{thousandsep}, and
  \var{thousandthpartsep} are strings used to separate integer from
  fractional part and three-digit groups in the integer and fractional
  part. The strings \var{plus} and \var{minus} are inserted in front
  of the unsigned value for non-negative and negative numbers,
  respectively.

  The format string \var{period} should generate a period. It must
  contain one string insert operators \code{\%s} for the period.

  \var{labelattrs} is a list of attributes to be added to the label
  attributes given in the painter. It should be used to setup \TeX{}
  features like \code{text.mathmode}. Text format options like
  \code{text.size} should instead be set at the painter.
\end{classdesc}

\begin{classdesc}{exponential}{plus="", minus="-",
                               mantissaexp=r"\{\{\%s\}\textbackslash cdot10\textasciicircum\{\%s\}\}",
                               skipexp0=r"\{\%s\}",
                               skipexp1=None,
                               nomantissaexp=r"\{10\textasciicircum\{\%s\}\}",
                               minusnomantissaexp=r"\{-10\textasciicircum\{\%s\}\}",
                               mantissamin=tick.rational((1, 1)), mantissamax=tick.rational((10L, 1)),
                               skipmantissa1=0, skipallmantissa1=1,
                               mantissatexter=decimal()}
  Instances of this class create decimal formatted labels with an
  exponential.

  The strings \var{plus} and \var{minus} are inserted in front of the
  unsigned value of the exponent.

  The format string \var{mantissaexp} should generate the exponent. It
  must contain two string insert operators \code{\%s}, the first for
  the mantissa and the second for the exponent. An alternative to the
  default is \code{r\textquotedbl\{\{\%s\}\{\e rm e\}\{\%s\}\}\textquotedbl}.

  The format string \var{skipexp0} is used to skip exponent \code{0} and must
  contain one string insert operator \code{\%s} for the mantissa.
  \code{None} turns off the special handling of exponent \code{0}.
  The format string \var{skipexp1} is similar to \var{skipexp0}, but
  for exponent \code{1}.

  The format string \var{nomantissaexp} is used to skip the mantissa
  \code{1} and must contain one string insert operator \code{\%s} for
  the exponent. \code{None} turns off the special handling of mantissa
  \code{1}. The format string \var{minusnomantissaexp} is similar
  to \var{nomantissaexp}, but for mantissa \code{-1}.

  The \class{tick.rational} instances \var{mantissamin}\textless
  \var{mantissamax} are minimum (including) and maximum (excluding) of
  the mantissa.

  The boolean \var{skipmantissa1} enables the skipping of any mantissa
  equals \code{1} and \code{-1}, when \var{minusnomantissaexp} is set.
  When the boolean \var{skipallmantissa1} is set, a mantissa equals
  \code{1} is skipped only, when all mantissa values are \code{1}.
  Skipping of a mantissa is stronger than the skipping of an exponent.

  \var{mantissatexter} is a texter instance for the mantissa.
\end{classdesc}

\begin{classdesc}{mixed}{smallestdecimal=tick.rational((1, 1000)),
                         biggestdecimal=tick.rational((9999, 1)),
                         equaldecision=1,
                         decimal=decimal(),
                         exponential=exponential()}
  Instances of this class create decimal formatted labels with an
  exponential, when the unsigned values are small or large compared to
  \var{1}.

  The rational instances \var{smallestdecimal} and
  \var{biggestdecimal} are the smallest and biggest decimal values,
  where the decimal texter should be used. The sign of the value is
  ignored here. For a tick at zero the decimal texter is considered
  best as well. \var{equaldecision} is a boolean to indicate whether
  the decision for the decimal or exponential texter should be done
  globally for all ticks.

  \var{decimal} and \var{exponential} are a decimal and an exponential
  texter instance, respectively.
\end{classdesc}

\begin{classdesc}{rational}{prefix="", infix="", suffix="",
                            numprefix="", numinfix="", numsuffix="",
                            denomprefix="", denominfix="", denomsuffix="",
                            plus="", minus="-", minuspos=0, over=r"{{\%s}\textbackslash over{\%s}}",
                            equaldenom=0, skip1=1, skipnum0=1, skipnum1=1, skipdenom1=1,
                            labelattrs=[text.mathmode]}
  Instances of this class create labels formated as fractions.

  The strings \var{prefix}, \var{infix}, and \var{suffix} are added to
  the label at the beginning, immediately after the plus or minus, and at
  the end, respectively. The strings \var{numprefix},
  \var{numinfix}, and \var{numsuffix} are added to the labels
  numerator accordingly whereas \var{denomprefix}, \var{denominfix},
  and \var{denomsuffix} do the same for the denominator.

  The strings \var{plus} and \var{minus} are inserted in front of the
  unsigned value. The position of the sign is defined by
  \var{minuspos} with values \code{1} (at the numerator), \code{0}
  (in front of the fraction), and \code{-1} (at the denominator).

  The format string \var{over} should generate the fraction. It
  must contain two string insert operators \code{\%s}, the first for
  the numerator and the second for the denominator. An alternative to
  the default is \code{\textquotedbl\{\{\%s\}/\{\%s\}\}\textquotedbl}.

  Usually, the numerator and denominator are canceled, while, when
  \var{equaldenom} is set, the least common multiple of all
  denominators is used.

  The boolean \var{skip1} indicates, that only the prefix, plus or minus,
  the infix and the suffix should be printed, when the value is
  \code{1} or \code{-1} and at least one of \var{prefix}, \var{infix}
  and \var{suffix} is present.

  The boolean \var{skipnum0} indicates, that only a \code{0} is
  printed when the numerator is zero.

  \var{skipnum1} is like \var{skip1} but for the numerator.

  \var{skipdenom1} skips the denominator, when it is \code{1} taking
  into account \var{denomprefix}, \var{denominfix}, \var{denomsuffix}
  \var{minuspos} and the sign of the number.

  \var{labelattrs} has the same meaning as for \var{decimal}.
\end{classdesc} % }}}

\section{Module \module{graph.axis.painter}: Painter} % {{{

\declaremodule{}{graph.axis.painter}
\modulesynopsis{Axes painters}

The following classes are part of the module
\module{graph.axis.painter}. Instances of the painter classes can be
passed to the painter keyword argument of regular axes.

\begin{classdesc}{rotatetext}{direction, epsilon=1e-10}
  This helper class is used in direction arguments of the painters
  below to prevent axis labels and titles being written upside down.
  In those cases the text will be rotated by 180 degrees.
  \var{direction} is an angle to be used relative to the tick
  direction. \var{epsilon} is the value by which 90 degrees can be
  exceeded before an 180 degree rotation is performed.
\end{classdesc}

The following two class variables are initialized for the most common
applications:

\begin{memberdesc}{parallel}
  \code{rotatetext(90)}
\end{memberdesc}

\begin{memberdesc}{orthogonal}
  \code{rotatetext(180)}
\end{memberdesc}

\begin{classdesc}{ticklength}{initial, factor}
  This helper class provides changeable \PyX{} lengths starting from
  an initial value \var{initial} multiplied by \var{factor} again and
  again. The resulting lengths are thus a geometric series.
\end{classdesc}

There are some class variables initialized with suitable values for
tick stroking. They are named \code{ticklength.SHORT},
\code{ticklength.SHORt}, \dots, \code{ticklength.short},
\code{ticklength.normal}, \code{ticklength.long}, \dots,
\code{ticklength.LONG}. \code{ticklength.normal} is initialized with
a length of \code{0.12} and the reciprocal of the golden mean as
\code{factor} whereas the others have a modified initial value
obtained by multiplication with or division by appropriate multiples of 
$\sqrt{2}$.

\begin{classdesc}{regular}{innerticklength=ticklength.normal,
                           outerticklength=None,
                           tickattrs=[],
                           gridattrs=None,
                           basepathattrs=[],
                           labeldist="0.3 cm",
                           labelattrs=[],
                           labeldirection=None,
                           labelhequalize=0,
                           labelvequalize=1,
                           titledist="0.3 cm",
                           titleattrs=[],
                           titledirection=rotatetext.parallel,
                           titlepos=0.5,
                           texrunner=None}
  Instances of this class are painters for regular axes like linear
  and logarithmic axes.

  \var{innerticklength} and \var{outerticklength} are visual \PyX{}
  lengths of the ticks, subticks, subsubticks \emph{etc.} plotted
  along the axis inside and outside of the graph. Provide changeable
  attributes to modify the lengths of ticks compared to subticks
  \emph{etc.} \code{None} turns off the ticks inside and outside the
  graph, respectively.

  \var{tickattrs} and \var{gridattrs} are changeable stroke attributes
  for the ticks and the grid, where \code{None} turns off the feature.
  \var{basepathattrs} are stroke attributes for the axis or
  \code{None} to turn it off. \var{basepathattrs} is merged with
  \code{[style.linecap.square]}.

  \var{labeldist} is the distance of the labels from the axis base path
  as a visual \PyX{} length. \var{labelattrs} is a list of text
  attributes for the labels. It is merged with
  \code{[text.halign.center, text.vshift.mathaxis]}.
  \var{labeldirection} is an instance of \var{rotatetext} to rotate
  the labels relative to the axis tick direction or \code{None}.

  The boolean values \var{labelhequalize} and \var{labelvequalize}
  force an equal alignment of all labels for straight vertical and
  horizontal axes, respectively.

  \var{titledist} is the distance of the title from the rest of the
  axis as a visual \PyX{} length. \var{titleattrs} is a list of text
  attributes for the title. It is merged with
  \code{[text.halign.center, text.vshift.mathaxis]}.
  \var{titledirection} is an instance of \var{rotatetext} to rotate
  the title relative to the axis tick direction or \code{None}.
  \var{titlepos} is the position of the title in graph coordinates.

  \var{texrunner} is the texrunner instance to create axis text like
  the axis title or labels. When not set the texrunner of the graph
  instance is taken to create the text.
\end{classdesc}

\begin{classdesc}{linked}{innerticklength=ticklength.short,
                          outerticklength=None,
                          tickattrs=[],
                          gridattrs=None,
                          basepathattrs=[],
                          labeldist="0.3 cm",
                          labelattrs=None,
                          labeldirection=None,
                          labelhequalize=0,
                          labelvequalize=1,
                          titledist="0.3 cm",
                          titleattrs=None,
                          titledirection=rotatetext.parallel,
                          titlepos=0.5,
                          texrunner=None}
  This class is identical to \class{regular} up to the default values of
  \var{labelattrs} and \var{titleattrs}. By turning off those
  features, this painter is suitable for linked axes.
\end{classdesc}

\begin{classdesc}{bar}{innerticklength=None,
                       outerticklength=None,
                       tickattrs=[],
                       basepathattrs=[],
                       namedist="0.3 cm",
                       nameattrs=[],
                       namedirection=None,
                       namepos=0.5,
                       namehequalize=0,
                       namevequalize=1,
                       titledist="0.3 cm",
                       titleattrs=[],
                       titledirection=rotatetext.parallel,
                       titlepos=0.5,
                       texrunner=None}
  Instances of this class are suitable painters for bar axes.

  \var{innerticklength} and \var{outerticklength} are visual \PyX{}
  lengths to mark the different bar regions along the axis inside and
  outside of the graph. \code{None} turns off the ticks inside and
  outside the graph, respectively. \var{tickattrs} are stroke
  attributes for the ticks or \code{None} to turn all ticks off.

  The parameters with prefix \var{name} are identical to their
  \var{label} counterparts in \class{regular}. All other parameters have
  the same meaning as in \class{regular}.
\end{classdesc}

\begin{classdesc}{linkedbar}{innerticklength=None,
                             outerticklength=None,
                             tickattrs=[],
                             basepathattrs=[],
                             namedist="0.3 cm",
                             nameattrs=None,
                             namedirection=None,
                             namepos=0.5,
                             namehequalize=0,
                             namevequalize=1,
                             titledist="0.3 cm",
                             titleattrs=None,
                             titledirection=rotatetext.parallel,
                             titlepos=0.5,
                             texrunner=None}
  This class is identical to \class{bar} up to the default values of
  \var{nameattrs} and \var{titleattrs}. By turning off those features,
  this painter is suitable for linked bar axes.
\end{classdesc}

\begin{classdesc}{split}{breaklinesdist="0.05 cm",
                         breaklineslength="0.5 cm",
                         breaklinesangle=-60,
                         titledist="0.3 cm",
                         titleattrs=[],
                         titledirection=rotatetext.parallel,
                         titlepos=0.5,
                         texrunner=None}
  Instances of this class are suitable painters for split axes.

  \var{breaklinesdist} and \var{breaklineslength} are the distance
  between axes break markers in visual \PyX{} lengths.
  \var{breaklinesangle} is the angle of the axis break marker with
  respect to the base path of the axis. All other parameters have the
  same meaning as in \class{regular}.
\end{classdesc}

\begin{classdesc}{linkedsplit}{breaklinesdist="0.05 cm",
                               breaklineslength="0.5 cm",
                               breaklinesangle=-60,
                               titledist="0.3 cm",
                               titleattrs=None,
                               titledirection=rotatetext.parallel,
                               titlepos=0.5,
                               texrunner=None}
  This class is identical to \class{split} up to the default value of
  \var{titleattrs}. By turning off this feature, this painter is
  suitable for linked split axes.
\end{classdesc} % }}}

\section{Module \module{graph.axis.rater}: Rater} % {{{

\declaremodule{}{graph.axis.rater}
\modulesynopsis{Axes raters}

The rating of axes is implemented in \module{graph.axis.rater}. When
an axis partitioning scheme returns several partitioning
possibilities, the partitions need to be rated by a positive number.
The axis partitioning rated lowest is considered best.

The rating consists of two steps. The first takes into account only
the number of ticks, subticks, labels and so on in comparison to
optimal numbers. Additionally, the extension 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, after the
layout of preferred partitionings has been calculated, the distance of 
the labels in a partition is taken into account as well at a smaller
weight factor by default. Thereby partitions with overlapping labels
will be rejected completely. Exceptionally sparse or dense labels will
receive a bad rating as well.

\begin{classdesc}{cube}{opt, left=None, right=None, weight=1}
  Instances of this class provide a number rater. \var{opt} is the
  optimal value. When not provided, \var{left} is set to \code{0} and
  \var{right} is set to \code{3*\var{opt}}. Weight is a multiplicator
  to the result.

  The rater calculates
  \code{\var{width}*((x-\var{opt})/(other-\var{opt}))**3} to rate the
  value \code{x}, where \code{other} is \var{left}
  (\code{x}\textless\var{opt}) or \var{right}
  (\code{x}\textgreater\var{opt}).
\end{classdesc}

\begin{classdesc}{distance}{opt, weight=0.1}
  Instances of this class provide a rater for a list of numbers.
  The purpose is to rate the distance between label boxes. \var{opt}
  is the optimal value.

  The rater calculates the sum of \code{\var{weight}*(\var{opt}/x-1)}
  (\code{x}\textless\var{opt}) or \code{\var{weight}*(x/\var{opt}-1)}
  (\code{x}\textgreater\var{opt}) for all elements \code{x} of the
  list. It returns this value divided by the number of elements in the
  list.
\end{classdesc}

\begin{classdesc}{rater}{ticks, labels, range, distance}
  Instances of this class are raters for axes partitionings.

  \var{ticks} and \var{labels} are both lists of number rater
  instances, where the first items are used for the number of ticks
  and labels, the second items are used for the number of subticks
  (including the ticks) and sublabels (including the labels) and so on
  until the end of the list is reached or no corresponding ticks are
  available.

  \var{range} is a number rater instance which rates the range of the
  ticks relative to the range of the data.

  \var{distance} is an distance rater instance.
\end{classdesc}

\begin{classdesc}{linear}{ticks=[cube(4), cube(10, weight=0.5)],
                          labels=[cube(4)],
                          range=cube(1, weight=2),
                          distance=distance("1 cm")}
  This class is suitable to rate partitionings of linear axes. It is
  equal to \class{rater} but defines predefined values for the
  arguments.
\end{classdesc}

\begin{classdesc}{lin}{...}
  This class is an abbreviation of \class{linear} described above.
\end{classdesc}

\begin{classdesc}{logarithmic}{ticks=[cube(5, right=20), cube(20, right=100, weight=0.5)],
                               labels=[cube(5, right=20), cube(5, right=20, weight=0.5)],
                               range=cube(1, weight=2),
                               distance=distance("1 cm")}
  This class is suitable to rate partitionings of logarithmic axes. It
  is equal to \class{rater} but defines predefined values for the
  arguments.
\end{classdesc}

\begin{classdesc}{log}{...}
  This class is an abbreviation of \class{logarithmic} described above.
\end{classdesc} % }}}

\section{Module \module{graph.axis.positioner}: Positioners} % {{{

\declaremodule{}{graph.axis.positioners}
\modulesynopsis{Axes positioners}

The position of an axis is defined by an instance of a class providing
the following methods:

\begin{methoddesc}{vbasepath}{v1=None, v2=None}
  Returns a path instance for the base path. \var{v1} and \var{v2}
  define the axis range in graph coordinates the base path should
  cover.
\end{methoddesc}

\begin{methoddesc}{vgridpath}{v}
  Returns a path instance for the grid path at position \var{v} in
  graph coordinates. The method might return \code{None} when no grid
  path is available (for an axis along a path for example).
\end{methoddesc}

\begin{methoddesc}{vtickpoint_pt}{v}
  Returns the position of \var{v} in graph coordinates as a tuple
  \code{(x, y)} in points.
\end{methoddesc}

\begin{methoddesc}{vtickdirection}{v}
  Returns the direction of a tick at \var{v} in graph coordinates as a
  tuple \code{(dx, dy)}. The tick direction points inside of the
  graph.
\end{methoddesc}

The module contains several implementations of those positioners, but
since the positioner instances are created by graphs etc. as needed,
the details are not interesting for the average \PyX{} user.

% }}} % }}}

% vim:fdm=marker