manual/axis.tex

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