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
}{list
}{data, title="user provided list",
% {{{
489 addlinenumbers=
1, **columns
}
490 This class creates graph data from externally provided data.
491 \var{data
} is a list of lines, where each line is a list of data
492 values for the columns.
494 \var{title
} is the title of the data to be used in the graph key.
496 The keywords of
\var{**columns
} become the data column names. The
497 values are the column numbers starting from one, when
498 \var{addlinenumbers
} is turned on (the zeroth column is added to
499 contain a line number in that case), while the column numbers starts
500 from zero, when
\var{addlinenumbers
} is switched off.
501 \end{classdesc
} % }}}
503 \begin{classdesc
}{data
}{data, title=notitle, context=
{}, copy=
1,
% {{{
504 replacedollar=
1, columncallback="
\_\_column\_\_", **columns
}
505 This class provides graph data out of other graph data.
\var{data
}
506 is the source of the data. All other parameters work like the equally
507 called parameters in
\class{graph.data.file
}. Indeed, the latter is
508 built on top of this class by reading the file and caching its
509 contents in a
\class{graph.data.list
} instance.
510 \end{classdesc
} % }}}
512 \begin{classdesc
}{conffile
}{filename, title=notitle, context=
{}, copy=
1,
% {{{
513 replacedollar=
1, columncallback="
\_\_column\_\_", **columns
}
514 This class reads data from a config file with the file name
515 \var{filename
}. The format of a config file is described within the
516 documentation of the
\module{ConfigParser
} module of the Python
519 Each section of the config file becomes a data line. The options in
520 a section are the columns. The name of the options will be used as
521 file column names. All other parameters work as in
522 \var{graph.data.file
} and
\var{graph.data.data
} since they all use
524 \end{classdesc
} % }}}
526 \begin{classdesc
}{cbdfile
}{filename, minrank=None, maxrank=None,
% {{{
527 title=notitle, context=
{}, copy=
1,
528 replacedollar=
1, columncallback="
\_\_column\_\_", **columns
}
529 This is an experimental class to read map data from cbd-files. See
530 \url{http://sepwww.stanford.edu/ftp/World_Map/
} for some world-map
532 \end{classdesc
} % }}}
534 The builtins in math expressions are listed in the following table:
535 \begin{tableii
}{l|l
}{textrm
}{name
}{value
}
536 \code{neg
}&
\code{lambda x: -x
}\\
537 \code{abs
}&
\code{lambda x: x <
0 and -x or x
}\\
538 \code{sgn
}&
\code{lambda x: x <
0 and -
1 or
1}\\
539 \code{sqrt
}&
\code{math.sqrt
}\\
540 \code{exp
}&
\code{math.exp
}\\
541 \code{log
}&
\code{math.log
}\\
542 \code{sin
}&
\code{math.sin
}\\
543 \code{cos
}&
\code{math.cos
}\\
544 \code{tan
}&
\code{math.tan
}\\
545 \code{asin
}&
\code{math.asin
}\\
546 \code{acos
}&
\code{math.acos
}\\
547 \code{atan
}&
\code{math.atan
}\\
548 \code{sind
}&
\code{lambda x: math.sin(math.pi/
180*x)
}\\
549 \code{cosd
}&
\code{lambda x: math.cos(math.pi/
180*x)
}\\
550 \code{tand
}&
\code{lambda x: math.tan(math.pi/
180*x)
}\\
551 \code{asind
}&
\code{lambda x:
180/math.pi*math.asin(x)
}\\
552 \code{acosd
}&
\code{lambda x:
180/math.pi*math.acos(x)
}\\
553 \code{atand
}&
\code{lambda x:
180/math.pi*math.atan(x)
}\\
554 \code{norm
}&
\code{lambda x, y: math.hypot(x, y)
}\\
555 \code{splitatvalue
}&see the
\code{splitatvalue
} description below\\
556 \code{pi
}&
\code{math.pi
}\\
557 \code{e
}&
\code{math.e
}
559 \code{math
} refers to Pythons
\module{math
} module. The
560 \code{splitatvalue
} function is defined as:
562 \begin{funcdesc
}{splitatvalue
}{value, *splitpoints
}
563 This method returns a tuple
\code{(section,
\var{value
})
}.
564 The section is calculated by comparing
\var{value
} with the values
565 of
{splitpoints
}. If
\var{splitpoints
} contains only a single item,
566 \code{section
} is
\code{0} when value is lower or equal this item
567 and
\code{1} else. For multiple splitpoints,
\code{section
} is
568 \code{0} when its lower or equal the first item,
\code{None
} when
569 its bigger than the first item but lower or equal the second item,
570 \code{1} when its even bigger the second item, but lower or equal
571 the third item. It continues to alter between
\code{None
} and
572 \code{2},
\code{3}, etc.
577 \section{Module
\module{graph.style
}: Styles
} % {{{
580 \declaremodule{}{graph.style
}
581 \modulesynopsis{Graph style
}
583 Please note that we are talking about graph styles here. Those are
584 responsible for plotting symbols, lines, bars and whatever else into a
585 graph. Do not mix it up with path styles like the line width, the line
586 style (solid, dashed, dotted
\emph{etc.
}) and others.
588 The following classes provide styles to be used at the
\method{plot()
}
589 method of a graph. The plot method accepts a list of styles. By that
590 you can combine several styles at the very same time.
592 Some of the styles below are hidden styles. Those do not create any
593 output, but they perform internal data handling and thus help on
594 modularization of the styles. Usually, a visible style will depend on
595 data provided by one or more hidden styles but most of the time it is
596 not necessary to specify the hidden styles manually. The hidden styles
597 register themself to be the default for providing certain internal
600 \begin{classdesc
}{pos
}{epsilon=
1e-10} % {{{
601 This class is a hidden style providing a position in the graph. It
602 needs a data column for each graph dimension. For that the column
603 names need to be equal to an axis name. Data points are considered
604 to be out of graph when their position in graph coordinates exceeds
605 the range
[0:
1] by more than
\var{epsilon
}.
606 \end{classdesc
} % }}}
608 \begin{classdesc
}{range
}{usenames=
{}, epsilon=
1e-10} % {{{
609 This class is a hidden style providing an errorbar range. It needs
610 data column names constructed out of a axis name
\code{X
} for each
611 dimension errorbar data should be provided as follows:
612 \begin{tableii
}{l|l
}{}{data name
}{description
}
613 \lineii{\code{Xmin
}}{minimal value
}
614 \lineii{\code{Xmax
}}{maximal value
}
615 \lineii{\code{dX
}}{minimal and maximal delta
}
616 \lineii{\code{dXmin
}}{minimal delta
}
617 \lineii{\code{dXmax
}}{maximal delta
}
619 When delta data are provided the style will also read column data
620 for the axis name
\code{X
} itself.
\var{usenames
} allows to insert a
621 translation dictionary from axis names to the identifiers
\code{X
}.
623 \var{epsilon
} is a comparison precision when checking for invalid
625 \end{classdesc
} % }}}
627 \begin{classdesc
}{symbol
}{symbol=changecross, size=
0.2*unit.v
\_cm,
% {{{
629 This class is a style for plotting symbols in a graph.
630 \var{symbol
} refers to a (changeable) symbol function with the
631 prototype
\code{symbol(c, x
\_pt, y
\_pt, size
\_pt, attrs)
} and draws
632 the symbol into the canvas
\code{c
} at the position
\code{(x
\_pt,
633 y
\_pt)
} with size
\code{size
\_pt} and attributes
\code{attrs
}. Some
634 predefined symbols are available in member variables listed below.
635 The symbol is drawn at size
\var{size
} using
\var{symbolattrs
}.
636 \var{symbolattrs
} is merged with
\code{defaultsymbolattrs
} which is
637 a list containing the decorator
\class{deco.stroked
}. An instance of
638 \class{symbol
} is the default style for all graph data classes
639 described in section~
\ref{graph:data
} except for
\class{function
}
640 and
\class{paramfunction
}.
643 The class
\class{symbol
} provides some symbol functions as member
646 \begin{memberdesc
}{cross
}
647 A cross. Should be used for stroking only.
650 \begin{memberdesc
}{plus
}
651 A plus. Should be used for stroking only.
654 \begin{memberdesc
}{square
}
655 A square. Might be stroked or filled or both.
658 \begin{memberdesc
}{triangle
}
659 A triangle. Might be stroked or filled or both.
662 \begin{memberdesc
}{circle
}
663 A circle. Might be stroked or filled or both.
666 \begin{memberdesc
}{diamond
}
667 A diamond. Might be stroked or filled or both.
670 \class{symbol
} provides some changeable symbol functions as member
673 \begin{memberdesc
}{changecross
}
674 attr.changelist(
[cross, plus, square, triangle, circle, diamond
])
677 \begin{memberdesc
}{changeplus
}
678 attr.changelist(
[plus, square, triangle, circle, diamond, cross
])
681 \begin{memberdesc
}{changesquare
}
682 attr.changelist(
[square, triangle, circle, diamond, cross, plus
])
685 \begin{memberdesc
}{changetriangle
}
686 attr.changelist(
[triangle, circle, diamond, cross, plus, square
])
689 \begin{memberdesc
}{changecircle
}
690 attr.changelist(
[circle, diamond, cross, plus, square, triangle
])
693 \begin{memberdesc
}{changediamond
}
694 attr.changelist(
[diamond, cross, plus, square, triangle, circle
])
697 \begin{memberdesc
}{changesquaretwice
}
698 attr.changelist(
[square, square, triangle, triangle, circle, circle, diamond, diamond
])
701 \begin{memberdesc
}{changetriangletwice
}
702 attr.changelist(
[triangle, triangle, circle, circle, diamond, diamond, square, square
])
705 \begin{memberdesc
}{changecircletwice
}
706 attr.changelist(
[circle, circle, diamond, diamond, square, square, triangle, triangle
])
709 \begin{memberdesc
}{changediamondtwice
}
710 attr.changelist(
[diamond, diamond, square, square, triangle, triangle, circle, circle
])
713 The class
\class{symbol
} provides two changeable decorators for
714 alternated filling and stroking. Those are especially useful in
715 combination with the
\method{change
}-
\method{twice
}-symbol methods
718 \begin{memberdesc
}{changestrokedfilled
}
719 attr.changelist(
[deco.stroked, deco.filled
])
722 \begin{memberdesc
}{changefilledstroked
}
723 attr.changelist(
[deco.filled, deco.stroked
])
724 \end{memberdesc
} % }}}
726 \begin{classdesc
}{line
}{lineattrs=
[]} % {{{
727 This class is a style to stroke lines in a graph.
728 \var{lineattrs
} is merged with
\code{defaultlineattrs
} which is
729 a list containing the member variable
\code{changelinestyle
} as
730 described below. An instance of
\class{line
} is the default style
731 of the graph data classes
\class{function
} and
\class{paramfunction
}
732 described in section~
\ref{graph:data
}.
735 The class
\class{line
} provides a changeable line style. Its
738 \begin{memberdesc
}{changelinestyle
}
739 attr.changelist(
[style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted
])
740 \end{memberdesc
} % }}}
742 \begin{classdesc
}{errorbar
}{size=
0.1*unit.v
\_cm, errorbarattrs=
[],
% {{{
744 This class is a style to stroke errorbars in a graph.
\var{size
} is
745 the size of the caps of the errorbars and
\var{errorbarattrs
} are
746 the stroke attributes. Errorbars and error caps are considered to be
747 out of the graph when their position in graph coordinates exceeds
748 the range
[0:
1] by more that
\var{epsilon
}. Out of graph caps are
749 omitted and the errorbars are cut to the valid graph range.
750 \end{classdesc
} % }}}
752 \begin{classdesc
}{text
}{textname="text", dxname=None, dyname=None,
% {{{
753 dxunit=
0.3*unit.v
\_cm, dyunit=
0.3*unit.v
\_cm,
754 textdx=
0*unit.v
\_cm, textdy=
0.3*unit.v
\_cm,
756 This class is a style to stroke text in a graph. The
757 text to be written has to be provided in the data column named
758 \code{textname
}.
\var{textdx
} and
\var{textdy
} are the position of the
759 text with respect to the position in the graph. Alternatively you can
760 specify a
\code{dxname
} and a
\code{dyname
} and provide appropriate
761 data in those columns to be taken in units of
\var{dxunit
} and
762 \var{dyunit
} to specify the position of the text for each point
763 separately.
\var{textattrs
} are text attributes for the output of
764 the text. Those attributes are merged with the default attributes
765 \code{textmodule.halign.center
} and
\code{textmodule.vshift.mathaxis
}.
766 \end{classdesc
} % }}}
768 \begin{classdesc
}{arrow
}{linelength=
0.25*unit.v
\_cm,
% {{{
769 arrowsize=
0.15*unit.v
\_cm,
770 lineattrs=
[], arrowattrs=
[], arrowpos=
0.5,
772 This class is a style to plot short lines with arrows into a
773 two-dimensional graph to a given graph position. The arrow
774 parameters are defined by two additional data columns named
775 \code{size
} and
\code{angle
} define the size and angle for each
776 arrow.
\code{size
} is taken as a factor to
\var{arrowsize
} and
777 \var{linelength
}, the size of the arrow and the length of the line
778 the arrow is plotted at.
\code{angle
} is the angle the arrow points
779 to with respect to a horizontal line. The
\code{angle
} is taken in
780 degrees and used in mathematically positive sense.
\var{lineattrs
}
781 and
\var{arrowattrs
} are styles for the arrow line and arrow head,
782 respectively.
\var{arrowpos
} defines the position of the arrow line
783 with respect to the position at the graph. The default
\code{0.5}
784 means centered at the graph position, whereas
\code{0} and
\code{1}
785 creates the arrows to start or end at the graph position,
786 respectively.
\var{epsilon
} is used as a cutoff for short arrows in
787 order to prevent numerical instabilities.
788 \end{classdesc
} % }}}
790 \begin{classdesc
}{rect
}{gradient=
color.gradient.Grey
} % {{{
791 This class is a style to plot colored rectangles into a
792 two-dimensional graph. The size of the rectangles is taken from
793 the data provided by the
\class{range
} style. The additional
794 data column named
\code{color} specifies the
color of the rectangle
795 defined by
\var{gradient
}. The valid
color range is
[0:
1].
798 Although this style can be used for plotting colored surfaces, it
799 will lead to a huge memory footprint of
\PyX{} together with a
800 long running time and large outputs. Improved support for colored
801 surfaces is planned for the future.
803 \end{classdesc
} % }}}
805 \begin{classdesc
}{histogram
}{lineattrs=
[], steps=
0, fromvalue=
0,
% {{{
806 frompathattrs=
[], fillable=
0,
807 autohistogramaxisindex=
0,
808 autohistogrampointpos=
0.5, epsilon=
1e-10}
809 This class is a style to plot histograms.
\var{lineattrs
} is merged
810 with
\code{defaultlineattrs
} which is
\code{[deco.stroked
]}. When
811 \var{steps
} is set, the histrogram is plotted as steps instead of
812 the default being a boxed histogram.
\var{fromvalue
} is the baseline
813 value of the histogram. When set to
\code{None
}, the histogram will
814 start at the baseline. When fromvalue is set,
\var{frompathattrs
}
815 are the stroke attributes used to show the histogram baseline path.
817 The
\var{fillable
} flag changes the stoke line of the histogram to
818 make it fillable properly. This is important on non-steped
819 histograms or on histograms, which hit the graph boundary.
821 Usually, a histogram wants a range specification (like for an
822 errorbar) in one graph dimension and a value for the other graph
823 dimension. By that, the widths of the histogram boxes might be
824 variable. But a typical use case is, that you just provide graph
825 positions for both graph dimensions. Then
826 \var{autohistogramaxisindex
} defines the graph dimension where the
827 histogram should be plotted on top of it. (
\code{0} thus means a
828 histogram at the x axes and
\code{1} for the y axes.) The style will
829 then demand equal spaced values on this axis. The histogram boxes
830 are usually centered on those values for
\var{autohistogrampointpos
}
831 equals
\code{0.5}, but they can also be aligned at the right side or
832 left side of this value for
\var{autohistogrampointpos
} being
833 \code{0} or
\code{1}.
835 Positions of the histograms are considered to be out of graph when
836 they exceed the graph coordinate range
[0:
1] by more than
838 \end{classdesc
} % }}}
840 \begin{classdesc
}{barpos
}{fromvalue=None, frompathattrs=
[], epsilon=
1e-10} % {{{
841 This class is a hidden style providing position information in a bar
842 graph. Those graphs need to contain a specialized axis, namely a bar
843 axis. The data column for this bar axis is named
\code{Xname
} where
844 \code{X
} is an axis name. In the other graph dimension the data
845 column name must be equal to an axis name. To plot several bars in a
846 single graph side by side, you need to have a nested bar axis and
847 provide a tuple as data for nested bar axis.
849 The bars start at
\var{fromvalue
} when provided. The
\var{fromvalue
}
850 is marked by a gridline stroked using
\var{frompathattrs
}. Thus this
851 hidden style might actually create some output. The value of a bar
852 axis is considered to be out of graph when its position in graph
853 coordinates exceeds the range
[0:
1] by more than
\var{epsilon
}.
854 \end{classdesc
} % }}}
856 \begin{classdesc
}{stackedbarpos
}{stackname, addontop=
0, epsilon=
1e-10} % {{{
857 This class is a hidden style providing position information in a bar
858 graph by stacking a new bar on top of another bar. The value of the
859 new bar is taken from the data column named
\var{stackname
}. When
860 \var{addontop
} is set, the values is taken relative to the previous
862 \end{classdesc
} % }}}
864 \begin{classdesc
}{bar
}{barattrs=
[]} % {{{
865 This class draws bars in a bar graph. The bars are filled using
866 \var{barattrs
}.
\var{barattrs
} is merged with
\code{defaultbarattrs
}
867 which is a list containing
\code{[color.gradient.Rainbow,
868 deco.stroked(
[color.grey.black
])
]}.
869 \end{classdesc
} % }}} % }}}
871 \begin{classdesc
}{changebar
}{barattrs=
[]} % {{{
872 This style works like the
\class{bar
} style, but instead of the
873 \var{barattrs
} to be changed on subsequent data instances the
874 \var{barattrs
} are changed for each value within a single data
875 instance. In the result the style can't be applied to several data
876 instances. The style raises an error instead.
877 \end{classdesc
} % }}} % }}}
879 \section{Module
\module{graph.key
}: Keys
} % {{{
882 \declaremodule{}{graph.key
}
883 \modulesynopsis{Graph keys
}
885 The following class provides a key, whose instances can be passed to
886 the constructor keyword argument
\code{key
} of a graph. The class is
887 implemented in
\module{graph.key
}.
889 \begin{classdesc
}{key
}{dist=
0.2*unit.v
\_cm,
890 pos="tr", hpos=None, vpos=None,
891 hinside=
1, vinside=
1,
892 hdist=
0.6*unit.v
\_cm,
893 vdist=
0.4*unit.v
\_cm,
894 symbolwidth=
0.5*unit.v
\_cm,
895 symbolheight=
0.25*unit.v
\_cm,
896 symbolspace=
0.2*unit.v
\_cm,
898 columns=
1, columndist=
0.5*unit.v
\_cm,
899 border=
0.3*unit.v
\_cm, keyattrs=None
}
900 This class writes the title of the data in a plot together with a
901 small illustration of the style. The style is responsible for its
904 \var{dist
} is a visual length and a distance between the key
905 entries.
\var{pos
} is the position of the key with respect to the
906 graph. Allowed values are combinations of
\code{"t"
} (top),
907 \code{"m"
} (middle) and
\code{"b"
} (bottom) with
\code{"l"
} (left),
908 \code{"c"
} (center) and
\code{"r"
} (right). Alternatively, you may
909 use
\var{hpos
} and
\var{vpos
} to specify the relative position
910 using the range
[0:
1].
\var{hdist
} and
\var{vdist
} are the distances
911 from the specified corner of the graph.
\var{hinside
} and
912 \var{vinside
} are numbers to be set to
0 or
1 to define whether the
913 key should be placed horizontally and vertically inside of the graph
916 \var{symbolwidth
} and
\var{symbolheight
} are passed to the style to
917 control the size of the style illustration.
\var{symbolspace
} is the
918 space between the illustration and the text.
\var{textattrs
} are
919 attributes for the text creation. They are merged with
920 \code{[text.vshift.mathaxis
]}.
922 \var{columns
} is a number of columns of the graph key and
923 \var{columndist
} is the distance between those columns.
925 When
\var{keyattrs
} is set to contain some draw attributes, the
926 graph key is enlarged by
\var{border
} and the key area is drawn
927 using
\var{keyattrs
}.
928 \end{classdesc
} % }}} % }}}
