Fix epsfile(kpsearch=1)
[PyX/mjg.git] / manual / axis.rst
blobb2f03ddd36b4fd854c68d922e08d918fe10d2ac0
2 .. module:: graph.axis
4 ****
5 Axes
6 ****
9 Component architecture
10 ======================
12 Axes are a fundamental component of graphs although there might be applications
13 outside of the graph system. Internally axes are constructed out of components,
14 which handle different tasks axes need to fulfill:
16 axis
17    Implements the conversion of a data value to a graph coordinate of range [0:1].
18    It does also handle the proper usage of the components in complicated tasks
19    (*i.e.* combine the partitioner, texter, painter and rater to find the best
20    partitioning).
22    An anchoredaxis is a container to combine an axis with an positioner and provide
23    a storage area for all kind of axis data. That way axis instances are reusable
24    (they do not store any data locally). The anchoredaxis and the positioner are
25    created by a graph corresponding to its geometry.
27 tick
28    Ticks are plotted along the axis. They might be labeled with text as well.
30 partitioner, we use "parter" as a short form
31    Creates one or several choices of tick lists suitable to a certain axis range.
33 texter
34    Creates labels for ticks when they are not set manually.
36 painter
37    Responsible for painting the axis.
39 rater
40    Calculate ratings, which can be used to select the best suitable partitioning.
42 positioner
43    Defines the position of an axis.
45 The names above map directly to modules which are provided in the directory
46 :file:`graph/axis` except for the anchoredaxis, which is part of the axis module
47 as well. Sometimes it might be convenient to import the axis directory directly
48 rather than to access iit through the graph. This would look like::
50    from pyx import *
51    graph.axis.painter() # and the like
53    from pyx.graph import axis
54    axis.painter() # this is shorter ...
56 In most cases different implementations are available through different classes,
57 which can be combined in various ways. There are various axis examples
58 distributed with PyX, where you can see some of the features of the axis with a
59 few lines of code each. Hence we can here directly come to the reference of the
60 available components.
63 .. module:: graph.axis.axis
65 Module :mod:`graph.axis.axis`: Axes
66 ===================================
68 The following classes are part of the module :mod:`graph.axis.axis`. However,
69 there is a shortcut to access those classes via ``graph.axis`` directly.
71 Instances of the following classes can be passed to the *\*\*axes* keyword
72 arguments of a graph. Those instances should only be used once.
75 .. class:: linear(min=None, max=None, reverse=0, divisor=None, title=None, parter=parter.autolinear(), manualticks=[], density=1, maxworse=2, rater=rater.linear(), texter=texter.mixed(), painter=painter.regular(), linkpainter=painter.linked(), fallbackrange=None)
77    This class provides a linear axis. *min* and *max* define the axis range. When
78    not set, they are adjusted automatically by the data to be plotted in the graph.
79    Note, that some data might want to access the range of an axis (*e.g.* the
80    :class:`function` class when no range was provided there) or you need to specify
81    a range when using the axis without plugging it into a graph (*e.g.* when
82    drawing an axis along a path). In cases where the data provides a range of zero
83    (e.g. a when plotting a constant function), then a *fallbackrange* can be set to
84    guarantee a minimal range of the axis.
86    *reverse* can be set to indicate a reversed axis starting with bigger values
87    first. Alternatively you can fix the axis range by *min* and *max* accordingly.
88    When divisor is set, it is taken to divide all data range and position
89    informations while creating ticks. You can create ticks not taking into account
90    a factor by that. *title* is the title of the axis.
92    *parter* is a partitioner instance, which creates suitable ticks for the axis
93    range. Those ticks are merged with ticks manually given  by *manualticks* before
94    proceeding with rating, painting *etc.* Manually placed ticks win against those
95    created by the partitioner. For automatic partitioners, which are able to
96    calculate several possible tick lists for a given axis range, the *density* is a
97    (linear) factor to favour more or less ticks. It should not be stressed to much
98    (its likely, that the result would be unappropriate or not at all valid in terms
99    of rating label distances). But within a range of say 0.5 to 2 (even bigger for
100    large graphs) it can help to get less or more ticks than the default would lead
101    to. *maxworse* is the number of trials with more and less ticks when a better
102    rating was already found. *rater* is a rater instance, which rates the ticks and
103    the label distances for being best suitable. It also takes into account
104    *density*. The rater is only needed, when the partitioner creates several tick
105    lists.
107    *texter* is a texter instance. It creates labels for those ticks, which claim to
108    have a label, but do not have a label string set already. Ticks created by
109    partitioners typically receive their label strings by texters. The *painter* is
110    finally used to construct the output. Note, that usually several output
111    constructions are needed, since the rater is also used to rate the distances
112    between the labels for an optimum. The *linkedpainter* is used as the axis
113    painter, when automatic link axes are created by the :meth:`createlinked`
114    method.
117 .. class:: lin(...)
119    This class is an abbreviation of :class:`linear` described above.
122 .. class:: logarithmic(min=None, max=None, reverse=0, divisor=None, title=None, parter=parter.autologarithmic(), manualticks=[], density=1, maxworse=2, rater=rater.logarithmic(), texter=texter.mixed(), painter=painter.regular(), linkpainter=painter.linked(), fallbackrange=None)
124    This class provides a logarithmic axis. All parameters work like
125    :class:`linear`. Only two parameters have a different default: *parter* and
126    *rater*. Furthermore and most importantly, the mapping between data and graph
127    coordinates is logarithmic.
130 .. class:: log(...)
132    This class is an abbreviation of :class:`logarithmic` described above.
135 .. class:: bar(subaxes=None, defaultsubaxis=linear(painter=None, linkpainter=None, parter=None, texter=None), dist=0.5, firstdist=None, lastdist=None, title=None, reverse=0, painter=painter.bar(), linkpainter=painter.linkedbar())
137    This class provides an axis suitable for a bar style. It handles a discrete set
138    of values and maps them to distinct ranges in graph coordinates. For that, the
139    axis gets a tuple of two values.
141    The first item is taken to be one of the discrete values valid on this axis. The
142    discrete values can be any hashable type and the order of the subaxes is defined
143    by the order the data is received or the inverse of that when *reverse* is set.
145    The second item is passed to the corresponding subaxis. The result of the
146    conversion done by the subaxis is mapped to the graph coordinate range reserved
147    for this subaxis. This range is defined by a size attribute of the subaxis,
148    which can be added to any axis. (see the sized linear axes described below for
149    some axes already having a size argument). When no size information is available
150    for a subaxis, a size value of 1 is used. The baraxis itself calculates its size
151    by suming up the sizes of its subaxes plus *firstdist*, *lastdist* and *dist*
152    times the number of subaxes minus 1.
154    *subaxes* should be a list or a dictionary mapping a discrete value of the bar
155    axis to the corresponding subaxis. When no subaxes are set or data is received
156    for an unknown discrete axis value, instances of defaultsubaxis are used as the
157    subaxis for this discrete value.
159    *dist* is used as the spacing between the ranges for each distinct value. It is
160    measured in the same units as the subaxis results, thus the default value of
161    ``0.5`` means half the width between the distinct values as the width for each
162    distinct value. *firstdist* and *lastdist* are used before the first and after
163    the last value. When set to ``None``, half of *dist* is used.
165    *title* is the title of the split axes and *painter* is a specialized painter
166    for an bar axis and *linkpainter* is used as the painter, when automatic link
167    axes are created by the :meth:`createlinked` method.
170 .. class:: nestedbar(subaxes=None, defaultsubaxis=bar(dist=0, painter=None, linkpainter=None), dist=0.5, firstdist=None, lastdist=None, title=None, reverse=0, painter=painter.bar(), linkpainter=painter.linkedbar())
172    This class is identical to the bar axis except for the different default value
173    for defaultsubaxis.
176 .. class:: split(subaxes=None, defaultsubaxis=linear(), dist=0.5, firstdist=0, lastdist=0, title=None, reverse=0, painter=painter.split(), linkpainter=painter.linkedsplit())
178    This class is identical to the bar axis except for the different default value
179    for defaultsubaxis, firstdist, lastdist, painter, and linkedpainter.
181 Sometimes you want to alter the default size of 1 of the subaxes. For that you
182 have to add a size attribute to the axis data. The two classes
183 :class:`sizedlinear` and :class:`autosizedlinear` do that for linear axes. Their
184 short names are :class:`sizedlin` and :class:`autosizedlin`.
185 :class:`sizedlinear` extends the usual linear axis by an first argument *size*.
186 :class:`autosizedlinear` creates the size out of its data range automatically
187 but sets an :class:`autolinear` parter with *extendtick* being ``None`` in order
188 to disable automatic range modifications while painting the axis.
190 The :mod:`axis` module also contains classes implementing so called anchored
191 axes, which combine an axis with an positioner and a storage place for axis
192 related data. Since these features are not interesting for the average PyX user,
193 we'll not go into all the details of their parameters and except for some handy
194 axis position methods:
197 .. class:: anchoredaxis()
199 .. method:: anchoredaxis.basepath(x1=None, x2=None)
201    Returns a path instance for the base path. *x1* and *x2* define the axis range,
202    the base path should cover. For ``None`` the beginning and end of the path is
203    taken, which might cover a longer range, when the axis is embedded as a subaxis.
204    For that case, a ``None`` value extends the range to the point of the middle
205    between two subaxes or the beginning or end of the whole axis, when the subaxis
206    is the first or last of the subaxes.
209 .. method:: anchoredaxis.vbasepath(v1=None, v2=None)
211    Like :meth:`basepath` but in graph coordinates.
214 .. method:: anchoredaxis.gridpath(x)
216    Returns a path instance for the grid path at position *x*. Might return ``None``
217    when no grid path is available.
220 .. method:: anchoredaxis.vgridpath(v)
222    Like :meth:`gridpath` but in graph coordinates.
225 .. method:: anchoredaxis.tickpoint(x)
227    Returns the position of *x* as a tuple ``(x, y)``.
230 .. method:: anchoredaxis.vtickpoint(v)
232    Like :meth:`tickpoint` but in graph coordinates.
235 .. method:: anchoredaxis.tickdirection(x)
237    Returns the direction of a tick at *x* as a tuple ``(dx, dy)``. The tick
238    direction points inside of the graph.
241 .. method:: anchoredaxis.vtickdirection(v)
243    Like :meth:`tickdirection` but in graph coordinates.
246 .. method:: anchoredaxis.vtickdirection(v)
248    Like :meth:`tickdirection` but in graph coordinates.
250 However, there are two anchored axes implementations :class:`linkedaxis` and
251 :class:`anchoredpathaxis` which are available to the user to create special
252 forms of anchored axes.
255 .. class:: linkedaxis(linkedaxis=None, errorname="manual-linked", painter=_marker)
257    This class implements an anchored axis to be passed to a graph constructor to
258    manually link the axis to another anchored axis instance *linkedaxis*. Note that
259    you can skip setting the value of *linkedaxis* in the constructor, but set it
260    later on by the :meth:`setlinkedaxis` method described below. *errorname* is
261    printed within error messages when the data is used and some problem occurs.
262    *painter* is used for painting the linked axis instead of the *linkedpainter*
263    provided by the *linkedaxis*.
266 .. method:: linkedaxis.setlinkedaxis(linkedaxis)
268    This method can be used to set the *linkedaxis* after constructing the axis. By
269    that you can create several graph instances with cycled linked axes.
272 .. class:: anchoredpathaxis(path, axis, direction=1)
274    This class implements an anchored axis the path *path*. *direction* defines the
275    direction of the ticks. Allowed values are ``1`` (left) and ``-1`` (right).
277 The :class:`anchoredpathaxis` contains as any anchored axis after calling its
278 :meth:`create` method the painted axis in the :attr:`canvas` member attribute.
279 The function :func:`pathaxis` has the same signature like the
280 :class:`anchoredpathaxis` class, but immediately creates the axis and returns
281 the painted axis.
284 .. module:: graph.axis.tick
286 Module :mod:`graph.axis.tick`: Axes ticks
287 =========================================
289 The following classes are part of the module :mod:`graph.axis.tick`.
292 .. class:: rational(x, power=1, floatprecision=10)
294    This class implements a rational number with infinite precision. For that it
295    stores two integers, the numerator ``num`` and a denominator ``denom``. Note
296    that the implementation of rational number arithmetics is not at all complete
297    and designed for its special use case of axis partitioning in PyX preventing any
298    roundoff errors.
300    *x* is the value of the rational created by a conversion from one of the
301    following input values:
303 * A float. It is converted to a rational with finite precision determined by
304      *floatprecision*.
306 * A string, which is parsed to a rational number with full precision. It is also
307      allowed to provide a fraction like ``"1/3"``.
309 * A sequence of two integers. Those integers are taken as numerator and
310      denominator of the rational.
312 * An instance defining instance variables ``num`` and ``denom`` like
313      :class:`rational` itself.
315    *power* is an integer to calculate ``x**power``. This is useful at certain
316    places in partitioners.
319 .. class:: tick(x, ticklevel=0, labellevel=0, label=None, labelattrs=[], power=1, floatprecision=10)
321    This class implements ticks based on rational numbers. Instances of this class
322    can be passed to the ``manualticks`` parameter of a regular axis.
324    The parameters *x*, *power*, and *floatprecision* share its meaning with
325    :class:`rational`.
327    A tick has a tick level (*i.e.* markers at the axis path) and a label lavel
328    (*e.i.* place text at the axis path), *ticklevel* and *labellevel*. These are
329    non-negative integers or *None*. A value of ``0`` means a regular tick or label,
330    ``1`` stands for a subtick or sublabel, ``2`` for subsubtick or subsublabel and
331    so on. ``None`` means omitting the tick or label. *label* is the text of the
332    label. When not set, it can be created automatically by a texter. *labelattrs*
333    are the attributes for the labels.
336 .. module:: graph.axis.parter
338 Module :mod:`graph.axis.parter`: Axes partitioners
339 ==================================================
341 The following classes are part of the module :mod:`graph.axis.parter`. Instances
342 of the classes can be passed to the parter keyword argument of regular axes.
345 .. class:: linear(tickdists=None, labeldists=None, extendtick=0, extendlabel=None, epsilon=1e-10)
347    Instances of this class creates equally spaced tick lists. The distances between
348    the ticks, subticks, subsubticks *etc.* starting from a tick at zero are given
349    as first, second, third *etc.* item of the list *tickdists*. For a tick
350    position, the lowest level wins, *i.e.* for ``[2, 1]`` even numbers will have
351    ticks whereas subticks are placed at odd integer. The items of *tickdists* might
352    be strings, floats or tuples as described for the *pos* parameter of class
353    :class:`tick`.
355    *labeldists* works equally for placing labels. When *labeldists* is kept
356    ``None``, labels will be placed at each tick position, but sublabels *etc.* will
357    not be used. This copy behaviour is also available *vice versa* and can be
358    disabled by an empty list.
360    *extendtick* can be set to a tick level for including the next tick of that
361    level when the data exceeds the range covered by the ticks by more than
362    *epsilon*. *epsilon* is taken relative to the axis range. *extendtick* is
363    disabled when set to ``None`` or for fixed range axes. *extendlabel* works
364    similar to *extendtick* but for labels.
367 .. class:: lin(...)
369    This class is an abbreviation of :class:`linear` described above.
372 .. class:: autolinear(variants=defaultvariants, extendtick=0, epsilon=1e-10)
374    Instances of this class creates equally spaced tick lists, where the distance
375    between the ticks is adjusted to the range of the axis automatically. Variants
376    are a list of possible choices for *tickdists* of :class:`linear`. Further
377    variants are build out of these by multiplying or dividing all the values by
378    multiples of ``10``. *variants* should be ordered that way, that the number of
379    ticks for a given range will decrease, hence the distances between the ticks
380    should increase within the *variants* list. *extendtick* and *epsilon* have the
381    same meaning as in :class:`linear`.
384 .. attribute:: autolinear.defaultvariants
386    ``[[tick.rational((1, 1)), tick.rational((1, 2))], [tick.rational((2, 1)),
387    tick.rational((1, 1))], [tick.rational((5, 2)), tick.rational((5, 4))],
388    [tick.rational((5, 1)), tick.rational((5, 2))]]``
391 .. class:: autolin(...)
393    This class is an abbreviation of :class:`autolinear` described above.
396 .. class:: preexp(pres, exp)
398    This is a storage class defining positions of ticks on a logarithmic scale. It
399    contains a list *pres* of positions :math:`p_i` and *exp*, a multiplicator
400    :math:`m`. Valid tick positions are defined by :math:`p_im^n` for any integer
401    :math:`n`.
404 .. class:: logarithmic(tickpreexps=None, labelpreexps=None, extendtick=0, extendlabel=None, epsilon=1e-10)
406    Instances of this class creates tick lists suitable to logarithmic axes. The
407    positions of the ticks, subticks, subsubticks *etc.* are defined by the first,
408    second, third *etc.* item of the list *tickpreexps*, which are all
409    :class:`preexp` instances.
411    *labelpreexps* works equally for placing labels. When *labelpreexps* is kept
412    ``None``, labels will be placed at each tick position, but sublabels *etc.* will
413    not be used. This copy behaviour is also available *vice versa* and can be
414    disabled by an empty list.
416    *extendtick*, *extendlabel* and *epsilon* have the same meaning as in
417    :class:`linear`.
419 Some :class:`preexp` instances for the use in :class:`logarithmic` are available
420 as instance variables (should be used read-only):
423 .. attribute:: logarithmic.pre1exp5
425    ``preexp([tick.rational((1, 1))], 100000)``
428 .. attribute:: logarithmic.pre1exp4
430    ``preexp([tick.rational((1, 1))], 10000)``
433 .. attribute:: logarithmic.pre1exp3
435    ``preexp([tick.rational((1, 1))], 1000)``
438 .. attribute:: logarithmic.pre1exp2
440    ``preexp([tick.rational((1, 1))], 100)``
443 .. attribute:: logarithmic.pre1exp
445    ``preexp([tick.rational((1, 1))], 10)``
448 .. attribute:: logarithmic.pre125exp
450    ``preexp([tick.rational((1, 1)), tick.rational((2, 1)), tick.rational((5, 1))],
451    10)``
454 .. attribute:: logarithmic.pre1to9exp
456    ``preexp([tick.rational((1, 1)) for x in range(1, 10)], 10)``
459 .. class:: log(...)
461    This class is an abbreviation of :class:`logarithmic` described above.
464 .. class:: autologarithmic(variants=defaultvariants, extendtick=0, extendlabel=None, epsilon=1e-10)
466    Instances of this class creates tick lists suitable to logarithmic axes, where
467    the distance between the ticks is adjusted to the range of the axis
468    automatically. Variants are a list of tuples with possible choices for
469    *tickpreexps* and *labelpreexps* of :class:`logarithmic`. *variants* should be
470    ordered that way, that the number of ticks for a given range will decrease
471    within the *variants* list.
473    *extendtick*, *extendlabel* and *epsilon* have the same meaning as in
474    :class:`linear`.
477 .. attribute:: autologarithmic.defaultvariants
479    ``[([log.pre1exp, log.pre1to9exp], [log.pre1exp, log.pre125exp]), ([log.pre1exp,
480    log.pre1to9exp], None), ([log.pre1exp2, log.pre1exp], None), ([log.pre1exp3,
481    log.pre1exp], None), ([log.pre1exp4, log.pre1exp], None), ([log.pre1exp5,
482    log.pre1exp], None)]``
485 .. class:: autolog(...)
487    This class is an abbreviation of :class:`autologarithmic` described above.
490 .. module:: graph.axis.texter
492 Module :mod:`graph.axis.texter`: Axes texter
493 ============================================
495 The following classes are part of the module :mod:`graph.axis.texter`. Instances
496 of the classes can be passed to the texter keyword argument of regular axes.
497 Texters are used to define the label text for ticks, which request to have a
498 label, but for which no label text has been specified so far. A typical case are
499 ticks created by partitioners described above.
502 .. class:: decimal(prefix="", infix="", suffix="", equalprecision=0, decimalsep=".", thousandsep="", thousandthpartsep="", plus="", minus="-", period=r"\\overline{%s}", labelattrs=[text.mathmode])
504    Instances of this class create decimal formatted labels.
506    The strings *prefix*, *infix*, and *suffix* are added to the label at the
507    beginning, immediately after the plus or minus, and at the end, respectively.
508    *decimalsep*, *thousandsep*, and *thousandthpartsep* are strings used to
509    separate integer from fractional part and three-digit groups in the integer and
510    fractional part. The strings *plus* and *minus* are inserted in front of the
511    unsigned value for non-negative and negative numbers, respectively.
513    The format string *period* should generate a period. It must contain one string
514    insert operators ``%s`` for the period.
516    *labelattrs* is a list of attributes to be added to the label attributes given
517    in the painter. It should be used to setup TeX features like ``text.mathmode``.
518    Text format options like ``text.size`` should instead be set at the painter.
521 .. class:: exponential(plus="", minus="-", mantissaexp=r"{{%s}\\cdot10^{%s}}", skipexp0=r"{%s}", skipexp1=None, nomantissaexp=r"{10^{%s}}", minusnomantissaexp=r"{-10^{%s}}", mantissamin=tick.rational((1, 1)), mantissamax=tick.rational((10L, 1)), skipmantissa1=0, skipallmantissa1=1, mantissatexter=decimal())
523    Instances of this class create decimal formatted labels with an exponential.
525    The strings *plus* and *minus* are inserted in front of the unsigned value of
526    the exponent.
528    The format string *mantissaexp* should generate the exponent. It must contain
529    two string insert operators ``%s``, the first for the mantissa and the second
530    for the exponent. An alternative to the default is ``r"{{%s}{\rm e}{%s}}"``.
532    The format string *skipexp0* is used to skip exponent ``0`` and must contain one
533    string insert operator ``%s`` for the mantissa. ``None`` turns off the special
534    handling of exponent ``0``. The format string *skipexp1* is similar to
535    *skipexp0*, but for exponent ``1``.
537    The format string *nomantissaexp* is used to skip the mantissa ``1`` and must
538    contain one string insert operator ``%s`` for the exponent. ``None`` turns off
539    the special handling of mantissa ``1``. The format string *minusnomantissaexp*
540    is similar to *nomantissaexp*, but for mantissa ``-1``.
542    The :class:`tick.rational` instances *mantissamin*< *mantissamax* are minimum
543    (including) and maximum (excluding) of the mantissa.
545    The boolean *skipmantissa1* enables the skipping of any mantissa equals ``1``
546    and ``-1``, when *minusnomantissaexp* is set. When the boolean
547    *skipallmantissa1* is set, a mantissa equals ``1`` is skipped only, when all
548    mantissa values are ``1``. Skipping of a mantissa is stronger than the skipping
549    of an exponent.
551    *mantissatexter* is a texter instance for the mantissa.
554 .. class:: mixed(smallestdecimal=tick.rational((1, 1000)), biggestdecimal=tick.rational((9999, 1)), equaldecision=1, decimal=decimal(), exponential=exponential())
556    Instances of this class create decimal formatted labels with an exponential,
557    when the unsigned values are small or large compared to *1*.
559    The rational instances *smallestdecimal* and *biggestdecimal* are the smallest
560    and biggest decimal values, where the decimal texter should be used. The sign of
561    the value is ignored here. For a tick at zero the decimal texter is considered
562    best as well. *equaldecision* is a boolean to indicate whether the decision for
563    the decimal or exponential texter should be done globally for all ticks.
565    *decimal* and *exponential* are a decimal and an exponential texter instance,
566    respectively.
569 .. class:: rational(prefix="", infix="", suffix="", numprefix="", numinfix="", numsuffix="", denomprefix="", denominfix="", denomsuffix="", plus="", minus="-", minuspos=0, over=r"%s\\over%s", equaldenom=0, skip1=1, skipnum0=1, skipnum1=1, skipdenom1=1, labelattrs=[text.mathmode])
571    Instances of this class create labels formated as fractions.
573    The strings *prefix*, *infix*, and *suffix* are added to the label at the
574    beginning, immediately after the plus or minus, and at the end, respectively.
575    The strings *numprefix*, *numinfix*, and *numsuffix* are added to the labels
576    numerator accordingly whereas *denomprefix*, *denominfix*, and *denomsuffix* do
577    the same for the denominator.
579    The strings *plus* and *minus* are inserted in front of the unsigned value. The
580    position of the sign is defined by *minuspos* with values ``1`` (at the
581    numerator), ``0`` (in front of the fraction), and ``-1`` (at the denominator).
583    The format string *over* should generate the fraction. It must contain two
584    string insert operators ``%s``, the first for the numerator and the second for
585    the denominator. An alternative to the default is ``"{{%s}/{%s}}"``.
587    Usually, the numerator and denominator are canceled, while, when *equaldenom* is
588    set, the least common multiple of all denominators is used.
590    The boolean *skip1* indicates, that only the prefix, plus or minus, the infix
591    and the suffix should be printed, when the value is ``1`` or ``-1`` and at least
592    one of *prefix*, *infix* and *suffix* is present.
594    The boolean *skipnum0* indicates, that only a ``0`` is printed when the
595    numerator is zero.
597    *skipnum1* is like *skip1* but for the numerator.
599    *skipdenom1* skips the denominator, when it is ``1`` taking into account
600    *denomprefix*, *denominfix*, *denomsuffix* *minuspos* and the sign of the
601    number.
603    *labelattrs* has the same meaning as for *decimal*.
606 .. module:: graph.axis.painter
608 Module :mod:`graph.axis.painter`: Axes painter
609 ==============================================
611 The following classes are part of the module :mod:`graph.axis.painter`.
612 Instances of the painter classes can be passed to the painter keyword argument
613 of regular axes.
616 .. class:: rotatetext(direction, epsilon=1e-10)
618    This helper class is used in direction arguments of the painters below to
619    prevent axis labels and titles being written upside down. In those cases the
620    text will be rotated by 180 degrees. *direction* is an angle to be used relative
621    to the tick direction. *epsilon* is the value by which 90 degrees can be
622    exceeded before an 180 degree rotation is performed.
624 The following two class variables are initialized for the most common
625 applications:
628 .. attribute:: rotatetext.parallel
630    ``rotatetext(90)``
633 .. attribute:: rotatetext.orthogonal
635    ``rotatetext(180)``
638 .. class:: ticklength(initial, factor)
640    This helper class provides changeable PyX lengths starting from an initial value
641    *initial* multiplied by *factor* again and again. The resulting lengths are thus
642    a geometric series.
644 There are some class variables initialized with suitable values for tick
645 stroking. They are named ``ticklength.SHORT``, ``ticklength.SHORt``, …,
646 ``ticklength.short``, ``ticklength.normal``, ``ticklength.long``, …,
647 ``ticklength.LONG``. ``ticklength.normal`` is initialized with a length of
648 ``0.12`` and the reciprocal of the golden mean as ``factor`` whereas the others
649 have a modified initial value obtained by multiplication with or division by
650 appropriate multiples of  :math:`\sqrt{2}`.
653 .. class:: regular(innerticklength=ticklength.normal, outerticklength=None, tickattrs=[], gridattrs=None, basepathattrs=[], labeldist="0.3 cm", labelattrs=[], labeldirection=None, labelhequalize=0, labelvequalize=1, titledist="0.3 cm", titleattrs=[], titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None)
655    Instances of this class are painters for regular axes like linear and
656    logarithmic axes.
658    *innerticklength* and *outerticklength* are visual PyX lengths of the ticks,
659    subticks, subsubticks *etc.* plotted along the axis inside and outside of the
660    graph. Provide changeable attributes to modify the lengths of ticks compared to
661    subticks *etc.* ``None`` turns off the ticks inside and outside the graph,
662    respectively.
664    *tickattrs* and *gridattrs* are changeable stroke attributes for the ticks and
665    the grid, where ``None`` turns off the feature. *basepathattrs* are stroke
666    attributes for the axis or ``None`` to turn it off. *basepathattrs* is merged
667    with ``[style.linecap.square]``.
669    *labeldist* is the distance of the labels from the axis base path as a visual
670    PyX length. *labelattrs* is a list of text attributes for the labels. It is
671    merged with ``[text.halign.center, text.vshift.mathaxis]``. *labeldirection* is
672    an instance of *rotatetext* to rotate the labels relative to the axis tick
673    direction or ``None``.
675    The boolean values *labelhequalize* and *labelvequalize* force an equal
676    alignment of all labels for straight vertical and horizontal axes, respectively.
678    *titledist* is the distance of the title from the rest of the axis as a visual
679    PyX length. *titleattrs* is a list of text attributes for the title. It is
680    merged with ``[text.halign.center, text.vshift.mathaxis]``. *titledirection* is
681    an instance of *rotatetext* to rotate the title relative to the axis tick
682    direction or ``None``. *titlepos* is the position of the title in graph
683    coordinates.
685    *texrunner* is the texrunner instance to create axis text like the axis title or
686    labels. When not set the texrunner of the graph instance is taken to create the
687    text.
690 .. class:: linked(innerticklength=ticklength.short, outerticklength=None, tickattrs=[], gridattrs=None, basepathattrs=[], labeldist="0.3 cm", labelattrs=None, labeldirection=None, labelhequalize=0, labelvequalize=1, titledist="0.3 cm", titleattrs=None, titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None)
692    This class is identical to :class:`regular` up to the default values of
693    *labelattrs* and *titleattrs*. By turning off those features, this painter is
694    suitable for linked axes.
697 .. class:: bar(innerticklength=None, outerticklength=None, tickattrs=[], basepathattrs=[], namedist="0.3 cm", nameattrs=[], namedirection=None, namepos=0.5, namehequalize=0, namevequalize=1, titledist="0.3 cm", titleattrs=[], titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None)
699    Instances of this class are suitable painters for bar axes.
701    *innerticklength* and *outerticklength* are visual PyX lengths to mark the
702    different bar regions along the axis inside and outside of the graph. ``None``
703    turns off the ticks inside and outside the graph, respectively. *tickattrs* are
704    stroke attributes for the ticks or ``None`` to turn all ticks off.
706    The parameters with prefix *name* are identical to their *label* counterparts in
707    :class:`regular`. All other parameters have the same meaning as in
708    :class:`regular`.
711 .. class:: linkedbar(innerticklength=None, outerticklength=None, tickattrs=[], basepathattrs=[], namedist="0.3 cm", nameattrs=None, namedirection=None, namepos=0.5, namehequalize=0, namevequalize=1, titledist="0.3 cm", titleattrs=None, titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None)
713    This class is identical to :class:`bar` up to the default values of *nameattrs*
714    and *titleattrs*. By turning off those features, this painter is suitable for
715    linked bar axes.
718 .. class:: split(breaklinesdist="0.05 cm", breaklineslength="0.5 cm", breaklinesangle=-60, titledist="0.3 cm", titleattrs=[], titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None)
720    Instances of this class are suitable painters for split axes.
722    *breaklinesdist* and *breaklineslength* are the distance between axes break
723    markers in visual PyX lengths. *breaklinesangle* is the angle of the axis break
724    marker with respect to the base path of the axis. All other parameters have the
725    same meaning as in :class:`regular`.
728 .. class:: linkedsplit(breaklinesdist="0.05 cm", breaklineslength="0.5 cm", breaklinesangle=-60, titledist="0.3 cm", titleattrs=None, titledirection=rotatetext.parallel, titlepos=0.5, texrunner=None)
730    This class is identical to :class:`split` up to the default value of
731    *titleattrs*. By turning off this feature, this painter is suitable for linked
732    split axes.
735 .. module:: graph.axis.rater
737 Module :mod:`graph.axis.rater`: Axes rater
738 ==========================================
740 The rating of axes is implemented in :mod:`graph.axis.rater`. When an axis
741 partitioning scheme returns several partitioning possibilities, the partitions
742 need to be rated by a positive number. The axis partitioning rated lowest is
743 considered best.
745 The rating consists of two steps. The first takes into account only the number
746 of ticks, subticks, labels and so on in comparison to optimal numbers.
747 Additionally, the extension of the axis range by ticks and labels is taken into
748 account. This rating leads to a preselection of possible partitions. In the
749 second step, after the layout of preferred partitionings has been calculated,
750 the distance of  the labels in a partition is taken into account as well at a
751 smaller weight factor by default. Thereby partitions with overlapping labels
752 will be rejected completely. Exceptionally sparse or dense labels will receive a
753 bad rating as well.
756 .. class:: cube(opt, left=None, right=None, weight=1)
758    Instances of this class provide a number rater. *opt* is the optimal value. When
759    not provided, *left* is set to ``0`` and *right* is set to ``3*opt``. Weight is
760    a multiplicator to the result.
762    The rater calculates ``width*((x-opt)/(other-opt))**3`` to rate the value ``x``,
763    where ``other`` is *left* (``x``<*opt*) or *right* (``x``>*opt*).
766 .. class:: distance(opt, weight=0.1)
768    Instances of this class provide a rater for a list of numbers. The purpose is to
769    rate the distance between label boxes. *opt* is the optimal value.
771    The rater calculates the sum of ``weight*(opt/x-1)`` (``x``<*opt*) or
772    ``weight*(x/opt-1)`` (``x``>*opt*) for all elements ``x`` of the list. It
773    returns this value divided by the number of elements in the list.
776 .. class:: rater(ticks, labels, range, distance)
778    Instances of this class are raters for axes partitionings.
780    *ticks* and *labels* are both lists of number rater instances, where the first
781    items are used for the number of ticks and labels, the second items are used for
782    the number of subticks (including the ticks) and sublabels (including the
783    labels) and so on until the end of the list is reached or no corresponding ticks
784    are available.
786    *range* is a number rater instance which rates the range of the ticks relative
787    to the range of the data.
789    *distance* is an distance rater instance.
792 .. class:: linear(ticks=[cube(4), cube(10, weight=0.5)], labels=[cube(4)], range=cube(1, weight=2), distance=distance("1 cm"))
794    This class is suitable to rate partitionings of linear axes. It is equal to
795    :class:`rater` but defines predefined values for the arguments.
798 .. class:: lin(...)
800    This class is an abbreviation of :class:`linear` described above.
803 .. class:: logarithmic(ticks=[cube(5, right=20), cube(20, right=100, weight=0.5)], labels=[cube(5, right=20), cube(5, right=20, weight=0.5)], range=cube(1, weight=2), distance=distance("1 cm"))
805    This class is suitable to rate partitionings of logarithmic axes. It is equal to
806    :class:`rater` but defines predefined values for the arguments.
809 .. class:: log(...)
811    This class is an abbreviation of :class:`logarithmic` described above.
814 .. module:: graph.axis.positioners
816 Module :mod:`graph.axis.positioner`: Axes positioners
817 =====================================================
819 The position of an axis is defined by an instance of a class providing the
820 following methods:
823 .. class:: positioner()
825 .. method:: positioner.vbasepath(v1=None, v2=None)
827    Returns a path instance for the base path. *v1* and *v2* define the axis range
828    in graph coordinates the base path should cover.
831 .. method:: positioner.vgridpath(v)
833    Returns a path instance for the grid path at position *v* in graph coordinates.
834    The method might return ``None`` when no grid path is available (for an axis
835    along a path for example).
838 .. method:: positioner.vtickpoint_pt(v)
840    Returns the position of *v* in graph coordinates as a tuple ``(x, y)`` in
841    points.
844 .. method:: positioner.vtickdirection(v)
846    Returns the direction of a tick at *v* in graph coordinates as a tuple ``(dx,
847    dy)``. The tick direction points inside of the graph.
849 The module contains several implementations of those positioners, but since the
850 positioner instances are created by graphs etc. as needed, the details are not
851 interesting for the average PyX user.