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