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