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