manual/axis.tex

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