1 \chapter{Module graph: graph plotting
}
3 \section{Introductory notes
}
5 The graph module is considered to be in constant, gradual development.
6 For the moment we concentrate ourself on standard
2d xy-graphs taking
7 all kind of possible specialties into account like any number of axes.
8 Architectural decisions play the most substantial role at the moment
9 and have hopefully already been done that way, that their flexibility
10 will suffice for future usage in quite different graph applications,
11 \emph{e.g.
} circular
2d graphs or even
3d graphs. We will describe
12 those parts of the graph module here, which are in a totally usable
13 state already and are hopefully not to be changed later on. However,
14 future developments certainly will cause some incompatibilities. At
15 least be warned: Nobody knows the hole list of things that will break.
16 At the moment, keeping backwards compatibility in the graph module is
17 not at all an issue. Although we do not yet claim any backwards
18 compatibility for the future at all, the graph module is certainly one
19 of the biggest construction sites within
\PyX.
21 The task of drawing graphs is splitted in quite some subtasks, which
22 are implemented by classes of its own. We tried to make those
23 components as independend as it is usefull and possible in order to
24 make them reuseable for different graph types. They are also
25 replaceable by the user to get more specialized graph drawing tasks
26 done without needing to implement a hole graph system. A major
27 abstraction layer are the so-called graph coordinates. Their range is
28 generally fixed to $
[0;
1]$. Only the graph does know about the
29 conversion between these coordinates and the position at the canvas
30 (the graph itself is its canvas, that can be inserted into another
31 canvas). By that, all other components can be reused for different
32 graph geometries. The interfaces between the components are documented
33 in docstrings of interface classes in the source. The interface
34 technique is used for documentation purposes only. For the user, the
35 most important informations (as described in the following) are the
36 parameters of the constructors of the various implementations of those
37 interface. They are documented in docstrings of the constructors of
38 the classes. While effort of clearing and documenting is still in
39 progress, some parts are already nicely documented as you may see by
45 A common feature of a graph are axes. An axis is responsible for the
46 conversion of values to graph coordinates. There are predefined axis
50 axis type&description\\
52 \texttt{linaxis
}&linear axis\\
53 \texttt{logaxis
}&logarithmic axis\\
57 Further axes types are available to support axes splitting and bar
58 graphs (other axes types might be added in the future as well), but
59 they behave quite different from the generic case and are thus
60 described separately below.
62 \subsection{Axes properties
}
64 Global properties of an axis are set as named parameters in the axis
65 constructor. Both, the
\verb|linaxis| and the
\verb|logaxis|, have the
66 same set of named parameters listed in the following table:
69 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
70 argument name&description\\
72 \texttt{title
}&axis title\\
73 \texttt{min
}&fixes axis minimum; if not set, it is automatically determined, but this might fail, for example for the $x$-range of functions, when it is not specified there\\
74 \texttt{max
}&as above, but for the maximum\\
75 \texttt{reverse
}&boolean; exchange minimum and maximum (might be used without setting minimum and maximum); if min>max and reverse is set, they cancel each other\\
76 \texttt{divisor
}&numerical divisor for the axis partitioning; default:
\texttt{1}\\
77 \texttt{suffix
}&a suffix to indicate the divisor within an automatic axis labeling\\
78 \texttt{datavmin
}&minimal graph coordinate when adjusting the axis minima to the graph data; default:
\texttt{0.05} (or
\texttt{0}, when min is present)\\
79 \texttt{datavmax
}&as above, but for the maximum; default:
\texttt{0.95} (or
\texttt{1}, when max is present)\\
80 \texttt{tickvmin
}&minimal graph coordinate for placing ticks to the axis; default:
\texttt{0}\\
81 \texttt{tickvmax
}&as above, but for the maximum; default:
\texttt{1}\\
82 \texttt{density
}&density parameter for the axis partition rating\\
83 \texttt{maxworse
}&number of trials with worse tick rating before giving up; default:
\texttt{2}\\
84 \texttt{painter
}&axis painter (described below)\\
85 \texttt{texter
}&texter for the axis labels (described below)\\
86 \texttt{part
}&axis partition (described below)\\
87 \texttt{rater
}&partition rater (described below)\\
91 \subsection{Partitioning of axes
}
93 The definition of ticks and labels appropriate to an axis range is
94 called partitioning. The axis partioning within
\PyX{} uses rational
95 arithmetics, which avoids any kind of rounding problems to the cost of
96 performance. The class
\verb|frac| supplies a rational number. It can
97 be initialized by another
\verb|frac| instance, a tuple of integers
98 (called enumerator and denominator), a float (which gets converted
99 into a frac with a finite resolution
\verb|floatprecision| of
10
100 digits per default) or a string with infinite precision (like
101 "
1.2345e-100" or even "
1/
3"). However, a partitioning is composed out
102 of a sorted list of ticks, where the class
\verb|tick| is derived from
103 \verb|frac| and has additional properties called
\verb|ticklevel|,
104 \verb|labellevel|,
\verb|label| and
\verb|labelattrs|. When the
105 ticklevel or the labellevel is
\verb|None|, it just means not present,
106 \verb|
0| means tick or label, respectively,
\verb|
1| means subtick or
107 sublevel and so on. When
\verb|labellevel| is not
\verb|None|, a
108 \verb|label| might be explicitly given, which will get used as the
109 text of that label. Otherwise the axis painter has to create an
110 appropriate text for the label. The
\verb|labelattrs| might specify
111 some attributes for the label to be used by the
\verb|text| method of
112 an
\verb|texrunner| instance.
114 You can pass a list of
\verb|tick| instance to the
\verb|part|
115 argument of an axis. By that you can place ticks whereever you want.
116 (In former versions there was a manual partitioner and the possibility
117 of mixing partitions for that. This is still available in this
118 version of
\PyX{}, but it will be removed in the future.) Additionally
119 you can use a partitioner to create ticks appropriate to the axis
120 range. This can be done by manually specifying distances between
121 ticks, subticks and so on. Alternatively there are automatic axis
122 partitioners available, which provide different partitions and the
123 rating of those different partitions by the
\verb|rater| become
124 crutial. Note, that you can combine manually set ticks and a
125 partitioner in the
\verb|part| argument of an axis.
127 \subsubsection{Partitioning of linear axes
}
129 The class
\verb|linpart| creates a linear partition as described by
130 named parameters of the constructor:
133 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
134 argument name&default&description\\
136 \texttt{tickdist
}&
\texttt{None
}&distance between ticks, subticks, etc. (see comment below); when the parameter is
\texttt{None
}, ticks will get placed at labels\\
137 \texttt{labeldist
}&
\texttt{None
}&distance between labels, sublabels, etc. (see comment below); when the parameter is
\texttt{None
}, labels will get placed at ticks\\
138 \texttt{labels
}&
\texttt{None
}&set the text for the labels manually\\
139 \texttt{extendtick
}&
\texttt{0}&allow for a range extention to include the next tick of the given level\\
140 \texttt{extendlabel
}&
\texttt{None
}&as above, but for labels\\
141 \texttt{epsilon
}&
\texttt{1e-10}&allow for exceeding the range by that relative value\\
142 \texttt{mix
}&
\texttt{()
}&an obsolete feature to mix-in additional ticks (to be removed in future versions)\\
146 The
\verb|ticks| and
\verb|labels| can either be a list or just a
147 single entry. When a list is provided, the first entry stands for
148 the tick or label, respectively, the second for the subtick or
149 sublabel, and so on. The entries are passed to the constructor of a
150 frac instance, e.g. there can be tuples (enumerator, denominator),
151 strings, floats, etc.
153 \subsubsection{Partitioning of logarithmic axes
}
155 The class
\verb|logpart| create a logarithmic partition. The
156 parameters of the constructor of the class
\verb|logpart| are quite
157 simular to the parameters of
\verb|linpart| discussed above. Instead
158 of the parameters
\verb|tickdist| and
\verb|labeldist| the parameters
159 \verb|tickpos| and
\verb|labelpos| are present. All other parameters
160 of
\verb|logpart| do not differ in comparision to
\verb|linpart|. The
161 \verb|tickdist| and
\verb|labeldist| parameters take either a single
162 \verb|preexp| instance or a list of
\verb|preexp| instances, where the
163 first stands for the ticks (labels), the second for subticks
164 (sublabels) and so on. A
\verb|preexp| instance contains a list of
165 \verb|pres|, which are
\verb|frac| instances defining some positions,
166 say $p_i$. Furthermore there is a
\verb|frac| instance called
167 \verb|exp|, say $e$. Valid tick and label positions are then given by
168 $s^np_i$, where $n$ is an integer.
172 name&values it descibes\\
174 \texttt{pre1exp5
}&
1 and multiple of $
10^
5$\\
175 \texttt{pre1exp4
}&
1 and multiple of $
10^
4$\\
176 \texttt{pre1exp3
}&
1 and multiple of $
10^
3$\\
177 \texttt{pre1exp2
}&
1 and multiple of $
10^
2$\\
178 \texttt{pre1exp
}&
1 and multiple of $
10$\\
179 \texttt{pre125exp
}&
1,
2,
5 and multiple of $
10$\\
180 \texttt{pre1to9exp
}&
1,
2,
\dots,
9 and multiple of $
10$\\
184 \subsubsection{Automatic partitioning of linear axes
}
186 When no explicit axis partitioner is given in the constructor argument
187 \verb|part| of an linear axis, it is initialized with an automatic
188 partitioning scheme for linear axes. This scheme is provided by the
189 class
\verb|autolinpart|, where the constructor takes the following
193 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
194 argument name&default&description\\
196 \texttt{variants
}&
\texttt{defaultvariants
}&list of possible values for the ticks parameter of
\texttt{linpart
} (labels are placed at the position of ticks)\\
197 \texttt{extendtick
}&
\texttt{0}&allow for a range extention to include the next tick of the given level\\
198 \texttt{epsilon
}&
\texttt{1e-10}&allow for exceeding the range by that relative value\\
199 \texttt{mix
}&
\texttt{()
}&as in linpart\\
203 The default value for the argument
\verb|variants|, namely
204 \verb|defaultvariants|, is defined as a class variable of
205 \verb|autolinpart| and has the value
\texttt{((frac(
1,
1), frac(
1,
206 2)), (frac(
2,
1), frac(
1,
1)), (frac(
5,
2), frac(
5,
4)), (frac(
5,
1),
207 frac(
5,
2)))
}. This implies, that the automatic axis partitioning
208 scheme allows for partitions using (ticks, subticks) with at distances
209 (
1,
1/
2), (
2,
1), (
5/
2,
5/
4), (
5,
5/
2). This list must be sorted by
210 the number of ticks the entries will lead to. The given fractions are
211 automatically multiplied or divided by
10 in order to fit better to
212 the axis range. Therefore those additional partitioning possibilities
213 (infinte possibilities) must not be given explicitly.
215 \subsubsection{Automatic partitioning of logarithmic axes
}
217 When no explicit axis partitioning is given in the constructor
218 argument
\verb|part| of an logarithmic axis, it is initialized with an
219 automatic partitioning schemes for logarithmic axes. This scheme is
220 provided by the class
\verb|autologpart|, where the constructor takes
221 the following arguments:
224 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
225 argument name&default&description\\
227 \texttt{variants
}&
\texttt{defaultvariants
}&list of pairs with possible values for the ticks and labels parameters of
\texttt{logpart
}\\
228 \texttt{extendtick
}&
\texttt{0}&allow for a range extention to include the next tick of the given level\\
229 \texttt{extendlabel
}&
\texttt{None
}&as above, but for labels\\
230 \texttt{epsilon
}&
\texttt{1e-10}&allow for exceeding the range by that relative value\\
231 \texttt{mix
}&
\texttt{()
}&as in linpart\\
235 The default value for the argument
\verb|variants|, namely
236 \verb|defaultvariants|, is defined as a class variable of
237 \verb|autologpart| and has the value:
239 (((pre1exp, pre1to9exp), # ticks & subticks,
240 (pre1exp, pre125exp)), # labels & sublevels
241 ((pre1exp, pre1to9exp), None), # ticks & subticks, labels=ticks
242 ((pre1exp2, pre1exp), None), # ticks & subticks, labels=ticks
243 ((pre1exp3, pre1exp), None), # ticks & subticks, labels=ticks
244 ((pre1exp4, pre1exp), None), # ticks & subticks, labels=ticks
245 ((pre1exp5, pre1exp), None)) # ticks & subticks, labels=ticks
247 As for the
\verb|autolinaxis|, this list must be sorted by the number
248 of ticks the entries will lead to.
250 \subsubsection{Rating of axes partitionings
}
252 When an axis partitioning scheme returns several partitioning
253 possibilities, the partitions are rated by an instance of a rater
254 class provided as the parameter
\verb|rater| at the axis constructor.
255 It is used to calculate a positive rating number for a given axis
256 partitioning. In the end, the lowest rated axis partitioning gets
259 The rating consists of two steps. The first takes into account only
260 the number of ticks, subticks, labels and so on in comparison to an
261 optimal number. Additionally, the transgression of the axis range by
262 ticks and labels is taken into account. This rating leads to a
263 preselection of possible partitions. In the second step the layout of
264 a partition gets acknowledged by rating the distance of the labels to
265 each other. Thereby partitions with overlapping labels get quashed
268 The class
\verb|axisrater| implements a rating with quite some
269 parameters specifically adjusted to linear and logarithmic axes. A
270 detailed description of the hole system goes beyond the scope of that
271 manual. Take your freedom and have a look at the
\PyX{} source code if
272 you wish to adopt the rating to personal preferences.
274 The overall optimal partition properties, namely the density of ticks
275 and labels, can be easily adjusted by the single parameter
276 \verb|density| of the axis constructor. The rating is
277 adjusted to the default densitiy value of
\verb|
1|, but modifications
278 of this parameter in the range of
0.5 (for less ticks) to
2 or even
3
279 (for more ticks) might be usefull.
281 \subsection{Creating label text
}
283 When a partition is created, the typical situation is that some of the
284 ticks have a
\verb|labellevel| not equal to
\verb|None| but there is
285 no
\verb|label| (a string) defined to be printed at this tick. The
286 task of a
\verb|texter| is to create those label strings for a given
287 list of ticks. There are different
\verb|texter| classes creating
288 different label strings.
290 \subsubsection{Decimal numbers
}
292 The class
\verb|decimaltexter| creates decimal labels. The format of
293 the labels can be configured by numerous arguments of the constructor
294 listed in the following table:
297 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
298 argument name&default&description\\
300 \texttt{prefix
}&
\texttt{""
}&string to be inserted in front of the number\\
301 \texttt{infix
}&
\texttt{""
}&string to be inserted between the plus or minus sign and the number\\
302 \texttt{suffix
}&
\texttt{""
}&string to be inserted after the number\\
303 \texttt{equalprecision
}&
\texttt{0}&forces a common number of digits after the comma\\
304 \texttt{decimalsep
}&
\texttt{"."
}&decimal separator\\
305 \texttt{thousandsep
}&
\texttt{""
}&thousand separator\\
306 \texttt{thousandthpartsep
}&
\texttt{""
}&thousandth part separator\\
307 \texttt{plus
}&
\texttt{""
}&plus sign\\
308 \texttt{minus
}&
\texttt{"-"
}&minus sign\\
309 \texttt{period
}&
\texttt{r"
\textbackslash overline\
{\%s\
}"
}&format string to indicate a period\\
310 \texttt{labelattrs
}&
\texttt{text.mathmode
}&a single attribute or a list of attributes to be added to the labelattrs\\
314 \subsubsection{Decimal numbers with an exponential
}
316 The class
\verb|exponentialtexter| creates decimal labels with an
317 exponent. The format of the labels can be configured by numerous
318 arguments of the constructor listed in the following table:
321 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
322 argument name&default&description\\
324 \texttt{plus
}&
\texttt{""
}&plus sign for the exponent\\
325 \texttt{minus
}&
\texttt{"-"
}&minus sign for the exponent\\
326 \texttt{mantissaexp
}&
\texttt{r"\
{\
{\%s\
}\textbackslash cdot10
\textasciicircum\
{\%s\
}\
}"
}&format string for manissa and exponent\\
327 \texttt{nomantissaexp
}&
\texttt{r"\
{10\textbackslash\
{\%s\
}\
}"
}&format string when skipping a manissa equals
1\\
328 \texttt{minusnomantissaexp
}&
\texttt{r"\
{-
1\textbackslash\
{\%s\
}\
}"
}&format string when skipping a manstissa equals -
1\\
329 \texttt{mantissamin
}&
\texttt{frac((
1,
1))
}&minimal value for the mantissa\\
330 \texttt{mantissamax
}&
\texttt{frac((
10,
1))
}&maximal value for the mantissa\\
331 \texttt{skipmantissa1
}&
\texttt{0}&skip mantissa equals
1\\
332 \texttt{skipallmantissa1
}&
\texttt{1}&skip mantissa when its always
1\\
333 \texttt{mantissatexter
}&
\texttt{decimaltexter()
}&texter for the mantissa\\
337 \subsubsection{Decimal numbers without or with an exponential
}
339 The class
\verb|defaulttexter| creates decimal labels without or
340 with an exponent. As the name says, its used as the default texter.
341 The texter splits the tick list into two lists, one to be passed to a
342 decimal texter and another to be passed to an exponential texter. This
343 splitting is based on the two properties
\verb|smallestdecimal| and
344 \verb|biggestdecimal|. See the following table for all available
348 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
349 argument name&default&description\\
351 \texttt{smallestdecimal
}&
\texttt{frac((
1,
1000))
}&the smallest number (ignoring the sign) where the decimal texter should be used\\
352 \texttt{biggestdecimal
}&
\texttt{frac((
9999,
1))
}&as above, but for the biggest number\\
353 \texttt{equaldecision
}&
\texttt{1}&either use the
\texttt{decimaltexter
} or the
\texttt{exponentialtexter
}\\
354 \texttt{decimaltexter
}&
\texttt{decimaltexter()
}&texter withoud an exponential\\
355 \texttt{exponentialtexter
}&
\texttt{exponentialtexter()
}&exponential with an exponential\\
359 \subsubsection{Rational numbers
}
361 The class
\verb|rationaltexter| creates rational labels. The format of
362 the labels can be configured by numerous arguments of the constructor
363 listed in the following table:
366 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
367 argument name&default&description\\
369 \texttt{prefix
}&
\texttt{""
}&string to be inserted in front of the rational\\
370 \texttt{infix
}&
\texttt{""
}&string to be inserted between the plus or minus sign and the rational\\
371 \texttt{suffix
}&
\texttt{""
}&string to be inserted after the rational\\
372 \texttt{enumprefix
}&
\texttt{""
}&as
\texttt{prefix
} but for the enumerator\\
373 \texttt{enuminfix
}&
\texttt{""
}&as
\texttt{infix
} but for the enumerator\\
374 \texttt{enumsuffix
}&
\texttt{""
}&as
\texttt{suffix
} but for the enumerator\\
375 \texttt{denomprefix
}&
\texttt{""
}&as
\texttt{prefix
} but for the denominator\\
376 \texttt{denominfix
}&
\texttt{""
}&as
\texttt{infix
} but for the denominator\\
377 \texttt{denomsuffix
}&
\texttt{""
}&as
\texttt{suffix
} but for the denominator\\
378 \texttt{plus
}&
\texttt{""
}&plus sign\\
379 \texttt{minus
}&
\texttt{"-"
}&minus sign\\
380 \texttt{minuspos
}&
\texttt{0}&position of the minus:
\texttt{0} -- in front of the fraction,
\texttt{1} -- in front of the enumerator,
\texttt{-
1} -- in front of the denominator\\
381 \texttt{over
}&
\texttt{r"\
{\
{\%s\
}\textbackslash over\
{\%s\
}\
}"
}&format string for the fraction\\
382 \texttt{equaldenom
}&
\texttt{0}&usually, the enumerator and the denominator are canceled; if set, take the least common multiple of all denominators\\
383 \texttt{skip1
}&
\texttt{1}&skip printing the fraction for
\texttt{1} when there is a
\texttt{prefix
},
\texttt{infix
}, or
\texttt{suffix
}\\
384 \texttt{skipenum0
}&
\texttt{1}&print
\texttt{0} instead of a fraction when the enumerator is
0\\
385 \texttt{skipenum1
}&
\texttt{1}&as
\texttt{skip1
} but for the enumerator\\
386 \texttt{skipdenom1
}&
\texttt{1}&skip the denominator when it is
\texttt{1} and there is no
\texttt{denomprefix
},
\texttt{denominfix
}, or
\texttt{denomsuffix
}\\
387 \texttt{labelattrs
}&
\texttt{text.mathmode
}&a single attribute or a list of attributes to be added to the labelattrs\\
391 \subsection{Painting of axes
}
393 A major task for an axis is its painting. It is done by instances of
394 \verb|axispainter|, provided to the constructor of an axis as its
395 \verb|painter| argument. The constructor of the axis painter receives
396 a numerous list of named parameters to modify the axis look. A list of
397 parameters is provided in the following table:
400 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
401 argument name&description\\
403 \texttt{innerticklengths
}$^
{1,
4}$&tick length of inner ticks (visual length);
\newline default:
\texttt{axispainter.defaultticklengths
}\\
404 \texttt{outerticklengths
}$^
{1,
4}$&as before, but for outer ticks; default:
\texttt{None
}\\
405 \texttt{tickattrs
}$^
{2,
4}$&stroke attributes for ticks; default:
\texttt{()
}\\
406 \texttt{gridattrs
}$^
{2,
4}$&stroke attributes for grid lines; default:
\texttt{None
}\\
407 \texttt{zerolineattrs
}$^
{3,
4}$&stroke attributes for a grid line at axis value
0; default:
\texttt{()
}\\
408 \texttt{baselineattrs
}$^
{3,
4}$&stroke attributes for the axis baseline;
\newline default:
\texttt{canvas.linecap.square
}\\
409 \texttt{labeldist
}&label distance from axis (visual length); default:
\texttt{"
0.3 cm"
}\\
410 \texttt{labelattrs
}$^
{2,
4}$&text attributes for labels;
\newline default:
\texttt{(text.halign.center, text.vshift.mathaxis)
}\\
411 \texttt{labeldirection
}$^
4$&relative label direction (see below); default:
\texttt{None
}\\
412 \texttt{labelhequalize
}&set width of labels to its maximum (boolean); default:
\texttt{0}\\
413 \texttt{labelvequalize
}&set height and depth of labels to their maxima (boolean); default:
\texttt{1}\\
414 \texttt{titledist
}&title distance from labels (visual length); default:
\texttt{"
0.3 cm"
}\\
415 \texttt{titleattrs
}$^
{3,
4}$&text attributes for title; default:
\texttt{(text.halign.center, text.vshift.mathaxis)
}\\
416 \texttt{titledirection
}$^
4$&relative title direction (see below);
\newline default:
\texttt{paralleltext
}\\
417 \texttt{titlepos
}&title position in graph coordinates; default:
\texttt{0.5}\\
422 The parameter should be a list, where the entries are attributes
423 for the different levels. When the level is larger then the list
424 length,
\verb|None| is assumed. When the parameter is not a list,
425 it is applied to all levels.\\
427 The parameter should be a list of lists, where the entries are
428 attributes for the different levels. When the level is larger then the
429 list length,
\verb|None| is assumed. When the parameter is not a
430 list of lists, it is applied to all levels.\\
432 The parameter should be a list. When the parameter is not a
433 list, the parameter is interpreted as a list with a single
436 The feature can be turned off by the value
\verb|None|. Within
437 lists or lists of lists, the value
\verb|None| might be
438 used to turn off the feature for some levels selectively.
441 Relative directions for labels (
\verb|labeldirection|) and titles
442 (
\verb|titledirection|) are instances of
\verb|rotatetext|. By that
443 the text direction is calculated relatively to the tick direction of
444 the axis and is added as an attribute of the text. The relative
445 direction provided by instances of the class
\verb|rotatetext| prevent
446 upside down text by flipping it by
180 degrees. For convenience, the
447 two self-explanatory values
\verb|rotatetext.parallel| and
448 \verb|rotatetext.orthogonal| are available, which are just instances of
449 rotatetext initializes by
\verb|-
90| degree and
\verb|
0|,
452 \subsection{Linked axes
}
454 Linked axes can be used whenever an axis should be repeated within a
455 single graph or even between different graphs although the intrinsic
456 meaning is to have only one axis plotted several times. Almost all
457 properties of a linked axis are supplied by the axis it is linked to
458 (you may call it the base axis), but some properties and methods might
459 be different. For the typical case (implemented by
\verb|linkaxis|)
460 only the painter of the axis is exchanged together with some
461 simplified behaviour when finishing the axis (there is no need to
462 recalculate the axis partition etc.). The constructor of
463 \verb|linkaxis| takes the axis to be linked to as the first parameter
464 and in the named parameter
\verb|painter| a new painter for the axis.
465 By default,
\verb|linkaxispainter| is used, which differs from the
466 standard
\verb|axispainter| by some default values for the arguments
467 only. Namely, the arguments
\verb|zerolineattrs|,
\verb|labelattrs|,
468 and
\verb|titleattrs| are set to
\verb|None| turing off these
471 \subsection{Special purpose axes
}
473 \subsubsection{Splitable axes
}
475 Axes with breaks are created by instances of the class
476 \verb|splitaxis|. Its constructor takes the following parameters:
479 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
480 argument name&description\\
482 (axis list)&a list of axes to be used as subaxes (this is the first parameter of the constructor; it has no name)\\
483 \texttt{splitlist
}&a single number or a list split points of the possitions of the axis breaks in graph coordinates; the value
\texttt{None
} forces
\texttt{relsizesplitdist
} to be used; default:
\texttt{0.5}\\
484 \texttt{splitdist
}&gap of the axis break; default:
\texttt{0.1}\\
485 \texttt{relsizesplitdist
}&used when
\texttt{splitlist
} entries are
\texttt{None
}; gap of the axis break in values of the surrounding axes (on logarithmic axes, a decade corresponds to
1); the split position is adjusted to give both surrounding axes the same scale (thus, their range must be completely fixed); default:
\texttt{1}\\
486 \texttt{title
}&axis title\\
487 \texttt{painter
}&axis painter; default:
\texttt{splitaxispainter()
} (described below)\\
491 A split axis is build up from a list of ``subaxes''. Those subaxes
492 have to provide some range information needed to identify the subaxis
493 to be used out of a plain number (thus all axes minima and maxima has
494 to be set except for the two subaxes at the egde, where for the first
495 only the maximum is needed, while for the last only the minimum is
496 needed). The only point left is the description of the specialized
497 \verb|splitaxispainter|, where the constructor takes the following
501 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
502 argument name&description\\
504 \texttt{breaklinesdist
}&(visual) distance between the break lines; default:
\texttt{0.05}\\
505 \texttt{breaklineslength
}&(visual) length of break lines; default:
\texttt{0.5}\\
506 \texttt{breaklinesangle
}&angle of the breakline with respect to the axis; default:
\texttt{-
60}\\
507 \texttt{breaklinesattrs
}&stroke attributes for the break lines (
\texttt{None
} to turn off the break lines, otherwise a single value or a tuple); default:
\texttt{()
}\\
510 Additionally, the painter takes parameters for the axis title
511 formatting like the standard axis painter class
\verb|axispainter|.
512 (There is a common base class
\verb|titleaxispainter| for that.) The
513 parameters are
\verb|titledist|,
\verb|titleattrs|,
514 \verb|titledirection|, and
\verb|titlepos|.
516 \subsubsection{Bar axes
}
518 Axes appropriate for bar graphs are created by instances of the class
519 \verb|baraxis|. Its constructor takes the following parameters:
522 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
523 argument name&description\\
525 \texttt{subaxis
}&baraxis can be recursive by having another axis as its subaxis; default:
\texttt{None
}\\
526 \texttt{multisubaxis
}&contains another baraxis instance to be used to construct a new subaxes for each item (by that a nested bar axis with a different number of subbars at each bar can be created) ; default:
\texttt{None
}\\
527 \texttt{title
}&axis title\\
528 \texttt{dist
}&distance between bars (relative to the bar width); default:
\texttt{0.5}\\
529 \texttt{firstdist
}&distance of the first bar to the border; default:
\texttt{0.5*dist
}\\
530 \texttt{lastdist
}&as before but for the last bar\\
531 \texttt{names
}&tuple of name identifiers for bars; when set, no other identifiers are allowed; default:
\texttt{None
}\\
532 \texttt{texts
}&dictionary translating names into label texts (otherwise just the names are used); default:
\texttt{\
{\
}}\\
533 \texttt{painter
}&axis painter; default:
\texttt{baraxispainter
} (described below)\\
537 In contrast to other axes, a bar axis uses name identifiers to
538 calculate a position at the axis. Usually, a style appropriate to a
539 bar axis (this is right now just the bar style) set those names out of
540 the data it recieves. However, the names can be forced and fixed.
542 Bar axes can be recursive. Thus for a given value, an appropriate
543 subaxis is choosen (usually another bar axis). Usually only a single
544 subaxis is needed, because it doesn't need to be painted and for each
545 value the same recursive subaxis transformation has to be applied.
546 This is achieved by using the parameter
\verb|subaxis|. Alternatively
547 you may use the
\verb|multisubaxis|. Here only a bar axis can be used.
548 Then the subaxes (note axes instead of axis) are painted as well
549 (however their painter can be set to not paint anything). For that,
550 duplications of the subaxis are created for each name. By that, each
551 subaxis can have different names, in particular different number of
554 The only point left is the description of the specialized
555 \verb|baraxispainter|. It works quite similar to the
556 \verb|axispainter|. Thus the constructors have quite some parameters
557 in common, namely
\verb|titledist|,
\verb|titleattrs|,
558 \verb|titledirection|,
\verb|titlepos|, and
\verb|baselineattrs|.
559 Furthermore the parameters
\verb|innerticklength| and
560 \verb|outerticklength| work like their counterparts in the
561 \verb|axispainter|, but only plain values are allowed there (no
562 lists). However, they are both
\verb|None| by default and no ticks
563 get plotted. Then there is a hole bunch of name
564 attribute identifiers, namely
\verb|namedist|,
\verb|nameattrs|,
565 \verb|namedirection|,
\verb|namehequalize|,
\verb|namevequalize| which
566 are identical to their counterparts called
\verb|label...| instead of
567 \verb|name...|. Last but not least, there is a parameter
\verb|namepos|
568 which is analogous to
\verb|titlepos| and set to
\verb|
0.5| by
574 \subsection{List of points
}
576 Instances of the class
\verb|data| link together a
\verb|datafile| (or
577 another instance of a class from the module
\verb|data|) and a
578 \verb|style| (see below; default is
\verb|symbol|). The link object is
579 needed in order to be able to plot several data from a singe file
580 without reading the file several times. However, for easy usage, it is
581 possible to provide just a filename instead of a
\verb|datafile|
582 instance as the first argument to the constructor of the class
583 \verb|data| thus hiding the underlying
\verb|datafile| instance
584 completely from view. This is the preferable solution as long as the
585 datafile gets used only once.
587 The additional parameters of the constructor of the class
\verb|data|
588 are named parameters. The values of those parameters describe data
589 columns which are linked to the names of the parameters within the
590 style. The data columns can be identified directly via their number or
591 title, or by means of mathematical expression (as in the addcolumn
592 method of the class
\verb|data| in the module
\verb|data|; see
593 chapter~
\ref{module:data
}; indeed a addcolumn call takes place to
594 evaluate mathematical expressions once and for all).
596 The constructors keyword argument
\verb|title| however does not
597 refer to a parameter of a style, but instead sets the title to be used
600 \subsection{Functions
}
602 The class
\verb|function| provides data generation out of a functional
603 expression. The default style for function plotting is
\verb|line|.
604 The constructor of
\verb|function| takes an expression as the first
605 parameter. The expression must be a string with exactly one equal sign
606 (
\verb|=|). At the left side the result axis identifier must be placed
607 and at the right side the expression must depend on exactly one
608 variable axis identifier. Hence, a valid expression looks like
609 \verb|"y=sin(x)"|. You can access own variables and functions by
610 providing them as a dictionary to the constructors
\verb|context|
613 Additional named parameters of the constructor are:
616 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
617 argument name&default&description\\
619 \texttt{min
}&
\texttt{None
}&minimal value for the variable parameter; when
\texttt{None
}, the axis data range will be used\\
620 \texttt{max
}&
\texttt{None
}&as above, but for the maximum\\
621 \texttt{points
}&
\texttt{100}&number of points to be calculated\\
622 \texttt{parser
}&
\texttt{mathtree.parser()
}&parser for the mathematical expression\\
623 \texttt{context
}&
\texttt{None
}&dictionary of extern variables and functions\\
624 \texttt{title
}&equal to the expression&title to be used in the graph key\\
628 The expression evaluation takes place at a linear raster on the
629 variable axis. More advanced methods (detection of rapidely changing
630 functions, handling of divergencies) are likely to be added in future
633 \subsection{Parametric functions
}
635 The class
\verb|paramfunction| provides data generation out of a
636 parametric representation of a function. The default style for
637 parametric function plotting is
\verb|line|. The parameter list of the
638 constructor of
\verb|paramfunction| starts with three parameters
639 describing the function parameter. The first parameter is a string,
640 namely the variable name. It is followed by a minimal and maximal
641 value to be used for that parameter. The next parameter contains an
642 expression assigning functions to the axis identifiers in a quite
643 pythonic tuple notation. As an example, such an expression could look
644 like
\verb|"x, y = sin(k), cos(
3*k)"|.
646 Additionally, the named parameters
\verb|points|,
\verb|parser|,
647 \verb|context|, and
\verb|title| behave like their equally named
648 counterparts in
\verb|function|.
653 Styles are used to draw data at a graph. A style determines what is
654 painted and how it is painted. Due to this powerfull approach there
655 are already some different styles available and the possibility to
656 introduce other styles opens even more prospects.
660 The class
\verb|symbol| can be used to plot symbols, errorbars and lines
661 configurable by parameters of the constructor. Providing
\verb|None|
662 to attributes hides the according component.
665 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
666 argument name&default&description\\
668 \texttt{symbol
}&
\texttt{changesymbol.cross()
}&symbol to be used (see below)\\
669 \texttt{size
}&
\texttt{"
0.2 cm"
}&size of the symbol (visual length)\\
670 \texttt{symbolattrs
}&
\texttt{canvas.stroked()
}&draw attributes for the symbol\\
671 \texttt{errorscale
}&
\texttt{0.5}&size of the errorbar caps (relative to the symbol size)\\
672 \texttt{errorbarattrs
}&
\texttt{()
}&stroke attributes for the errorbars\\
673 \texttt{lineattrs
}&
\texttt{None
}&stroke attributes for the line\\
677 The parameter
\verb|symbol| has to be a routine, which returns a path to
678 be drawn (e.g. stroked or filled). There are several such routines
679 already available in the class
\verb|symbol|, namely
\verb|cross|,
680 \verb|plus|,
\verb|square|,
\verb|triangle|,
\verb|circle|, and
681 \verb|diamond|. Furthermore, changeable attributes might be used here
682 (like the default value
\verb|changesymbol.cross|), see
683 section~
\ref{graph:changeattrs
} for details.
685 The attributes are available as class variables after plotting the
686 style for outside usage. Additionally, the variable
\verb|path|
687 contains the path of the line (even when it wasn't plotted), which
688 might be used to get crossing points, fill areas, etc.
690 Valid data names to be used when providing data to symbols are listed
691 in the following table. The character
\verb|X| stands for axis names
692 like
\verb|x|,
\verb|x2|,
\verb|y|, etc.
696 data name&description\\
698 \texttt{X
}&position of the symbol\\
699 \texttt{Xmin
}&minimum for the errorbar\\
700 \texttt{Xmax
}&maximum for the errorbar\\
701 \texttt{dX
}&relative size of the errorbar:
\texttt{Xmin, Xmax = X-dX, X+Xd
}\\
702 \texttt{dXmin
}&relative minimum
\texttt{Xmin = X-dXmin
}\\
703 \texttt{dXmax
}&relative maximum
\texttt{Xmax = X+dXmax
}\\
709 The class
\verb|line| is inherited from the class
\verb|symbol| and
710 restricted itself to line drawing. The constructor takes only the
711 \verb|lineattrs| keyword argment, which is by default set to
712 \verb|(changelinestyle(), canvas.linejoin.round)|. The other features
713 of the symbol style are turned off.
715 \subsection{Rectangles
}
717 The class
\verb|rect| draws filled rectangles into a graph. The size
718 and the position of the rectangles to be plotted can be provided by
719 the same data names like for the errorbars of the class
\verb|symbol|.
720 Indeed, the class
\verb|symbol| reuses most of the symbol code by
721 inheritance, while modifying the errorbar look into a colored filled
722 rectangle and turing off the symbol itself.
724 The
color to be used for the filling of the rectangles is taken from a
725 palette provided to the constructor by the named parameter
726 \verb|palette| (default is
\verb|
color.palette.Gray|). The data
727 name
\verb|
color| is used to select the
color out of this palette.
731 Another style to be used within graphs is the class
\verb|text|, which
732 adds the output of text to the class
\verb|symbol|. The text
733 position relative to the symbol is defined by the two named
734 parameters
\verb|textdx| and
\verb|textdy| having a default of
735 \verb|"
0 cm"| and
\verb|"
0.3 cm"|, respectively, which are by default
736 interpreted as visual length. A further named parameter
737 \verb|textattrs| may contain a list of text attributes (or just a
738 single attribute). The default for this parameter is
739 \verb|text.halign.center|. Furthermore the constructor of this class
740 allows all other attributes of the class
\verb|symbol|.
744 The class
\verb|arrow| can be used to plot small arrows into a graph
745 where the size and direction of the arrows has to be given within the
746 data. The constructor of the class takes the following parameters:
749 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
750 argument name&default&description\\
752 \texttt{linelength
}&
\texttt{"
0.2 cm"
}&length of a the arrow line (visual length)\\
753 \texttt{arrowattrs
}&
\texttt{()
}&stroke attributes\\
754 \texttt{arrowsize
}&
\texttt{"
0.1 cm"
}&size of the arrow (visual length)\\
755 \texttt{arrowdict
}&
\texttt{\
{\
}}&attributes to be used in the
\texttt{earrow
} constructor\\
756 \texttt{epsilon
}&
1e-10&smallest allowed arrow size factor for a arrow to become plotted (avoid numerical instabilities)\\
760 The arrow allows for data names like the symbol and introduces
761 additionally the data names
\verb|size| for the arrow size (as an
762 multiplicator for the sizes provided to the constructor) and
763 \verb|angle| for the arrow direction (in degree).
767 The class
\verb|bar| must be used in combination with an
768 \verb|baraxis| in order to create bar plots. The constructor takes the
769 following parameters:
772 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
773 argument name&description\\
775 \texttt{fromzero
}&bars start at zero (boolean); default:
\texttt{1}\\
776 \texttt{stacked
}&stack bars (boolean/integer); for values bigger than
1 it is the number of bars to be stacked; default:
\texttt{0}\\
777 \texttt{skipmissing
}&skip entries in the bar axis, when datapoints are missing; default:
\texttt{1}\\
778 \texttt{xbar
}&bars parallel to the graphs x-direction (boolean); default:
\texttt{0}\\
779 \texttt{barattrs
}&fill attributes; default:
\texttt{(canvas.stroked(
color.gray.black), changecolor.Rainbow())
}\\
782 Additionally, the bar style takes two data names appropriate to the
783 graph (like
\verb|x|,
\verb|x2|, and
\verb|y|).
785 \subsection{Iterateable style attributes
}
786 \label{graph:changeattrs
}
788 The attributes provided to the constructors of styles can usually
789 handle so called iterateable attributes, which are changing itself
790 when plotting several data sets. Iterateable attributes can be easily
791 written, but there are already some iterateable attributes available
792 for the most common cases. For example a
color change is done by
793 instances of the class
\verb|colorchange|, where the constructor takes
794 a palette. Applying this attribute to a style and using this style at
795 a list of data, the
color will get changed lineary along the
796 palette from one end to the other. The class
\verb|colorchange|
797 includes inherited classes as class variables, which are called like
798 the
color palettes shown in appendix~
\ref{palettename
}. For them the
799 default palette is set to the appropriate
color palette.
801 Another attribute changer is called
\verb|changesequence|. The
802 constructor takes a list of attributes and the attribute changer
803 cycles through this list whenever a new attribute is requested.
804 This attribute changer is used to implement the following attribute
809 attribute changer&description\\
811 \texttt{changelinestyle
}&iterates linestyles solid, dashed, dotted, dashdotted\\
812 \texttt{changestrokedfilled
}&iterates
\texttt{(canvas.stroked(), canvas.filled())
}\\
813 \texttt{changefilledstroked
}&iterates
\texttt{(canvas.filled(), canvas.stroked())
}\\
817 The class
\verb|changesymbol| can be used to cycle throu symbols and it
818 provides already various specialized classes as class variables. To
819 loop over all available symbols (cross, plus, square, triangle,
820 circle, and diamond) the equal named class variables can be used. They
821 start at that symbol they are named of. Thus
\verb|changesymbol.cross()|
822 cycles throu the list starting at the cross symbol. Furthermore
823 there are four class variables called
\verb|squaretwice|,
824 \verb|triangletwice|,
\verb|circletwice|, and
\verb|diamondtwice|.
825 They cycle throu the four fillable symbols, but returning the symbols
826 twice before they go on to the next one. They are intented to be used
827 in combination with
\verb|changestrokedfilled| and
828 \verb|changefilledstroked|.
832 Graph keys can be created by instances of the class
\verb|key|. Its
833 constructor takes the following keyword arguments:
836 \begin{tabularx
}{\linewidth}{l>
{\raggedright\arraybackslash}X
}
837 argument name&description\\
839 \texttt{dist
}&(vertical) distance between the key entries (visual length); default:
\texttt{"
0.2 cm"
}\\
840 \texttt{pos
}&
\texttt{"tr"
} (top right; default),
\texttt{"br"
} (bottom right),
\texttt{"tl"
} (top left),
\texttt{"bl"
} (bottom left)\\
841 \texttt{hdist
}&horizontal distance of the key (visual length); default:
\texttt{"
0.6 cm"
}\\
842 \texttt{vdist
}&vertical distance of the key (visual length); default:
\texttt{"
0.4 cm"
}\\
843 \texttt{hinside
}&align horizonally inside to the graph (boolean); default:
\texttt{1}\\
844 \texttt{vinside
}&align vertically inside to the graph (boolean); default:
\texttt{1}\\
845 \texttt{symbolwidth
}&width reserved for the symbol (visual length); default:
\texttt{"
0.5 cm"
}\\
846 \texttt{symbolheight
}&height reserved for the symbol (visual length); default:
\texttt{"
0.25 cm"
}\\
847 \texttt{symbolspace
}&distance between symbol and text (visual length); default:
\texttt{"
0.2 cm"
}\\
848 \texttt{textattrs
}&text attributes (a list or a single entry); default:
\texttt{text.vshift.mathaxis
}\\
852 The data description to be printed in the graph key is given by the
853 title of the data drawn.
857 The class
\verb|graphxy| draws standard x-y-graphs. It is a subcanvas
858 and can thus be just inserted into a canvas. The x-axes are named
859 \verb|x|,
\verb|x2|,
\verb|x3|,
\dots and equally the y-axes. The
860 number of axes is not limited. All odd numbered axes are plotted at
861 the bottom (for x axes) and at the left (for y axes) and all even
862 numbered axes are plotted opposite to them. The lower numbers are
865 The constructor of
\verb|graphxy| takes axes as named parameters where
866 the parameter name is an axis name as just described. Those parameters
867 refer to an axis instance as they where described in
868 section~
\ref{graph:axes
}. When no
\verb|x| or
\verb|y| is provided,
869 they are automatically set to instances of
\verb|linaxis|. When no
870 \verb|x2| or
\verb|y2| axes are given they are initialized as standard
871 linkaxis to the axis
\verb|x| and
\verb|y|. However, you can turn off
872 the automatism by setting those axes explicitly to
\verb|None|.
874 However, the constructor takes some more attributes listed in the
878 \begin{tabularx
}{\linewidth}{ll>
{\raggedright\arraybackslash}X
}
879 argument name&default&description\\
881 \texttt{xpos
}&
\texttt{"
0"
}&x position of the graph (user length)\\
882 \texttt{ypos
}&
\texttt{"
0"
}&y position of the graph (user length)\\
883 \texttt{width
}&
\texttt{None
}&width of the graph area (axes are outside of that range)\\
884 \texttt{height
}&
\texttt{None
}&as abovem, but for the height\\
885 \texttt{ratio
}&
\texttt{goldenrule
}&width/height ratio when only a width or height is provided\\
886 \texttt{backgroundattrs
}&
\texttt{None
}&background attributes for the graph area\\
887 \texttt{axisdist
}&
\texttt{"
0.8 cm"
}&distance between axis (visual length)\\
888 \texttt{key
}&
\texttt{None
}&
\texttt{key
} instance for an automatic graph key\\
892 After a graph is constructed, data can be plotted via the
\verb|plot|
893 method. The first argument should be an instance of the data providing
894 classes described in section~
\ref{graph:data
}. This first parameter
895 can also be a list of those instances when you want to iterate the
896 style you explicitly provide as a second parameter to the plot method.
897 The plot method returns the plotinfo instance (or a list of plotinfo
898 instances when a data list was provided). The plotinfo class has
899 attributes
\verb|data| and
\verb|style|, which provide access to the
900 plotted data and the style, respectively. Just as an example, from the
901 style you can access the path of the drawed line, fill areas with it
904 After the plot method was called once or several times, you may
905 explicitly call the method
\verb|finish|. Most of the graphs
906 functionallity becomes available just after (partially) finishing the
907 graph. A partial finish can even modify the order in which a graph
908 performs its drawing process. By default the five methods
909 \verb|dolayout|,
\verb|dobackground|,
\verb|doaxis|,
\verb|dodata|,
910 and
\verb|dokey| are called in that order. The method
\verb|dolayout|
911 must always be called first, but this is internally ensured once you
912 call any of the routines yourself. After
\verb|dolayout| gets called,
913 the method
\verb|plot| can not be used anymore.
915 To get a position within a graph as a tuple out of some axes values,
916 the method
\verb|pos| can be used. It takes two values for a position
917 at the x and y axis. By default, the axes named
\verb|x| or
\verb|y|
918 are used, but this is changed when the keyword arguments
\verb|xaxis|
919 and
\verb|yaxis| are set to other axes. The graph axes are available
920 by their name using the dictionary
\verb|axes|. Each axis has a method
921 \verb|gridpath| which is set by the graph. It returns a path of a grid
922 line for a given position at the axis.
924 To manually add a graph key, use the
\verb|addkey| method, which takes
925 a
\verb|key| instance first followed by several
\verb|plotinfo|