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