implement ligatures and kerning
[PyX.git] / manual / graph.tex
blob300c620649ccd1884118f13585ed4edae665ac1e
1 \chapter{Graphs}
2 \label{graph}
4 \section{Introduction} % {{{
5 \PyX{} can be used for data and function plotting. At present
6 x-y-graphs and x-y-z-graphs are supported only. However, the component
7 architecture of the graph system described in section
8 \ref{graph:components} allows for additional graph geometries while
9 reusing most of the existing components.
11 Creating a graph splits into two basic steps. First you have to create
12 a graph instance. The most simple form would look like:
13 \begin{verbatim}
14 from pyx import *
15 g = graph.graphxy(width=8)
16 \end{verbatim}
17 The graph instance \code{g} created in this example can then be used
18 to actually plot something into the graph. Suppose you have some data
19 in a file \file{graph.dat} you want to plot. The content of the file
20 could look like:
21 \verbatiminput{graph.dat}
22 To plot these data into the graph \code{g} you must perform:
23 \begin{verbatim}
24 g.plot(graph.data.file("graph.dat", x=1, y=2))
25 \end{verbatim}
26 The method \method{plot()} takes the data to be plotted and optionally
27 a list of graph styles to be used to plot the data. When no styles are
28 provided, a default style defined by the data instance is used. For
29 data read from a file by an instance of \class{graph.data.file}, the
30 default are symbols. When instantiating \class{graph.data.file}, you
31 not only specify the file name, but also a mapping from columns to
32 axis names and other information the styles might make use of
33 (\emph{e.g.} data for error bars to be used by the errorbar style).
35 While the graph is already created by that, we still need to perform a
36 write of the result into a file. Since the graph instance is a canvas,
37 we can just call its \method{writeEPSfile()} method.
38 \begin{verbatim}
39 g.writeEPSfile("graph")
40 \end{verbatim}
41 The result \file{graph.eps} is shown in figure~\ref{fig:graph}.
43 \begin{figure}[ht]
44 \centerline{\includegraphics{graph}}
45 \caption[A minimalistic plot for the data from a file.]{A minimalistic plot for the data from file \file{graph.dat}.}
46 \label{fig:graph}
47 \end{figure}
49 Instead of plotting data from a file, other data source are available
50 as well. For example function data is created and placed into
51 \method{plot()} by the following line:
52 \begin{verbatim}
53 g.plot(graph.data.function("y(x)=x**2"))
54 \end{verbatim}
55 You can plot different data in a single graph by calling
56 \method{plot()} several times before \method{writeEPSfile()} or
57 \method{writePDFfile()}. Note that a calling \method{plot()} will fail
58 once a graph was forced to ``finish'' itself. This happens
59 automatically, when the graph is written to a file. Thus it is not an
60 option to call \method{plot()} after \method{writeEPSfile()} or
61 \method{writePDFfile()}. The topic of the finalization of a graph is
62 addressed in more detail in section~\ref{graph:graph}. As you can see
63 in figure~\ref{fig:graph2}, a function is plotted as a line by
64 default.
66 \begin{figure}[ht]
67 \centerline{\includegraphics{graph2}}
68 \caption{Plotting data from a file together with a function.}
69 \label{fig:graph2}
70 \end{figure}
72 While the axes ranges got adjusted automatically in the previous
73 example, they might be fixed by keyword options in axes constructors.
74 Plotting only a function will need such a setting at least in the
75 variable coordinate. The following code also shows how to set a
76 logathmic axis in y-direction:
78 \verbatiminput{graph3.py}
80 The result is shown in figure~\ref{fig:graph3}.
82 \begin{figure}[ht]
83 \centerline{\includegraphics{graph3}}
84 \caption{Plotting a function for a given axis range and use a
85 logarithmic y-axis.}
86 \label{fig:graph3}
87 \end{figure} % }}}
89 \section{Component architecture} % {{{
90 \label{graph:components}
92 Creating a graph involves a variety of tasks, which thus can be
93 separated into components without significant additional costs.
94 This structure manifests itself also in the \PyX{} source, where there
95 are different modules for the different tasks. They interact by some
96 well-defined interfaces. They certainly have to be completed and
97 stabilized in their details, but the basic structure came up in the
98 continuous development quite clearly. The basic parts of a graph are:
100 \begin{definitions}
101 \term{graph}
102 Defines the geometry of the graph by means of graph coordinates with
103 range [0:1]. Keeps lists of plotted data, axes \emph{etc.}
104 \term{data}
105 Produces or prepares data to be plotted in graphs.
106 \term{style}
107 Performs the plotting of the data into the graph. It gets data,
108 converts them via the axes into graph coordinates and uses the graph
109 to finally plot the data with respect to the graph geometry methods.
110 \term{key}
111 Responsible for the graph keys.
112 \term{axis}
113 Creates axes for the graph, which take care of the mapping from data
114 values to graph coordinates. Because axes are also responsible for
115 creating ticks and labels, showing up in the graph themselves and
116 other things, this task is splitted into several independent
117 subtasks. Axes are discussed separately in chapter~\ref{axis}.
118 \end{definitions} % }}}
120 \section{Module \module{graph.graph}: Graphs} % {{{
121 \label{graph:graph}
123 \declaremodule{}{graph.graph}
124 \modulesynopsis{Graph geometry}
126 The classes \class{graphxy} and \class{graphxyz} are part of the
127 module \module{graph.graph}. However, there are shortcuts to access
128 the classes via \code{graph.graphxy} and \code{graph.graphxyz},
129 respectively.
131 \begin{classdesc}{graphxy}{xpos=0, ypos=0, width=None, height=None,
132 ratio=goldenmean, key=None, backgroundattrs=None,
133 axesdist=0.8*unit.v\_cm, xaxisat=None, yaxisat=None, **axes}
134 This class provides an x-y-graph. A graph instance is also a fully
135 functional canvas.
137 The position of the graph on its own canvas is specified by
138 \var{xpos} and \var{ypos}. The size of the graph is specified by
139 \var{width}, \var{height}, and \var{ratio}. These parameters define
140 the size of the graph area not taking into account the additional
141 space needed for the axes. Note that you have to specify at least
142 \var{width} or \var{height}. \var{ratio} will be used as the ratio
143 between \var{width} and \var{height} when only one of these is
144 provided.
146 \var{key} can be set to a \class{graph.key.key} instance to create
147 an automatic graph key. \code{None} omits the graph key.
149 \var{backgroundattrs} is a list of attributes for drawing the
150 background of the graph. Allowed are decorators, strokestyles, and
151 fillstyles. \code{None} disables background drawing.
153 \var{axisdist} is the distance between axes drawn at the same side
154 of a graph.
156 \var{xaxisat} and \var{yaxisat} specify a value at the y and x axis,
157 where the corresponding axis should be moved to. It's a shortcut for
158 corresonding calls of \method{axisatv()} described below. Moving an
159 axis by \var{xaxisat} or \var{yaxisat} disables the automatic
160 creation of a linked axis at the opposite side of the graph.
162 \var{**axes} receives axes instances. Allowed keywords (axes names)
163 are \code{x}, \code{x2}, \code{x3}, \emph{etc.} and \code{y},
164 \code{y2}, \code{y3}, \emph{etc.} When not providing an \code{x} or
165 \code{y} axis, linear axes instances will be used automatically.
166 When not providing a \code{x2} or \code{y2} axis, linked axes to the
167 \code{x} and \code{y} axes are created automatically and \emph{vice
168 versa}. As an exception, a linked axis is not created automatically
169 when the axis is placed at a specific position by \var{xaxisat} or
170 \var{yaxisat}. You can disable the automatic creation of axes by
171 setting the linked axes to \code{None}. The even numbered axes are
172 plotted at the top (\code{x} axes) and right (\code{y} axes) while
173 the others are plotted at the bottom (\code{x} axes) and left
174 (\code{y} axes) in ascending order each.
175 \end{classdesc}
177 Some instance attributes might be useful for outside read-access.
178 Those are:
180 \begin{memberdesc}{axes}
181 A dictionary mapping axes names to the \class{anchoredaxis} instances.
182 \end{memberdesc}
184 To actually plot something into the graph, the following instance
185 method \method{plot()} is provided:
187 \begin{methoddesc}{plot}{data, styles=None}
188 Adds \var{data} to the list of data to be plotted. Sets \var{styles}
189 to be used for plotting the data. When \var{styles} is \code{None},
190 the default styles for the data as provided by \var{data} is used.
192 \var{data} should be an instance of any of the data described in
193 section~\ref{graph:data}.
195 When the same combination of styles (\emph{i.e.} the same
196 references) are used several times within the same graph instance,
197 the styles are kindly asked by the graph to iterate their
198 appearance. Its up to the styles how this is performed.
200 Instead of calling the plot method several times with different
201 \var{data} but the same style, you can use a list (or something
202 iterateable) for \var{data}.
203 \end{methoddesc}
205 While a graph instance only collects data initially, at a certain
206 point it must create the whole plot. Once this is done, further calls
207 of \method{plot()} will fail. Usually you do not need to take care
208 about the finalization of the graph, because it happens automatically
209 once you write the plot into a file. However, sometimes position
210 methods (described below) are nice to be accessible. For that, at
211 least the layout of the graph must have been finished. By calling the
212 \method{do}-methods yourself you can also alter the order in which the
213 graph components are plotted. Multiple calls to any of the
214 \method{do}-methods have no effect (only the first call counts). The
215 orginal order in which the \method{do}-methods are called is:
217 \begin{methoddesc}{dolayout}{}
218 Fixes the layout of the graph. As part of this work, the ranges of
219 the axes are fitted to the data when the axes ranges are allowed to
220 adjust themselves to the data ranges. The other \method{do}-methods
221 ensure, that this method is always called first.
222 \end{methoddesc}
224 \begin{methoddesc}{dobackground}{}
225 Draws the background.
226 \end{methoddesc}
228 \begin{methoddesc}{doaxes}{}
229 Inserts the axes.
230 \end{methoddesc}
232 \begin{methoddesc}{doplot}{plotitem}
233 Plots the plotitem as returned by the graphs plot method.
234 \end{methoddesc}
236 \begin{methoddesc}{dodata}{}
237 Plots the data.
238 \end{methoddesc}
240 \begin{methoddesc}{dokey}{}
241 Inserts the graph key.
242 \end{methoddesc}
244 \begin{methoddesc}{finish}{}
245 Finishes the graph by calling all pending \method{do}-methods. This
246 is done automatically, when the output is created.
247 \end{methoddesc}
249 The graph provides some methods to access its geometry:
251 \begin{methoddesc}{pos}{x, y, xaxis=None, yaxis=None}
252 Returns the given point at \var{x} and \var{y} as a tuple
253 \code{(xpos, ypos)} at the graph canvas. \var{x} and \var{y} are
254 anchoredaxis instances for the two axes \var{xaxis} and \var{yaxis}.
255 When \var{xaxis} or \var{yaxis} are \code{None}, the axes with names
256 \code{x} and \code{y} are used. This method fails if called before
257 \method{dolayout()}.
258 \end{methoddesc}
260 \begin{methoddesc}{vpos}{vx, vy}
261 Returns the given point at \var{vx} and \var{vy} as a tuple
262 \code{(xpos, ypos)} at the graph canvas. \var{vx} and \var{vy} are
263 graph coordinates with range [0:1].
264 \end{methoddesc}
266 \begin{methoddesc}{vgeodesic}{vx1, vy1, vx2, vy2}
267 Returns the geodesic between points \var{vx1}, \var{vy1} and
268 \var{vx2}, \var{vy2} as a path. All parameters are in graph
269 coordinates with range [0:1]. For \class{graphxy} this is a straight
270 line.
271 \end{methoddesc}
273 \begin{methoddesc}{vgeodesic\_el}{vx1, vy1, vx2, vy2}
274 Like \method{vgeodesic()} but this method returns the path element to
275 connect the two points.
276 \end{methoddesc}
278 % dirty hack to add a whole list of methods to the index:
279 \index{xbasepath()@\texttt{xbasepath()} (graphxy method)}
280 \index{xvbasepath()@\texttt{xvbasepath()} (graphxy method)}
281 \index{xgridpath()@\texttt{xgridpath()} (graphxy method)}
282 \index{xvgridpath()@\texttt{xvgridpath()} (graphxy method)}
283 \index{xtickpoint()@\texttt{xtickpoint()} (graphxy method)}
284 \index{xvtickpoint()@\texttt{xvtickpoint()} (graphxy method)}
285 \index{xtickdirection()@\texttt{xtickdirection()} (graphxy method)}
286 \index{xvtickdirection()@\texttt{xvtickdirection()} (graphxy method)}
287 \index{ybasepath()@\texttt{ybasepath()} (graphxy method)}
288 \index{yvbasepath()@\texttt{yvbasepath()} (graphxy method)}
289 \index{ygridpath()@\texttt{ygridpath()} (graphxy method)}
290 \index{yvgridpath()@\texttt{yvgridpath()} (graphxy method)}
291 \index{ytickpoint()@\texttt{ytickpoint()} (graphxy method)}
292 \index{yvtickpoint()@\texttt{yvtickpoint()} (graphxy method)}
293 \index{ytickdirection()@\texttt{ytickdirection()} (graphxy method)}
294 \index{yvtickdirection()@\texttt{yvtickdirection()} (graphxy method)}
296 Further geometry information is available by the \member{axes}
297 instance variable, with is a dictionary mapping axis names to
298 \class{anchoredaxis} instances. Shortcuts to the anchoredaxis
299 positioner methods for the \code{x}- and \code{y}-axis become
300 available after \method{dolayout()} as \class{graphxy} methods
301 \code{Xbasepath}, \code{Xvbasepath}, \code{Xgridpath},
302 \code{Xvgridpath}, \code{Xtickpoint}, \code{Xvtickpoint},
303 \code{Xtickdirection}, and \code{Xvtickdirection} where the prefix
304 \code{X} stands for \code{x} and \code{y}.
306 \begin{methoddesc}{axistrafo}{axis, t}
307 This method can be used to apply a transformation \var{t} to an
308 \class{anchoredaxis} instance \var{axis} to modify the axis position
309 and the like. This method fails when called on a not yet finished
310 axis, i.e. it should be used after \method{dolayout()}.
311 \end{methoddesc}
313 \begin{methoddesc}{axisatv}{axis, v}
314 This method calls \method{axistrafo()} with a transformation to move
315 the axis \var{axis} to a graph position \var{v} (in graph
316 coordinates).
317 \end{methoddesc}
319 The class \class{graphxyz} is very similar to the \class{graphxy}
320 class, except for its additional dimension. In the following
321 documentation only the differences to the \class{graphxy} class are
322 described.
324 \begin{classdesc}{graphxyz}{xpos=0, ypos=0, size=None,
325 xscale=1, yscale=1, zscale=1/goldenmean,
326 projector=central(10, -30, 30), key=None,
327 **axes}
328 This class provides an x-y-z-graph.
330 The position of the graph on its own canvas is specified by
331 \var{xpos} and \var{ypos}. The size of the graph is specified by
332 \var{size} and the length factors \var{xscale}, \var{yscale}, and
333 \var{zscale}. The final size of the graph depends on the projector
334 \var{projector}, which is called with \code{x}, \code{y}, and
335 \code{z} values up to \var{xscale}, \var{yscale}, and \var{zscale}
336 respectively and scaling the result by \var{size}. For a parallel
337 projector changing \var{size} is thus identical to changing
338 \var{xscale}, \var{yscale}, and \var{zscale} by the same factor. For
339 the central projector the projectors internal distance would also
340 need to be changed by this factor. Thus \var{size} changes the size
341 of the whole graph without changing the projection.
343 \var{projector} defines the conversion of 3d coordinates to 2d
344 coordinates. It can be an instance of \class{central} or
345 \class{parallel} described below.
347 \var{**axes} receives axes instances as for \class{graphxyz}. The
348 graphxyz allows for 4 axes per graph dimension \code{x}, \code{x2},
349 \code{x3}, \code{x4}, \code{y}, \code{y2}, \code{y3}, \code{y4},
350 \code{z}, \code{z2}, \code{z3}, and \code{z4}. The x-y-plane is the
351 horizontal plane at the bottom and the \code{x}, \code{x2},
352 \code{y}, and \code{y2} axes are placed at the boundary of this
353 plane with \code{x} and \code{y} always being in front. \code{x3},
354 \code{x4}, \code{y3}, and \code{y4} are handled similar, but for the
355 top plane of the graph. The \code{z} axis is placed at the origin of
356 the \code{x} and \code{y} dimension, whereas \code{z2} is placed at
357 the final point of the \code{x} dimension, \code{z3} at the final
358 point of the \code{y} dimension and \code{z4} at the final point of
359 the \code{x} and \code{y} dimension together.
360 \end{classdesc}
362 \begin{memberdesc}{central}
363 The central attribute of the graphxyz is the \class{central} class.
364 See the class description below.
365 \end{memberdesc}
367 \begin{memberdesc}{parallel}
368 The parallel attribute of the graphxyz is the \class{parallel} class.
369 See the class description below.
370 \end{memberdesc}
372 Regarding the 3d to 2d transformation the methods \method{pos},
373 \method{vpos}, \method{vgeodesic}, and \method{vgeodesic\_el} are
374 available as for class \class{graphxy} and just take an additional
375 argument for the dimension. Note that a similar transformation method
376 (3d to 2d) is available as part of the projector as well already, but
377 only the graph acknowledges its size, the scaling and the internal
378 tranformation of the graph coordinates to the scaled coordinates. As
379 the projector also implements a \method{zindex} and a \method{angle}
380 method, those are also available at the graph level in the graph
381 coordinate variant (i.e. having an additional v in its name and using
382 values from 0 to 1 per dimension).
384 \begin{methoddesc}{vzindex}{vx, vy, vz}
385 The depths of the point defined by \var{vx}, \var{vy}, and \var{vz}
386 scaled to a range [-1:1] where 1 in closed to the viewer. All
387 arguments passed to the method are in graph coordinates with range
388 [0:1].
389 \end{methoddesc}
391 \begin{methoddesc}{vangle}{vx1, vy1, vz1, vx2, vy2, vz2, vx3, vy3, vz3}
392 The cosine of the angle of the view ray thru point \code{(vx1, vy1,
393 vz1)} and the plane defined by the points \code{(vx1, vy1, vz1)},
394 \code{(vx2, vy2, vz2)}, and \code{(vx3, vy3, vz3)}. All arguments
395 passed to the method are in graph coordinates with range [0:1].
396 \end{methoddesc}
398 There are two projector classes \class{central} and \class{parallel}:
400 \begin{classdesc}{central}{distance, phi, theta, anglefactor=math.pi/180}
401 Instances of this class implement a central projection for the given
402 parameters.
404 \var{distance} is the distance of the viewer from the origin. Note
405 that the \class{graphxyz} class uses the range \code{-xscale} to
406 \code{xscale}, \code{-yscale} to \code{yscale}, and \code{-zscale}
407 to \code{zscale} for the coordinates \code{x}, \code{y}, and
408 \code{z}. As those scales are of the order of one (by default), the
409 distance should be of the order of 10 to give nice results. Smaller
410 distances increase the central projection character while for huge
411 distances the central projection becomes identical to the parallel
412 projection.
414 \code{phi} is the angle of the viewer in the x-y-plane and
415 \code{theta} is the angle of the viewer to the x-y-plane. The
416 standard notation for spheric coordinates are used. The angles are
417 multiplied by \var{anglefactor} which is initialized to do a degree
418 in radiant transformation such that you can specify \code{phi} and
419 \code{theta} in degree while the internal computation is always done
420 in radiants.
421 \end{classdesc}
423 \begin{classdesc}{parallel}{phi, theta, anglefactor=math.pi/180}
424 Instances of this class implement a parallel projection for the
425 given parameters. There is no distance for that transformation
426 (compared to the central projection). All other parameters are
427 identical to the \class{central} class.
428 \end{classdesc} % }}}
430 \section{Module \module{graph.data}: Data} % {{{
431 \label{graph:data}
433 \declaremodule{}{graph.data}
434 \modulesynopsis{Graph data}
436 The following classes provide data for the \method{plot()} method of a
437 graph. The classes are implemented in \module{graph.data}.
439 \begin{classdesc}{file}{filename, % {{{
440 commentpattern=defaultcommentpattern,
441 columnpattern=defaultcolumnpattern,
442 stringpattern=defaultstringpattern,
443 skiphead=0, skiptail=0, every=1, title=notitle,
444 context=\{\}, copy=1,
445 replacedollar=1, columncallback="\_\_column\_\_",
446 **columns}
447 This class reads data from a file and makes them available to the
448 graph system. \var{filename} is the name of the file to be read.
449 The data should be organized in columns.
451 The arguments \var{commentpattern}, \var{columnpattern}, and
452 \var{stringpattern} are responsible for identifying the data in each
453 line of the file. Lines matching \var{commentpattern} are ignored
454 except for the column name search of the last non-empty comment line
455 before the data. By default a line starting with one of the
456 characters \character{\#}, \character{\%}, or \character{!} as well
457 as an empty line is treated as a comment.
459 A non-comment line is analysed by repeatedly matching
460 \var{stringpattern} and, whenever the stringpattern does not match,
461 by \var{columnpattern}. When the \var{stringpattern} matches, the
462 result is taken as the value for the next column without further
463 transformations. When \var{columnpattern} matches, it is tried to
464 convert the result to a float. When this fails the result is taken
465 as a string as well. By default, you can write strings with spaces
466 surrounded by \character{\textquotedbl} immediately surrounded by
467 spaces or begin/end of line in the data file. Otherwise
468 \character{\textquotedbl} is not taken to be special.
470 \var{skiphead} and \var{skiptail} are numbers of data lines to be
471 ignored at the beginning and end of the file while \var{every}
472 selects only every \var{every} line from the data.
474 \var{title} is the title of the data to be used in the graph key. A
475 default title is constructed out of \var{filename} and
476 \var{**columns}. You may set \var{title} to \code{None} to disable
477 the title.
479 Finally, \var{columns} define columns out of the existing columns
480 from the file by a column number or a mathematical expression (see
481 below). When \var{copy} is set the names of the columns in the file
482 (file column names) and the freshly created columns having the names
483 of the dictionary key (data column names) are passed as data to the
484 graph styles. The data columns may hide file columns when names are
485 equal. For unset \var{copy} the file columns are not available to
486 the graph styles.
488 File column names occur when the data file contains a comment line
489 immediately in front of the data (except for empty or empty comment
490 lines). This line will be parsed skipping the matched comment
491 identifier as if the line would be regular data, but it will not be
492 converted to floats even if it would be possible to convert the
493 items. The result is taken as file column names, \emph{i.e.} a
494 string representation for the columns in the file.
496 The values of \var{**columns} can refer to column numbers in the
497 file starting at \code{1}. The column \code{0} is also available
498 and contains the line number starting from \code{1} not counting
499 comment lines, but lines skipped by \var{skiphead}, \var{skiptail},
500 and \var{every}. Furthermore values of \var{**columns} can be
501 strings: file column names or complex mathematical expressions. To
502 refer to columns within mathematical expressions you can also use
503 file column names when they are valid variable identifiers. Equal
504 named items in context will then be hidden. Alternatively columns
505 can be access by the syntax \code{\$\textless number\textgreater}
506 when \var{replacedollar} is set. They will be translated into
507 function calls to \var{columncallback}, which is a function to
508 access column data by index or name.
510 \var{context} allows for accessing external variables and functions
511 when evaluating mathematical expressions for columns. Additionally
512 to the identifiers in \var{context}, the file column names, the
513 \var{columncallback} function and the functions shown in the table
514 ``builtins in math expressions'' at the end of the section are
515 available.
517 Example:
518 \begin{verbatim}
519 graph.data.file("test.dat", a=1, b="B", c="2*B+$3")
520 \end{verbatim}
521 with \file{test.dat} looking like:
522 \begin{verbatim}
523 # A B C
524 1.234 1 2
525 5.678 3 4
526 \end{verbatim}
527 The columns with name \code{"a"}, \code{"b"}, \code{"c"} will become
528 \code{"[1.234, 5.678]"}, \code{"[1.0, 3.0]"}, and \code{"[4.0,
529 10.0]"}, respectively. The columns \code{"A"}, \code{"B"},
530 \code{"C"} will be available as well, since \var{copy} is enabled by
531 default.
533 When creating several data instances accessing the same file,
534 the file is read only once. There is an inherent caching of the
535 file contents.
536 \end{classdesc}
538 For the sake of completeness we list the default patterns:
540 \begin{memberdesc}{defaultcommentpattern}
541 \code{re.compile(r\textquotedbl (\#+|!+|\%+)\e s*\textquotedbl)}
542 \end{memberdesc}
544 \begin{memberdesc}{defaultcolumnpattern}
545 \code{re.compile(r\textquotedbl\e \textquotedbl(.*?)\e \textquotedbl(\e s+|\$)\textquotedbl)}
546 \end{memberdesc}
548 \begin{memberdesc}{defaultstringpattern}
549 \code{re.compile(r\textquotedbl(.*?)(\e s+|\$)\textquotedbl)}
550 \end{memberdesc} % }}}
552 \begin{classdesc}{function}{expression, title=notitle, % {{{
553 min=None, max=None, points=100,
554 context=\{\}}
555 This class creates graph data from a function. \var{expression} is
556 the mathematical expression of the function. It must also contain
557 the result variable name including the variable the function depends
558 on by assignment. A typical example looks like \code{"y(x)=sin(x)"}.
560 \var{title} is the title of the data to be used in the graph key. By
561 default \var{expression} is used. You may set \var{title} to
562 \code{None} to disable the title.
564 \var{min} and \var{max} give the range of the variable. If not set,
565 the range spans the whole axis range. The axis range might be set
566 explicitly or implicitly by ranges of other data. \var{points} is
567 the number of points for which the function is calculated. The
568 points are choosen linearly in terms of graph coordinates.
570 \var{context} allows for accessing external variables and functions.
571 Additionally to the identifiers in \var{context}, the variable name
572 and the functions shown in the table ``builtins in math
573 expressions'' at the end of the section are available.
574 \end{classdesc} % }}}
576 \begin{classdesc}{paramfunction}{varname, min, max, expression, % {{{
577 title=notitle, points=100,
578 context=\{\}}
579 This class creates graph data from a parametric function.
580 \var{varname} is the parameter of the function. \var{min} and
581 \var{max} give the range for that variable. \var{points} is the
582 number of points for which the function is calculated. The points
583 are choosen lineary in terms of the parameter.
585 \var{expression} is the mathematical expression for the parametric
586 function. It contains an assignment of a tuple of functions to a
587 tuple of variables. A typical example looks like
588 \code{"x, y = cos(k), sin(k)"}.
590 \var{title} is the title of the data to be used in the graph key. By
591 default \var{expression} is used. You may set \var{title} to
592 \code{None} to disable the title.
594 \var{context} allows for accessing external variables and functions.
595 Additionally to the identifiers in \var{context}, \var{varname} and
596 the functions shown in the table ``builtins in math expressions'' at
597 the end of the section are available.
598 \end{classdesc} % }}}
600 \begin{classdesc}{values}{title="user provided values", % {{{
601 **columns}
602 This class creates graph data from externally provided data.
603 Each column is a list of values to be used for that column.
605 \var{title} is the title of the data to be used in the graph key.
606 \end{classdesc} % }}}
608 \begin{classdesc}{points}{data, title="user provided points", % {{{
609 addlinenumbers=1, **columns}
610 This class creates graph data from externally provided data.
611 \var{data} is a list of lines, where each line is a list of data
612 values for the columns.
614 \var{title} is the title of the data to be used in the graph key.
616 The keywords of \var{**columns} become the data column names. The
617 values are the column numbers starting from one, when
618 \var{addlinenumbers} is turned on (the zeroth column is added to
619 contain a line number in that case), while the column numbers starts
620 from zero, when \var{addlinenumbers} is switched off.
621 \end{classdesc} % }}}
623 \begin{classdesc}{data}{data, title=notitle, context={}, copy=1, % {{{
624 replacedollar=1, columncallback="\_\_column\_\_", **columns}
625 This class provides graph data out of other graph data. \var{data}
626 is the source of the data. All other parameters work like the equally
627 called parameters in \class{graph.data.file}. Indeed, the latter is
628 built on top of this class by reading the file and caching its
629 contents in a \class{graph.data.list} instance.
630 \end{classdesc} % }}}
632 \begin{classdesc}{conffile}{filename, title=notitle, context={}, copy=1, % {{{
633 replacedollar=1, columncallback="\_\_column\_\_", **columns}
634 This class reads data from a config file with the file name
635 \var{filename}. The format of a config file is described within the
636 documentation of the \module{ConfigParser} module of the Python
637 Standard Library.
639 Each section of the config file becomes a data line. The options in
640 a section are the columns. The name of the options will be used as
641 file column names. All other parameters work as in
642 \var{graph.data.file} and \var{graph.data.data} since they all use
643 the same code.
644 \end{classdesc} % }}}
646 \begin{classdesc}{cbdfile}{filename, minrank=None, maxrank=None, % {{{
647 title=notitle, context={}, copy=1,
648 replacedollar=1, columncallback="\_\_column\_\_", **columns}
649 This is an experimental class to read map data from cbd-files. See
650 \url{http://sepwww.stanford.edu/ftp/World_Map/} for some world-map
651 data.
652 \end{classdesc} % }}}
654 The builtins in math expressions are listed in the following table:
655 \begin{tableii}{l|l}{textrm}{name}{value}
656 \code{neg}&\code{lambda x: -x}\\
657 \code{abs}&\code{lambda x: x < 0 and -x or x}\\
658 \code{sgn}&\code{lambda x: x < 0 and -1 or 1}\\
659 \code{sqrt}&\code{math.sqrt}\\
660 \code{exp}&\code{math.exp}\\
661 \code{log}&\code{math.log}\\
662 \code{sin}&\code{math.sin}\\
663 \code{cos}&\code{math.cos}\\
664 \code{tan}&\code{math.tan}\\
665 \code{asin}&\code{math.asin}\\
666 \code{acos}&\code{math.acos}\\
667 \code{atan}&\code{math.atan}\\
668 \code{sind}&\code{lambda x: math.sin(math.pi/180*x)}\\
669 \code{cosd}&\code{lambda x: math.cos(math.pi/180*x)}\\
670 \code{tand}&\code{lambda x: math.tan(math.pi/180*x)}\\
671 \code{asind}&\code{lambda x: 180/math.pi*math.asin(x)}\\
672 \code{acosd}&\code{lambda x: 180/math.pi*math.acos(x)}\\
673 \code{atand}&\code{lambda x: 180/math.pi*math.atan(x)}\\
674 \code{norm}&\code{lambda x, y: math.hypot(x, y)}\\
675 \code{splitatvalue}&see the \code{splitatvalue} description below\\
676 \code{pi}&\code{math.pi}\\
677 \code{e}&\code{math.e}
678 \end{tableii}
679 \code{math} refers to Pythons \module{math} module. The
680 \code{splitatvalue} function is defined as:
682 \begin{funcdesc}{splitatvalue}{value, *splitpoints}
683 This method returns a tuple \code{(section, \var{value})}.
684 The section is calculated by comparing \var{value} with the values
685 of {splitpoints}. If \var{splitpoints} contains only a single item,
686 \code{section} is \code{0} when value is lower or equal this item
687 and \code{1} else. For multiple splitpoints, \code{section} is
688 \code{0} when its lower or equal the first item, \code{None} when
689 its bigger than the first item but lower or equal the second item,
690 \code{1} when its even bigger the second item, but lower or equal
691 the third item. It continues to alter between \code{None} and
692 \code{2}, \code{3}, etc.
693 \end{funcdesc}
695 % }}}
697 \section{Module \module{graph.style}: Styles} % {{{
698 \label{graph:style}
700 \declaremodule{}{graph.style}
701 \modulesynopsis{Graph style}
703 Please note that we are talking about graph styles here. Those are
704 responsible for plotting symbols, lines, bars and whatever else into a
705 graph. Do not mix it up with path styles like the line width, the line
706 style (solid, dashed, dotted \emph{etc.}) and others.
708 The following classes provide styles to be used at the \method{plot()}
709 method of a graph. The plot method accepts a list of styles. By that
710 you can combine several styles at the very same time.
712 Some of the styles below are hidden styles. Those do not create any
713 output, but they perform internal data handling and thus help on
714 modularization of the styles. Usually, a visible style will depend on
715 data provided by one or more hidden styles but most of the time it is
716 not necessary to specify the hidden styles manually. The hidden styles
717 register themself to be the default for providing certain internal
718 data.
720 \begin{classdesc}{pos}{epsilon=1e-10} % {{{
721 This class is a hidden style providing a position in the graph. It
722 needs a data column for each graph dimension. For that the column
723 names need to be equal to an axis name. Data points are considered
724 to be out of graph when their position in graph coordinates exceeds
725 the range [0:1] by more than \var{epsilon}.
726 \end{classdesc} % }}}
728 \begin{classdesc}{range}{usenames={}, epsilon=1e-10} % {{{
729 This class is a hidden style providing an errorbar range. It needs
730 data column names constructed out of a axis name \code{X} for each
731 dimension errorbar data should be provided as follows:
732 \begin{tableii}{l|l}{}{data name}{description}
733 \lineii{\code{Xmin}}{minimal value}
734 \lineii{\code{Xmax}}{maximal value}
735 \lineii{\code{dX}}{minimal and maximal delta}
736 \lineii{\code{dXmin}}{minimal delta}
737 \lineii{\code{dXmax}}{maximal delta}
738 \end{tableii}
739 When delta data are provided the style will also read column data
740 for the axis name \code{X} itself. \var{usenames} allows to insert a
741 translation dictionary from axis names to the identifiers \code{X}.
743 \var{epsilon} is a comparison precision when checking for invalid
744 errorbar ranges.
745 \end{classdesc} % }}}
747 \begin{classdesc}{symbol}{symbol=changecross, size=0.2*unit.v\_cm, % {{{
748 symbolattrs=[]}
749 This class is a style for plotting symbols in a graph.
750 \var{symbol} refers to a (changeable) symbol function with the
751 prototype \code{symbol(c, x\_pt, y\_pt, size\_pt, attrs)} and draws
752 the symbol into the canvas \code{c} at the position \code{(x\_pt,
753 y\_pt)} with size \code{size\_pt} and attributes \code{attrs}. Some
754 predefined symbols are available in member variables listed below.
755 The symbol is drawn at size \var{size} using \var{symbolattrs}.
756 \var{symbolattrs} is merged with \code{defaultsymbolattrs} which is
757 a list containing the decorator \class{deco.stroked}. An instance of
758 \class{symbol} is the default style for all graph data classes
759 described in section~\ref{graph:data} except for \class{function}
760 and \class{paramfunction}.
761 \end{classdesc}
763 The class \class{symbol} provides some symbol functions as member
764 variables, namely:
766 \begin{memberdesc}{cross}
767 A cross. Should be used for stroking only.
768 \end{memberdesc}
770 \begin{memberdesc}{plus}
771 A plus. Should be used for stroking only.
772 \end{memberdesc}
774 \begin{memberdesc}{square}
775 A square. Might be stroked or filled or both.
776 \end{memberdesc}
778 \begin{memberdesc}{triangle}
779 A triangle. Might be stroked or filled or both.
780 \end{memberdesc}
782 \begin{memberdesc}{circle}
783 A circle. Might be stroked or filled or both.
784 \end{memberdesc}
786 \begin{memberdesc}{diamond}
787 A diamond. Might be stroked or filled or both.
788 \end{memberdesc}
790 \class{symbol} provides some changeable symbol functions as member
791 variables, namely:
793 \begin{memberdesc}{changecross}
794 attr.changelist([cross, plus, square, triangle, circle, diamond])
795 \end{memberdesc}
797 \begin{memberdesc}{changeplus}
798 attr.changelist([plus, square, triangle, circle, diamond, cross])
799 \end{memberdesc}
801 \begin{memberdesc}{changesquare}
802 attr.changelist([square, triangle, circle, diamond, cross, plus])
803 \end{memberdesc}
805 \begin{memberdesc}{changetriangle}
806 attr.changelist([triangle, circle, diamond, cross, plus, square])
807 \end{memberdesc}
809 \begin{memberdesc}{changecircle}
810 attr.changelist([circle, diamond, cross, plus, square, triangle])
811 \end{memberdesc}
813 \begin{memberdesc}{changediamond}
814 attr.changelist([diamond, cross, plus, square, triangle, circle])
815 \end{memberdesc}
817 \begin{memberdesc}{changesquaretwice}
818 attr.changelist([square, square, triangle, triangle, circle, circle, diamond, diamond])
819 \end{memberdesc}
821 \begin{memberdesc}{changetriangletwice}
822 attr.changelist([triangle, triangle, circle, circle, diamond, diamond, square, square])
823 \end{memberdesc}
825 \begin{memberdesc}{changecircletwice}
826 attr.changelist([circle, circle, diamond, diamond, square, square, triangle, triangle])
827 \end{memberdesc}
829 \begin{memberdesc}{changediamondtwice}
830 attr.changelist([diamond, diamond, square, square, triangle, triangle, circle, circle])
831 \end{memberdesc}
833 The class \class{symbol} provides two changeable decorators for
834 alternated filling and stroking. Those are especially useful in
835 combination with the \method{change}-\method{twice}-symbol methods
836 above. They are:
838 \begin{memberdesc}{changestrokedfilled}
839 attr.changelist([deco.stroked, deco.filled])
840 \end{memberdesc}
842 \begin{memberdesc}{changefilledstroked}
843 attr.changelist([deco.filled, deco.stroked])
844 \end{memberdesc} % }}}
846 \begin{classdesc}{line}{lineattrs=[]} % {{{
847 This class is a style to stroke lines in a graph.
848 \var{lineattrs} is merged with \code{defaultlineattrs} which is
849 a list containing the member variable \code{changelinestyle} as
850 described below. An instance of \class{line} is the default style
851 of the graph data classes \class{function} and \class{paramfunction}
852 described in section~\ref{graph:data}.
853 \end{classdesc}
855 The class \class{line} provides a changeable line style. Its
856 definition is:
858 \begin{memberdesc}{changelinestyle}
859 attr.changelist([style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted])
860 \end{memberdesc} % }}}
862 \begin{classdesc}{impulses}{lineattrs=[], fromvalue=0, % {{{
863 frompathattrs=[], valueaxisindex=1}
864 This class is a style to plot impulses. \var{lineattrs} is merged
865 with \code{defaultlineattrs} which is a list containing the member
866 variable \code{changelinestyle} of the \class{line} class.
867 \var{fromvalue} is the baseline value of the impulses. When set to
868 \code{None}, the impulses will start at the baseline. When fromvalue
869 is set, \var{frompathattrs} are the stroke attributes used to show
870 the impulses baseline path.
871 \end{classdesc} % }}}
873 \begin{classdesc}{errorbar}{size=0.1*unit.v\_cm, errorbarattrs=[], % {{{
874 epsilon=1e-10}
875 This class is a style to stroke errorbars in a graph. \var{size} is
876 the size of the caps of the errorbars and \var{errorbarattrs} are
877 the stroke attributes. Errorbars and error caps are considered to be
878 out of the graph when their position in graph coordinates exceeds
879 the range [0:1] by more that \var{epsilon}. Out of graph caps are
880 omitted and the errorbars are cut to the valid graph range.
881 \end{classdesc} % }}}
883 \begin{classdesc}{text}{textname="text", dxname=None, dyname=None, % {{{
884 dxunit=0.3*unit.v\_cm, dyunit=0.3*unit.v\_cm,
885 textdx=0*unit.v\_cm, textdy=0.3*unit.v\_cm,
886 textattrs=[]}
887 This class is a style to stroke text in a graph. The
888 text to be written has to be provided in the data column named
889 \code{textname}. \var{textdx} and \var{textdy} are the position of the
890 text with respect to the position in the graph. Alternatively you can
891 specify a \code{dxname} and a \code{dyname} and provide appropriate
892 data in those columns to be taken in units of \var{dxunit} and
893 \var{dyunit} to specify the position of the text for each point
894 separately. \var{textattrs} are text attributes for the output of
895 the text. Those attributes are merged with the default attributes
896 \code{textmodule.halign.center} and \code{textmodule.vshift.mathaxis}.
897 \end{classdesc} % }}}
899 \begin{classdesc}{arrow}{linelength=0.25*unit.v\_cm, % {{{
900 arrowsize=0.15*unit.v\_cm,
901 lineattrs=[], arrowattrs=[], arrowpos=0.5,
902 epsilon=1e-10}
903 This class is a style to plot short lines with arrows into a
904 two-dimensional graph to a given graph position. The arrow
905 parameters are defined by two additional data columns named
906 \code{size} and \code{angle} define the size and angle for each
907 arrow. \code{size} is taken as a factor to \var{arrowsize} and
908 \var{linelength}, the size of the arrow and the length of the line
909 the arrow is plotted at. \code{angle} is the angle the arrow points
910 to with respect to a horizontal line. The \code{angle} is taken in
911 degrees and used in mathematically positive sense. \var{lineattrs}
912 and \var{arrowattrs} are styles for the arrow line and arrow head,
913 respectively. \var{arrowpos} defines the position of the arrow line
914 with respect to the position at the graph. The default \code{0.5}
915 means centered at the graph position, whereas \code{0} and \code{1}
916 creates the arrows to start or end at the graph position,
917 respectively. \var{epsilon} is used as a cutoff for short arrows in
918 order to prevent numerical instabilities.
919 \end{classdesc} % }}}
921 \begin{classdesc}{rect}{gradient=color.gradient.Grey} % {{{
922 This class is a style to plot colored rectangles into a
923 two-dimensional graph. The size of the rectangles is taken from
924 the data provided by the \class{range} style. The additional
925 data column named \code{color} specifies the color of the rectangle
926 defined by \var{gradient}. The valid color range is [0:1].
928 \begin{note}
929 Although this style can be used for plotting colored surfaces, it
930 will lead to a huge memory footprint of \PyX{} together with a
931 long running time and large outputs. Improved support for colored
932 surfaces is planned for the future.
933 \end{note}
934 \end{classdesc} % }}}
936 \begin{classdesc}{histogram}{lineattrs=[], steps=0, fromvalue=0, % {{{
937 frompathattrs=[], fillable=0, rectkey=0,
938 autohistogramaxisindex=0,
939 autohistogrampointpos=0.5, epsilon=1e-10}
940 This class is a style to plot histograms. \var{lineattrs} is merged
941 with \code{defaultlineattrs} which is \code{[deco.stroked]}. When
942 \var{steps} is set, the histrogram is plotted as steps instead of
943 the default being a boxed histogram. \var{fromvalue} is the baseline
944 value of the histogram. When set to \code{None}, the histogram will
945 start at the baseline. When fromvalue is set, \var{frompathattrs}
946 are the stroke attributes used to show the histogram baseline path.
948 The \var{fillable} flag changes the stoke line of the histogram to
949 make it fillable properly. This is important on non-steped
950 histograms or on histograms, which hit the graph boundary.
951 \var{rectkey} can be set to generate a rectanglar area instead of a
952 line in the graph key.
954 In the most general case, a histogram is defined by a range
955 specification (like for an errorbar) in one graph dimension (say,
956 along the x-axis) and a value for the other graph dimension. This
957 allows for the widths of the histogram boxes being variable. Often,
958 however, all histogram bin ranges are equally sized, and instead of
959 passing the range, the position of the bin along the x-axis fully
960 specifies the histogram - assuming that there are at least two bins.
961 This common case is supported via two parameters:
962 \var{autohistogramaxisindex}, which defines the index of the
963 independent histogram axis (in the case just described this would be
964 \code{0} designating the x axis). \var{autohistogrampointpos},
965 defines the relative position of the center of the histogram bin:
966 \code{0.5} means that the bin is centered at the values passed to
967 the style, \code{0} (\code{1}) means that the bin is aligned at the
968 right-(left-)hand side.
970 XXX describe, how to specify general histograms with varying bin widths
972 Positions of the histograms are considered to be out of graph when
973 they exceed the graph coordinate range [0:1] by more than
974 \var{epsilon}.
975 \end{classdesc} % }}}
977 \begin{classdesc}{barpos}{fromvalue=None, frompathattrs=[], epsilon=1e-10} % {{{
978 This class is a hidden style providing position information in a bar
979 graph. Those graphs need to contain a specialized axis, namely a bar
980 axis. The data column for this bar axis is named \code{Xname} where
981 \code{X} is an axis name. In the other graph dimension the data
982 column name must be equal to an axis name. To plot several bars in a
983 single graph side by side, you need to have a nested bar axis and
984 provide a tuple as data for nested bar axis.
986 The bars start at \var{fromvalue} when provided. The \var{fromvalue}
987 is marked by a gridline stroked using \var{frompathattrs}. Thus this
988 hidden style might actually create some output. The value of a bar
989 axis is considered to be out of graph when its position in graph
990 coordinates exceeds the range [0:1] by more than \var{epsilon}.
991 \end{classdesc} % }}}
993 \begin{classdesc}{stackedbarpos}{stackname, addontop=0, epsilon=1e-10} % {{{
994 This class is a hidden style providing position information in a bar
995 graph by stacking a new bar on top of another bar. The value of the
996 new bar is taken from the data column named \var{stackname}. When
997 \var{addontop} is set, the values is taken relative to the previous
998 top of the bar.
999 \end{classdesc} % }}}
1001 \begin{classdesc}{bar}{barattrs=[]} % {{{
1002 This class draws bars in a bar graph. The bars are filled using
1003 \var{barattrs}. \var{barattrs} is merged with \code{defaultbarattrs}
1004 which is a list containing \code{[color.gradient.Rainbow,
1005 deco.stroked([color.grey.black])]}.
1006 \end{classdesc} % }}}
1008 \begin{classdesc}{changebar}{barattrs=[]} % {{{
1009 This style works like the \class{bar} style, but instead of the
1010 \var{barattrs} to be changed on subsequent data instances the
1011 \var{barattrs} are changed for each value within a single data
1012 instance. In the result the style can't be applied to several data
1013 instances. The style raises an error instead.
1014 \end{classdesc} % }}}
1016 \begin{classdesc}{gridpos}{index1=0, index2=1, % {{{
1017 gridlines1=1, gridlines2=1, gridattrs=[],
1018 epsilon=1e-10}
1019 This class is a hidden style providing rectangular grid information
1020 out of graph positions for graph dimensions \var{index1} and
1021 \var{index2}. Data points are considered to be out of graph when
1022 their position in graph coordinates exceeds the range [0:1] by more
1023 than \var{epsilon}. Data points are merged to a single graph
1024 coordinate value when their difference in graph coordinates is below
1025 \var{epsilon}.
1026 \end{classdesc} % }}}
1028 \begin{classdesc}{grid}{gridlines1=1, gridlines2=1, gridattrs=[]} % {{{
1029 Strokes a rectangular grid in the first grid direction, when
1030 \var{gridlines1} is set and in the second grid direction, when
1031 \var{gridlines2} is set. \var{gridattrs} is merged with
1032 \code{defaultgridattrs} which is a list containing the member
1033 variable \code{changelinestyle} of the \class{line} class.
1034 \end{classdesc} % }}}
1036 \begin{classdesc}{surface}{colorname="color", % {{{
1037 gradient=color.gradient.Grey,
1038 mincolor=None, maxcolor=None,
1039 gridlines1=0.05, gridlines2=0.05,
1040 gridcolor=None,
1041 backcolor=color.gray.black}
1042 Draws a surface of a rectangular grid. Each rectangle is divided
1043 into 4 triangles.
1045 The grid can be colored using values provided by the data column
1046 named \var{columnname}. The values are rescaled to the range [0:1]
1047 using mincolor and maxcolor (which are taken from the minimal and
1048 maximal values, but larger bounds could be set).
1050 If no \var{columnname} column exists, the surface style falls back
1051 to a lightning coloring taking into account the angle between the
1052 view ray and the triangle and the distance between viewer and
1053 triangle. The precise conversion is defined in the
1054 \method{lightning} method.
1056 If a \var{gridcolor} is set, the rectangular grid is marked by small
1057 stripes of the relative (compared to each rectangle) size of
1058 \var{gridlines1} and \var{gridlines2} for the first and second grid
1059 direction, respectively.
1061 \var{backcolor} is used to fill triangles shown from the back. If
1062 \var{backcolor} is set to \code{None}, back sides are not drawn
1063 differently from the front sides.
1065 The surface is encoded using a single mesh. While this is quite
1066 space efficient, it has the following implications:
1067 \begin{itemize}
1068 \item All colors must use the same color space.
1069 \item HSB colors are not allowed, whereas Gray, RGB, and CMYK are
1070 allowed. You can convert HSB colors into a different color space
1071 before passing them to the surface.
1072 \item The grid itself is also constructed out of triangles. The
1073 grid is transformed along with the triangles thus looking quite
1074 different from a stroked grid (as done by the grid style).
1075 \item Occlusion is handled by proper painting order.
1076 \item Color changes are continuous (in the selected color
1077 space) for each triangle.
1078 \end{itemize}
1079 \end{classdesc} % }}}
1081 % }}}
1083 \section{Module \module{graph.key}: Keys} % {{{
1084 \label{graph:key}
1086 \declaremodule{}{graph.key}
1087 \modulesynopsis{Graph keys}
1089 The following class provides a key, whose instances can be passed to
1090 the constructor keyword argument \code{key} of a graph. The class is
1091 implemented in \module{graph.key}.
1093 \begin{classdesc}{key}{dist=0.2*unit.v\_cm,
1094 pos="tr", hpos=None, vpos=None,
1095 hinside=1, vinside=1,
1096 hdist=0.6*unit.v\_cm,
1097 vdist=0.4*unit.v\_cm,
1098 symbolwidth=0.5*unit.v\_cm,
1099 symbolheight=0.25*unit.v\_cm,
1100 symbolspace=0.2*unit.v\_cm,
1101 textattrs=[],
1102 columns=1, columndist=0.5*unit.v\_cm,
1103 border=0.3*unit.v\_cm, keyattrs=None}
1104 This class writes the title of the data in a plot together with a
1105 small illustration of the style. The style is responsible for its
1106 illustration.
1108 \var{dist} is a visual length and a distance between the key
1109 entries. \var{pos} is the position of the key with respect to the
1110 graph. Allowed values are combinations of \code{"t"} (top),
1111 \code{"m"} (middle) and \code{"b"} (bottom) with \code{"l"} (left),
1112 \code{"c"} (center) and \code{"r"} (right). Alternatively, you may
1113 use \var{hpos} and \var{vpos} to specify the relative position
1114 using the range [0:1]. \var{hdist} and \var{vdist} are the distances
1115 from the specified corner of the graph. \var{hinside} and
1116 \var{vinside} are numbers to be set to 0 or 1 to define whether the
1117 key should be placed horizontally and vertically inside of the graph
1118 or not.
1120 \var{symbolwidth} and \var{symbolheight} are passed to the style to
1121 control the size of the style illustration. \var{symbolspace} is the
1122 space between the illustration and the text. \var{textattrs} are
1123 attributes for the text creation. They are merged with
1124 \code{[text.vshift.mathaxis]}.
1126 \var{columns} is a number of columns of the graph key and
1127 \var{columndist} is the distance between those columns.
1129 When \var{keyattrs} is set to contain some draw attributes, the
1130 graph key is enlarged by \var{border} and the key area is drawn
1131 using \var{keyattrs}.
1132 \end{classdesc} % }}} % }}}
1134 % vim:fdm=marker