3 \section{Introduction
} % {{{
4 \PyX{} can be used for data and function plotting. At present only
5 x-y-graphs are supported. However, the component architecture of the
6 graph system described in section
\ref{graph:components
} allows for
7 additional graph geometries while reusing most of the existing
10 Creating a graph splits into two basic steps. First you have to create
11 a graph instance. The most simple form would look like:
14 g = graph.graphxy(width=
8)
16 The graph instance
\code{g
} created in this example can then be used
17 to actually plot something into the graph. Suppose you have some data
18 in a file
\file{graph.dat
} you want to plot. The content of the file
20 \verbatiminput{graph.dat
}
21 To plot these data into the graph
\code{g
} you must perform:
23 g.plot(graph.data.file("graph.dat", x=
1, y=
2))
25 The method
\method{plot()
} takes the data to be plotted and optionally
26 a list of graph styles to be used to plot the data. When no styles are
27 provided, a default style defined by the data instance is used. For
28 data read from a file by an instance of
\class{graph.data.file
}, the
29 default are symbols. When instantiating
\class{graph.data.file
}, you
30 not only specify the file name, but also a mapping from columns to
31 axis names and other information the styles might make use of
32 (
\emph{e.g.
} data for error bars to be used by the errorbar style).
34 While the graph is already created by that, we still need to perform a
35 write of the result into a file. Since the graph instance is a canvas,
36 we can just call its
\method{writeEPSfile()
} method.
38 g.writeEPSfile("graph")
40 The result
\file{graph.eps
} is shown in 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, other data source are available
49 as well. For example function data is created and placed into
50 \method{plot()
} by the following line:
52 g.plot(graph.data.function("y=x**
2"))
54 You can plot different data in a single graph by calling
55 \method{plot()
} several times before
\method{writeEPSfile()
}. Note
56 that a calling
\method{plot()
} will fail once a graph was forced to
57 ``finish'' itself. This happens automatically, when the graph is
58 written to a file. Thus it is not an option to call
\method{plot()
}
59 after
\method{writeEPSfile()
}. The topic of the finalization of a
60 graph is addressed in more detail in section~
\ref{graph:graph
}. As you
61 can see in figure~
\ref{fig:graph2
}, a function is plotted as a line by
65 \centerline{\includegraphics{graph2
}}
66 \caption{Plotting data from a file together with a function.
}
70 While the axes ranges got adjusted automatically in the previous
71 example, they might be fixed by keyword options in axes constructors.
72 Plotting only a function will need such a setting at least in the
73 variable coordinate. The following code also shows how to set a
74 logathmic axis in y-direction:
76 \verbatiminput{graph3.py
}
78 The result is shown in figure~
\ref{fig:graph3
}.
81 \centerline{\includegraphics{graph3
}}
82 \caption{Plotting a function for a given axis range and use a
87 \section{Component architecture
} % {{{
88 \label{graph:components
}
90 Creating a graph involves a variety of tasks, which thus can be
91 separated into components without significant additional costs.
92 This structure manifests itself also in the
\PyX{} source, where there
93 are different modules for the different tasks. They interact by some
94 well-defined interfaces. They certainly have to be completed and
95 stabilized in their details, but the basic structure came up in the
96 continuous development quite clearly. The basic parts of a graph are:
100 Defines the geometry of the graph by means of graph coordinates with
101 range
[0:
1]. Keeps lists of plotted data, axes
\emph{etc.
}
103 Produces or prepares data to be plotted in graphs.
105 Performs the plotting of the data into the graph. It gets data,
106 converts them via the axes into graph coordinates and uses the graph
107 to finally plot the data with respect to the graph geometry methods.
109 Responsible for the graph keys.
111 Creates axes for the graph, which take care of the mapping from data
112 values to graph coordinates. Because axes are also responsible for
113 creating ticks and labels, showing up in the graph themselves and
114 other things, this task is splitted into several independent
115 subtasks. Axes are discussed separately in chapter~
\ref{axis
}.
116 \end{definitions
} % }}}
118 \section{Module graph/graph: X-Y-Graphs
} % {{{
121 \declaremodule{}{graph.graph
}
122 \modulesynopsis{Graph geometry
}
124 The class
\class{graphxy
} is part of the module
\module{graph.graph
}.
125 However, there is a shortcut to access this class via
126 \code{graph.graphxy
}.
128 \begin{classdesc
}{graphxy
}{xpos=
0, ypos=
0, width=None, height=None,
129 ratio=goldenmean, key=None, backgroundattrs=None,
130 axesdist=
0.8*unit.v
\_cm, **axes
}
131 This class provides an x-y-graph. A graph instance is also a fully
134 The position of the graph on its own canvas is specified by
135 \var{xpos
} and
\var{ypos
}. The size of the graph is specified by
136 \var{width
},
\var{height
}, and
\var{ratio
}. These parameters define
137 the size of the graph area not taking into account the additional
138 space needed for the axes. Note that you have to specify at least
139 \var{width
} or
\var{height
}.
\var{ratio
} will be used as the ratio
140 between
\var{width
} and
\var{height
} when only one of these is
143 \var{key
} can be set to a
\class{graph.key.key
} instance to create
144 an automatic graph key.
\code{None
} omits the graph key.
146 \var{backgroundattrs
} is a list of attributes for drawing the
147 background of the graph. Allowed are decorators, strokestyles, and
148 fillstyles.
\code{None
} disables background drawing.
150 \var{axisdist
} is the distance between axes drawn at the same side
153 \var{**axes
} receives axes instances. Allowed keywords (axes names)
154 are
\code{x
},
\code{x2
},
\code{x3
},
\emph{etc.
} and
\code{y
},
155 \code{y2
},
\code{y3
},
\emph{etc.
} When not providing an
\code{x
} or
156 \code{y
} axis, linear axes instances will be used automatically.
157 When not providing a
\code{x2
} or
\code{y2
} axis, linked axes to the
158 \code{x
} and
\code{y
} axes are created automatically. You may set
159 those axes to
\code{None
} to disable the automatic creation of axes.
160 The even numbered axes are plotted at the top (
\code{x
} axes) and
161 right (
\code{y
} axes) while the others are plotted at the bottom
162 (
\code{x
} axes) and left (
\code{y
} axes) in ascending order each.
163 Axes instances should only be used once.
166 Some instance attributes might be useful for outside read-access.
169 \begin{memberdesc
}{axes
}
170 A dictionary mapping axes names to the
\class{axis
} instances.
173 \begin{memberdesc
}{axespos
}
174 A dictionary mapping axes names to the
\class{axispos
} instances.
177 To actually plot something into the graph, the following instance
178 method
\method{plot()
} is provided:
180 \begin{methoddesc
}{plot
}{data, styles=None
}
181 Adds
\var{data
} to the list of data to be plotted. Sets
\var{styles
}
182 to be used for plotting the data. When
\var{styles
} is
\code{None
},
183 the default styles for the data as provided by
\var{data
} is used.
185 \var{data
} should be an instance of any of the data described in
186 section~
\ref{graph:data
}. This instance should only be used once.
188 When the same combination of styles (
\emph{i.e.
} the same
189 references) are used several times within the same graph instance,
190 the styles are kindly asked by the graph to iterate their
191 appearence. Its up to the styles how this is performed.
193 Instead of calling the plot method several times with different
194 \var{data
} but the same style, you can use a list (or something
195 iterateable) for
\var{data
}.
198 While a graph instance only collects data initially, at a certain
199 point it must create the whole plot. Once this is done, further calls
200 of
\method{plot()
} will fail. Usually you do not need to take care
201 about the finalization of the graph, because it happens automatically
202 once you write the plot into a file. However, sometimes position
203 methods (described below) are nice to be accessible. For that, at
204 least the layout of the graph must have been finished. By calling the
205 \method{do
}-methods yourself you can also alter the order in which the
206 graph components are plotted. Multiple calls to any of the
207 \method{do
}-methods have no effect (only the first call counts). The
208 orginal order in which the
\method{do
}-methods are called is:
210 \begin{methoddesc
}{dolayout
}{}
211 Fixes the layout of the graph. As part of this work, the ranges of
212 the axes are fitted to the data when the axes ranges are allowed to
213 adjust themselves to the data ranges. The other
\method{do
}-methods
214 ensure, that this method is always called first.
217 \begin{methoddesc
}{dobackground
}{}
218 Draws the background.
221 \begin{methoddesc
}{doaxes
}{}
225 \begin{methoddesc
}{dodata
}{}
229 \begin{methoddesc
}{dokey
}{}
230 Inserts the graph key.
233 \begin{methoddesc
}{finish
}{}
234 Finishes the graph by calling all pending
\method{do
}-methods. This
235 is done automatically, when the output is created.
238 The graph provides some methods to access its geometry:
240 \begin{methoddesc
}{pos
}{x, y, xaxis=None, yaxis=None
}
241 Returns the given point at
\var{x
} and
\var{y
} as a tuple
242 \code{(xpos, ypos)
} at the graph canvas.
\var{x
} and
\var{y
} are
243 axis data values for the two axes
\var{xaxis
} and
\var{yaxis
}. When
244 \var{xaxis
} or
\var{yaxis
} are
\code{None
}, the axes with names
245 \code{x
} and
\code{y
} are used. This method fails if called before
249 \begin{methoddesc
}{vpos
}{vx, vy
}
250 Returns the given point at
\var{vx
} and
\var{vy
} as a tuple
251 \code{(xpos, ypos)
} at the graph canvas.
\var{vx
} and
\var{vy
} are
252 graph coordinates with range
[0:
1].
255 \begin{methoddesc
}{vgeodesic
}{vx1, vy1, vx2, vy2
}
256 Returns the geodesic between points
\var{vx1
},
\var{vy1
} and
257 \var{vx2
},
\var{vy2
} as a path. All parameters are in graph
258 coordinates with range
[0:
1]. For
\class{graphxy
} this is a straight
262 \begin{methoddesc
}{vgeodesic
\_el}{vx1, vy1, vx2, vy2
}
263 Like
\method{vgeodesic()
} but this method returns the path element to
264 connect the two points.
267 % dirty hack to add a whole list of methods to the index:
268 \index{xbasepath()@
\texttt{xbasepath()
} (graphxy method)
}
269 \index{xvbasepath()@
\texttt{xvbasepath()
} (graphxy method)
}
270 \index{xgridpath()@
\texttt{xgridpath()
} (graphxy method)
}
271 \index{xvgridpath()@
\texttt{xvgridpath()
} (graphxy method)
}
272 \index{xtickpoint()@
\texttt{xtickpoint()
} (graphxy method)
}
273 \index{xvtickpoint()@
\texttt{xvtickpoint()
} (graphxy method)
}
274 \index{xtickdirection()@
\texttt{xtickdirection()
} (graphxy method)
}
275 \index{xvtickdirection()@
\texttt{xvtickdirection()
} (graphxy method)
}
276 \index{ybasepath()@
\texttt{ybasepath()
} (graphxy method)
}
277 \index{yvbasepath()@
\texttt{yvbasepath()
} (graphxy method)
}
278 \index{ygridpath()@
\texttt{ygridpath()
} (graphxy method)
}
279 \index{yvgridpath()@
\texttt{yvgridpath()
} (graphxy method)
}
280 \index{ytickpoint()@
\texttt{ytickpoint()
} (graphxy method)
}
281 \index{yvtickpoint()@
\texttt{yvtickpoint()
} (graphxy method)
}
282 \index{ytickdirection()@
\texttt{ytickdirection()
} (graphxy method)
}
283 \index{yvtickdirection()@
\texttt{yvtickdirection()
} (graphxy method)
}
285 Further geometry information is available by the
\member{axespos
}
286 instance variable. Shortcuts to the
\class{axispos
} methods for the
287 \code{x
}- and
\code{y
}-axis become available after
\method{dolayout()
}
288 as
\class{graphxy
} methods
\code{Xbasepath
},
\code{Xvbasepath
},
289 \code{Xgridpath
},
\code{Xvgridpath
},
\code{Xtickpoint
},
290 \code{Xvtickpoint
},
\code{Xtickdirection
}, and
\code{Xvtickdirection
}
291 where the prefix
\code{X
} stands for
\code{x
} and
\code{y
}.
% }}}
293 \section{Module graph/data: Data
} % {{{
296 \declaremodule{}{graph.data
}
297 \modulesynopsis{Graph data
}
299 The following classes provide data for the
\method{plot()
} method of a
300 graph. The classes are implemented in
\module{graph.data
}.
302 \begin{classdesc
}{file
}{filename,
% {{{
303 commentpattern=defaultcommentpattern,
304 columnpattern=defaultcolumnpattern,
305 stringpattern=defaultstringpattern,
306 skiphead=
0, skiptail=
0, every=
1, title=notitle,
307 parser=dataparser(), context=\
{\
}, **columns
}
308 This class reads data from a file and makes them available to the
309 graph system.
\var{filename
} is the name of the file to be read.
310 The data should be organized in columns.
312 The arguments
\var{commentpattern
},
\var{columnpattern
}, and
313 \var{stringpattern
} are responsible for identifying the data in each
314 line of the file. Lines matching
\var{commentpattern
} are ignored
315 except for the column name search of the last non-emtpy comment line
316 before the data. By default a line starting with one of the
317 characters
\character{\#
},
\character{\%
}, or
\character{!
} as well
318 as an empty line is treated as a comment.
320 A non-comment line is analysed by repeatedly matching
321 \var{stringpattern
} and, whenever the stringpattern does not match,
322 by
\var{columnpattern
}. When the
\var{stringpattern
} matches, the
323 result is taken as the value for the next column without further
324 transformations. When
\var{columnpattern
} matches, it is tried to
325 convert the result to a float. When this fails the result is taken
326 as a string as well. By default, you can write strings with spaces
327 surrounded by
\character{\textquotedbl} immediately surrounded by
328 spaces or begin/end of line in the data file. Otherwise
329 \character{\textquotedbl} is not taken to be special.
331 \var{skiphead
} and
\var{skiptail
} are numbers of data lines to be
332 ignored at the beginning and end of the file while
\var{every
}
333 selects only every
\var{every
} line from the data.
335 \var{title
} is the title of the data to be used in the graph key. A
336 default title is constructed out of
\var{filename
} and
337 \var{**columns
}. You may set
\var{title
} to
\code{None
} to disable
340 \var{parser
} is the parser for mathematical expressions provided in
341 \var{**columns
}. When in doubt, this is probably uninteresting for
342 you.
\var{context
} allows for accessing external variables and
343 functions when evaluating mathematical expressions for columns. As
344 an example you may use
\code{context=locals()
} or something similar.
346 Finally,
\var{columns
} defines the data columns. To make it a bit
347 more complicated, there are file column names and new created data
348 column names, namely the keys of the dictionary
\var{**columns
}.
349 Only the later, the data column names, are valid identifiers for the
350 data columns at later usage (by the graph styles).
352 File column names occur when the data file contains a comment line
353 immediately in front of the data (except for empty or empty comment
354 lines). This line will be parsed skipping the matched comment
355 identifier as if the line would be regular data, but it will not be
356 converted to floats even if it would be possible to convert the
357 items. The result is taken as file column names,
\emph{i.e.
} a
358 string representation for the columns in the file.
360 The values of
\var{**columns
} can refer to column numbers in the
361 file starting at
\code{1}. The column
\code{0} is also available
362 and contains the line number starting from
\code{1} not counting
363 comment lines, but lines skiped by
\var{skiphead
},
\var{skiptail
},
364 and
\var{every
}. Furthermore values of
\var{**columns
} can be
365 strings: file column names or complex mathematical expressions. To
366 refer to columns within mathematical expressions you can also use
367 file column names when they are valid variable names or by the
368 syntax
\code{\$
\textless number
\textgreater} or even
369 \code{\$(
\textless expression
\textgreater)
}, where
\code{\textless
370 number
\textgreater} is a non-negative integer and
\code{\textless
371 expression
\textgreater} a valid mathematical expression itself. In
372 those mathematical expressions the
\var{context
} is available, but
373 data from other columns are not. Negative numbers count the columns
374 from the end. Example:
376 graph.data.file("test.dat", a=
1, b="B", c="
2*B+$
3")
378 with
\file{test.dat
} looking like:
384 The columns with name
\code{"a"
},
\code{"b"
},
\code{"c"
} will become
385 \code{"
[1.234,
5.678]"
},
\code{"
[1.0,
3.0]"
}, and
\code{"
[4.0,
386 10.0]"
}, respectively.
388 When creating several data instances accessing the same file,
389 the file is read only once. There is an inherent caching of the
393 For the sake of completeness we list the default patterns:
395 \begin{memberdesc
}{defaultcommentpattern
}
396 \code{re.compile(r
\textquotedbl (\#+|!+|\%+)
\e s*
\textquotedbl)
}
399 \begin{memberdesc
}{defaultcolumnpattern
}
400 \code{re.compile(r
\textquotedbl\e \textquotedbl(.*?)
\e \textquotedbl(
\e s+|\$)
\textquotedbl)
}
403 \begin{memberdesc
}{defaultstringpattern
}
404 \code{re.compile(r
\textquotedbl(.*?)(
\e s+|\$)
\textquotedbl)
}
405 \end{memberdesc
} % }}}
407 \begin{classdesc
}{function
}{expression, title=notitle,
% {{{
408 min=None, max=None, points=
100,
409 parser=mathtree.parser(),
411 This class creates graph data from a function.
\var{expression
} is
412 the mathematical expression of the function. It must also contain
413 the result variable name by assignment. Thus a typical example looks
414 like
\code{"y=sin(x)"
}.
416 \var{title
} is the title of the data to be used in the graph key. By
417 default
\var{expression
} is used. You may set
\var{title
} to
418 \code{None
} to disable the title.
420 \var{min
} and
\var{max
} give the range of the variable. If not set,
421 the range spans the whole axis range. The axis range might be set
422 explicitly or implicitly by ranges of other data.
\var{points
} is
423 the number of points for which the function is calculated. The
424 points are choosen linearly in terms of graph coordinates.
426 \var{parser
} is the parser for the mathematical expression. When in
427 doubt, this is probably uninteresting for you.
\var{context
} allows
428 for accessing external variables and functions. As an example you
429 may use
\code{context=locals()
} or something similar.
431 Note when accessing external variables: In principle, it is unclear,
432 which of the variables should be used as the
433 dependent variable. The solution is, that there should be exactly
434 one variable, which is a valid and used axis name.
437 [graph.data.function("y=x**i", context=locals()) for i in range(
1,
5)
]
439 The result of this expression could just be passed to a graphs
440 \method{plot()
} method, since not only data instances but also lists
441 of data instances are allowed.
442 \end{classdesc
} % }}}
444 \begin{classdesc
}{paramfunction
}{varname, min, max, expression,
% {{{
445 title=notitle, points=
100,
446 parser=mathtree.parser(),
448 This class creates graph data from a parametric function.
449 \var{varname
} is the parameter of the function.
\var{min
} and
450 \var{max
} give the range for that variable.
\var{points
} is the
451 number of points for which the function is calculated. The points
452 are choosen lineary in terms of the parameter.
454 \var{expression
} is the mathematical expression for the parametric
455 function. It contains an assignment of a tuple of functions to a
458 \var{title
} is the title of the data to be used in the graph key. By
459 default
\var{expression
} is used. You may set
\var{title
} to
460 \code{None
} to disable the title.
462 \var{parser
} is the parser for mathematical expressions. When in
463 doubt, this is probably uninteresting for you.
\var{context
} allows
464 for accessing external variables and functions. As an example you
465 may use
\code{context=locals()
} or something similar.
466 \end{classdesc
} % }}}
468 \begin{classdesc
}{list
}{data, title="user provided list",
% {{{
469 addlinenumbers=
1, **columns
}
470 This class creates graph data from externally provided data.
471 \var{data
} is a list of lines, where each line is a list of data
472 values for the columns.
474 \var{title
} is the title of the data to be used in the graph key.
476 The keywords of
\var{**columns
} become the data column names. The
477 values are the column numbers starting from one, when
478 \var{addlinenumbers
} is turned on (the zeroth column is added to
479 contain a line number in that case), while the column numbers starts
480 from zero, when
\var{addlinenumbers
} is switched off.
481 \end{classdesc
} % }}}
483 \begin{classdesc
}{data
}{data, title=notitle, parser=dataparser(),
% {{{
484 context=
{}, **columns
}
485 This class provides graph data out of other graph data.
\var{data
}
486 is the source of the data. All other parameters work like the equally
487 called parameters in
\class{graph.data.file
}. Indeed, the latter is
488 built on top of this class by reading the file and caching its
489 contents in a
\class{graph.data.list
} instance. The columns are then
490 selected by creating new data out of the existing data.
491 \end{classdesc
} % }}}
493 \begin{classdesc
}{conffile
}{filename, title=notitle, parser=dataparser(),
% {{{
494 context=
{}, **columns
}
495 This class reads data from a config file with the file name
496 \var{filename
}. The format of a config file is described within the
497 documentation of the
\module{ConfigParser
} module of the Python
500 Each section of the config file becomes a data line. The options in
501 a section are the columns. The name of the options will be used as
502 file column names. All other parameters work as in
503 \var{graph.data.file
} and
\var{graph.data.data
} since they all use
505 \end{classdesc
} % }}} % }}}
507 \section{Module graph/style: Styles
} % {{{
510 \declaremodule{}{graph.style
}
511 \modulesynopsis{Graph style
}
513 Please note that we are talking about graph styles here. Those are
514 responsible for plotting symbols, lines, bars and whatever else into a
515 graph. Do not mix it up with path styles like the line width, the line
516 style (solid, dashed, dotted
\emph{etc.
}) and others.
518 The following classes provide styles to be used at the
\method{plot()
}
519 method of a graph. The plot method accepts a list of styles. By that
520 you can combine several styles at the very same time.
522 Some of the styles below are hidden styles. Those do not create any
523 output, but they perform internal data handling and thus help on
524 modularization of the styles. Usually, a visible style will depend on
525 data provided by one or more hidden styles but most of the time it is
526 not necessary to specify the hidden styles manually. The hidden styles
527 register themself to be the default for providing certain internal
530 \begin{classdesc
}{pos
}{epsilon=
1e-10} % {{{
531 This class is a hidden style providing a position in the graph. It
532 needs a data column for each graph dimension. For that the column
533 names need to be equal to an axis name. Data points are considered
534 to be out of graph when their position in graph coordinates exceeds
535 the range
[0:
1] by more than
\var{epsilon
}.
536 \end{classdesc
} % }}}
538 \begin{classdesc
}{range
}{usenames=
{}, epsilon=
1e-10} % {{{
539 This class is a hidden style providing an errorbar range. It needs
540 data column names constructed out of a axis name
\code{X
} for each
541 dimension errorbar data should be provided as follows:
542 \begin{tableii
}{l|l
}{}{data name
}{description
}
543 \lineii{\code{Xmin
}}{minimal value
}
544 \lineii{\code{Xmax
}}{maximal value
}
545 \lineii{\code{dX
}}{minimal and maximal delta
}
546 \lineii{\code{dXmin
}}{minimal delta
}
547 \lineii{\code{dXmax
}}{maximal delta
}
549 When delta data are provided the style will also read column data
550 for the axis name
\code{X
} itself.
\var{usenames
} allows to insert a
551 translation dictionary from axis names to the identifiers
\code{X
}.
553 \var{epsilon
} is a comparison precision when checking for invalid
555 \end{classdesc
} % }}}
557 \begin{classdesc
}{symbol
}{symbol=changecross, size=
0.2*unit.v
\_cm,
% {{{
559 This class is a style for plotting symbols in a graph.
560 \var{symbol
} refers to a (changeable) symbol function with the
561 prototype
\code{symbol(c, x
\_pt, y
\_pt, size
\_pt, attrs)
} and draws
562 the symbol into the canvas
\code{c
} at the position
\code{(x
\_pt,
563 y
\_pt)
} with size
\code{size
\_pt} and attributes
\code{attrs
}. Some
564 predefined symbols are available in member variables listed below.
565 The symbol is drawn at size
\var{size
} using
\var{symbolattrs
}.
566 \var{symbolattrs
} is merged with
\code{defaultsymbolattrs
} which is
567 a list containing the decorator
\class{deco.stroked
}. An instance of
568 \class{symbol
} is the default style for all graph data classes
569 described in section~
\ref{graph:data
} except for
\class{function
}
570 and
\class{paramfunction
}.
573 The class
\class{symbol
} provides some symbol functions as member
576 \begin{memberdesc
}{cross
}
577 A cross. Should be used for stroking only.
580 \begin{memberdesc
}{plus
}
581 A plus. Should be used for stroking only.
584 \begin{memberdesc
}{square
}
585 A square. Might be stroked or filled or both.
588 \begin{memberdesc
}{triangle
}
589 A triangle. Might be stroked or filled or both.
592 \begin{memberdesc
}{circle
}
593 A circle. Might be stroked or filled or both.
596 \begin{memberdesc
}{diamond
}
597 A diamond. Might be stroked or filled or both.
600 \class{symbol
} provides some changeable symbol functions as member
603 \begin{memberdesc
}{changecross
}
604 attr.changelist(
[cross, plus, square, triangle, circle, diamond
])
607 \begin{memberdesc
}{changeplus
}
608 attr.changelist(
[plus, square, triangle, circle, diamond, cross
])
611 \begin{memberdesc
}{changesquare
}
612 attr.changelist(
[square, triangle, circle, diamond, cross, plus
])
615 \begin{memberdesc
}{changetriangle
}
616 attr.changelist(
[triangle, circle, diamond, cross, plus, square
])
619 \begin{memberdesc
}{changecircle
}
620 attr.changelist(
[circle, diamond, cross, plus, square, triangle
])
623 \begin{memberdesc
}{changediamond
}
624 attr.changelist(
[diamond, cross, plus, square, triangle, circle
])
627 \begin{memberdesc
}{changesquaretwice
}
628 attr.changelist(
[square, square, triangle, triangle, circle, circle, diamond, diamond
])
631 \begin{memberdesc
}{changetriangletwice
}
632 attr.changelist(
[triangle, triangle, circle, circle, diamond, diamond, square, square
])
635 \begin{memberdesc
}{changecircletwice
}
636 attr.changelist(
[circle, circle, diamond, diamond, square, square, triangle, triangle
])
639 \begin{memberdesc
}{changediamondtwice
}
640 attr.changelist(
[diamond, diamond, square, square, triangle, triangle, circle, circle
])
643 The class
\class{symbol
} provides two changeable decorators for
644 alternated filling and stroking. Those are especially useful in
645 combination with the
\method{change
}-
\method{twice
}-symbol methods
648 \begin{memberdesc
}{changestrokedfilled
}
649 attr.changelist(
[deco.stroked, deco.filled
])
652 \begin{memberdesc
}{changefilledstroked
}
653 attr.changelist(
[deco.filled, deco.stroked
])
654 \end{memberdesc
} % }}}
656 \begin{classdesc
}{line
}{lineattrs=
[]} % {{{
657 This class is a style to stroke lines in a graph.
658 \var{lineattrs
} is merged with
\code{defaultlineattrs
} which is
659 a list containing the member variable
\code{changelinestyle
} as
660 described below. An instance of
\class{line
} is the default style
661 of the graph data classes
\class{function
} and
\class{paramfunction
}
662 described in section~
\ref{graph:data
}.
665 The class
\class{line
} provides a changeable line style. Its
668 \begin{memberdesc
}{changelinestyle
}
669 attr.changelist(
[style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted
])
670 \end{memberdesc
} % }}}
672 \begin{classdesc
}{errorbar
}{size=
0.1*unit.v
\_cm, errorbarattrs=
[],
% {{{
674 This class is a style to stroke errorbars in a graph.
\var{size
} is
675 the size of the caps of the errorbars and
\var{errorbarattrs
} are
676 the stroke attributes. Errorbars and error caps are considered to be
677 out of the graph when their position in graph coordinates exceeds
678 the range
[0:
1] by more that
\var{epsilon
}. Out of graph caps are
679 omitted and the errorbars are cut to the valid graph range.
680 \end{classdesc
} % }}}
682 \begin{classdesc
}{text
}{textname="text",
% {{{
683 textdx=
0*unit.v
\_cm, textdy=
0.3*unit.v
\_cm,
685 This class is a style to stroke text in a graph. The
686 text to be written has to be provided in the data column named
687 \code{textname
}.
\var{textdx
} and
\var{textdy
} are the position of the
688 text with respect to the position in the graph.
\var{textattrs
} are text
689 attributes for the output of the text.
690 \end{classdesc
} % }}}
692 \begin{classdesc
}{arrow
}{linelength=
0.25*unit.v
\_cm,
% {{{
693 arrowsize=
0.15*unit.v
\_cm,
694 lineattrs=
[], arrowattrs=
[],
696 This class is a style to plot short lines with arrows into a
697 two-dimensional graph to a given graph position. The arrow
698 parameters are defined by two additional data columns named
699 \code{size
} and
\code{angle
} define the size and angle for each
700 arrow.
\code{size
} is taken as a factor to
\var{arrowsize
} and
701 \var{linelength
}, the size of the arrow and the length of the line
702 the arrow is plotted at.
\code{angle
} is the angle the arrow points
703 to with respect to a horizontal line. The
\code{angle
} is taken in
704 degrees and used in mathematically positive sense.
\var{lineattrs
}
705 and
\var{arrowattrs
} are styles for the arrow line and arrow head,
706 respectively.
\var{epsilon
} is used as a cutoff for short arrows in
707 order to prevent numerical instabilities.
708 \end{classdesc
} % }}}
710 \begin{classdesc
}{rect
}{palette=
color.palette.Grey
} % {{{
711 This class is a style to plot colored rectangles into a
712 two-dimensional graph. The size of the rectangles is taken from
713 the data provided by the
\class{range
} style. The additional
714 data column named
\code{color} specifies the
color of the rectangle
715 defined by
\var{palette
}. The valid
color range is
[0:
1].
718 Although this style can be used for plotting colored surfaces, it
719 will lead to a huge memory footprint of
\PyX{} together with a
720 long running time and large outputs. Improved support for colored
721 surfaces is planned for the future.
723 \end{classdesc
} % }}}
725 \begin{classdesc
}{barpos
}{fromvalue=None, frompathattrs=
[],
% {{{
726 subnames=None, epsilon=
1e-10}
727 This class is a hidden style providing position information in a bar
728 graph. Those graphs need to contain a specialized axis, namely a bar
729 axis. The data column for this bar axis is named
\code{Xname
} where
730 \code{X
} is an axis name. In the other graph dimension the data
731 column name must be equal to an axis name. When plotting several
732 bars in a single graph, those bars are placed side by side (at the
733 same value of
\code{Xname
}). The name axis, a bar axis, must then be
734 a nested bar axis. The names used for the subaxis can be set by
735 \var{subnames
}. When not set, integer numbers starting from zero
738 The bars start at
\var{fromvalue
} when provided. The
\var{fromvalue
}
739 is marked by a gridline stroked using
\var{frompathattrs
}. Thus this
740 hidden style might actually create some output. The value of a bar
741 axis is considered to be out of graph when its position in graph
742 coordinates exceeds the range
[0:
1] by more than
\var{epsilon
}.
743 \end{classdesc
} % }}}
745 \begin{classdesc
}{stackedbarpos
}{stackname, epsilon=
1e-10} % {{{
746 This class is a hidden style providing position information in a bar
747 graph by stacking a new bar on top of another bar. The value of the
748 new bar is taken from the data column named
\var{stackname
}.
749 \end{classdesc
} % }}}
751 \begin{classdesc
}{bar
}{barattrs=
[]} % {{{
752 This class draws bars in a bar graph. The bars are filled using
753 \var{barattrs
}.
\var{barattrs
} is merged with
\code{defaultbarattrs
}
754 which is a list containing
\code{[color.palette.Rainbow,
755 deco.stroked(
[color.grey.black
])
]}.
756 \end{classdesc
} % }}} % }}}
758 \section{Module graph/key: Keys
} % {{{
761 \declaremodule{}{graph.key
}
762 \modulesynopsis{Graph keys
}
764 The following class provides a key, whose instances can be passed to
765 the constructor keyword argument
\code{key
} of a graph. The class is
766 implemented in
\module{graph.key
}.
768 \begin{classdesc
}{key
}{dist=
0.2*unit.v
\_cm,
769 pos="tr", hpos=None, vpos=None,
770 hinside=
1, vinside=
1,
771 hdist=
0.6*unit.v
\_cm,
772 vdist=
0.4*unit.v
\_cm,
773 symbolwidth=
0.5*unit.v
\_cm,
774 symbolheight=
0.25*unit.v
\_cm,
775 symbolspace=
0.2*unit.v
\_cm,
777 border=
0.3*unit.v
\_cm, keyattrs=None
}
778 This class writes the title of the data in a plot together with a
779 small illustration of the style. The style is responsible for its
782 \var{dist
} is a visual length and a distance between the key
783 entries.
\var{pos
} is the position of the key with respect to the
784 graph. Allowed values are combinations of
\code{"t"
} (top),
785 \code{"m"
} (middle) and
\code{"b"
} (bottom) with
\code{"l"
} (left),
786 \code{"c"
} (center) and
\code{"r"
} (right). Alternatively, you may
787 use
\var{hpos
} and
\var{vpos
} to specify the relative position
788 using the range
[0:
1].
\var{hdist
} and
\var{vdist
} are the distances
789 from the specified corner of the graph.
\var{hinside
} and
790 \var{vinside
} are numbers to be set to
0 or
1 to define whether the
791 key should be placed horizontally and vertically inside of the graph
794 \var{symbolwidth
} and
\var{symbolheight
} are passed to the style to
795 control the size of the style illustration.
\var{symbolspace
} is the
796 space between the illustration and the text.
\var{textattrs
} are
797 attributes for the text creation. They are merged with
798 \code{[text.vshift.mathaxis
]}.
800 When
\var{keyattrs
} is set to contain some draw attributes, the
801 graph key is enlarged by
\var{border
} and the key area is drawn
802 using
\var{keyattrs
}.
803 \end{classdesc
} % }}} % }}}
