3 % workaround for a bug in pdftex 1.21 or in whatever:
4 % the \file macro contains \let\e=\textbackslash and pdfTeX
5 % complains about \e being undefined. ???
8 \section{Introduction
} % {{{
9 \PyX{} can be used for data and function plotting. At present only
10 x-y-graphs are supported. However, the component architecture of the
11 graph system described in section
\ref{graph:components
} allows for
12 additional graph geometries while reusing most of the existing
15 Creating a graph splits into two basic steps. First you have to create
16 a graph instance. The most simple form would look like:
19 g = graph.graphxy(width=
8)
21 The graph instance
\code{g
} created in this example can then be used
22 to actually plot something into the graph. Suppose you have some data
23 in a file
\file{graph.dat
} you want to plot. The content of the file
25 \verbatiminput{graph.dat
}
26 To plot these data into the graph
\code{g
} you must perform:
28 g.plot(graph.data.file("graph.dat", x=
1, y=
2))
30 The method
\method{plot()
} takes the data to be plotted and optionally
31 a list of graph styles to be used to plot the data. When no styles are
32 provided, a default style defined by the data instance is used. For
33 data read from a file by an instance of
\class{graph.data.file
}, the
34 default are symbols. When instantiating
\class{graph.data.file
}, you
35 not only specify the file name, but also a mapping from columns to
36 axis names and other information the styles might make use of
37 (
\emph{e.g.
} data for error bars to be used by the errorbar style).
39 While the graph is already created by that, we still need to perform a
40 write of the result into a file. Since the graph instance is a canvas,
41 we can just call its
\method{writeEPSfile()
} method.
43 g.writeEPSfile("graph")
45 The result
\file{graph.eps
} is shown in figure~
\ref{fig:graph
}.
48 \centerline{\includegraphics{graph
}}
49 \caption{A minimalistic plot for the data from file
\file{graph.dat
}.
}
53 Instead of plotting data from a file, other data source are available
54 as well. For example function data is created and placed into
55 \method{plot()
} by the following line:
57 g.plot(graph.data.function("y(x)=x**
2"))
59 You can plot different data in a single graph by calling
60 \method{plot()
} several times before
\method{writeEPSfile()
} or
61 \method{writePDFfile()
}. Note that a calling
\method{plot()
} will fail
62 once a graph was forced to ``finish'' itself. This happens
63 automatically, when the graph is written to a file. Thus it is not an
64 option to call
\method{plot()
} after
\method{writeEPSfile()
} or
65 \method{writePDFfile()
}. The topic of the finalization of a graph is
66 addressed in more detail in section~
\ref{graph:graph
}. As you can see
67 in figure~
\ref{fig:graph2
}, a function is plotted as a line by
71 \centerline{\includegraphics{graph2
}}
72 \caption{Plotting data from a file together with a function.
}
76 While the axes ranges got adjusted automatically in the previous
77 example, they might be fixed by keyword options in axes constructors.
78 Plotting only a function will need such a setting at least in the
79 variable coordinate. The following code also shows how to set a
80 logathmic axis in y-direction:
82 \verbatiminput{graph3.py
}
84 The result is shown in figure~
\ref{fig:graph3
}.
87 \centerline{\includegraphics{graph3
}}
88 \caption{Plotting a function for a given axis range and use a
93 \section{Component architecture
} % {{{
94 \label{graph:components
}
96 Creating a graph involves a variety of tasks, which thus can be
97 separated into components without significant additional costs.
98 This structure manifests itself also in the
\PyX{} source, where there
99 are different modules for the different tasks. They interact by some
100 well-defined interfaces. They certainly have to be completed and
101 stabilized in their details, but the basic structure came up in the
102 continuous development quite clearly. The basic parts of a graph are:
106 Defines the geometry of the graph by means of graph coordinates with
107 range
[0:
1]. Keeps lists of plotted data, axes
\emph{etc.
}
109 Produces or prepares data to be plotted in graphs.
111 Performs the plotting of the data into the graph. It gets data,
112 converts them via the axes into graph coordinates and uses the graph
113 to finally plot the data with respect to the graph geometry methods.
115 Responsible for the graph keys.
117 Creates axes for the graph, which take care of the mapping from data
118 values to graph coordinates. Because axes are also responsible for
119 creating ticks and labels, showing up in the graph themselves and
120 other things, this task is splitted into several independent
121 subtasks. Axes are discussed separately in chapter~
\ref{axis
}.
122 \end{definitions
} % }}}
124 \section{Module
\module{graph.graph
}: X-Y-Graphs
} % {{{
127 \declaremodule{}{graph.graph
}
128 \modulesynopsis{Graph geometry
}
130 The class
\class{graphxy
} is part of the module
\module{graph.graph
}.
131 However, there is a shortcut to access this class via
132 \code{graph.graphxy
}.
134 \begin{classdesc
}{graphxy
}{xpos=
0, ypos=
0, width=None, height=None,
135 ratio=goldenmean, key=None, backgroundattrs=None,
136 axesdist=
0.8*unit.v
\_cm, xaxisat=None, yaxisat=None, **axes
}
137 This class provides an x-y-graph. A graph instance is also a fully
140 The position of the graph on its own canvas is specified by
141 \var{xpos
} and
\var{ypos
}. The size of the graph is specified by
142 \var{width
},
\var{height
}, and
\var{ratio
}. These parameters define
143 the size of the graph area not taking into account the additional
144 space needed for the axes. Note that you have to specify at least
145 \var{width
} or
\var{height
}.
\var{ratio
} will be used as the ratio
146 between
\var{width
} and
\var{height
} when only one of these is
149 \var{key
} can be set to a
\class{graph.key.key
} instance to create
150 an automatic graph key.
\code{None
} omits the graph key.
152 \var{backgroundattrs
} is a list of attributes for drawing the
153 background of the graph. Allowed are decorators, strokestyles, and
154 fillstyles.
\code{None
} disables background drawing.
156 \var{axisdist
} is the distance between axes drawn at the same side
159 \var{xaxisat
} and
\var{yaxisat
} specify a value at the y and x axis,
160 where the corresponding axis should be moved to. It's a shortcut for
161 corresonding calls of
\method{axisatv()
} described below. Moving an
162 axis by
\var{xaxisat
} or
\var{yaxisat
} disables the automatic
163 creation of a linked axis at the opposite side of the graph.
165 \var{**axes
} receives axes instances. Allowed keywords (axes names)
166 are
\code{x
},
\code{x2
},
\code{x3
},
\emph{etc.
} and
\code{y
},
167 \code{y2
},
\code{y3
},
\emph{etc.
} When not providing an
\code{x
} or
168 \code{y
} axis, linear axes instances will be used automatically.
169 When not providing a
\code{x2
} or
\code{y2
} axis, linked axes to the
170 \code{x
} and
\code{y
} axes are created automatically and
\emph{vice
171 versa
}. As an exception, a linked axis is not created automatically
172 when the axis is placed at a specific position by
\var{xaxisat
} or
173 \var{yaxisat
}. You can disable the automatic creation of axes by
174 setting the linked axes to
\code{None
}. The even numbered axes are
175 plotted at the top (
\code{x
} axes) and right (
\code{y
} axes) while
176 the others are plotted at the bottom (
\code{x
} axes) and left
177 (
\code{y
} axes) in ascending order each.
180 Some instance attributes might be useful for outside read-access.
183 \begin{memberdesc
}{axes
}
184 A dictionary mapping axes names to the
\class{anchoredaxis
} instances.
187 To actually plot something into the graph, the following instance
188 method
\method{plot()
} is provided:
190 \begin{methoddesc
}{plot
}{data, styles=None
}
191 Adds
\var{data
} to the list of data to be plotted. Sets
\var{styles
}
192 to be used for plotting the data. When
\var{styles
} is
\code{None
},
193 the default styles for the data as provided by
\var{data
} is used.
195 \var{data
} should be an instance of any of the data described in
196 section~
\ref{graph:data
}.
198 When the same combination of styles (
\emph{i.e.
} the same
199 references) are used several times within the same graph instance,
200 the styles are kindly asked by the graph to iterate their
201 appearance. Its up to the styles how this is performed.
203 Instead of calling the plot method several times with different
204 \var{data
} but the same style, you can use a list (or something
205 iterateable) for
\var{data
}.
208 While a graph instance only collects data initially, at a certain
209 point it must create the whole plot. Once this is done, further calls
210 of
\method{plot()
} will fail. Usually you do not need to take care
211 about the finalization of the graph, because it happens automatically
212 once you write the plot into a file. However, sometimes position
213 methods (described below) are nice to be accessible. For that, at
214 least the layout of the graph must have been finished. By calling the
215 \method{do
}-methods yourself you can also alter the order in which the
216 graph components are plotted. Multiple calls to any of the
217 \method{do
}-methods have no effect (only the first call counts). The
218 orginal order in which the
\method{do
}-methods are called is:
220 \begin{methoddesc
}{dolayout
}{}
221 Fixes the layout of the graph. As part of this work, the ranges of
222 the axes are fitted to the data when the axes ranges are allowed to
223 adjust themselves to the data ranges. The other
\method{do
}-methods
224 ensure, that this method is always called first.
227 \begin{methoddesc
}{dobackground
}{}
228 Draws the background.
231 \begin{methoddesc
}{doaxes
}{}
235 \begin{methoddesc
}{dodata
}{}
239 \begin{methoddesc
}{dokey
}{}
240 Inserts the graph key.
243 \begin{methoddesc
}{finish
}{}
244 Finishes the graph by calling all pending
\method{do
}-methods. This
245 is done automatically, when the output is created.
248 The graph provides some methods to access its geometry:
250 \begin{methoddesc
}{pos
}{x, y, xaxis=None, yaxis=None
}
251 Returns the given point at
\var{x
} and
\var{y
} as a tuple
252 \code{(xpos, ypos)
} at the graph canvas.
\var{x
} and
\var{y
} are
253 anchoredaxis instances for the two axes
\var{xaxis
} and
\var{yaxis
}.
254 When
\var{xaxis
} or
\var{yaxis
} are
\code{None
}, the axes with names
255 \code{x
} and
\code{y
} are used. This method fails if called before
259 \begin{methoddesc
}{vpos
}{vx, vy
}
260 Returns the given point at
\var{vx
} and
\var{vy
} as a tuple
261 \code{(xpos, ypos)
} at the graph canvas.
\var{vx
} and
\var{vy
} are
262 graph coordinates with range
[0:
1].
265 \begin{methoddesc
}{vgeodesic
}{vx1, vy1, vx2, vy2
}
266 Returns the geodesic between points
\var{vx1
},
\var{vy1
} and
267 \var{vx2
},
\var{vy2
} as a path. All parameters are in graph
268 coordinates with range
[0:
1]. For
\class{graphxy
} this is a straight
272 \begin{methoddesc
}{vgeodesic
\_el}{vx1, vy1, vx2, vy2
}
273 Like
\method{vgeodesic()
} but this method returns the path element to
274 connect the two points.
277 % dirty hack to add a whole list of methods to the index:
278 \index{xbasepath()@
\texttt{xbasepath()
} (graphxy method)
}
279 \index{xvbasepath()@
\texttt{xvbasepath()
} (graphxy method)
}
280 \index{xgridpath()@
\texttt{xgridpath()
} (graphxy method)
}
281 \index{xvgridpath()@
\texttt{xvgridpath()
} (graphxy method)
}
282 \index{xtickpoint()@
\texttt{xtickpoint()
} (graphxy method)
}
283 \index{xvtickpoint()@
\texttt{xvtickpoint()
} (graphxy method)
}
284 \index{xtickdirection()@
\texttt{xtickdirection()
} (graphxy method)
}
285 \index{xvtickdirection()@
\texttt{xvtickdirection()
} (graphxy method)
}
286 \index{ybasepath()@
\texttt{ybasepath()
} (graphxy method)
}
287 \index{yvbasepath()@
\texttt{yvbasepath()
} (graphxy method)
}
288 \index{ygridpath()@
\texttt{ygridpath()
} (graphxy method)
}
289 \index{yvgridpath()@
\texttt{yvgridpath()
} (graphxy method)
}
290 \index{ytickpoint()@
\texttt{ytickpoint()
} (graphxy method)
}
291 \index{yvtickpoint()@
\texttt{yvtickpoint()
} (graphxy method)
}
292 \index{ytickdirection()@
\texttt{ytickdirection()
} (graphxy method)
}
293 \index{yvtickdirection()@
\texttt{yvtickdirection()
} (graphxy method)
}
295 Further geometry information is available by the
\member{axes
}
296 instance variable, with is a dictionary mapping axis names to
297 \class{anchoredaxis
} instances. Shortcuts to the anchoredaxis
298 positioner methods for the
\code{x
}- and
\code{y
}-axis become
299 available after
\method{dolayout()
} as
\class{graphxy
} methods
300 \code{Xbasepath
},
\code{Xvbasepath
},
\code{Xgridpath
},
301 \code{Xvgridpath
},
\code{Xtickpoint
},
\code{Xvtickpoint
},
302 \code{Xtickdirection
}, and
\code{Xvtickdirection
} where the prefix
303 \code{X
} stands for
\code{x
} and
\code{y
}.
305 \begin{methoddesc
}{axistrafo
}{axis, t
}
306 This method can be used to apply a transformation
\var{t
} to an
307 \class{anchoredaxis
} instance
\var{axis
} to modify the axis position
308 and the like. This method fails when called on a not yet finished
309 axis, i.e. it should be used after
\method{dolayout()
}.
312 \begin{methoddesc
}{axisatv
}{axis, v
}
313 This method calls
\method{axistrafo()
} with a transformation to move
314 the axis
\var{axis
} to a graph position
\var{v
} (in graph
316 \end{methoddesc
} % }}}
318 \section{Module
\module{graph.data
}: Data
} % {{{
321 \declaremodule{}{graph.data
}
322 \modulesynopsis{Graph data
}
324 The following classes provide data for the
\method{plot()
} method of a
325 graph. The classes are implemented in
\module{graph.data
}.
327 \begin{classdesc
}{file
}{filename,
% {{{
328 commentpattern=defaultcommentpattern,
329 columnpattern=defaultcolumnpattern,
330 stringpattern=defaultstringpattern,
331 skiphead=
0, skiptail=
0, every=
1, title=notitle,
332 context=\
{\
}, copy=
1,
333 replacedollar=
1, columncallback="
\_\_column\_\_",
335 This class reads data from a file and makes them available to the
336 graph system.
\var{filename
} is the name of the file to be read.
337 The data should be organized in columns.
339 The arguments
\var{commentpattern
},
\var{columnpattern
}, and
340 \var{stringpattern
} are responsible for identifying the data in each
341 line of the file. Lines matching
\var{commentpattern
} are ignored
342 except for the column name search of the last non-empty comment line
343 before the data. By default a line starting with one of the
344 characters
\character{\#
},
\character{\%
}, or
\character{!
} as well
345 as an empty line is treated as a comment.
347 A non-comment line is analysed by repeatedly matching
348 \var{stringpattern
} and, whenever the stringpattern does not match,
349 by
\var{columnpattern
}. When the
\var{stringpattern
} matches, the
350 result is taken as the value for the next column without further
351 transformations. When
\var{columnpattern
} matches, it is tried to
352 convert the result to a float. When this fails the result is taken
353 as a string as well. By default, you can write strings with spaces
354 surrounded by
\character{\textquotedbl} immediately surrounded by
355 spaces or begin/end of line in the data file. Otherwise
356 \character{\textquotedbl} is not taken to be special.
358 \var{skiphead
} and
\var{skiptail
} are numbers of data lines to be
359 ignored at the beginning and end of the file while
\var{every
}
360 selects only every
\var{every
} line from the data.
362 \var{title
} is the title of the data to be used in the graph key. A
363 default title is constructed out of
\var{filename
} and
364 \var{**columns
}. You may set
\var{title
} to
\code{None
} to disable
367 Finally,
\var{columns
} define columns out of the existing columns
368 from the file by a column number or a mathematical expression (see
369 below). When
\var{copy
} is set the names of the columns in the file
370 (file column names) and the freshly created columns having the names
371 of the dictionary key (data column names) are passed as data to the
372 graph styles. The data columns may hide file columns when names are
373 equal. For unset
\var{copy
} the file columns are not available to
376 File column names occur when the data file contains a comment line
377 immediately in front of the data (except for empty or empty comment
378 lines). This line will be parsed skipping the matched comment
379 identifier as if the line would be regular data, but it will not be
380 converted to floats even if it would be possible to convert the
381 items. The result is taken as file column names,
\emph{i.e.
} a
382 string representation for the columns in the file.
384 The values of
\var{**columns
} can refer to column numbers in the
385 file starting at
\code{1}. The column
\code{0} is also available
386 and contains the line number starting from
\code{1} not counting
387 comment lines, but lines skipped by
\var{skiphead
},
\var{skiptail
},
388 and
\var{every
}. Furthermore values of
\var{**columns
} can be
389 strings: file column names or complex mathematical expressions. To
390 refer to columns within mathematical expressions you can also use
391 file column names when they are valid variable identifiers. Equal
392 named items in context will then be hidden. Alternatively columns
393 can be access by the syntax
\code{\$
\textless number
\textgreater}
394 when
\var{replacedollar
} is set. They will be translated into
395 function calls to
\var{columncallback
}, which is a function to
396 access column data by index or name.
398 \var{context
} allows for accessing external variables and functions
399 when evaluating mathematical expressions for columns. Additionally
400 to the identifiers in
\var{context
}, the file column names, the
401 \var{columncallback
} function and the functions shown in the table
402 ``builtins in math expressions'' at the end of the section are
407 graph.data.file("test.dat", a=
1, b="B", c="
2*B+$
3")
409 with
\file{test.dat
} looking like:
415 The columns with name
\code{"a"
},
\code{"b"
},
\code{"c"
} will become
416 \code{"
[1.234,
5.678]"
},
\code{"
[1.0,
3.0]"
}, and
\code{"
[4.0,
417 10.0]"
}, respectively. The columns
\code{"A"
},
\code{"B"
},
418 \code{"C"
} will be available as well, since
\var{copy
} is enabled by
421 When creating several data instances accessing the same file,
422 the file is read only once. There is an inherent caching of the
426 For the sake of completeness we list the default patterns:
428 \begin{memberdesc
}{defaultcommentpattern
}
429 \code{re.compile(r
\textquotedbl (\#+|!+|\%+)
\e s*
\textquotedbl)
}
432 \begin{memberdesc
}{defaultcolumnpattern
}
433 \code{re.compile(r
\textquotedbl\e \textquotedbl(.*?)
\e \textquotedbl(
\e s+|\$)
\textquotedbl)
}
436 \begin{memberdesc
}{defaultstringpattern
}
437 \code{re.compile(r
\textquotedbl(.*?)(
\e s+|\$)
\textquotedbl)
}
438 \end{memberdesc
} % }}}
440 \begin{classdesc
}{function
}{expression, title=notitle,
% {{{
441 min=None, max=None, points=
100,
443 This class creates graph data from a function.
\var{expression
} is
444 the mathematical expression of the function. It must also contain
445 the result variable name including the variable the function depends
446 on by assignment. A typical example looks like
\code{"y(x)=sin(x)"
}.
448 \var{title
} is the title of the data to be used in the graph key. By
449 default
\var{expression
} is used. You may set
\var{title
} to
450 \code{None
} to disable the title.
452 \var{min
} and
\var{max
} give the range of the variable. If not set,
453 the range spans the whole axis range. The axis range might be set
454 explicitly or implicitly by ranges of other data.
\var{points
} is
455 the number of points for which the function is calculated. The
456 points are choosen linearly in terms of graph coordinates.
458 \var{context
} allows for accessing external variables and functions.
459 Additionally to the identifiers in
\var{context
}, the variable name
460 and the functions shown in the table ``builtins in math
461 expressions'' at the end of the section are available.
462 \end{classdesc
} % }}}
464 \begin{classdesc
}{paramfunction
}{varname, min, max, expression,
% {{{
465 title=notitle, points=
100,
467 This class creates graph data from a parametric function.
468 \var{varname
} is the parameter of the function.
\var{min
} and
469 \var{max
} give the range for that variable.
\var{points
} is the
470 number of points for which the function is calculated. The points
471 are choosen lineary in terms of the parameter.
473 \var{expression
} is the mathematical expression for the parametric
474 function. It contains an assignment of a tuple of functions to a
475 tuple of variables. A typical example looks like
476 \code{"x, y = cos(k), sin(k)"
}.
478 \var{title
} is the title of the data to be used in the graph key. By
479 default
\var{expression
} is used. You may set
\var{title
} to
480 \code{None
} to disable the title.
482 \var{context
} allows for accessing external variables and functions.
483 Additionally to the identifiers in
\var{context
},
\var{varname
} and
484 the functions shown in the table ``builtins in math expressions'' at
485 the end of the section are available.
486 \end{classdesc
} % }}}
488 \begin{classdesc
}{values
}{title="user provided values",
% {{{
490 This class creates graph data from externally provided data.
491 Each column is a list of values to be used for that column.
493 \var{title
} is the title of the data to be used in the graph key.
494 \end{classdesc
} % }}}
496 \begin{classdesc
}{points
}{data, title="user provided points",
% {{{
497 addlinenumbers=
1, **columns
}
498 This class creates graph data from externally provided data.
499 \var{data
} is a list of lines, where each line is a list of data
500 values for the columns.
502 \var{title
} is the title of the data to be used in the graph key.
504 The keywords of
\var{**columns
} become the data column names. The
505 values are the column numbers starting from one, when
506 \var{addlinenumbers
} is turned on (the zeroth column is added to
507 contain a line number in that case), while the column numbers starts
508 from zero, when
\var{addlinenumbers
} is switched off.
509 \end{classdesc
} % }}}
511 \begin{classdesc
}{data
}{data, title=notitle, context=
{}, copy=
1,
% {{{
512 replacedollar=
1, columncallback="
\_\_column\_\_", **columns
}
513 This class provides graph data out of other graph data.
\var{data
}
514 is the source of the data. All other parameters work like the equally
515 called parameters in
\class{graph.data.file
}. Indeed, the latter is
516 built on top of this class by reading the file and caching its
517 contents in a
\class{graph.data.list
} instance.
518 \end{classdesc
} % }}}
520 \begin{classdesc
}{conffile
}{filename, title=notitle, context=
{}, copy=
1,
% {{{
521 replacedollar=
1, columncallback="
\_\_column\_\_", **columns
}
522 This class reads data from a config file with the file name
523 \var{filename
}. The format of a config file is described within the
524 documentation of the
\module{ConfigParser
} module of the Python
527 Each section of the config file becomes a data line. The options in
528 a section are the columns. The name of the options will be used as
529 file column names. All other parameters work as in
530 \var{graph.data.file
} and
\var{graph.data.data
} since they all use
532 \end{classdesc
} % }}}
534 \begin{classdesc
}{cbdfile
}{filename, minrank=None, maxrank=None,
% {{{
535 title=notitle, context=
{}, copy=
1,
536 replacedollar=
1, columncallback="
\_\_column\_\_", **columns
}
537 This is an experimental class to read map data from cbd-files. See
538 \url{http://sepwww.stanford.edu/ftp/World_Map/
} for some world-map
540 \end{classdesc
} % }}}
542 The builtins in math expressions are listed in the following table:
543 \begin{tableii
}{l|l
}{textrm
}{name
}{value
}
544 \code{neg
}&
\code{lambda x: -x
}\\
545 \code{abs
}&
\code{lambda x: x <
0 and -x or x
}\\
546 \code{sgn
}&
\code{lambda x: x <
0 and -
1 or
1}\\
547 \code{sqrt
}&
\code{math.sqrt
}\\
548 \code{exp
}&
\code{math.exp
}\\
549 \code{log
}&
\code{math.log
}\\
550 \code{sin
}&
\code{math.sin
}\\
551 \code{cos
}&
\code{math.cos
}\\
552 \code{tan
}&
\code{math.tan
}\\
553 \code{asin
}&
\code{math.asin
}\\
554 \code{acos
}&
\code{math.acos
}\\
555 \code{atan
}&
\code{math.atan
}\\
556 \code{sind
}&
\code{lambda x: math.sin(math.pi/
180*x)
}\\
557 \code{cosd
}&
\code{lambda x: math.cos(math.pi/
180*x)
}\\
558 \code{tand
}&
\code{lambda x: math.tan(math.pi/
180*x)
}\\
559 \code{asind
}&
\code{lambda x:
180/math.pi*math.asin(x)
}\\
560 \code{acosd
}&
\code{lambda x:
180/math.pi*math.acos(x)
}\\
561 \code{atand
}&
\code{lambda x:
180/math.pi*math.atan(x)
}\\
562 \code{norm
}&
\code{lambda x, y: math.hypot(x, y)
}\\
563 \code{splitatvalue
}&see the
\code{splitatvalue
} description below\\
564 \code{pi
}&
\code{math.pi
}\\
565 \code{e
}&
\code{math.e
}
567 \code{math
} refers to Pythons
\module{math
} module. The
568 \code{splitatvalue
} function is defined as:
570 \begin{funcdesc
}{splitatvalue
}{value, *splitpoints
}
571 This method returns a tuple
\code{(section,
\var{value
})
}.
572 The section is calculated by comparing
\var{value
} with the values
573 of
{splitpoints
}. If
\var{splitpoints
} contains only a single item,
574 \code{section
} is
\code{0} when value is lower or equal this item
575 and
\code{1} else. For multiple splitpoints,
\code{section
} is
576 \code{0} when its lower or equal the first item,
\code{None
} when
577 its bigger than the first item but lower or equal the second item,
578 \code{1} when its even bigger the second item, but lower or equal
579 the third item. It continues to alter between
\code{None
} and
580 \code{2},
\code{3}, etc.
585 \section{Module
\module{graph.style
}: Styles
} % {{{
588 \declaremodule{}{graph.style
}
589 \modulesynopsis{Graph style
}
591 Please note that we are talking about graph styles here. Those are
592 responsible for plotting symbols, lines, bars and whatever else into a
593 graph. Do not mix it up with path styles like the line width, the line
594 style (solid, dashed, dotted
\emph{etc.
}) and others.
596 The following classes provide styles to be used at the
\method{plot()
}
597 method of a graph. The plot method accepts a list of styles. By that
598 you can combine several styles at the very same time.
600 Some of the styles below are hidden styles. Those do not create any
601 output, but they perform internal data handling and thus help on
602 modularization of the styles. Usually, a visible style will depend on
603 data provided by one or more hidden styles but most of the time it is
604 not necessary to specify the hidden styles manually. The hidden styles
605 register themself to be the default for providing certain internal
608 \begin{classdesc
}{pos
}{epsilon=
1e-10} % {{{
609 This class is a hidden style providing a position in the graph. It
610 needs a data column for each graph dimension. For that the column
611 names need to be equal to an axis name. Data points are considered
612 to be out of graph when their position in graph coordinates exceeds
613 the range
[0:
1] by more than
\var{epsilon
}.
614 \end{classdesc
} % }}}
616 \begin{classdesc
}{range
}{usenames=
{}, epsilon=
1e-10} % {{{
617 This class is a hidden style providing an errorbar range. It needs
618 data column names constructed out of a axis name
\code{X
} for each
619 dimension errorbar data should be provided as follows:
620 \begin{tableii
}{l|l
}{}{data name
}{description
}
621 \lineii{\code{Xmin
}}{minimal value
}
622 \lineii{\code{Xmax
}}{maximal value
}
623 \lineii{\code{dX
}}{minimal and maximal delta
}
624 \lineii{\code{dXmin
}}{minimal delta
}
625 \lineii{\code{dXmax
}}{maximal delta
}
627 When delta data are provided the style will also read column data
628 for the axis name
\code{X
} itself.
\var{usenames
} allows to insert a
629 translation dictionary from axis names to the identifiers
\code{X
}.
631 \var{epsilon
} is a comparison precision when checking for invalid
633 \end{classdesc
} % }}}
635 \begin{classdesc
}{symbol
}{symbol=changecross, size=
0.2*unit.v
\_cm,
% {{{
637 This class is a style for plotting symbols in a graph.
638 \var{symbol
} refers to a (changeable) symbol function with the
639 prototype
\code{symbol(c, x
\_pt, y
\_pt, size
\_pt, attrs)
} and draws
640 the symbol into the canvas
\code{c
} at the position
\code{(x
\_pt,
641 y
\_pt)
} with size
\code{size
\_pt} and attributes
\code{attrs
}. Some
642 predefined symbols are available in member variables listed below.
643 The symbol is drawn at size
\var{size
} using
\var{symbolattrs
}.
644 \var{symbolattrs
} is merged with
\code{defaultsymbolattrs
} which is
645 a list containing the decorator
\class{deco.stroked
}. An instance of
646 \class{symbol
} is the default style for all graph data classes
647 described in section~
\ref{graph:data
} except for
\class{function
}
648 and
\class{paramfunction
}.
651 The class
\class{symbol
} provides some symbol functions as member
654 \begin{memberdesc
}{cross
}
655 A cross. Should be used for stroking only.
658 \begin{memberdesc
}{plus
}
659 A plus. Should be used for stroking only.
662 \begin{memberdesc
}{square
}
663 A square. Might be stroked or filled or both.
666 \begin{memberdesc
}{triangle
}
667 A triangle. Might be stroked or filled or both.
670 \begin{memberdesc
}{circle
}
671 A circle. Might be stroked or filled or both.
674 \begin{memberdesc
}{diamond
}
675 A diamond. Might be stroked or filled or both.
678 \class{symbol
} provides some changeable symbol functions as member
681 \begin{memberdesc
}{changecross
}
682 attr.changelist(
[cross, plus, square, triangle, circle, diamond
])
685 \begin{memberdesc
}{changeplus
}
686 attr.changelist(
[plus, square, triangle, circle, diamond, cross
])
689 \begin{memberdesc
}{changesquare
}
690 attr.changelist(
[square, triangle, circle, diamond, cross, plus
])
693 \begin{memberdesc
}{changetriangle
}
694 attr.changelist(
[triangle, circle, diamond, cross, plus, square
])
697 \begin{memberdesc
}{changecircle
}
698 attr.changelist(
[circle, diamond, cross, plus, square, triangle
])
701 \begin{memberdesc
}{changediamond
}
702 attr.changelist(
[diamond, cross, plus, square, triangle, circle
])
705 \begin{memberdesc
}{changesquaretwice
}
706 attr.changelist(
[square, square, triangle, triangle, circle, circle, diamond, diamond
])
709 \begin{memberdesc
}{changetriangletwice
}
710 attr.changelist(
[triangle, triangle, circle, circle, diamond, diamond, square, square
])
713 \begin{memberdesc
}{changecircletwice
}
714 attr.changelist(
[circle, circle, diamond, diamond, square, square, triangle, triangle
])
717 \begin{memberdesc
}{changediamondtwice
}
718 attr.changelist(
[diamond, diamond, square, square, triangle, triangle, circle, circle
])
721 The class
\class{symbol
} provides two changeable decorators for
722 alternated filling and stroking. Those are especially useful in
723 combination with the
\method{change
}-
\method{twice
}-symbol methods
726 \begin{memberdesc
}{changestrokedfilled
}
727 attr.changelist(
[deco.stroked, deco.filled
])
730 \begin{memberdesc
}{changefilledstroked
}
731 attr.changelist(
[deco.filled, deco.stroked
])
732 \end{memberdesc
} % }}}
734 \begin{classdesc
}{line
}{lineattrs=
[]} % {{{
735 This class is a style to stroke lines in a graph.
736 \var{lineattrs
} is merged with
\code{defaultlineattrs
} which is
737 a list containing the member variable
\code{changelinestyle
} as
738 described below. An instance of
\class{line
} is the default style
739 of the graph data classes
\class{function
} and
\class{paramfunction
}
740 described in section~
\ref{graph:data
}.
743 The class
\class{line
} provides a changeable line style. Its
746 \begin{memberdesc
}{changelinestyle
}
747 attr.changelist(
[style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted
])
748 \end{memberdesc
} % }}}
750 \begin{classdesc
}{impulses
}{lineattrs=
[], fromvalue=
0,
% {{{
751 frompathattrs=
[], valueaxisindex=
1}
752 This class is a style to plot impulses.
\var{lineattrs
} is merged
753 with
\code{defaultlineattrs
} which is a list containing the member
754 variable
\code{changelinestyle
} as described above.
\var{fromvalue
}
755 is the baseline value of the impulses. When set to
\code{None
}, the
756 impulses will start at the baseline. When fromvalue is set,
757 \var{frompathattrs
} are the stroke attributes used to show the
758 impulses baseline path.
759 \end{classdesc
} % }}}
761 \begin{classdesc
}{errorbar
}{size=
0.1*unit.v
\_cm, errorbarattrs=
[],
% {{{
763 This class is a style to stroke errorbars in a graph.
\var{size
} is
764 the size of the caps of the errorbars and
\var{errorbarattrs
} are
765 the stroke attributes. Errorbars and error caps are considered to be
766 out of the graph when their position in graph coordinates exceeds
767 the range
[0:
1] by more that
\var{epsilon
}. Out of graph caps are
768 omitted and the errorbars are cut to the valid graph range.
769 \end{classdesc
} % }}}
771 \begin{classdesc
}{text
}{textname="text", dxname=None, dyname=None,
% {{{
772 dxunit=
0.3*unit.v
\_cm, dyunit=
0.3*unit.v
\_cm,
773 textdx=
0*unit.v
\_cm, textdy=
0.3*unit.v
\_cm,
775 This class is a style to stroke text in a graph. The
776 text to be written has to be provided in the data column named
777 \code{textname
}.
\var{textdx
} and
\var{textdy
} are the position of the
778 text with respect to the position in the graph. Alternatively you can
779 specify a
\code{dxname
} and a
\code{dyname
} and provide appropriate
780 data in those columns to be taken in units of
\var{dxunit
} and
781 \var{dyunit
} to specify the position of the text for each point
782 separately.
\var{textattrs
} are text attributes for the output of
783 the text. Those attributes are merged with the default attributes
784 \code{textmodule.halign.center
} and
\code{textmodule.vshift.mathaxis
}.
785 \end{classdesc
} % }}}
787 \begin{classdesc
}{arrow
}{linelength=
0.25*unit.v
\_cm,
% {{{
788 arrowsize=
0.15*unit.v
\_cm,
789 lineattrs=
[], arrowattrs=
[], arrowpos=
0.5,
791 This class is a style to plot short lines with arrows into a
792 two-dimensional graph to a given graph position. The arrow
793 parameters are defined by two additional data columns named
794 \code{size
} and
\code{angle
} define the size and angle for each
795 arrow.
\code{size
} is taken as a factor to
\var{arrowsize
} and
796 \var{linelength
}, the size of the arrow and the length of the line
797 the arrow is plotted at.
\code{angle
} is the angle the arrow points
798 to with respect to a horizontal line. The
\code{angle
} is taken in
799 degrees and used in mathematically positive sense.
\var{lineattrs
}
800 and
\var{arrowattrs
} are styles for the arrow line and arrow head,
801 respectively.
\var{arrowpos
} defines the position of the arrow line
802 with respect to the position at the graph. The default
\code{0.5}
803 means centered at the graph position, whereas
\code{0} and
\code{1}
804 creates the arrows to start or end at the graph position,
805 respectively.
\var{epsilon
} is used as a cutoff for short arrows in
806 order to prevent numerical instabilities.
807 \end{classdesc
} % }}}
809 \begin{classdesc
}{rect
}{gradient=
color.gradient.Grey
} % {{{
810 This class is a style to plot colored rectangles into a
811 two-dimensional graph. The size of the rectangles is taken from
812 the data provided by the
\class{range
} style. The additional
813 data column named
\code{color} specifies the
color of the rectangle
814 defined by
\var{gradient
}. The valid
color range is
[0:
1].
817 Although this style can be used for plotting colored surfaces, it
818 will lead to a huge memory footprint of
\PyX{} together with a
819 long running time and large outputs. Improved support for colored
820 surfaces is planned for the future.
822 \end{classdesc
} % }}}
824 \begin{classdesc
}{histogram
}{lineattrs=
[], steps=
0, fromvalue=
0,
% {{{
825 frompathattrs=
[], fillable=
0, rectkey=
0,
826 autohistogramaxisindex=
0,
827 autohistogrampointpos=
0.5, epsilon=
1e-10}
828 This class is a style to plot histograms.
\var{lineattrs
} is merged
829 with
\code{defaultlineattrs
} which is
\code{[deco.stroked
]}. When
830 \var{steps
} is set, the histrogram is plotted as steps instead of
831 the default being a boxed histogram.
\var{fromvalue
} is the baseline
832 value of the histogram. When set to
\code{None
}, the histogram will
833 start at the baseline. When fromvalue is set,
\var{frompathattrs
}
834 are the stroke attributes used to show the histogram baseline path.
836 The
\var{fillable
} flag changes the stoke line of the histogram to
837 make it fillable properly. This is important on non-steped
838 histograms or on histograms, which hit the graph boundary.
839 \var{rectkey
} can be set to generate a rectanglar area instead of a
840 line in the graph key.
842 Usually, a histogram wants a range specification (like for an
843 errorbar) in one graph dimension and a value for the other graph
844 dimension. By that, the widths of the histogram boxes might be
845 variable. But a typical use case is, that you just provide graph
846 positions for both graph dimensions. Then
847 \var{autohistogramaxisindex
} defines the graph dimension where the
848 histogram should be plotted on top of it. (
\code{0} thus means a
849 histogram at the x axes and
\code{1} for the y axes.) The style will
850 then demand equal spaced values on this axis. The histogram boxes
851 are usually centered on those values for
\var{autohistogrampointpos
}
852 equals
\code{0.5}, but they can also be aligned at the right side or
853 left side of this value for
\var{autohistogrampointpos
} being
854 \code{0} or
\code{1}.
856 Positions of the histograms are considered to be out of graph when
857 they exceed the graph coordinate range
[0:
1] by more than
859 \end{classdesc
} % }}}
861 \begin{classdesc
}{barpos
}{fromvalue=None, frompathattrs=
[], epsilon=
1e-10} % {{{
862 This class is a hidden style providing position information in a bar
863 graph. Those graphs need to contain a specialized axis, namely a bar
864 axis. The data column for this bar axis is named
\code{Xname
} where
865 \code{X
} is an axis name. In the other graph dimension the data
866 column name must be equal to an axis name. To plot several bars in a
867 single graph side by side, you need to have a nested bar axis and
868 provide a tuple as data for nested bar axis.
870 The bars start at
\var{fromvalue
} when provided. The
\var{fromvalue
}
871 is marked by a gridline stroked using
\var{frompathattrs
}. Thus this
872 hidden style might actually create some output. The value of a bar
873 axis is considered to be out of graph when its position in graph
874 coordinates exceeds the range
[0:
1] by more than
\var{epsilon
}.
875 \end{classdesc
} % }}}
877 \begin{classdesc
}{stackedbarpos
}{stackname, addontop=
0, epsilon=
1e-10} % {{{
878 This class is a hidden style providing position information in a bar
879 graph by stacking a new bar on top of another bar. The value of the
880 new bar is taken from the data column named
\var{stackname
}. When
881 \var{addontop
} is set, the values is taken relative to the previous
883 \end{classdesc
} % }}}
885 \begin{classdesc
}{bar
}{barattrs=
[]} % {{{
886 This class draws bars in a bar graph. The bars are filled using
887 \var{barattrs
}.
\var{barattrs
} is merged with
\code{defaultbarattrs
}
888 which is a list containing
\code{[color.gradient.Rainbow,
889 deco.stroked(
[color.grey.black
])
]}.
890 \end{classdesc
} % }}}
892 \begin{classdesc
}{changebar
}{barattrs=
[]} % {{{
893 This style works like the
\class{bar
} style, but instead of the
894 \var{barattrs
} to be changed on subsequent data instances the
895 \var{barattrs
} are changed for each value within a single data
896 instance. In the result the style can't be applied to several data
897 instances. The style raises an error instead.
898 \end{classdesc
} % }}} % }}}
900 \section{Module
\module{graph.key
}: Keys
} % {{{
903 \declaremodule{}{graph.key
}
904 \modulesynopsis{Graph keys
}
906 The following class provides a key, whose instances can be passed to
907 the constructor keyword argument
\code{key
} of a graph. The class is
908 implemented in
\module{graph.key
}.
910 \begin{classdesc
}{key
}{dist=
0.2*unit.v
\_cm,
911 pos="tr", hpos=None, vpos=None,
912 hinside=
1, vinside=
1,
913 hdist=
0.6*unit.v
\_cm,
914 vdist=
0.4*unit.v
\_cm,
915 symbolwidth=
0.5*unit.v
\_cm,
916 symbolheight=
0.25*unit.v
\_cm,
917 symbolspace=
0.2*unit.v
\_cm,
919 columns=
1, columndist=
0.5*unit.v
\_cm,
920 border=
0.3*unit.v
\_cm, keyattrs=None
}
921 This class writes the title of the data in a plot together with a
922 small illustration of the style. The style is responsible for its
925 \var{dist
} is a visual length and a distance between the key
926 entries.
\var{pos
} is the position of the key with respect to the
927 graph. Allowed values are combinations of
\code{"t"
} (top),
928 \code{"m"
} (middle) and
\code{"b"
} (bottom) with
\code{"l"
} (left),
929 \code{"c"
} (center) and
\code{"r"
} (right). Alternatively, you may
930 use
\var{hpos
} and
\var{vpos
} to specify the relative position
931 using the range
[0:
1].
\var{hdist
} and
\var{vdist
} are the distances
932 from the specified corner of the graph.
\var{hinside
} and
933 \var{vinside
} are numbers to be set to
0 or
1 to define whether the
934 key should be placed horizontally and vertically inside of the graph
937 \var{symbolwidth
} and
\var{symbolheight
} are passed to the style to
938 control the size of the style illustration.
\var{symbolspace
} is the
939 space between the illustration and the text.
\var{textattrs
} are
940 attributes for the text creation. They are merged with
941 \code{[text.vshift.mathaxis
]}.
943 \var{columns
} is a number of columns of the graph key and
944 \var{columndist
} is the distance between those columns.
946 When
\var{keyattrs
} is set to contain some draw attributes, the
947 graph key is enlarged by
\var{border
} and the key area is drawn
948 using
\var{keyattrs
}.
949 \end{classdesc
} % }}} % }}}
