1 \chapter{Graphs
\label{graph
}}
3 \PyX{} can be used for data and function plotting. At present only
4 x-y-graphs are supported. However, the component architecture of the
5 graph system described in section
\ref{graph:components
} allows for
6 additional graph geometries while reusing most of the existing
9 Creating a graph splits into two basic steps. First you have to create
10 a graph instance. The most simple form would look like:
13 g = graph.graphxy(width=
8)
15 The graph instance
\code{g
} created in this example can then be used
16 to actually plot something into the graph. Suppose you have some data
17 in a file
\file{graph.dat
} you want to plot. The content of the file
19 \verbatiminput{graph.dat
}
20 To plot these data into the graph
\code{g
} you must perform:
22 g.plot(graph.data.file("graph.dat", x=
1, y=
2))
24 The method
\method{plot()
} takes the data to be plotted and optionally
25 a graph style to be used to plot the data. When no style is provided,
26 a default style defined by the data instance is used. For data read
27 from a file by an instance of
\class{graph.data.file
}, the default are
28 symbols. When instantiating
\class{graph.data.file
}, you not only
29 specify the file name, but also a mapping from columns to axis names
30 and other information the style might use (
\emph{e.g.
} data for error
31 bars for the symbol style).
33 While the graph is already created by that, we still need to perform a
34 write of the result into a file. Since the graph instance is a canvas,
35 we can just call its
\method{writeEPSfile()
} method.
37 g.writeEPSfile("graph")
39 will create the file
\file{graph.eps
} as shown in
40 figure~
\ref{fig:graph
}.
43 \centerline{\includegraphics{graph
}}
44 \caption{A minimalistic plot for the data from file
\file{graph.dat
}.
}
48 Instead of plotting data from a file, we could also use other data
49 sources like functions. The procedure would be as before, but we would
50 place different data into
\method{plot()
}:
52 g.plot(graph.data.function("y=x**
2"))
54 You can plot different data into a single graph by calling the
55 \method{plot()
} several times. Thus the command above might just be
56 inserted before
\method{writeEPSfile()
} of the original example.
57 Note that a call to
\method{plot()
} will fail once you forced the
58 graph to ``finish'' itself. This happens automatically, when you
59 write the output. Thus it is not an option to call
\method{plot()
}
60 after
\method{writeEPSfile()
}. The topic of the finalization of a
61 graph is addressed in more detail in section~
\ref{graph:graph
}. As
62 you can see in figure~
\ref{fig:graph2
}, a function is plotted as a
65 \centerline{\includegraphics{graph2
}}
66 \caption{Plotting data from a file together with a function.
}
70 \section{Component architecture
\label{graph:components
}}
72 Creating a graph involves a variety of tasks, which thus can be
73 separated into components without significant additional costs.
74 This structure manifests itself also in the
\PyX{} source, where there
75 are different modules for the different tasks. They interact by some
76 welldefined interfaces. They certainly have to be completed and
77 stabilized in their details, but the basic structure came up in the
78 continuous development quite clearly. The basic parts of a graph are:
82 Defines the geometry of the graph by means of graph coordinates with
83 range
[0:
1]. Keeps lists of plotted data, axes
\emph{etc.
}
85 Produces or prepares data to be plotted in graphs.
87 Performs the plotting of the data into the graph. It gets data,
88 converts them via the axes into graph coordinates and uses the graph
89 to finally plot the data with respect to the graph geometry methods.
91 Responsible for the graph keys.
93 Creates axes for the graph, which take care of the mapping from data
94 values to graph coordinates. Because axes are also responsible for
95 creating ticks and labels, showing up in the graph themselves and
96 other things, this task is splitted into several independent
97 subtasks. Axes are discussed separately in chapter~
\ref{axis
}.
100 \section{X-Y-Graphs
\label{graph:graph
}}
102 \declaremodule{}{graph.graph
}
103 \modulesynopsis{Graph geometry
}
105 The class
\class{graphxy
} is part of the module
\module{graph.graph
}.
106 However, there is a shortcut to access this class via
107 \code{graph.graphxy
}.
109 \begin{classdesc
}{graphxy
}{xpos=
0, ypos=
0, width=None, height=None,
110 ratio=goldenmean, key=None, backgroundattrs=None, axesdist="
0.8 cm",
112 This class provides an x-y-graph. A graph instance is also a fully
115 The position of the graph on its own canvas is specified by
116 \var{xpos
} and
\var{ypos
}. The size of the graph is specified by
117 \var{width
},
\var{height
}, and
\var{ratio
}. These parameters define
118 the size of the graph area not taking into account the additional
119 space needed for the axes. Note that you have to specify at least
120 \var{width
} or
\var{height
}.
\var{ratio
} will be used as the ratio
121 between
\var{width
} and
\var{height
} when only one of these is
124 \var{key
} can be set to a
\class{graph.key.key
} instance to create
125 an automatic graph key.
\code{None
} omits the graph key.
127 \var{backgroundattrs
} is a list of attributes for drawing the
128 background of the graph. Allowed are decorators, strokestyles, and
129 fillstyles.
\code{None
} disables background drawing.
131 \var{axisdist
} is the distance between axes drawn at the same side
134 \var{**axes
} receives axes instances. Allowed keywords (axes names)
135 are
\code{x
},
\code{x2
},
\code{x3
},
\emph{etc.
} and
\code{y
},
136 \code{y2
},
\code{y3
},
\emph{etc.
} When not providing an
\code{x
} or
137 \code{y
} axis, linear axes instances will be used automatically.
138 When not providing a
\code{x2
} or
\code{y2
} axis, linked axes to the
139 \code{x
} and
\code{y
} axes are created automatically. You may set
140 those axes to
\code{None
} to disable the automatic creation of axes.
141 The even numbered axes are plotted at the top (
\code{x
} axes) and
142 right (
\code{y
} axes) while the others are plotted at the bottom
143 (
\code{x
} axes) and left (
\code{y
} axes) in ascending order each.
144 Axes instances should only be used once.
147 Some instance attributes might be useful for outside read-access.
150 \begin{memberdesc
}{axes
}
151 A dictionary mapping axes names to the
\class{axis
} instances.
154 \begin{memberdesc
}{axespos
}
155 A dictionary mapping axes names to the
\class{axispos
} instances.
158 To actually plot something into the graph, the following instance
159 method
\method{plot()
} is provided:
161 \begin{methoddesc
}{plot
}{data, style=None
}
162 Adds
\var{data
} to the list of data to be plotted. Sets
\var{style
}
163 to be used for plotting the data. When
\var{style
} is
\code{None
},
164 the default style for the data as provided by
\var{data
} is used.
166 \var{data
} should be an instance of any of the data described in
167 section~
\ref{graph:data
}. This instance should only be used once.
169 When a style is used several times within the same graph instance,
170 it is kindly asked by the graph to iterate its appearence. Its up
171 to the style how this is performed.
173 Instead of calling the plot method several times with different
174 \var{data
} but the same style, you can use a list (or something
175 iterateable) for
\var{data
}.
178 While a graph instance only collects data initially, at a certain
179 point it must create the whole plot. Once this is done, further calls
180 of
\method{plot()
} will fail. Usually you do not need to take care
181 about the finalization of the graph, because it happens automatically
182 once you write the plot into a file. However, sometimes position
183 methods (described below) are nice to be accessible. For that, at
184 least the layout of the graph must be done. By calling the
185 \method{do
}-methods yourself you can also alter the order in which
186 the graph is plotted. Multiple calls to any of the
187 \method{do
}-methods have no effect (only the first call counts). The
188 orginal order in which the
\method{do
}-methods are called is:
190 \begin{methoddesc
}{dolayout
}{}
191 Fixes the layout of the graph. As part of this work, the ranges of
192 the axes are fitted to the data when the axes ranges are allowed to
193 adjust themselves to the data ranges. The other
\method{do
}-methods
194 ensure, that this method is always called first.
197 \begin{methoddesc
}{dobackground
}{}
198 Draws the background.
201 \begin{methoddesc
}{doaxes
}{}
205 \begin{methoddesc
}{dodata
}{}
209 \begin{methoddesc
}{dokey
}{}
210 Inserts the graph key.
213 \begin{methoddesc
}{finish
}{}
214 Finishes the graph by calling all pending
\method{do
}-methods. This
215 is done automatically, when the output is created.
218 The graph provides some methods to access its geometry:
220 \begin{methoddesc
}{pos
}{x, y, xaxis=None, yaxis=None
}
221 Returns the given point at
\var{x
} and
\var{y
} as a tuple
222 \code{(xpos, ypos)
} at the graph canvas.
\var{x
} and
\var{y
} are
223 axis data values for the two axes
\var{xaxis
} and
\var{yaxis
}. When
224 \var{xaxis
} or
\var{yaxis
} are
\code{None
}, the axes with names
225 \code{x
} and
\code{y
} are used. This method fails if called before
229 \begin{methoddesc
}{vpos
}{vx, vy
}
230 Returns the given point at
\var{vx
} and
\var{vy
} as a tuple
231 \code{(xpos, ypos)
} at the graph canvas.
\var{vx
} and
\var{vy
} are
232 graph coordinates with range
[0:
1].
235 \begin{methoddesc
}{vgeodesic
}{vx1, vy1, vx2, vy2
}
236 Returns the geodesic between points
\var{vx1
},
\var{vy1
} and
237 \var{vx2
},
\var{vy2
} as a path. All parameters are in graph
238 coordinates with range
[0:
1]. For
\class{graphxy
} this is a straight
242 \begin{methoddesc
}{vgeodesic
\_el}{vx1, vy1, vx2, vy2
}
243 Like
\method{vgeodesic()
} but this method returns the path element to
244 connect the two points.
247 % dirty hack to add a whole list of methods to the index:
248 \index{xbasepath()@
\texttt{xbasepath()
} (graphxy method)
}
249 \index{xvbasepath()@
\texttt{xvbasepath()
} (graphxy method)
}
250 \index{xgridpath()@
\texttt{xgridpath()
} (graphxy method)
}
251 \index{xvgridpath()@
\texttt{xvgridpath()
} (graphxy method)
}
252 \index{xtickpoint()@
\texttt{xtickpoint()
} (graphxy method)
}
253 \index{xvtickpoint()@
\texttt{xvtickpoint()
} (graphxy method)
}
254 \index{xtickdirection()@
\texttt{xtickdirection()
} (graphxy method)
}
255 \index{xvtickdirection()@
\texttt{xvtickdirection()
} (graphxy method)
}
256 \index{ybasepath()@
\texttt{ybasepath()
} (graphxy method)
}
257 \index{yvbasepath()@
\texttt{yvbasepath()
} (graphxy method)
}
258 \index{ygridpath()@
\texttt{ygridpath()
} (graphxy method)
}
259 \index{yvgridpath()@
\texttt{yvgridpath()
} (graphxy method)
}
260 \index{ytickpoint()@
\texttt{ytickpoint()
} (graphxy method)
}
261 \index{yvtickpoint()@
\texttt{yvtickpoint()
} (graphxy method)
}
262 \index{ytickdirection()@
\texttt{ytickdirection()
} (graphxy method)
}
263 \index{yvtickdirection()@
\texttt{yvtickdirection()
} (graphxy method)
}
265 Further geometry information is available by the
\member{axespos
}
266 instance variable. Shortcuts to the
\class{axispos
} methods for the
267 \code{x
} and
\code{y
} axis become available after
\method{dolayout()
}
268 as
\class{graphxy
} methods
\code{Xbasepath
},
\code{Xvbasepath
},
269 \code{Xgridpath
},
\code{Xvgridpath
},
\code{Xtickpoint
},
270 \code{Xvtickpoint
},
\code{Xtickdirection
}, and
\code{Xvtickdirection
}
271 where the prefix
\code{X
} stands for
\code{x
} and
\code{y
}.
273 \section{Data
\label{graph:data
}}
275 \declaremodule{}{graph.data
}
276 \modulesynopsis{Graph data
}
278 The following classes provide data for the
\method{plot()
} method of a
279 graph. The classes are implemented in
\module{graph.data
}.
281 \begin{classdesc
}{file
}{filename,
282 commentpattern=defaultcommentpattern,
283 columnpattern=defaultcolumnpattern,
284 stringpattern=defaultstringpattern,
285 skiphead=
0, skiptail=
0, every=
1, title=notitle,
286 parser=dataparser(), context=\
{\
}, **columns
}
287 This class reads data from a file and makes them available to the
288 graph system.
\var{filename
} is the name of the file to be read.
289 The data should be organized in columns.
291 The arguments
\var{commentpattern
},
\var{columnpattern
}, and
292 \var{stringpattern
} are responsible for identifying the data in each
293 line of the file. Lines matching
\var{commentpattern
} are ignored
294 except for the column name search of the last non-emtpy comment line
295 before the data. By default a line starting with one of the
296 characters
\character{\#
},
\character{\%
}, or
\character{!
} is
297 treated as comment. A line is analysed by repeatedly matching
298 \var{stringpattern
} and, whenever the stringpattern does not match,
299 by
\var{columnpattern
}. When the
\var{stringpattern
} matches, the
300 result is taken as the value for the next column without further
301 transformations. When
\var{columnpattern
} matches, it is tried to
302 convert the result to a float. When this fails the result is taken
303 as a string as well. By default, you can write strings with spaces
304 surrounded by
\character{\textquotedbl} immediately surrounded by
305 spaces or begin/end of line in the data file. Otherwise
306 \character{\textquotedbl} is not taken to be special.
308 \var{skiphead
} and
\var{skipfoot
} are numbers of data lines to be
309 ignored at the beginning and end of the file while
\var{every
}
310 selects only every
\var{every
} line from the data.
312 \var{title
} is the title of the data to be used in the graph key. A
313 default title is constructed out of
\var{filename
} and
314 \var{**columns
}. You may set
\var{title
} to
\code{None
} to disable
317 \var{parser
} is the parser for mathematical expressions provided in
318 \var{**columns
}. When in doubt, this is probably uninteresting for
319 you.
\var{context
} allows for accessing external variables and
320 functions when evaluating mathematical expressions for columns. As
321 an example you may use
\code{context=locals()
} or something similar.
323 Finally,
\var{columns
} defines the data columns. To make it a bit
324 more complicated, there are file column names and new created data
325 column names, namely the keywords of
\var{**columns
}. File column
326 names occur when the data file contains a comment line immediately
327 in front of the data. This line will be parsed skipping the comment
328 character (even if it occurs multiple times) as if it would be
329 regular data, but it will not be converted to floats even if it
330 would be possible to convert them. The values of
\var{**columns
} can
331 refer to column numbers in the file (starting with
\code{1}). The
332 column
\code{0} is also available and contains the line number
333 starting from
\code{1} not counting comment lines. Furthermore
334 values of
\var{**columns
} can be strings: file column names or
335 mathematical expressions. To refer to columns within mathematical
336 expressions you can also use file column names when they are valid
337 variable names or by the syntax
\code{\$
\textless
338 number
\textgreater} or even
\code{\$(
\textless
339 expression
\textgreater)
}, where
\code{\textless number
\textgreater}
340 is a non-negative integer and
\code{\textless
341 expression
\textgreater} a valid mathematical expression itself. For
342 the latter, negative numbers count the columns from the end.
345 graph.data.file("test.dat", a=
1, b="B", c="
2*B+$
3")
347 with
\file{test.dat
} looking like:
353 The columns with name
\samp{a
},
\samp{b
},
\samp{c
} will become
354 \samp{[1.234,
5.678]},
\samp{[1.0,
3.0]}, and
\samp{[4.0,
10.0]},
357 When creating several data instances accessing the same file,
358 the file is read only once. There is an inherent caching of the
362 For the sake of completeness we list the default patterns:
364 \begin{memberdesc
}{defaultcommentpattern
}
365 \code{re.compile(r
\textquotedbl (\#+|!+|\%+)
\e s*
\textquotedbl)
}
368 \begin{memberdesc
}{defaultcolumnpattern
}
369 \code{re.compile(r
\textquotedbl\e \textquotedbl(.*?)
\e \textquotedbl(
\e s+|\$)
\textquotedbl)
}
372 \begin{memberdesc
}{defaultstringpattern
}
373 \code{re.compile(r
\textquotedbl(.*?)(
\e s+|\$)
\textquotedbl)
}
376 \begin{classdesc
}{function
}{expression, title=notitle,
377 min=None, max=None, points=
100,
378 parser=mathtree.parser(),
380 This class creates graph data from a function.
\var{expression
} is
381 the mathematical expression of the function. It must also contain
382 the result variable name by assignment. Thus a typical example looks
383 like
\samp{y=sin(x)
}.
385 \var{title
} is the title of the data to be used in the graph key. By
386 default
\var{expression
} is used. You may set
\var{title
} to
387 \code{None
} to disable the title.
389 \var{min
} and
\var{max
} give the range of the variable. If not set,
390 the range spans the whole axis range. The axis range might be set
391 explicitly or implicitly by ranges of other data.
\var{points
} is
392 the number of points for which the function is calculated. The
393 points are choosen linearly in terms of graph coordinates.
395 \var{parser
} is the parser for the mathematical expression. When in
396 doubt, this is probably uninteresting for you.
\var{context
} allows
397 for accessing external variables and functions. As an example you
398 may use
\code{context=locals()
} or something similar.
400 Note when accessing external variables: In principle, it is unclear,
401 which of the variables should be used as the
402 dependent variable. The solution is, that there should be exactly
403 one variable, which is a valid and used axis name.
406 [graph.data.function("y=x**i", context=locals()) for i in range(
1,
5)
]
408 The result of this expression could just be passed to a graphs
409 \method{plot()
} method, since not only data instances but also lists
410 of data instances are allowed.
413 \begin{classdesc
}{paramfunction
}{varname, min, max, expression,
414 title=notitle, points=
100,
415 parser=mathtree.parser(),
417 This class creates graph data from a parametric function.
418 \var{varname
} is the parameter of the function.
\var{min
} and
419 \var{max
} give the range for that variable.
\var{points
} is the
420 number of points for which the function is calculated. The points
421 are choosen lineary in terms of the parameter.
423 \var{expression
} is the mathematical expression for the parametric
424 function. It contains an assignment of a tuple of functions to a
427 \var{title
} is the title of the data to be used in the graph key. By
428 default
\var{expression
} is used. You may set
\var{title
} to
429 \code{None
} to disable the title.
431 \var{parser
} is the parser for mathematical expressions. When in
432 doubt, this is probably uninteresting for you.
\var{context
} allows
433 for accessing external variables and functions. As an example you
434 may use
\code{context=locals()
} or something similar.
437 \begin{classdesc
}{list
}{points, title="user provided list",
438 maxcolumns=None, addlinenumbers=
1, **columns
}
439 This class creates graph data from externally provided data.
440 \var{points
} is a list of lines, where each line is a list of data
441 values for the columns.
443 \var{title
} is the title of the data to be used in the graph key.
445 \var{maxcolumn
} is the number of columns in the points list. If set
446 to
\code{None
}, the number of columns will be calculated by cycling
447 through the points. Each element of
\var{points
},
\emph{i.e.
} each
448 line, will be checked and adjusted to the number of columns.
450 \var{addlinenumbers
} is a boolean indicating whether line numbers
451 should be added or not. Note that the line numbers are stored in
452 column
\code{0}. A transformation (see
\class{data
} below) will
453 always keep the first column. When not adding line numbers, you
454 should be aware, that the numbering in
\var{**columns
} becomes
455 different from the usual case, where the first column containing
456 data (not the line number) has column number
\code{1}.
458 The keywords of
\var{**columns
} become the data column names. The
459 values are the column numbers starting from one, when
460 \var{addlinenumbers
} is turned on (the zeroth column is the line
461 number then), while the column numbers starts from zero, when
462 \var{addlinenumbers
} is switched off.
465 \begin{classdesc
}{data
}{data, title=notitle, parser=dataparser(),
466 context=
{}, **columns
}
467 This class provides graph data out of other graph data.
\var{data
}
468 is the source of the data. All other parameters work like the equally
469 called parameters in
\class{graph.data.file
}. Indeed, the latter is
470 built on top of this class by reading the file and caching its
471 contents in a
\class{graph.data.list
} instance. The columns are then
472 selected by creating new data out of the existing data. Note that
473 the data themselves are not copied as long as no new columns need to be
477 \begin{classdesc
}{conffile
}{filename, title=notitle,
478 parser=dataparser(), context=
{},
480 This class reads data from a config file with the file name
481 \var{filename
}. The format of a config file is described within the
482 documentation of the
\module{ConfigParser
} module of the Python
485 Each section of the config file becomes a data line. The options in
486 a section are the columns. The name of the options will be used as
487 file column names. All other parameters work as in
488 \var{graph.data.file
} and
\var{graph.data.data
} since they all use
492 \section{Styles
\label{graph:style
}}
494 \declaremodule{}{graph.style
}
495 \modulesynopsis{Graph style
}
497 Please note that we are talking about graph styles here. Those are
498 responsible for plotting symbols, lines, bars and whatever else into a
499 graph. Do not mix it up with path styles like the line width, the line
500 style (solid, dashed, dotted
\emph{etc.
}) and others.
502 The following classes provide styles to be used at the
\method{plot()
}
503 method of a graph. The classes are implemented in
\module{graph.style
}.
505 \begin{classdesc
}{symbolline
}{symbol=changecross, size="
0.2 cm",
506 errorscale=
0.5, symbolattrs=
[],
507 errorbarattrs=
[], lineattrs=
[],
509 This class is a style for plotting symbols, lines and errorbars into a
510 graph.
\var{symbol
} refers to a (changeable) symbol method (see
511 below). The symbol is drawn at size
\var{size
} (a visual
\PyX{}
512 length; also changeable) using
\var{symbolattrs
}.
\var{symbolattrs
}
513 are merged with the decorator
\class{deco.stroked
}.
\var{errorscale
}
514 is the size of the error bars compared to the symbol size.
515 \var{errorbarattrs
} and
\var{lineattrs
} are strokestyles for
516 stroking the errorbars and lines, respecively.
\var{lineattrs
} are
517 merged with
\var{changelinestyle
} (see below).
\var{epsilon
} is used
518 to determine, when a symbol is outside of the graph (in graph
521 \var{symbolline
} is useable on graphs with arbitrary dimension and
522 geometry. It needs one data column for each graph dimension. The
523 data names must be equal to an axis name. Furthermore there can be
524 data names constructed out of the axis names for identifying data
525 for the error bars. Suppose
\code{X
} is an axis name. Then
526 \class{symbolline
} allows for the following data names as well:
528 \begin{tableii
}{l|l
}{}{data name
}{description
}
529 \lineii{\code{Xmin
}}{minimal value
}
530 \lineii{\code{Xmax
}}{maximal value
}
531 \lineii{\code{dX
}}{minimal and maximal delta
}
532 \lineii{\code{dXmin
}}{minimal delta
}
533 \lineii{\code{dXmax
}}{maximal delta
}
536 Minimal and maximal values are calculated from delta by subtracting
537 and adding it to the value itself. Most of the data names are mutually
538 exclusive (whenever a minimal or maximal value would be set twice).
541 \class{symbolline
} provides some symbol methods, namely:
543 \begin{methoddesc
}{cross
}{x_pt, y_pt, size_pt
}
544 A cross. Should be used for stroking only.
547 \begin{methoddesc
}{plus
}{x_pt, y_pt, size_pt
}
548 A plus. Should be used for stroking only.
551 \begin{methoddesc
}{square
}{x_pt, y_pt, size_pt
}
552 A square. Might be stroked or filled or both.
555 \begin{methoddesc
}{triangle
}{x_pt, y_pt, size_pt
}
556 A triangle. Might be stroked or filled or both.
559 \begin{methoddesc
}{circle
}{x_pt, y_pt, size_pt
}
560 A circle. Might be stroked or filled or both.
563 \begin{methoddesc
}{diamond
}{x_pt, y_pt, size_pt
}
564 A diamond. Might be stroked or filled or both.
567 \class{symbolline
} provides some changeable symbol methods as class
570 \begin{memberdesc
}{changecross
}
571 attr.changelist(
[cross, plus, square, triangle, circle, diamond
])
574 \begin{memberdesc
}{changeplus
}
575 attr.changelist(
[plus, square, triangle, circle, diamond, cross
])
578 \begin{memberdesc
}{changesquare
}
579 attr.changelist(
[square, triangle, circle, diamond, cross, plus
])
582 \begin{memberdesc
}{changetriangle
}
583 attr.changelist(
[triangle, circle, diamond, cross, plus, square
])
586 \begin{memberdesc
}{changecircle
}
587 attr.changelist(
[circle, diamond, cross, plus, square, triangle
])
590 \begin{memberdesc
}{changediamond
}
591 attr.changelist(
[diamond, cross, plus, square, triangle, circle
])
594 \begin{memberdesc
}{changesquaretwice
}
595 attr.changelist(
[square, square, triangle, triangle, circle, circle, diamond, diamond
])
598 \begin{memberdesc
}{changetriangletwice
}
599 attr.changelist(
[triangle, triangle, circle, circle, diamond, diamond, square, square
])
602 \begin{memberdesc
}{changecircletwice
}
603 attr.changelist(
[circle, circle, diamond, diamond, square, square, triangle, triangle
])
606 \begin{memberdesc
}{changediamondtwice
}
607 attr.changelist(
[diamond, diamond, square, square, triangle, triangle, circle, circle
])
610 \class{symbolline
} provides two changeable decorators for alternated filling
611 and stroking. Those are especially useful in combination with the
612 \method{change
}-
\method{twice
}-symbol methods above. They are:
614 \begin{memberdesc
}{changestrokedfilled
}
615 attr.changelist(
[deco.stroked, deco.filled
])
618 \begin{memberdesc
}{changefilledstroked
}
619 attr.changelist(
[deco.filled, deco.stroked
])
622 Finally, there is a changeable line style used by default. It is
625 \begin{memberdesc
}{changelinestyle
}
626 attr.changelist(
[style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted
])
629 \begin{classdesc
}{symbol
}{symbol=changecross, size="
0.2 cm",
630 errorscale=
0.5, symbolattrs=
[],
631 errorbarattrs=
[], epsilon=
1e-10}
632 This class is a style to plot symbols and errorbars into a graph. It
633 is equivalent to
\class{symbollines
} except that it does not allow
634 for lines. An instance of
\class{symbol
} is the default style for
635 all data classes described in section~
\ref{graph:data
} except for
636 \class{function
} and
\class{paramfunction
}.
639 \begin{classdesc
}{line
}{errorbarattrs=
[]}
640 This class is a style to stroke lines into a graph. It is equivalent
641 to
\class{symbollines
} except that it does not allow for symbols and
642 errorbars. Thus it also does not accept data names for error bars.
643 Instances of
\class{line
} are the default style for the data classes
644 \class{function
} and
\class{paramfunction
}.
647 \begin{classdesc
}{text
}{textdx="
0", textdy="
0.3 cm", textattrs=
[],
648 symbol=changecross, size="
0.2 cm",
649 errorscale=
0.5, symbolattrs=
[],
650 errorbarattrs=
[], epsilon=
1e-10}
651 This class enhances
\class{symbol
} by adding text to the symbol. The
652 text to be written has to be provided in the additional data column named
653 \code{text
}.
\var{textdx
} and
\var{textdy
} are the position of the
654 text with respect to the symbol.
\var{textattrs
} are text
655 attributes for the output of the text. All other parameters have the
656 same meaning as in the
\class{symbol
} class.
659 \begin{classdesc
}{arrow
}{linelength="
0.25 cm", arrowsize="
0.15 cm",
660 lineattrs=
[], arrowattrs=
[], epsilon=
1e-10}
661 This class is a style to plot short lines with arrows into a
662 two-dimensional graph. The position of the arrow is defined by two
663 data columns named like an axis for each graph dimension. Two
664 additional data columns named
\code{size
} and
\code{angle
} define
665 the size and angle for each arrow.
\code{size
} is taken as a factor
666 to
\var{arrowsize
} and
\var{linelength
}, the size of the arrow and
667 the length of the line the arrow is plotted at.
\code{angle
} is the
668 angle the arrow points to with respect to a horizontal line. The
669 \code{angle
} is taken in degrees and used in mathematically positive
670 sense.
\var{lineattrs
} and
\var{arrowattrs
} are styles for the arrow
671 line and arrow head, respectively.
\var{epsilon
} is used to
672 determine, when the arrow is outside of the graph (in graph
676 \begin{classdesc
}{rect
}{palette=
color.palette.Gray
}
677 This class is a style to plot coloured rectangles into a
678 two-dimensional graph. The positions of the rectangles are given by four
679 data columns named
\code{Xmin
} and
\code{Xmax
} where
\code{X
} stands
680 for two axis names, one for each graph dimension. The additional
681 data column named
\code{color} specifies the
color of the rectangle
682 defined by
\var{palette
}. Thus the valid
color range is
[0:
1].
685 Although this style can be used for plotting coloured surfaces, it
686 will lead to a huge memory footprint of
\PyX{} together with a
687 long running time and large outputs. Improved support for coloured
688 surfaces is planned for the future.
692 \begin{classdesc
}{bar
}{fromvalue=None, frompathattrs=
[], barattrs=
[],
693 subnames=None, epsilon=
1e-10}
694 This class is a style to plot bars into a two-dimensional graph. The
695 bars are plotted on top of a specialized axis, namely a bar axis.
696 The data column for this bar axis is named
\code{Xname
} where
697 \code{X
} is an axis name. The bar value has the name of an axis of the
698 other graph dimension. Suppose the name of this value axis is
699 \code{Y
} than you can stack further bars on top of this bar by
700 providing additional data columns consecutively named
701 \code{Ystack1
},
\code{Ystack2
},
\code{Ystack3
},
\emph{etc.
}
702 When plotting several bars in a single graph, those bars are placed
703 side by side (at the same value of
\code{Xname
}). The name axis, a
704 bar axis, must then be a nested bar axis. The names used for the
705 subaxis can be set by
\var{subnames
}. When not set, integer numbers
706 starting from zero will be used.
708 The bars start at
\var{fromvalue
} when provided. The
\var{fromvalue
}
709 is marked by a gridline stroked using
\var{frompathattrs
}. The bars
710 are filled using
\var{barattrs
}.
\var{barattrs
} is merged with
711 \samp{[color.palette.Rainbow, deco.stroked(
[color.gray.black
])
]} and
712 iterated independently when several bars are plotted side by side
713 and when several bars are plotted on top of each other. When mixing
714 both possibilities, you may use nested changeable styles.
717 \section{Keys
\label{graph:key
}}
719 \declaremodule{}{graph.key
}
720 \modulesynopsis{Graph keys
}
722 The following class provides a key, whose instances can be passed to
723 the constructor keyword argument
\code{key
} of a graph. The class is
724 implemented in
\module{graph.key
}.
726 \begin{classdesc
}{key
}{dist="
0.2 cm", pos="tr", hinside=
1, vinside=
1,
727 hdist="
0.6 cm", vdist="
0.4 cm",
728 symbolwidth="
0.5 cm", symbolheight="
0.25 cm",
729 symbolspace="
0.2 cm", textattrs=
[]}
730 This class writes the title of the data in a plot together with a
731 small illustration of the style. The style is responsible for its
734 \var{dist
} is a visual length and a distance between the key
735 entries.
\var{pos
} is the position of the key with respect to the
736 graph. Allowed values are combinations of
\samp{t
} (top) and
737 \samp{b
} (bottom) with
\samp{l
} (left) and
\samp{r
} (right).
738 \var{hdist
} and
\var{vdist
} are the distances from the specified
739 corner of the graph.
\var{hinside
} and
\var{vinside
} are booleans to
740 define whether the key should be placed horizontally and vertically
741 inside of the graph or not.
743 \var{symbolwidth
} and
\var{symbolheight
} are passed to the style to
744 control the size of the style illustration.
\var{symbolspace
} is the
745 space between the illustration and the text.
\var{textattrs
} are
746 attributes for the text creation. They are merged with
747 \samp{[text.vshift.mathaxis
]}.
