manual/axis.tex

   1 \chapter{Axes\label{axis}}
   2
   3 Axes are a fundamental component of graphs although there might be
   4 applications outside of the graph system. Internally axes are
   5 constructed out of components, which handle different tasks axes
   6 need to fulfill:
   7
   8 \begin{definitions}
   9 \term{axis}
  10   Basically a container for axis data and the components. It
  11   implements the conversion of a data value to a graph coordinate of
  12   range [0:1]. It does also handle the proper usage of the components
  13   in complicated tasks (\emph{i.e.} combine the partitioner, texter,
  14   painter and rater to find the best partitioning).
  15 \term{tick}
  16   Ticks are plotted along the axis. They might be labeled with text as
  17   well.
  18 \term{partitioner, in the code the short form ``parter'' is used}
  19   Creates one or several choices of tick lists suitable to a certain
  20   axis range.
  21 \term{texter}
  22   Creates labels for ticks when they are not set manually.
  23 \term{painter}
  24   Responsible for painting the axis.
  25 \term{rater}
  26   Calculate ratings, which can be used to select the best suitable
  27   partitioning.
  28 \end{definitions}
  29
  30 The names above map directly to modules which are provided in the
  31 directory \file{graph/axis}. Sometimes it might be convenient to
  32 import the axis directory directly rather than to access iit through
  33 the graph. This would look like:
  34 \begin{verbatim}
  35   from pyx import *
  36   graph.axis.painter() # and the like
  37
  38   from pyx.graph import axis
  39   axis.painter() # this is shorter ...
  40 \end{verbatim}
  41
  42 In most cases different implementations are available through
  43 different classes, which can be combined in various ways. There are
  44 various axis examples distributed with \PyX{}, where you can see some
  45 of the features of the axis with a few lines of code each. Hence we
  46 can here directly come to the reference of the available
  47 components.
  48
  49 \section{Axes}
  50
  51 \declaremodule{}{graph.axis.axis}
  52 \modulesynopsis{Axes}
  53
  54 The following classes are part of the module \module{graph.axis.axis}.
  55 However, there is a shortcut to access those classes via
  56 \code{graph.axis} directly.
  57
  58 The position of an axis is defined by an instance of a class providing
  59 the following methods:
  60
  61 \begin{methoddesc}[axispos]{basepath}{x1=None, x2=None}
  62   Returns a path instance for the base path. \var{x1} and \var{x2}
  63   define the axis range, the base path should cover.
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}[axispos]{vbasepath}{v1=None, v2=None}
  67   Like \method{basepath} but in graph coordinates.
  68 \end{methoddesc}
  69
  70 \begin{methoddesc}[axispos]{gridpath}{x}
  71   Returns a path instance for the grid path at position \var{x}.
  72   Might return \code{None} when no grid path is available.
  73 \end{methoddesc}
  74
  75 \begin{methoddesc}[axispos]{vgridpath}{v}
  76   Like \method{gridpath} but in graph coordinates.
  77 \end{methoddesc}
  78
  79 \begin{methoddesc}[axispos]{tickpoint}{x}
  80   Returns the position of \var{x} as a tuple \samp{(x, y)}.
  81 \end{methoddesc}
  82
  83 \begin{methoddesc}[axispos]{vtickpoint}{v}
  84   Like \method{tickpoint} but in graph coordinates.
  85 \end{methoddesc}
  86
  87 \begin{methoddesc}[axispos]{tickdirection}{x}
  88   Returns the direction of a tick at \var{x} as a tuple \samp{(dx, dy)}.
  89   The tick direction points inside of the graph.
  90 \end{methoddesc}
  91
  92 \begin{methoddesc}[axispos]{vtickdirection}{v}
  93   Like \method{tickdirection} but in graph coordinates.
  94 \end{methoddesc}
  95
  96 Instances of the following classes can be passed to the \var{**axes}
  97 keyword arguments of a graph. Those instances should only be used once.
  98
  99 \begin{classdesc}{linear}{min=None, max=None, reverse=0, divisor=None, title=None,
 100                           parter=parter.autolinear(), manualticks=[],
 101                           density=1, maxworse=2, rater=rater.linear(),
 102                           texter=texter.mixed(), painter=painter.regular()}
 103   This class provides a linear axis. \var{min} and \var{max} define the
 104   axis range. When not set, they are adjusted automatically by the
 105   data to be plotted in the graph. Note, that some data might want to
 106   access the range of an axis (\emph{e.g.} the \class{function} class
 107   when no range was provided there) or you need to specify a range
 108   when using the axis without plugging it into a graph (\emph{e.g.}
 109   when drawing an axis along a path).
 110
 111   \var{reverse} can be set to indicate a reversed axis starting with
 112   bigger values first. Alternatively you can fix the axis range by
 113   \var{min} and \var{max} accordingly. When divisor is set, it is
 114   taken to divide all data range and position informations while
 115   creating ticks. You can create ticks not taking into account a
 116   factor by that. \var{title} is the title of the axis.
 117
 118   \var{parter} is a partitioner instance, which creates suitable ticks
 119   for the axis range. Those ticks are merged with ticks manually given
 120   by \var{manualticks} before proceeding with rating, painting
 121   \emph{etc.} Manually placed ticks win against those created by the
 122   partitioner. For automatic partitioners, which are able to calculate
 123   several possible tick lists for a given axis range, the
 124   \var{density} is a (linear) factor to favour more or less ticks. It
 125   should not be stressed to much (its likely, that the result would be
 126   unappropriate or not at all valid in terms of rating label
 127   distances). But within a range of say 0.5 to 2 (even bigger for
 128   large graphs) it can help to get less or more ticks than the default
 129   would lead to. \var{maxworse} is the number of trials with more
 130   and less ticks when a better rating was already found. \var{rater}
 131   is a rater instance, which rates the ticks and the label distances
 132   for being best suitable. It also takes into account \var{density}.
 133   The rater is only needed, when the partitioner creates several tick
 134   lists.
 135
 136   \var{texter} is a texter instance. It creates labels for those
 137   ticks, which claim to have a label, but do not have a label string
 138   set already. Ticks created by partitioners typically receive their
 139   label strings by texters. The \var{painter} is finally used to
 140   construct the output. Note, that usually several output
 141   constructions are needed, since the rater is also used to rate the
 142   distances between the label for an optimum.
 143 \end{classdesc}
 144
 145 \begin{classdesc}{lin}{...}
 146   This class is an abbreviation of \class{linear} described above.
 147 \end{classdesc}
 148
 149 \begin{classdesc}{logarithmic}{min=None, max=None, reverse=0, divisor=None, title=None,
 150                                parter=parter.autologarithmic(), manualticks=[],
 151                                density=1, maxworse=2, rater=rater.logarithmic(),
 152                                texter=texter.mixed(), painter=painter.regular()}
 153   This class provides a logarithmic axis. All parameters work like
 154   \class{linear}. Only two parameters have a different default:
 155   \var{parter} and \var{rater}. Furthermore and most importantly, the
 156   mapping between data and graph coordinates is logarithmic.
 157 \end{classdesc}
 158
 159 \begin{classdesc}{log}{...}
 160 This class is an abbreviation of \class{logarithmic} described above.
 161 \end{classdesc}
 162
 163 \begin{classdesc}{linked}{linkedaxis, painter=painter.linked()}
 164   This class provides an axis, which is linked to another axis
 165   instance. This means, it shares all its properties with the axis it
 166   is linked to except for the painter. Thus a linked axis is painted
 167   differently.
 168
 169   A standard application are the \code{x2} and \code{y2} axes in an
 170   x-y-graph. Linked axes to the \code{x} and \code{y} axes are created
 171   automatically when not disabled by setting those axes to
 172   \code{None}. By that, ticks are stroked at both sides of an
 173   x-y-graph. However, linked axes can be used in other cases as
 174   well. You can link axes within a graph or between different graphs
 175   as long as the original axis is finished first (it must fix its
 176   layout first).
 177 \end{classdesc}
 178
 179 \begin{classdesc}{split}{subaxes, splitlist=[0.5],
 180                          splitdist=0.1, relsizesplitdist=1,
 181                          title=None, painter=painter.split()}
 182   This class provides an axis, splitting the input values to its
 183   subaxes depending on the range of the subaxes. Thus the subaxes
 184   need to have fixed range, up to the minimum of the first axis and
 185   the maximum of the last axis. \var{subaxes} actually takes the list
 186   of subaxes. \var{splitlist} defines the positions of the splitting
 187   in graph coordinates. Thus the length of \var{subaxes} must be the
 188   length of \var{splitlist} plus one. If an entry in \var{splitlist}
 189   is \code{None}, the axes aside define the split position taking into
 190   account the ratio of the axes ranges (measured by an internal
 191   \code{relsize} attribute of each axis).
 192
 193   \var{splitdist} is the space reserved for a splitting in graph
 194   coordinates, when the corresponding entry in \var{splitlist} is not
 195   \code{None}. \var{relsizesplitdist} is the space reserved for the
 196   splitting in terms, when the corresponding entry in \var{splitlist}
 197   is \code{None} compared to the \code{relsize} of the axes aside.
 198
 199   \var{title} is the title of the split axes and \var{painter} is a
 200   specialized painter, which takes care of marking the axes breaks,
 201   while the painting of the subaxes is performed by their painters
 202   themselves.
 203 \end{classdesc}
 204
 205 \begin{classdesc}{linkedsplit}{linkedaxis,
 206                                painter=painter.linkedsplit(),
 207                                subaxispainter=omitsubaxispainter}
 208   This class provides an axis, which is linked to an instance of
 209   \class{split}. The purpose of a linked axis is described in class
 210   \class{linked} above. \var{painter} replaces the painter from the
 211   \var{linkedaxis} instance.
 212
 213   While this class creates linked axes for the subaxes of
 214   \var{linkedsplit} as well, the question arises what painters to use
 215   there. When \var{subaxispainter} is not set, no painter is given
 216   explicitly leaving this decision to the subaxes themself. This will
 217   lead to omitting all labels and the title. However, you can use a
 218   changeable attribute of painters in \var{subaxispainter} to replace
 219   the default.
 220 \end{classdesc}
 221
 222 \begin{classdesc}{bar}{subaxis=None, multisubaxis=None,
 223                        dist=0.5, firstdist=None, lastdist=None,
 224                        title=None, painter=painter.bar()}
 225   This class provides an axis suitable for a bar style. It handles a
 226   discrete set of values and maps them to distinct ranges in graph
 227   coordinates. For that, the axis gets a list as data values. The
 228   first entry is taken to be one of the discrete values valid on this
 229   axis. All other parameters, lets call them others, are passed to a
 230   subaxis. When others has only one entry, it is passed as a value,
 231   otherwise as a list. The result of the conversion done by the
 232   subaxis is mapped into the graph coordinate range for this discrete
 233   value. When neither \var{subaxis} nor \var{multisubaxis} is set,
 234   others must be a single value in the range [0:1]. This value is used
 235   for the position at the subaxis without conversion.
 236
 237   When \var{subaxis} is set, it is used for the conversion of others.
 238   When \var{multisubaxis} is set, it must be an instance of \var{bar}
 239   as well. It is then duplicated for each of the discrete values
 240   allowed for the axis. By that, you can create nested bar axes with
 241   different discrete values for each discrete value of the axis. It
 242   is not allowed to set both, \var{subaxis} and \var{multisubaxis}.
 243
 244   \var{dist} is used as the spacing between the ranges for each
 245   distinct value. It is measured in the same units as the subaxis
 246   results, thus the default value of \code{0.5} means half the width
 247   between the distinct values as the width for each distinct value.
 248   \var{firstdist} and \var{lastdist} are used before the first and
 249   after the last value. When set to \code{None}, half of \var{dist}
 250   is used.
 251
 252   \var{title} is the title of the split axes and \var{painter} is a
 253   specialized painter for an bar axis. When \var{multisubaxis} is
 254   used, their painters are called as well, otherwise they are not
 255   taken into account.
 256 \end{classdesc}
 257
 258 \begin{funcdesc}{pathaxis}{path, axis, direction=1}
 259   This function returns a (specialized) canvas containing the axis
 260   \var{axis} painted along the path \var{path}. \var{direction}
 261   defines the direction of the ticks. Allowed values are \code{1}
 262   (left) and \code{-1} (right).
 263 \end{funcdesc}
 264
 265 \section{Ticks}
 266
 267 \declaremodule{}{graph.axis.tick}
 268 \modulesynopsis{Axes ticks}
 269
 270 The following classes are part of the module \module{graph.axis.tick}.
 271
 272 \begin{classdesc}{rational}{x, power=1, floatprecision=10}
 273   This class implements a rational number with infinite precision. For
 274   that it stores two integers, the numerator \code{num} and a
 275   denominator \code{denom}. Note that the implementation of rational
 276   number arithmetics is not at all complete and designed for its
 277   special use case of axis partitioning in \PyX{} preventing any
 278   roundoff errors.
 279
 280   \var{x} is the value of the rational created by a conversion from
 281   one of the following input values:
 282   \begin{itemize}
 283   \item A float. It is converted to a rational with finite precision
 284     determined by \var{floatprecision}.
 285   \item A string, which is parsed to a rational number with full
 286     precision. It is also allowed to provide a fraction like
 287     \samp{1/3}.
 288   \item A sequence of two integers. Those integers are taken as
 289     numerator and denominator of the rational.
 290   \item An instance defining instance variables \code{num} and
 291   \code{denom} like \class{rational} itself.
 292   \end{itemize}
 293
 294   \var{power} is an integer to calculate \code{\var{x}**\var{power}}.
 295   This is useful at certain places in partitioners.
 296 \end{classdesc}
 297
 298 \begin{classdesc}{tick}{x, ticklevel=0, labellevel=0, label=None,
 299                         labelattrs=[], power=1, floatprecision=10}
 300   This class implements ticks based on rational numbers. Instances of
 301   this class can be passed to the \code{manualticks} parameter of a
 302   regular axis.
 303
 304   The parameters \var{x}, \var{power}, and \var{floatprecision} share
 305   its meaning with \class{rational}.
 306
 307   A tick has a tick level (\emph{i.e.} markers at the axis path) and a
 308   label lavel (\emph{e.i.} place text at the axis path),
 309   \var{ticklevel} and \var{labellevel}. These are non-negative
 310   integers or \var{None}. A value of \code{0} means a regular tick or
 311   label, \code{1} stands for a subtick or sublabel, \code{2} for
 312   subsubtick or subsublabel and so on. \code{None} means omitting the
 313   tick or label. \var{label} is the text of the label. When not set,
 314   it can be created automatically by a texter. \var{labelattrs} are
 315   the attributes for the labels.
 316 \end{classdesc}
 317
 318 \section{Partitioners}
 319
 320 \declaremodule{}{graph.axis.parter}
 321 \modulesynopsis{Axes partitioners}
 322
 323 The following classes are part of the module \module{graph.axis.parter}.
 324 Instances of the classes can be passed to the parter keyword argument
 325 of regular axes.
 326
 327 \begin{classdesc}{linear}{tickdist=None, labeldist=None,
 328                           extendtick=0, extendlabel=None,
 329                           epsilon=1e-10}
 330   Instances of this class creates equally spaced tick lists. The
 331   distances between the ticks, subticks, subsubticks \emph{etc.}
 332   starting from a tick at zero are given as first, second, third
 333   \emph{etc.} item of the list \var{tickdist}. For a tick position,
 334   the lowest level wins, \emph{i.e.} for \code{[2, 1]} even numbers
 335   will have ticks whereas subticks are placed at odd integer. The
 336   items of \var{tickdist} might be strings, floats or tuples as
 337   described for the \var{pos} parameter of class \class{tick}.
 338
 339   \var{labeldist} works equally for placing labels. When
 340   \var{labeldist} is kept \code{None}, labels will be placed at each
 341   tick position, but sublabels \emph{etc.} will not be used. This copy
 342   behaviour is also available \emph{vice versa} and can be disabled by
 343   an empty list.
 344
 345   \var{extendtick} can be set to a tick level for including the next
 346   tick of that level when the data exceed the range covered by the
 347   ticks by more then \var{epsilon}. \var{epsilon} is taken relative
 348   to the axis range. \var{extendtick} is disabled when set to
 349   \code{None} or for fixed range axes. \var{extendlabel} works similar
 350   to \var{extendtick} but for labels.
 351 \end{classdesc}
 352
 353 \begin{classdesc}{lin}{...}
 354 This class is an abbreviation of \class{linear} described above.
 355 \end{classdesc}
 356
 357 \begin{classdesc}{autolinear}{variants=defaultvariants,
 358                               extendtick=0,
 359                               epsilon=1e-10}
 360   Instances of this class creates equally spaced tick lists, where the
 361   distance between the ticks is adjusted to the range of the axis
 362   automatically. Variants are a list of possible choices for
 363   \var{tickdist} of \class{linear}. Further variants are build out of
 364   these by multiplying or dividing all the values by multiples of
 365   \code{10}. \var{variants} should be ordered that way, that the
 366   number of ticks for a given range will decrease, hence the distances
 367   between the ticks should increase within the \var{variants} list.
 368   \var{extendtick} and \var{epsilon} have the same meaning as in
 369   \class{linear}.
 370 \end{classdesc}
 371
 372 \begin{memberdesc}{defaultvariants}
 373   \code{[[tick.rational((1, 1)),
 374   tick.rational((1, 2))], [tick.rational((2, 1)), tick.rational((1,
 375   1))], [tick.rational((5, 2)), tick.rational((5, 4))],
 376   [tick.rational((5, 1)), tick.rational((5, 2))]]}
 377 \end{memberdesc}
 378
 379 \begin{classdesc}{autolin}{...}
 380 This class is an abbreviation of \class{autolinear} described above.
 381 \end{classdesc}
 382
 383 \begin{classdesc}{preexp}{pres, exp}
 384   This is a storage class defining positions of ticks on a
 385   logarithmic scale. It contains a list \var{pres} of positions $p_i$
 386   and \var{exp}, a multiplicator $m$. Valid tick positions are defined
 387   by $p_im^n$ for any integer $n$.
 388 \end{classdesc}
 389
 390 \begin{classdesc}{logarithmic}{tickpos=None, labelpos=None,
 391                                extendtick=0, extendlabel=None,
 392                                epsilon=1e-10}
 393   Instances of this class creates tick lists suitable to logarithmic
 394   axes. The positions of the ticks, subticks, subsubticks \emph{etc.}
 395   are defined by the first, second, third \emph{etc.} item of the list
 396   \var{tickpos}, which are all \class{preexp} instances.
 397
 398   \var{labelpos} works equally for placing labels. When \var{labelpos}
 399   is kept \code{None}, labels will be placed at each tick position,
 400   but sublabels \emph{etc.} will not be used. This copy behaviour is
 401   also available \emph{vice versa} and can be disabled by an empty
 402   list.
 403
 404   \var{extendtick}, \var{extendlabel} and \var{epsilon} have the same
 405   meaning as in \class{linear}.
 406 \end{classdesc}
 407
 408 Some \class{preexp} instances for the use in \class{logarithmic} are
 409 available as instance variables (should be used read-only):
 410
 411 \begin{memberdesc}{pre1exp5}
 412   \code{preexp([tick.rational((1, 1))], 100000)}
 413 \end{memberdesc}
 414
 415 \begin{memberdesc}{pre1exp4}
 416   \code{preexp([tick.rational((1, 1))], 10000)}
 417 \end{memberdesc}
 418
 419 \begin{memberdesc}{pre1exp3}
 420   \code{preexp([tick.rational((1, 1))], 1000)}
 421 \end{memberdesc}
 422
 423 \begin{memberdesc}{pre1exp2}
 424   \code{preexp([tick.rational((1, 1))], 100)}
 425 \end{memberdesc}
 426
 427 \begin{memberdesc}{pre1exp}
 428   \code{preexp([tick.rational((1, 1))], 10)}
 429 \end{memberdesc}
 430
 431 \begin{memberdesc}{pre125exp}
 432   \code{preexp([tick.rational((1, 1)), tick.rational((2, 1)), tick.rational((5, 1))], 10)}
 433 \end{memberdesc}
 434
 435 \begin{memberdesc}{pre1to9exp}
 436   \code{preexp([tick.rational((1, 1)) for x in range(1, 10)], 10)}
 437 \end{memberdesc}
 438
 439 \begin{classdesc}{log}{...}
 440 This class is an abbreviation of \class{logarithmic} described above.
 441 \end{classdesc}
 442
 443 \begin{classdesc}{autologarithmic}{variants=defaultvariants,
 444                                    extendtick=0, extendlabel=None,
 445                                    epsilon=1e-10}
 446   Instances of this class creates tick lists suitable to logarithmic
 447   axes, where the distance between the ticks is adjusted to the range
 448   of the axis automatically. Variants are a list of tuples with
 449   possible choices for \var{tickpos} and \var{labelpos} of
 450   \class{logarithmic}. \var{variants} should be ordered that way, that
 451   the number of ticks for a given range will decrease within the
 452   \var{variants} list.
 453
 454   \var{extendtick}, \var{extendlabel} and \var{epsilon} have the same
 455   meaning as in \class{linear}.
 456 \end{classdesc}
 457
 458 \begin{memberdesc}{defaultvariants}
 459   \code{[([log.pre1exp, log.pre1to9exp], [log.pre1exp,
 460   log.pre125exp]), ([log.pre1exp, log.pre1to9exp], None),
 461   ([log.pre1exp2, log.pre1exp], None), ([log.pre1exp3,
 462   log.pre1exp], None), ([log.pre1exp4, log.pre1exp], None),
 463   ([log.pre1exp5, log.pre1exp], None)]}
 464 \end{memberdesc}
 465
 466 \begin{classdesc}{autolog}{...}
 467 This class is an abbreviation of \class{autologarithmic} described above.
 468 \end{classdesc}
 469
 470 \section{Texter}
 471
 472 \declaremodule{}{graph.axis.texter}
 473 \modulesynopsis{Axes texters}
 474
 475 The following classes are part of the module \module{graph.axis.texter}.
 476 Instances of the classes can be passed to the texter keyword argument
 477 of regular axes. Texters are used to define the label text for ticks,
 478 which request to have a label, but for which no label text has been specified
 479 so far. A typical case are ticks created by partitioners described
 480 above.
 481
 482 \begin{classdesc}{decimal}{prefix="", infix="", suffix="", equalprecision=0,
 483                            decimalsep=".", thousandsep="", thousandthpartsep="",
 484                            plus="", minus="-", period=r"\textbackslash overline\{\%s\}",
 485                            labelattrs=[text.mathmode]}
 486   Instances of this class create decimal formatted labels.
 487
 488   The strings \var{prefix}, \var{infix}, and \var{suffix} are added to
 489   the label at the beginning, immediately after the plus or minus, and at
 490   the end, respectively. \var{decimalsep}, \var{thousandsep}, and
 491   \var{thousandthpartsep} are strings used to separate integer from
 492   fractional part and three-digit groups in the integer and fractional
 493   part. The strings \var{plus} and \var{minus} are inserted in front
 494   of the unsigned value for non-negative and negative numbers,
 495   respectively.
 496
 497   The format string \var{period} should generate a period. It must
 498   contain one string insert operators \samp{\%s} for the period.
 499
 500   \var{labelattrs} is a list of attributes to be added to the label
 501   attributes given in the painter. It should be used to setup \TeX{}
 502   features like \code{text.mathmode}. Text format options like
 503   \code{text.size} should instead be set at the painter.
 504 \end{classdesc}
 505
 506 \begin{classdesc}{exponential}{plus="", minus="-",
 507                                mantissaexp=r"\{\{\%s\}\textbackslash cdot10\textasciicircum\{\%s\}\}",
 508                                skipexp0=r"\{\%s\}",
 509                                skipexp1=None,
 510                                nomantissaexp=r"\{10\textasciicircum\{\%s\}\}",
 511                                minusnomantissaexp=r"\{-10\textasciicircum\{\%s\}\}",
 512                                mantissamin=tick.rational((1, 1)), mantissamax=tick.rational((10L, 1)),
 513                                skipmantissa1=0, skipallmantissa1=1,
 514                                mantissatexter=decimal()}
 515   Instances of this class create decimal formatted labels with an
 516   exponential.
 517
 518   The strings \var{plus} and \var{minus} are inserted in front of the
 519   unsigned value of the exponent.
 520
 521   The format string \var{mantissaexp} should generate the exponent. It
 522   must contain two string insert operators \samp{\%s}, the first for
 523   the mantissa and the second for the exponent. An alternative to the
 524   default is \samp{r\textquotedbl\{\{\%s\}\{\e rm e\}\{\%s\}\}\textquotedbl}.
 525
 526   The format string \var{skipexp0} is used to skip exponent \code{0} and must
 527   contain one string insert operator \samp{\%s} for the mantissa.
 528   \code{None} turns off the special handling of exponent \code{0}.
 529   The format string \var{skipexp1} is similar to \var{skipexp0}, but
 530   for exponent \code{1}.
 531
 532   The format string \var{nomantissaexp} is used to skip the mantissa
 533   \code{1} and must contain one string insert operator \samp{\%s} for
 534   the exponent. \code{None} turns off the special handling of mantissa
 535   \code{1}. The format string \var{minusnomantissaexp} is similar
 536   to \var{nomantissaexp}, but for mantissa \code{-1}.
 537
 538   The \class{tick.rational} instances \var{mantissamin}\textless
 539   \var{mantissamax} are minimum (including) and maximum (excluding) of
 540   the mantissa.
 541
 542   The boolean \var{skipmantissa1} enables the skipping of any mantissa
 543   equals \code{1} and \code{-1}, when \var{minusnomantissaexp} is set.
 544   When the boolean \var{skipallmantissa1} is set, a mantissa equals
 545   \code{1} is skipped only, when all mantissa values are \code{1}.
 546   Skipping of a mantissa is stronger than the skipping of an exponent.
 547
 548   \var{mantissatexter} is a texter instance for the mantissa.
 549 \end{classdesc}
 550
 551 \begin{classdesc}{mixed}{smallestdecimal=tick.rational((1, 1000)),
 552                          biggestdecimal=tick.rational((9999, 1)),
 553                          equaldecision=1,
 554                          decimal=decimal(),
 555                          exponential=exponential()}
 556   Instances of this class create decimal formatted labels with an
 557   exponential, when the unsigned values are small or large compared to
 558   \var{1}.
 559
 560   The rational instances \var{smallestdecimal} and
 561   \var{biggestdecimal} are the smallest and biggest decimal values,
 562   where the decimal texter should be used. The sign of the value is
 563   ignored here. For a tick at zero the decimal texter is considered
 564   best as well. \var{equaldecision} is a boolean to indicate whether
 565   the decision for the decimal or exponential texter should be done
 566   globally for all ticks.
 567
 568   \var{decimal} and \var{exponential} are a decimal and an exponential
 569   texter instance, respectively.
 570 \end{classdesc}
 571
 572 \begin{classdesc}{rational}{prefix="", infix="", suffix="",
 573                             numprefix="", numinfix="", numsuffix="",
 574                             denomprefix="", denominfix="", denomsuffix="",
 575                             plus="", minus="-", minuspos=0, over=r"{{\%s}\textbackslash over{\%s}}",
 576                             equaldenom=0, skip1=1, skipnum0=1, skipnum1=1, skipdenom1=1,
 577                             labelattrs=[text.mathmode]}
 578   Instances of this class create labels formated as fractions.
 579
 580   The strings \var{prefix}, \var{infix}, and \var{suffix} are added to
 581   the label at the beginning, immediately after the plus or minus, and at
 582   the end, respectively. The strings \var{numprefix},
 583   \var{numinfix}, and \var{numsuffix} are added to the labels
 584   numerator accordingly whereas \var{denomprefix}, \var{denominfix},
 585   and \var{denomsuffix} do the same for the denominator.
 586
 587   The strings \var{plus} and \var{minus} are inserted in front of the
 588   unsigned value. The position of the sign is defined by
 589   \var{minuspos} with values \code{1} (at the numerator), \code{0}
 590   (in front of the fraction), and \code{-1} (at the denominator).
 591
 592   The format string \var{over} should generate the fraction. It
 593   must contain two string insert operators \samp{\%s}, the first for
 594   the numerator and the second for the denominator. An alternative to
 595   the default is \samp{\textquotedbl\{\{\%s\}/\{\%s\}\}\textquotedbl}.
 596
 597   Usually, the numerator and denominator are canceled, while, when
 598   \var{equaldenom} is set, the least common multiple of all
 599   denominators is used.
 600
 601   The boolean \var{skip1} indicates, that only the prefix, plus or minus,
 602   the infix and the suffix should be printed, when the value is
 603   \code{1} or \code{-1} and at least one of \var{prefix}, \var{infix}
 604   and \var{suffix} is present.
 605
 606   The boolean \var{skipnum0} indicates, that only a \code{0} is
 607   printed when the numerator is zero.
 608
 609   \var{skipnum1} is like \var{skip1} but for the numerator.
 610
 611   \var{skipdenom1} skips the denominator, when it is \code{1} taking
 612   into account \var{denomprefix}, \var{denominfix}, \var{denomsuffix}
 613   \var{minuspos} and the sign of the number.
 614
 615   \var{labelattrs} has the same meaning as for \var{decimal}.
 616 \end{classdesc}
 617
 618 \section{Painter}
 619
 620 \declaremodule{}{graph.axis.painter}
 621 \modulesynopsis{Axes painters}
 622
 623 The following classes are part of the module
 624 \module{graph.axis.painter}. Instances of the painter classes can be
 625 passed to the painter keyword argument of regular axes.
 626
 627 \begin{classdesc}{rotatetext}{direction, epsilon=1e-10}
 628   This helper class is used in direction arguments of the painters
 629   below to prevent axis labels and titles being written upside down.
 630   In those cases the text will be rotated by 180 degrees.
 631   \var{direction} is an angle to be used relative to the tick
 632   direction. \var{epsilon} is the value by which 90 degrees can be
 633   exceeded before an 180 degree rotation is performed.
 634 \end{classdesc}
 635
 636 The following two class variables are initialized for the most common
 637 applications:
 638
 639 \begin{memberdesc}{parallel}
 640   \code{rotatetext(90)}
 641 \end{memberdesc}
 642
 643 \begin{memberdesc}{orthogonal}
 644   \code{rotatetext(180)}
 645 \end{memberdesc}
 646
 647 \begin{classdesc}{ticklength}{initial, factor}
 648   This helper class provides changeable \PyX{} lengths starting from
 649   an initial value \var{initial} multiplied by \var{factor} again and
 650   again. The resulting lengths are thus a geometric series.
 651 \end{classdesc}
 652
 653 There are some class variables initialized with suitable values for
 654 tick stroking. They are named \code{ticklength.SHORT},
 655 \code{ticklength.SHORt}, \dots, \code{ticklength.short},
 656 \code{ticklength.normal}, \code{ticklength.long}, \dots,
 657 \code{ticklength.LONG}. \code{ticklength.normal} is initialized with
 658 a length of \code{0.12} and the reciprocal of the golden mean as
 659 \code{factor} whereas the others have a modified initial value
 660 obtained by multiplication with or division by appropriate multiples of
 661 $\sqrt{2}$.
 662
 663 \begin{classdesc}{regular}{innerticklength=ticklength.normal,
 664                            outerticklength=None,
 665                            tickattrs=[],
 666                            gridattrs=None,
 667                            basepathattrs=[],
 668                            labeldist="0.3 cm",
 669                            labelattrs=[],
 670                            labeldirection=None,
 671                            labelhequalize=0,
 672                            labelvequalize=1,
 673                            titledist="0.3 cm",
 674                            titleattrs=[],
 675                            titledirection=rotatetext.parallel,
 676                            titlepos=0.5,
 677                            texrunner=text.defaulttexrunner}
 678   Instances of this class are painters for regular axes like linear
 679   and logarithmic axes.
 680
 681   \var{innerticklength} and \var{outerticklength} are visual \PyX{}
 682   lengths of the ticks, subticks, subsubticks \emph{etc.} plotted
 683   along the axis inside and outside of the graph. Provide changeable
 684   attributes to modify the lengths of ticks compared to subticks
 685   \emph{etc.} \code{None} turns off the ticks inside and outside the
 686   graph, respectively.
 687
 688   \var{tickattrs} and \var{gridattrs} are changeable stroke attributes
 689   for the ticks and the grid, where \code{None} turns off the feature.
 690   \var{basepathattrs} are stroke attributes for the axis or
 691   \code{None} to turn it off. \var{basepathattrs} is merged with
 692   \samp{[style.linecap.square]}.
 693
 694   \var{labeldist} is the distance of the labels from the axis base path
 695   as a visual \PyX{} length. \var{labelattrs} is a list of text
 696   attributes for the labels. It is merged with
 697   \samp{[text.halign.center, text.vshift.mathaxis]}.
 698   \var{labeldirection} is an instance of \var{rotatetext} to rotate
 699   the labels relative to the axis tick direction or \code{None}.
 700
 701   The boolean values \var{labelhequalize} and \var{labelvequalize}
 702   force an equal alignment of all labels for straight vertical and
 703   horizontal axes, respectively.
 704
 705   \var{titledist} is the distance of the title from the rest of the
 706   axis as a visual \PyX{} length. \var{titleattrs} is a list of text
 707   attributes for the title. It is merged with
 708   \samp{[text.halign.center, text.vshift.mathaxis]}.
 709   \var{titledirection} is an instance of \var{rotatetext} to rotate
 710   the title relative to the axis tick direction or \code{None}.
 711   \var{titlepos} is the position of the title in graph coordinates.
 712
 713   \var{texrunner} is the texrunner instance to create axis text like
 714   the axis title or labels.
 715 \end{classdesc}
 716
 717 \begin{classdesc}{linked}{innerticklength=ticklength.short,
 718                           outerticklength=None,
 719                           tickattrs=[],
 720                           gridattrs=None,
 721                           basepathattrs=[],
 722                           labeldist="0.3 cm",
 723                           labelattrs=None,
 724                           labeldirection=None,
 725                           labelhequalize=0,
 726                           labelvequalize=1,
 727                           titledist="0.3 cm",
 728                           titleattrs=None,
 729                           titledirection=rotatetext.parallel,
 730                           titlepos=0.5,
 731                           texrunner=text.defaulttexrunner}
 732   This class is identical to \class{regular} up to the default values of
 733   \var{labelattrs} and \var{titleattrs}. By turning off those
 734   features, this painter is suitable for linked axes.
 735 \end{classdesc}
 736
 737 \begin{classdesc}{split}{breaklinesdist="0.05 cm",
 738                          breaklineslength="0.5 cm",
 739                          breaklinesangle=-60,
 740                          titledist="0.3 cm",
 741                          titleattrs=None,
 742                          titledirection=rotatetext.parallel,
 743                          titlepos=0.5,
 744                          texrunner=text.defaulttexrunner}
 745   Instances of this class are suitable painters for split axes.
 746
 747   \var{breaklinesdist} and \var{breaklineslength} are the distance
 748   between axes break markers in visual \PyX{} lengths.
 749   \var{breaklinesangle} is the angle of the axis break marker with
 750   respect to the base path of the axis. All other parameters have the
 751   same meaning as in \class{regular}.
 752 \end{classdesc}
 753
 754 \begin{classdesc}{linkedsplit}{breaklinesdist="0.05 cm",
 755                                breaklineslength="0.5 cm",
 756                                breaklinesangle=-60,
 757                                titledist="0.3 cm",
 758                                titleattrs=None,
 759                                titledirection=rotatetext.parallel,
 760                                titlepos=0.5,
 761                                texrunner=text.defaulttexrunner}
 762   This class is identical to \class{split} up to the default value of
 763   \var{titleattrs}. By turning off this feature, this painter is
 764   suitable for linked split axes.
 765 \end{classdesc}
 766
 767 \begin{classdesc}{bar}{innerticklength=None,
 768                        outerticklength=None,
 769                        tickattrs=[],
 770                        basepathattrs=[],
 771                        namedist="0.3 cm",
 772                        nameattrs=[],
 773                        namedirection=None,
 774                        namepos=0.5,
 775                        namehequalize=0,
 776                        namevequalize=1,
 777                        titledist="0.3 cm",
 778                        titleattrs=[],
 779                        titledirection=rotatetext.parallel,
 780                        titlepos=0.5,
 781                        texrunner=text.defaulttexrunner}
 782   Instances of this class are suitable painters for bar axes.
 783
 784   \var{innerticklength} and \var{outerticklength} are visual \PyX{}
 785   lengths to mark the different bar regions along the axis inside and
 786   outside of the graph. \code{None} turns off the ticks inside and
 787   outside the graph, respectively. \var{tickattrs} are stroke
 788   attributes for the ticks or \code{None} to turn all ticks off.
 789
 790   The parameters with prefix \var{name} are identical to their
 791   \var{label} counterparts in \class{regular}. All other parameters have
 792   the same meaning as in \class{regular}.
 793 \end{classdesc}
 794
 795 \begin{classdesc}{linkedbar}{innerticklength=None,
 796                              outerticklength=None,
 797                              tickattrs=[],
 798                              basepathattrs=[],
 799                              namedist="0.3 cm",
 800                              nameattrs=None,
 801                              namedirection=None,
 802                              namepos=0.5,
 803                              namehequalize=0,
 804                              namevequalize=1,
 805                              titledist="0.3 cm",
 806                              titleattrs=None,
 807                              titledirection=rotatetext.parallel,
 808                              titlepos=0.5,
 809                              texrunner=text.defaulttexrunner}
 810   This class is identical to \class{bar} up to the default values of
 811   \var{nameattrs} and \var{titleattrs}. By turning off those features,
 812   this painter is suitable for linked bar axes.
 813 \end{classdesc}
 814
 815 \section{Rater}
 816
 817 \declaremodule{}{graph.axis.rater}
 818 \modulesynopsis{Axes raters}
 819
 820 The rating of axes is implemented in \module{graph.axis.rater}. When
 821 an axis partitioning scheme returns several partitioning
 822 possibilities, the partitions need to be rated by a positive number.
 823 The axis partitioning rated lowest is considered best.
 824
 825 The rating consists of two steps. The first takes into account only
 826 the number of ticks, subticks, labels and so on in comparison to
 827 optimal numbers. Additionally, the extension of the axis range by
 828 ticks and labels is taken into account. This rating leads to a
 829 preselection of possible partitions. In the second step, after the
 830 layout of preferred partitionings has been calculated, the distance of
 831 the labels in a partition is taken into account as well at a smaller
 832 weight factor by default. Thereby partitions with overlapping labels
 833 will be rejected completely. Exceptionally sparse or dense labels will
 834 receive a bad rating as well.
 835
 836 \begin{classdesc}{cube}{opt, left=None, right=None, weight=1}
 837   Instances of this class provide a number rater. \var{opt} is the
 838   optimal value. When not provided, \var{left} is set to \code{0} and
 839   \var{right} is set to \code{3*\var{opt}}. Weight is a multiplicator
 840   to the result.
 841
 842   The rater calculates
 843   \code{\var{width}*((x-\var{opt})/(other-\var{opt}))**3} to rate the
 844   value \code{x}, where \code{other} is \var{left}
 845   (\code{x}\textless\var{opt}) or \var{right}
 846   (\code{x}\textgreater\var{opt}).
 847 \end{classdesc}
 848
 849 \begin{classdesc}{distance}{opt, weight=0.1}
 850   Instances of this class provide a rater for a list of numbers.
 851   The purpose is to rate the distance between label boxes. \var{opt}
 852   is the optimal value.
 853
 854   The rater calculates the sum of \code{\var{weight}*(\var{opt}/x-1)}
 855   (\code{x}\textless\var{opt}) or \code{\var{weight}*(x/\var{opt}-1)}
 856   (\code{x}\textgreater\var{opt}) for all elements \code{x} of the
 857   list. It returns this value divided by the number of elements in the
 858   list.
 859 \end{classdesc}
 860
 861 \begin{classdesc}{rater}{ticks, labels, range, distance}
 862   Instances of this class are raters for axes partitionings.
 863
 864   \var{ticks} and \var{labels} are both lists of number rater
 865   instances, where the first items are used for the number of ticks
 866   and labels, the second items are used for the number of subticks
 867   (including the ticks) and sublabels (including the labels) and so on
 868   until the end of the list is reached or no corresponding ticks are
 869   available.
 870
 871   \var{range} is a number rater instance which rates the range of the
 872   ticks relative to the range of the data.
 873
 874   \var{distance} is an distance rater instance.
 875 \end{classdesc}
 876
 877 \begin{classdesc}{linear}{ticks=[cube(4), cube(10, weight=0.5)],
 878                           labels=[cube(4)],
 879                           range=cube(1, weight=2),
 880                           distance=distance("1 cm")}
 881   This class is suitable to rate partitionings of linear axes. It is
 882   equal to \class{rater} but defines predefined values for the
 883   arguments.
 884 \end{classdesc}
 885
 886 \begin{classdesc}{lin}{...}
 887   This class is an abbreviation of \class{linear} described above.
 888 \end{classdesc}
 889
 890 \begin{classdesc}{logarithmic}{ticks=[cube(5, right=20), cube(20, right=100, weight=0.5)],
 891                                labels=[cube(5, right=20), cube(5, right=20, weight=0.5)],
 892                                range=cube(1, weight=2),
 893                                distance=distance("1 cm")}
 894   This class is suitable to rate partitionings of logarithmic axes. It
 895   is equal to \class{rater} but defines predefined values for the
 896   arguments.
 897 \end{classdesc}
 898
 899 \begin{classdesc}{log}{...}
 900   This class is an abbreviation of \class{logarithmic} described above.
 901 \end{classdesc}
 902