12 PyX can be used for data and function plotting. At present x-y-graphs and
13 x-y-z-graphs are supported only. However, the component architecture of the
14 graph system described in section :ref:`graph:components` allows for additional
15 graph geometries while reusing most of the existing components.
19 Creating a graph splits into two basic steps. First you have to create a graph
20 instance. The most simple form would look like::
23 g = graph.graphxy(width=8)
25 The graph instance ``g`` created in this example can then be used to actually
26 plot something into the graph. Suppose you have some data in a file
27 :file:`graph.dat` you want to plot. The content of the file could look like:
30 .. include:: ../includes/graph.dat
33 To plot these data into the graph ``g`` you must perform::
35 g.plot(graph.data.file("graph.dat", x=1, y=2))
37 The method :meth:`plot` takes the data to be plotted and optionally a list of
38 graph styles to be used to plot the data. When no styles are provided, a default
39 style defined by the data instance is used. For data read from a file by an
40 instance of :class:`graph.data.file`, the default are symbols. When
41 instantiating :class:`graph.data.file`, you not only specify the file name, but
42 also a mapping from columns to axis names and other information the styles might
43 make use of (*e.g.* data for error bars to be used by the errorbar style).
45 While the graph is already created by that, we still need to perform a write of
46 the result into a file. Since the graph instance is a canvas, we can just call
47 its :meth:`writeEPSfile` method. ::
49 g.writeEPSfile("graph")
51 The result :file:`graph.eps` is shown in figure :ref:`fig:graph`.
59 .. centered:: A minimalistic plot for the data from file :file:`graph.dat`.
61 Instead of plotting data from a file, other data source are available as well.
62 For example function data is created and placed into :meth:`plot` by the
65 g.plot(graph.data.function("y(x)=x**2"))
67 You can plot different data in a single graph by calling :meth:`plot` several
68 times before :meth:`writeEPSfile` or :meth:`writePDFfile`. Note that a calling
69 :meth:`plot` will fail once a graph was forced to "finish" itself. This happens
70 automatically, when the graph is written to a file. Thus it is not an option to
71 call :meth:`plot` after :meth:`writeEPSfile` or :meth:`writePDFfile`. The topic
72 of the finalization of a graph is addressed in more detail in section
73 :ref:`graph:graph`. As you can see in figure :ref:`fig:graph2`, a function is
74 plotted as a line by default.
82 .. centered:: Plotting data from a file together with a function.
84 While the axes ranges got adjusted automatically in the previous example, they
85 might be fixed by keyword options in axes constructors. Plotting only a function
86 will need such a setting at least in the variable coordinate. The following code
87 also shows how to set a logathmic axis in y-direction:
90 .. include:: ../includes/graph3.py
93 The result is shown in figure :ref:`fig:graph3`.
101 .. centered:: Plotting a function for a given axis range and use a logarithmic y-axis.
104 Component architecture
105 ======================
109 .. _graph:components:
111 Creating a graph involves a variety of tasks, which thus can be separated into
112 components without significant additional costs. This structure manifests itself
113 also in the PyX source, where there are different modules for the different
114 tasks. They interact by some well-defined interfaces. They certainly have to be
115 completed and stabilized in their details, but the basic structure came up in
116 the continuous development quite clearly. The basic parts of a graph are:
119 Defines the geometry of the graph by means of graph coordinates with range
120 [0:1]. Keeps lists of plotted data, axes *etc.*
123 Produces or prepares data to be plotted in graphs.
126 Performs the plotting of the data into the graph. It gets data, converts them
127 via the axes into graph coordinates and uses the graph to finally plot the data
128 with respect to the graph geometry methods.
131 Responsible for the graph keys.
134 Creates axes for the graph, which take care of the mapping from data values to
135 graph coordinates. Because axes are also responsible for creating ticks and
136 labels, showing up in the graph themselves and other things, this task is
137 splitted into several independent subtasks. Axes are discussed separately in
143 Module :mod:`graph.graph`: Graphs
144 =================================
150 .. module:: graph.graph
151 :synopsis: Graph geometry
154 The classes :class:`graphxy` and :class:`graphxyz` are part of the module
155 :mod:`graph.graph`. However, there are shortcuts to access the classes via
156 ``graph.graphxy`` and ``graph.graphxyz``, respectively.
159 .. class:: graphxy(xpos=0, ypos=0, width=None, height=None, ratio=goldenmean, key=None, backgroundattrs=None, axesdist=0.8*unit.v_cm, xaxisat=None, yaxisat=None, **axes)
161 This class provides an x-y-graph. A graph instance is also a fully functional
164 The position of the graph on its own canvas is specified by *xpos* and *ypos*.
165 The size of the graph is specified by *width*, *height*, and *ratio*. These
166 parameters define the size of the graph area not taking into account the
167 additional space needed for the axes. Note that you have to specify at least
168 *width* or *height*. *ratio* will be used as the ratio between *width* and
169 *height* when only one of these is provided.
171 *key* can be set to a :class:`graph.key.key` instance to create an automatic
172 graph key. ``None`` omits the graph key.
174 *backgroundattrs* is a list of attributes for drawing the background of the
175 graph. Allowed are decorators, strokestyles, and fillstyles. ``None`` disables
178 *axisdist* is the distance between axes drawn at the same side of a graph.
180 *xaxisat* and *yaxisat* specify a value at the y and x axis, where the
181 corresponding axis should be moved to. It's a shortcut for corresonding calls of
182 :meth:`axisatv` described below. Moving an axis by *xaxisat* or *yaxisat*
183 disables the automatic creation of a linked axis at the opposite side of the
186 *\*\*axes* receives axes instances. Allowed keywords (axes names) are ``x``,
187 ``x2``, ``x3``, *etc.* and ``y``, ``y2``, ``y3``, *etc.* When not providing an
188 ``x`` or ``y`` axis, linear axes instances will be used automatically. When not
189 providing a ``x2`` or ``y2`` axis, linked axes to the ``x`` and ``y`` axes are
190 created automatically and *vice versa*. As an exception, a linked axis is not
191 created automatically when the axis is placed at a specific position by
192 *xaxisat* or *yaxisat*. You can disable the automatic creation of axes by
193 setting the linked axes to ``None``. The even numbered axes are plotted at the
194 top (``x`` axes) and right (``y`` axes) while the others are plotted at the
195 bottom (``x`` axes) and left (``y`` axes) in ascending order each.
197 Some instance attributes might be useful for outside read-access. Those are:
200 .. attribute:: graphxy.axes
202 A dictionary mapping axes names to the :class:`anchoredaxis` instances.
204 To actually plot something into the graph, the following instance method
205 :meth:`plot` is provided:
208 .. method:: graphxy.plot(data, styles=None)
210 Adds *data* to the list of data to be plotted. Sets *styles* to be used for
211 plotting the data. When *styles* is ``None``, the default styles for the data as
212 provided by *data* is used.
214 *data* should be an instance of any of the data described in section
217 When the same combination of styles (*i.e.* the same references) are used
218 several times within the same graph instance, the styles are kindly asked by the
219 graph to iterate their appearance. Its up to the styles how this is performed.
221 Instead of calling the plot method several times with different *data* but the
222 same style, you can use a list (or something iterateable) for *data*.
224 While a graph instance only collects data initially, at a certain point it must
225 create the whole plot. Once this is done, further calls of :meth:`plot` will
226 fail. Usually you do not need to take care about the finalization of the graph,
227 because it happens automatically once you write the plot into a file. However,
228 sometimes position methods (described below) are nice to be accessible. For
229 that, at least the layout of the graph must have been finished. By calling the
230 :meth:`do`\ -methods yourself you can also alter the order in which the graph
231 components are plotted. Multiple calls to any of the :meth:`do`\ -methods have
232 no effect (only the first call counts). The orginal order in which the
233 :meth:`do`\ -methods are called is:
236 .. method:: graphxy.dolayout()
238 Fixes the layout of the graph. As part of this work, the ranges of the axes are
239 fitted to the data when the axes ranges are allowed to adjust themselves to the
240 data ranges. The other :meth:`do`\ -methods ensure, that this method is always
244 .. method:: graphxy.dobackground()
246 Draws the background.
249 .. method:: graphxy.doaxes()
254 .. method:: graphxy.doplotitem(plotitem)
256 Plots the plotitem as returned by the graphs plot method.
259 .. method:: graphxy.doplot()
261 Plots all (remaining) plotitems.
264 .. method:: graphxy.dokeyitem()
266 Inserts a plotitem in the graph key as returned by the graphs plot method.
269 .. method:: graphxy.dokey()
271 Inserts the graph key.
274 .. method:: graphxy.finish()
276 Finishes the graph by calling all pending :meth:`do`\ -methods. This is done
277 automatically, when the output is created.
279 The graph provides some methods to access its geometry:
282 .. method:: graphxy.pos(x, y, xaxis=None, yaxis=None)
284 Returns the given point at *x* and *y* as a tuple ``(xpos, ypos)`` at the graph
285 canvas. *x* and *y* are anchoredaxis instances for the two axes *xaxis* and
286 *yaxis*. When *xaxis* or *yaxis* are ``None``, the axes with names ``x`` and
287 ``y`` are used. This method fails if called before :meth:`dolayout`.
290 .. method:: graphxy.vpos(vx, vy)
292 Returns the given point at *vx* and *vy* as a tuple ``(xpos, ypos)`` at the
293 graph canvas. *vx* and *vy* are graph coordinates with range [0:1].
296 .. method:: graphxy.vgeodesic(vx1, vy1, vx2, vy2)
298 Returns the geodesic between points *vx1*, *vy1* and *vx2*, *vy2* as a path. All
299 parameters are in graph coordinates with range [0:1]. For :class:`graphxy` this
303 .. method:: graphxy.vgeodesic_el(vx1, vy1, vx2, vy2)
305 Like :meth:`vgeodesic` but this method returns the path element to connect the
309 single: xbasepath()@xbasepath() (graphxy method)
310 single: xvbasepath()@xvbasepath() (graphxy method)
311 single: xgridpath()@xgridpath() (graphxy method)
312 single: xvgridpath()@xvgridpath() (graphxy method)
313 single: xtickpoint()@xtickpoint() (graphxy method)
314 single: xvtickpoint()@xvtickpoint() (graphxy method)
315 single: xtickdirection()@xtickdirection() (graphxy method)
316 single: xvtickdirection()@xvtickdirection() (graphxy method)
317 single: ybasepath()@ybasepath() (graphxy method)
318 single: yvbasepath()@yvbasepath() (graphxy method)
319 single: ygridpath()@ygridpath() (graphxy method)
320 single: yvgridpath()@yvgridpath() (graphxy method)
321 single: ytickpoint()@ytickpoint() (graphxy method)
322 single: yvtickpoint()@yvtickpoint() (graphxy method)
323 single: ytickdirection()@ytickdirection() (graphxy method)
324 single: yvtickdirection()@yvtickdirection() (graphxy method)
326 .. % dirty hack to add a whole list of methods to the index:
328 Further geometry information is available by the :attr:`axes` instance variable,
329 with is a dictionary mapping axis names to :class:`anchoredaxis` instances.
330 Shortcuts to the anchoredaxis positioner methods for the ``x``\ - and ``y``\
331 -axis become available after :meth:`dolayout` as :class:`graphxy` methods
332 ``Xbasepath``, ``Xvbasepath``, ``Xgridpath``, ``Xvgridpath``, ``Xtickpoint``,
333 ``Xvtickpoint``, ``Xtickdirection``, and ``Xvtickdirection`` where the prefix
334 ``X`` stands for ``x`` and ``y``.
337 .. method:: graphxy.axistrafo(axis, t)
339 This method can be used to apply a transformation *t* to an
340 :class:`anchoredaxis` instance *axis* to modify the axis position and the like.
341 This method fails when called on a not yet finished axis, i.e. it should be used
342 after :meth:`dolayout`.
345 .. method:: graphxy.axisatv(axis, v)
347 This method calls :meth:`axistrafo` with a transformation to move the axis
348 *axis* to a graph position *v* (in graph coordinates).
350 The class :class:`graphxyz` is very similar to the :class:`graphxy` class,
351 except for its additional dimension. In the following documentation only the
352 differences to the :class:`graphxy` class are described.
355 .. class:: graphxyz(xpos=0, ypos=0, size=None, xscale=1, yscale=1, zscale=1/goldenmean, projector=central(10, -30, 30), key=None, **axes)
357 This class provides an x-y-z-graph.
359 The position of the graph on its own canvas is specified by *xpos* and *ypos*.
360 The size of the graph is specified by *size* and the length factors *xscale*,
361 *yscale*, and *zscale*. The final size of the graph depends on the projector
362 *projector*, which is called with ``x``, ``y``, and ``z`` values up to *xscale*,
363 *yscale*, and *zscale* respectively and scaling the result by *size*. For a
364 parallel projector changing *size* is thus identical to changing *xscale*,
365 *yscale*, and *zscale* by the same factor. For the central projector the
366 projectors internal distance would also need to be changed by this factor. Thus
367 *size* changes the size of the whole graph without changing the projection.
369 *projector* defines the conversion of 3d coordinates to 2d coordinates. It can
370 be an instance of :class:`central` or :class:`parallel` described below.
372 *\*\*axes* receives axes instances as for :class:`graphxyz`. The graphxyz allows
373 for 4 axes per graph dimension ``x``, ``x2``, ``x3``, ``x4``, ``y``, ``y2``,
374 ``y3``, ``y4``, ``z``, ``z2``, ``z3``, and ``z4``. The x-y-plane is the
375 horizontal plane at the bottom and the ``x``, ``x2``, ``y``, and ``y2`` axes are
376 placed at the boundary of this plane with ``x`` and ``y`` always being in front.
377 ``x3``, ``x4``, ``y3``, and ``y4`` are handled similar, but for the top plane of
378 the graph. The ``z`` axis is placed at the origin of the ``x`` and ``y``
379 dimension, whereas ``z2`` is placed at the final point of the ``x`` dimension,
380 ``z3`` at the final point of the ``y`` dimension and ``z4`` at the final point
381 of the ``x`` and ``y`` dimension together.
384 .. attribute:: graphxyz.central
386 The central attribute of the graphxyz is the :class:`central` class. See the
387 class description below.
390 .. attribute:: graphxyz.parallel
392 The parallel attribute of the graphxyz is the :class:`parallel` class. See the
393 class description below.
395 Regarding the 3d to 2d transformation the methods :meth:`pos`, :meth:`vpos`,
396 :meth:`vgeodesic`, and :meth:`vgeodesic_el` are available as for class
397 :class:`graphxy` and just take an additional argument for the dimension. Note
398 that a similar transformation method (3d to 2d) is available as part of the
399 projector as well already, but only the graph acknowledges its size, the scaling
400 and the internal tranformation of the graph coordinates to the scaled
401 coordinates. As the projector also implements a :meth:`zindex` and a
402 :meth:`angle` method, those are also available at the graph level in the graph
403 coordinate variant (i.e. having an additional v in its name and using values
404 from 0 to 1 per dimension).
407 .. method:: graphxyz.vzindex(vx, vy, vz)
409 The depths of the point defined by *vx*, *vy*, and *vz* scaled to a range [-1:1]
410 where 1 in closed to the viewer. All arguments passed to the method are in graph
411 coordinates with range [0:1].
414 .. method:: graphxyz.vangle(vx1, vy1, vz1, vx2, vy2, vz2, vx3, vy3, vz3)
416 The cosine of the angle of the view ray thru point ``(vx1, vy1, vz1)`` and the
417 plane defined by the points ``(vx1, vy1, vz1)``, ``(vx2, vy2, vz2)``, and
418 ``(vx3, vy3, vz3)``. All arguments passed to the method are in graph coordinates
421 There are two projector classes :class:`central` and :class:`parallel`:
424 .. class:: central(distance, phi, theta, anglefactor=math.pi/180)
426 Instances of this class implement a central projection for the given parameters.
428 *distance* is the distance of the viewer from the origin. Note that the
429 :class:`graphxyz` class uses the range ``-xscale`` to ``xscale``, ``-yscale`` to
430 ``yscale``, and ``-zscale`` to ``zscale`` for the coordinates ``x``, ``y``, and
431 ``z``. As those scales are of the order of one (by default), the distance should
432 be of the order of 10 to give nice results. Smaller distances increase the
433 central projection character while for huge distances the central projection
434 becomes identical to the parallel projection.
436 ``phi`` is the angle of the viewer in the x-y-plane and ``theta`` is the angle
437 of the viewer to the x-y-plane. The standard notation for spheric coordinates
438 are used. The angles are multiplied by *anglefactor* which is initialized to do
439 a degree in radiant transformation such that you can specify ``phi`` and
440 ``theta`` in degree while the internal computation is always done in radiants.
443 .. class:: parallel(phi, theta, anglefactor=math.pi/180)
445 Instances of this class implement a parallel projection for the given
446 parameters. There is no distance for that transformation (compared to the
447 central projection). All other parameters are identical to the :class:`central`
453 Module :mod:`graph.data`: Data
454 ==============================
460 .. module:: graph.data
461 :synopsis: Graph data
464 The following classes provide data for the :meth:`plot` method of a graph. The
465 classes are implemented in :mod:`graph.data`.
468 .. class:: file(filename, commentpattern=defaultcommentpattern, columnpattern=defaultcolumnpattern, stringpattern=defaultstringpattern, skiphead=0, skiptail=0, every=1, title=notitle, context={}, copy=1, replacedollar=1, columncallback="__column__", **columns)
470 This class reads data from a file and makes them available to the graph system.
471 *filename* is the name of the file to be read. The data should be organized in
474 The arguments *commentpattern*, *columnpattern*, and *stringpattern* are
475 responsible for identifying the data in each line of the file. Lines matching
476 *commentpattern* are ignored except for the column name search of the last non-
477 empty comment line before the data. By default a line starting with one of the
478 characters ``'#'``, ``'%'``, or ``'!'`` as well as an empty line is treated as a
481 A non-comment line is analysed by repeatedly matching *stringpattern* and,
482 whenever the stringpattern does not match, by *columnpattern*. When the
483 *stringpattern* matches, the result is taken as the value for the next column
484 without further transformations. When *columnpattern* matches, it is tried to
485 convert the result to a float. When this fails the result is taken as a string
486 as well. By default, you can write strings with spaces surrounded by ``'"'``
487 immediately surrounded by spaces or begin/end of line in the data file.
488 Otherwise ``'"'`` is not taken to be special.
490 *skiphead* and *skiptail* are numbers of data lines to be ignored at the
491 beginning and end of the file while *every* selects only every *every* line from
494 *title* is the title of the data to be used in the graph key. A default title is
495 constructed out of *filename* and *\*\*columns*. You may set *title* to ``None``
496 to disable the title.
498 Finally, *columns* define columns out of the existing columns from the file by a
499 column number or a mathematical expression (see below). When *copy* is set the
500 names of the columns in the file (file column names) and the freshly created
501 columns having the names of the dictionary key (data column names) are passed as
502 data to the graph styles. The data columns may hide file columns when names are
503 equal. For unset *copy* the file columns are not available to the graph styles.
505 File column names occur when the data file contains a comment line immediately
506 in front of the data (except for empty or empty comment lines). This line will
507 be parsed skipping the matched comment identifier as if the line would be
508 regular data, but it will not be converted to floats even if it would be
509 possible to convert the items. The result is taken as file column names, *i.e.*
510 a string representation for the columns in the file.
512 The values of *\*\*columns* can refer to column numbers in the file starting at
513 ``1``. The column ``0`` is also available and contains the line number starting
514 from ``1`` not counting comment lines, but lines skipped by *skiphead*,
515 *skiptail*, and *every*. Furthermore values of *\*\*columns* can be strings:
516 file column names or complex mathematical expressions. To refer to columns
517 within mathematical expressions you can also use file column names when they are
518 valid variable identifiers. Equal named items in context will then be hidden.
519 Alternatively columns can be access by the syntax ``$<number>`` when
520 *replacedollar* is set. They will be translated into function calls to
521 *columncallback*, which is a function to access column data by index or name.
523 *context* allows for accessing external variables and functions when evaluating
524 mathematical expressions for columns. Additionally to the identifiers in
525 *context*, the file column names, the *columncallback* function and the
526 functions shown in the table "builtins in math expressions" at the end of the
527 section are available.
531 graph.data.file("test.dat", a=1, b="B", c="2*B+$3")
533 with :file:`test.dat` looking like::
539 The columns with name ``"a"``, ``"b"``, ``"c"`` will become ``"[1.234,
540 5.678]"``, ``"[1.0, 3.0]"``, and ``"[4.0, 10.0]"``, respectively. The columns
541 ``"A"``, ``"B"``, ``"C"`` will be available as well, since *copy* is enabled by
544 When creating several data instances accessing the same file, the file is read
545 only once. There is an inherent caching of the file contents.
547 For the sake of completeness we list the default patterns:
550 .. attribute:: file.defaultcommentpattern
552 ``re.compile(r"(#+|!+|%+)\s*")``
555 .. attribute:: file.defaultcolumnpattern
557 ``re.compile(r"\"(.*?)\"(\s+|$)")``
560 .. attribute:: file.defaultstringpattern
562 ``re.compile(r"(.*?)(\s+|$)")``
567 .. class:: function(expression, title=notitle, min=None, max=None, points=100, context={})
569 This class creates graph data from a function. *expression* is the mathematical
570 expression of the function. It must also contain the result variable name
571 including the variable the function depends on by assignment. A typical example
572 looks like ``"y(x)=sin(x)"``.
574 *title* is the title of the data to be used in the graph key. By default
575 *expression* is used. You may set *title* to ``None`` to disable the title.
577 *min* and *max* give the range of the variable. If not set, the range spans the
578 whole axis range. The axis range might be set explicitly or implicitly by ranges
579 of other data. *points* is the number of points for which the function is
580 calculated. The points are choosen linearly in terms of graph coordinates.
582 *context* allows for accessing external variables and functions. Additionally to
583 the identifiers in *context*, the variable name and the functions shown in the
584 table "builtins in math expressions" at the end of the section are available.
589 .. class:: paramfunction(varname, min, max, expression, title=notitle, points=100, context={})
591 This class creates graph data from a parametric function. *varname* is the
592 parameter of the function. *min* and *max* give the range for that variable.
593 *points* is the number of points for which the function is calculated. The
594 points are choosen lineary in terms of the parameter.
596 *expression* is the mathematical expression for the parametric function. It
597 contains an assignment of a tuple of functions to a tuple of variables. A
598 typical example looks like ``"x, y = cos(k), sin(k)"``.
600 *title* is the title of the data to be used in the graph key. By default
601 *expression* is used. You may set *title* to ``None`` to disable the title.
603 *context* allows for accessing external variables and functions. Additionally to
604 the identifiers in *context*, *varname* and the functions shown in the table
605 "builtins in math expressions" at the end of the section are available.
610 .. class:: values(title="user provided values", **columns)
612 This class creates graph data from externally provided data. Each column is a
613 list of values to be used for that column.
615 *title* is the title of the data to be used in the graph key.
620 .. class:: points(data, title="user provided points", addlinenumbers=1, **columns)
622 This class creates graph data from externally provided data. *data* is a list of
623 lines, where each line is a list of data values for the columns.
625 *title* is the title of the data to be used in the graph key.
627 The keywords of *\*\*columns* become the data column names. The values are the
628 column numbers starting from one, when *addlinenumbers* is turned on (the zeroth
629 column is added to contain a line number in that case), while the column numbers
630 starts from zero, when *addlinenumbers* is switched off.
635 .. class:: data(data, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns)
637 This class provides graph data out of other graph data. *data* is the source of
638 the data. All other parameters work like the equally called parameters in
639 :class:`graph.data.file`. Indeed, the latter is built on top of this class by
640 reading the file and caching its contents in a :class:`graph.data.list`
646 .. class:: conffile(filename, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns)
648 This class reads data from a config file with the file name *filename*. The
649 format of a config file is described within the documentation of the
650 :mod:`ConfigParser` module of the Python Standard Library.
652 Each section of the config file becomes a data line. The options in a section
653 are the columns. The name of the options will be used as file column names. All
654 other parameters work as in *graph.data.file* and *graph.data.data* since they
655 all use the same code.
660 .. class:: cbdfile(filename, minrank=None, maxrank=None, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns)
662 This is an experimental class to read map data from cbd-files. See
663 `<http://sepwww.stanford.edu/ftp/World_Map/>`_ for some world-map data.
665 The builtins in math expressions are listed in the following table:
669 +------------------+--------------------------------------------+
671 +==================+============================================+
672 | ``neg`` | ``lambda x: -x`` |
673 +------------------+--------------------------------------------+
674 | ``abs`` | ``lambda x: x < 0 and -x or x`` |
675 +------------------+--------------------------------------------+
676 | ``sgn`` | ``lambda x: x < 0 and -1 or 1`` |
677 +------------------+--------------------------------------------+
678 | ``sqrt`` | ``math.sqrt`` |
679 +------------------+--------------------------------------------+
680 | ``exp`` | ``math.exp`` |
681 +------------------+--------------------------------------------+
682 | ``log`` | ``math.log`` |
683 +------------------+--------------------------------------------+
684 | ``sin`` | ``math.sin`` |
685 +------------------+--------------------------------------------+
686 | ``cos`` | ``math.cos`` |
687 +------------------+--------------------------------------------+
688 | ``tan`` | ``math.tan`` |
689 +------------------+--------------------------------------------+
690 | ``asin`` | ``math.asin`` |
691 +------------------+--------------------------------------------+
692 | ``acos`` | ``math.acos`` |
693 +------------------+--------------------------------------------+
694 | ``atan`` | ``math.atan`` |
695 +------------------+--------------------------------------------+
696 | ``sind`` | ``lambda x: math.sin(math.pi/180*x)`` |
697 +------------------+--------------------------------------------+
698 | ``cosd`` | ``lambda x: math.cos(math.pi/180*x)`` |
699 +------------------+--------------------------------------------+
700 | ``tand`` | ``lambda x: math.tan(math.pi/180*x)`` |
701 +------------------+--------------------------------------------+
702 | ``asind`` | ``lambda x: 180/math.pi*math.asin(x)`` |
703 +------------------+--------------------------------------------+
704 | ``acosd`` | ``lambda x: 180/math.pi*math.acos(x)`` |
705 +------------------+--------------------------------------------+
706 | ``atand`` | ``lambda x: 180/math.pi*math.atan(x)`` |
707 +------------------+--------------------------------------------+
708 | ``norm`` | ``lambda x, y: math.hypot(x, y)`` |
709 +------------------+--------------------------------------------+
710 | ``splitatvalue`` | see the ``splitatvalue`` description below |
711 +------------------+--------------------------------------------+
712 | ``pi`` | ``math.pi`` |
713 +------------------+--------------------------------------------+
714 | ``e`` | ``math.e`` |
715 +------------------+--------------------------------------------+
717 ``math`` refers to Pythons :mod:`math` module. The ``splitatvalue`` function is
721 .. function:: splitatvalue(value, *splitpoints)
723 This method returns a tuple ``(section, value)``. The section is calculated by
724 comparing *value* with the values of splitpoints. If *splitpoints* contains only
725 a single item, ``section`` is ``0`` when value is lower or equal this item and
726 ``1`` else. For multiple splitpoints, ``section`` is ``0`` when its lower or
727 equal the first item, ``None`` when its bigger than the first item but lower or
728 equal the second item, ``1`` when its even bigger the second item, but lower or
729 equal the third item. It continues to alter between ``None`` and ``2``, ``3``,
735 Module :mod:`graph.style`: Styles
736 =================================
742 .. module:: graph.style
743 :synopsis: Graph style
746 Please note that we are talking about graph styles here. Those are responsible
747 for plotting symbols, lines, bars and whatever else into a graph. Do not mix it
748 up with path styles like the line width, the line style (solid, dashed, dotted
751 The following classes provide styles to be used at the :meth:`plot` method of a
752 graph. The plot method accepts a list of styles. By that you can combine several
753 styles at the very same time.
755 Some of the styles below are hidden styles. Those do not create any output, but
756 they perform internal data handling and thus help on modularization of the
757 styles. Usually, a visible style will depend on data provided by one or more
758 hidden styles but most of the time it is not necessary to specify the hidden
759 styles manually. The hidden styles register themself to be the default for
760 providing certain internal data.
763 .. class:: pos(epsilon=1e-10)
765 This class is a hidden style providing a position in the graph. It needs a data
766 column for each graph dimension. For that the column names need to be equal to
767 an axis name. Data points are considered to be out of graph when their position
768 in graph coordinates exceeds the range [0:1] by more than *epsilon*.
775 .. class:: range(usenames=, epsilon=1e-10)
777 This class is a hidden style providing an errorbar range. It needs data column
778 names constructed out of a axis name ``X`` for each dimension errorbar data
779 should be provided as follows:
783 +-----------+---------------------------+
784 | data name | description |
785 +===========+===========================+
786 | ``Xmin`` | minimal value |
787 +-----------+---------------------------+
788 | ``Xmax`` | maximal value |
789 +-----------+---------------------------+
790 | ``dX`` | minimal and maximal delta |
791 +-----------+---------------------------+
792 | ``dXmin`` | minimal delta |
793 +-----------+---------------------------+
794 | ``dXmax`` | maximal delta |
795 +-----------+---------------------------+
797 When delta data are provided the style will also read column data for the axis
798 name ``X`` itself. *usenames* allows to insert a translation dictionary from
799 axis names to the identifiers ``X``.
801 *epsilon* is a comparison precision when checking for invalid errorbar ranges.
806 .. class:: symbol(symbol=changecross, size=0.2*unit.v_cm, symbolattrs=[])
808 This class is a style for plotting symbols in a graph. *symbol* refers to a
809 (changeable) symbol function with the prototype ``symbol(c, x_pt, y_pt, size_pt,
810 attrs)`` and draws the symbol into the canvas ``c`` at the position ``(x_pt,
811 y_pt)`` with size ``size_pt`` and attributes ``attrs``. Some predefined symbols
812 are available in member variables listed below. The symbol is drawn at size
813 *size* using *symbolattrs*. *symbolattrs* is merged with ``defaultsymbolattrs``
814 which is a list containing the decorator :class:`deco.stroked`. An instance of
815 :class:`symbol` is the default style for all graph data classes described in
816 section :ref:`graph:data` except for :class:`function` and
817 :class:`paramfunction`.
819 The class :class:`symbol` provides some symbol functions as member variables,
823 .. attribute:: symbol.cross
825 A cross. Should be used for stroking only.
828 .. attribute:: symbol.plus
830 A plus. Should be used for stroking only.
833 .. attribute:: symbol.square
835 A square. Might be stroked or filled or both.
838 .. attribute:: symbol.triangle
840 A triangle. Might be stroked or filled or both.
843 .. attribute:: symbol.circle
845 A circle. Might be stroked or filled or both.
848 .. attribute:: symbol.diamond
850 A diamond. Might be stroked or filled or both.
852 :class:`symbol` provides some changeable symbol functions as member variables,
856 .. attribute:: symbol.changecross
858 attr.changelist([cross, plus, square, triangle, circle, diamond])
861 .. attribute:: symbol.changeplus
863 attr.changelist([plus, square, triangle, circle, diamond, cross])
866 .. attribute:: symbol.changesquare
868 attr.changelist([square, triangle, circle, diamond, cross, plus])
871 .. attribute:: symbol.changetriangle
873 attr.changelist([triangle, circle, diamond, cross, plus, square])
876 .. attribute:: symbol.changecircle
878 attr.changelist([circle, diamond, cross, plus, square, triangle])
881 .. attribute:: symbol.changediamond
883 attr.changelist([diamond, cross, plus, square, triangle, circle])
886 .. attribute:: symbol.changesquaretwice
888 attr.changelist([square, square, triangle, triangle, circle, circle, diamond,
892 .. attribute:: symbol.changetriangletwice
894 attr.changelist([triangle, triangle, circle, circle, diamond, diamond, square,
898 .. attribute:: symbol.changecircletwice
900 attr.changelist([circle, circle, diamond, diamond, square, square, triangle,
904 .. attribute:: symbol.changediamondtwice
906 attr.changelist([diamond, diamond, square, square, triangle, triangle, circle,
909 The class :class:`symbol` provides two changeable decorators for alternated
910 filling and stroking. Those are especially useful in combination with the
911 :meth:`change`\ -\ :meth:`twice`\ -symbol methods above. They are:
914 .. attribute:: symbol.changestrokedfilled
916 attr.changelist([deco.stroked, deco.filled])
919 .. attribute:: symbol.changefilledstroked
921 attr.changelist([deco.filled, deco.stroked])
926 .. class:: line(lineattrs=[])
928 This class is a style to stroke lines in a graph. *lineattrs* is merged with
929 ``defaultlineattrs`` which is a list containing the member variable
930 ``changelinestyle`` as described below. An instance of :class:`line` is the
931 default style of the graph data classes :class:`function` and
932 :class:`paramfunction` described in section :ref:`graph:data`.
936 The class :class:`line` provides a changeable line style. Its definition is:
939 .. attribute:: line.changelinestyle
941 attr.changelist([style.linestyle.solid, style.linestyle.dashed,
942 style.linestyle.dotted, style.linestyle.dashdotted])
947 .. class:: impulses(lineattrs=[], fromvalue=0, frompathattrs=[], valueaxisindex=1)
949 This class is a style to plot impulses. *lineattrs* is merged with
950 ``defaultlineattrs`` which is a list containing the member variable
951 ``changelinestyle`` of the :class:`line` class. *fromvalue* is the baseline
952 value of the impulses. When set to ``None``, the impulses will start at the
953 baseline. When fromvalue is set, *frompathattrs* are the stroke attributes used
954 to show the impulses baseline path.
959 .. class:: errorbar(size=0.1*unit.v_cm, errorbarattrs=[], epsilon=1e-10)
961 This class is a style to stroke errorbars in a graph. *size* is the size of the
962 caps of the errorbars and *errorbarattrs* are the stroke attributes. Errorbars
963 and error caps are considered to be out of the graph when their position in
964 graph coordinates exceeds the range [0:1] by more that *epsilon*. Out of graph
965 caps are omitted and the errorbars are cut to the valid graph range.
970 .. class:: text(textname="text", dxname=None, dyname=None, dxunit=0.3*unit.v_cm, dyunit=0.3*unit.v_cm, textdx=0*unit.v_cm, textdy=0.3*unit.v_cm, textattrs=[])
972 This class is a style to stroke text in a graph. The text to be written has to
973 be provided in the data column named ``textname``. *textdx* and *textdy* are the
974 position of the text with respect to the position in the graph. Alternatively
975 you can specify a ``dxname`` and a ``dyname`` and provide appropriate data in
976 those columns to be taken in units of *dxunit* and *dyunit* to specify the
977 position of the text for each point separately. *textattrs* are text attributes
978 for the output of the text. Those attributes are merged with the default
979 attributes ``textmodule.halign.center`` and ``textmodule.vshift.mathaxis``.
984 .. class:: arrow(linelength=0.25*unit.v_cm, arrowsize=0.15*unit.v_cm, lineattrs=[], arrowattrs=[], arrowpos=0.5, epsilon=1e-10, decorator=deco.earrow)
986 This class is a style to plot short lines with arrows into a two-dimensional
987 graph to a given graph position. The arrow parameters are defined by two
988 additional data columns named ``size`` and ``angle`` define the size and angle
989 for each arrow. ``size`` is taken as a factor to *arrowsize* and *linelength*,
990 the size of the arrow and the length of the line the arrow is plotted at.
991 ``angle`` is the angle the arrow points to with respect to a horizontal line.
992 The ``angle`` is taken in degrees and used in mathematically positive sense.
993 *lineattrs* and *arrowattrs* are styles for the arrow line and arrow head,
994 respectively. *arrowpos* defines the position of the arrow line with respect to
995 the position at the graph. The default ``0.5`` means centered at the graph
996 position, whereas ``0`` and ``1`` creates the arrows to start or end at the
997 graph position, respectively. *epsilon* is used as a cutoff for short arrows in
998 order to prevent numerical instabilities. *decorator* defines the decorator to
999 be added to the line.
1004 .. class:: rect(gradient=color.gradient.Grey)
1006 This class is a style to plot colored rectangles into a two-dimensional graph.
1007 The size of the rectangles is taken from the data provided by the :class:`range`
1008 style. The additional data column named ``color`` specifies the color of the
1009 rectangle defined by *gradient*. The valid color range is [0:1].
1016 .. class:: histogram(lineattrs=[], steps=0, fromvalue=0, frompathattrs=[], fillable=0, rectkey=0, autohistogramaxisindex=0, autohistogrampointpos=0.5, epsilon=1e-10)
1018 This class is a style to plot histograms. *lineattrs* is merged with
1019 ``defaultlineattrs`` which is ``[deco.stroked]``. When *steps* is set, the
1020 histrogram is plotted as steps instead of the default being a boxed histogram.
1021 *fromvalue* is the baseline value of the histogram. When set to ``None``, the
1022 histogram will start at the baseline. When fromvalue is set, *frompathattrs* are
1023 the stroke attributes used to show the histogram baseline path.
1025 The *fillable* flag changes the stoke line of the histogram to make it fillable
1026 properly. This is important on non-steped histograms or on histograms, which hit
1027 the graph boundary. *rectkey* can be set to generate a rectanglar area instead
1028 of a line in the graph key.
1030 In the most general case, a histogram is defined by a range specification (like
1031 for an errorbar) in one graph dimension (say, along the x-axis) and a value for
1032 the other graph dimension. This allows for the widths of the histogram boxes
1033 being variable. Often, however, all histogram bin ranges are equally sized, and
1034 instead of passing the range, the position of the bin along the x-axis fully
1035 specifies the histogram - assuming that there are at least two bins. This common
1036 case is supported via two parameters: *autohistogramaxisindex*, which defines
1037 the index of the independent histogram axis (in the case just described this
1038 would be ``0`` designating the x axis). *autohistogrampointpos*, defines the
1039 relative position of the center of the histogram bin: ``0.5`` means that the bin
1040 is centered at the values passed to the style, ``0`` (``1``) means that the bin
1041 is aligned at the right-(left-)hand side.
1043 XXX describe, how to specify general histograms with varying bin widths
1045 Positions of the histograms are considered to be out of graph when they exceed
1046 the graph coordinate range [0:1] by more than *epsilon*.
1051 .. class:: barpos(fromvalue=None, frompathattrs=[], epsilon=1e-10)
1053 This class is a hidden style providing position information in a bar graph.
1054 Those graphs need to contain a specialized axis, namely a bar axis. The data
1055 column for this bar axis is named ``Xname`` where ``X`` is an axis name. In the
1056 other graph dimension the data column name must be equal to an axis name. To
1057 plot several bars in a single graph side by side, you need to have a nested bar
1058 axis and provide a tuple as data for nested bar axis.
1062 The bars start at *fromvalue* when provided. The *fromvalue* is marked by a
1063 gridline stroked using *frompathattrs*. Thus this hidden style might actually
1064 create some output. The value of a bar axis is considered to be out of graph
1065 when its position in graph coordinates exceeds the range [0:1] by more than
1071 .. class:: stackedbarpos(stackname, addontop=0, epsilon=1e-10)
1073 This class is a hidden style providing position information in a bar graph by
1074 stacking a new bar on top of another bar. The value of the new bar is taken from
1075 the data column named *stackname*. When *addontop* is set, the values is taken
1076 relative to the previous top of the bar.
1083 .. class:: bar(barattrs=[], epsilon=1e-10, gradient=color.gradient.RedBlack)
1085 This class draws bars in a bar graph. The bars are filled using *barattrs*.
1086 *barattrs* is merged with ``defaultbarattrs`` which is a list containing
1087 ``[color.gradient.Rainbow, deco.stroked([color.grey.black])]``.
1091 The bar style has limited support for 3d graphs: Occlusion does not work
1092 properly on stacked bars or multiple dataset. *epsilon* is used in 3d to prevent
1093 numerical instabilities on bars without hight. When *gradient* is not ``None``
1094 it is used to calculate a lighting coloring taking into account the angle
1095 between the view ray and the bar and the distance between viewer and bar. The
1096 precise conversion is defined in the :meth:`lighting` method.
1101 .. class:: changebar(barattrs=[])
1103 This style works like the :class:`bar` style, but instead of the *barattrs* to
1104 be changed on subsequent data instances the *barattrs* are changed for each
1105 value within a single data instance. In the result the style can't be applied to
1106 several data instances and does not support 3d. The style raises an error
1114 .. class:: gridpos(index1=0, index2=1, gridlines1=1, gridlines2=1, gridattrs=[], epsilon=1e-10)
1116 This class is a hidden style providing rectangular grid information out of graph
1117 positions for graph dimensions *index1* and *index2*. Data points are considered
1118 to be out of graph when their position in graph coordinates exceeds the range
1119 [0:1] by more than *epsilon*. Data points are merged to a single graph
1120 coordinate value when their difference in graph coordinates is below *epsilon*.
1125 .. class:: grid(gridlines1=1, gridlines2=1, gridattrs=[])
1127 Strokes a rectangular grid in the first grid direction, when *gridlines1* is set
1128 and in the second grid direction, when *gridlines2* is set. *gridattrs* is
1129 merged with ``defaultgridattrs`` which is a list containing the member variable
1130 ``changelinestyle`` of the :class:`line` class.
1137 .. class:: surface(colorname="color", gradient=color.gradient.Grey, mincolor=None, maxcolor=None, gridlines1=0.05, gridlines2=0.05, gridcolor=None, backcolor=color.gray.black)
1139 Draws a surface of a rectangular grid. Each rectangle is divided into 4
1142 The grid can be colored using values provided by the data column named
1143 *colorname*. The values are rescaled to the range [0:1] using mincolor and
1144 maxcolor (which are taken from the minimal and maximal values, but larger bounds
1147 If no *colorname* column exists, the surface style falls back to a lighting
1148 coloring taking into account the angle between the view ray and the triangle and
1149 the distance between viewer and triangle. The precise conversion is defined in
1150 the :meth:`lighting` method.
1152 If a *gridcolor* is set, the rectangular grid is marked by small stripes of the
1153 relative (compared to each rectangle) size of *gridlines1* and *gridlines2* for
1154 the first and second grid direction, respectively.
1156 *backcolor* is used to fill triangles shown from the back. If *backcolor* is set
1157 to ``None``, back sides are not drawn differently from the front sides.
1159 The surface is encoded using a single mesh. While this is quite space efficient,
1160 it has the following implications:
1162 * All colors must use the same color space.
1164 * HSB colors are not allowed, whereas Gray, RGB, and CMYK are allowed. You can
1165 convert HSB colors into a different color space before passing them to the
1168 * The grid itself is also constructed out of triangles. The grid is transformed
1169 along with the triangles thus looking quite different from a stroked grid (as
1170 done by the grid style).
1172 * Occlusion is handled by proper painting order.
1174 * Color changes are continuous (in the selected color space) for each triangle.
1180 Module :mod:`graph.key`: Keys
1181 =============================
1187 .. module:: graph.key
1188 :synopsis: Graph keys
1191 The following class provides a key, whose instances can be passed to the
1192 constructor keyword argument ``key`` of a graph. The class is implemented in
1196 .. class:: key(dist=0.2*unit.v_cm, pos="tr", hpos=None, vpos=None, hinside=1, vinside=1, hdist=0.6*unit.v_cm, vdist=0.4*unit.v_cm, symbolwidth=0.5*unit.v_cm, symbolheight=0.25*unit.v_cm, symbolspace=0.2*unit.v_cm, textattrs=[], columns=1, columndist=0.5*unit.v_cm, border=0.3*unit.v_cm, keyattrs=None)
1198 This class writes the title of the data in a plot together with a small
1199 illustration of the style. The style is responsible for its illustration.
1201 *dist* is a visual length and a distance between the key entries. *pos* is the
1202 position of the key with respect to the graph. Allowed values are combinations
1203 of ``"t"`` (top), ``"m"`` (middle) and ``"b"`` (bottom) with ``"l"`` (left),
1204 ``"c"`` (center) and ``"r"`` (right). Alternatively, you may use *hpos* and
1205 *vpos* to specify the relative position using the range [0:1]. *hdist* and
1206 *vdist* are the distances from the specified corner of the graph. *hinside* and
1207 *vinside* are numbers to be set to 0 or 1 to define whether the key should be
1208 placed horizontally and vertically inside of the graph or not.
1210 *symbolwidth* and *symbolheight* are passed to the style to control the size of
1211 the style illustration. *symbolspace* is the space between the illustration and
1212 the text. *textattrs* are attributes for the text creation. They are merged with
1213 ``[text.vshift.mathaxis]``.
1215 *columns* is a number of columns of the graph key and *columndist* is the
1216 distance between those columns.
1218 When *keyattrs* is set to contain some draw attributes, the graph key is
1219 enlarged by *border* and the key area is drawn using *keyattrs*.