manual/axis.tex

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