prevent double call of _cleanup, which harms usefiles (and is a bad idea in general)

[PyX.git] / faq / plotting_graphs.rst

==================
Plotting of graphs
==================

General aspects
===============

.. _mingraphdata:

How do I generate a graph from data as simply as possible?
----------------------------------------------------------

Suppose that you have a data file ``x.dat`` containing values for ``x`` and
``y`` in two columns. Then the following code will do the job::

   from pyx import *

   g = graph.graphxy(width=10)
   g.plot(graph.data.file("x.dat", x=1, y=2))
   g.writeEPSfile("x")

``graphxy`` creates a canvas (called ``g`` in this example) onto which the
graph will be drawn and it sets the default behavior including the axis. There
is, however, no default value for the width of the graph. In ``plot`` you have
to specify the name of the data file and the columns from which the data should
be taken. Finally, ``writeEPSfile`` will generate the postscript file ``x.eps``
which you can view or print.

A minimal example is also provided in the PyX distribution as
``examples/graphs/minimal.py``.

.. _mingraphfunc:

How do I generate a graph of a function as simply as possible?
--------------------------------------------------------------

The following example will draw a parabola::

   from pyx import *

   g = graph.graphxy(width=10,
                     x=graph.axis.linear(min=-2, max=2)
                     )

   g.plot(graph.data.function("y(x)=x**2"))

   g.writeEPSfile("x")

Most of the code has been explained in :ref:`mingraphdata`. The main
difference is that here you need to specify minimum and maximum for the
``x``-axis so that PyX knows in which range to evaluate the function.

Another, slightly more complex, example is also provided in the PyX
distribution as ``examples/graphs/piaxis.py``.

How can I stack graphs?
-----------------------

PyX always needs a canvas to draw on. One possibility therefore consists in
creating a new canvas with ::

   c = canvas.canvas()

and inserting the graphs into this canvas with ``c.insert(…)``. Here, ``…`` has
to be replaced by the name of the graph. Alternatively, the canvas created with
``graph.graphxy`` for one of the graphs can be used to insert the other graphs
even if they will be positioned outside the first graph.

The second issue to address is positioning of the graphs. By specifying
``xpos`` and ``ypos`` when calling ``graphxy`` you can define the position of a
graph. Later on, the position and size of a graph ``g`` can be referred to as
``g.xpos`` ``g.ypos`` ``g.width`` and ``g.height`` even if for example the
height has never been specified explicitly but is only defined by a PyX
default. 

The following example shows how to put graph ``gupper`` above graph ``glower``
on a canvas ``c``::

   from pyx import *
   from graph import graphxy

   c = canvas.canvas()

   glower = graphxy(width=10)
   glower.plot(...)
   c.insert(glower)

   gupper = graphxy(width=10, ypos=glower.ypos+glower.height+2)
   gupper.plot(...)

   c.insert(gupper)
   c.writeEPSfile(...)

where ``…`` has to be replaced by the appropriate information like data and
symbol specifications and the name of the output file. Here, ``c.insert`` is
used to actually insert the subcanvasses for the graphs into the main canvas
``c`` and ``c.writeEPSfile`` in the last line requests to write the contents of
this canvas to a file.


How can I plot grid data?
-------------------------

PyX offers support for plotting three-dimensional data as two-dimensional color
plots or grey-scale plots and of vector fields by providing ways to plot
rectangles and arrows in graphs. 

We start by considering the task of creating a two-dimensional color plot by
plotting a number of filled rectangles. One first needs to create a data set
which consists of five entries per data point. These are the lower left corner
(*x*\ :sub:`min`, *y*\ :sub:`min`) and the upper right corner (*x*\ :sub:`max`,
*y*\ :sub:`max`) of the triangle and a value between 0 and 1 determining the
color via a PyX color palette. The following code gives an idea of how to
proceed::

   g.plot(graph.data.file("datafile.dat", xmin=1, xmax=2, ymin=3, ymax=4, color=5),
                 [graph.style.rect(color.palette.ReverseRainbow)]
          )
   g.dodata()

Here, we assume that the data are stored in ``datafile.dat`` and the columns
contain *x*\ :sub:`min`, *x* :sub:`max`, *y*\ :sub:`min`, *y*\ :sub:`max`, and
the color value in this order. The columns are numbered from 1, since the 0th
column contains the line number. To determine the color, we use the
``ReverseRainbow`` palette. The last line instructs PyX to plot the rectangles
before plotting the axes. Otherwise, the axes might be covered partially by the
rectangles and, in particular, the ticks might not be visible. Gray-scale plots
can easily be generated by specifying the palette ``Gray`` or ``ReverseGray``
(cf. appendix C of the manual for a list of predefined palettes).

At first sight, it seems surprising that plotting of grid data requires the
specification of four coordinates for the rectangle. The reason is that this
allows to draw rectangles of varying sizes which may help to reduce the size of
the postscript file by combining rectangles of the same color in horizontal or
vertical direction. For example, it may be sufficient to plot a grey-scale
image in a small number of grey shades and then combining rectangles may be
appropriate. Note, though, that this step is part of the data creation and not
preformed by PyX. Another advantage of fully specifying each rectangle is that
it is straightforward to leave parts of the graph blank.

The same ideas as for the color plot can be applied to plot vector fields where
each data point is represented by an arrow. In this case a data point is
specified by the position of the arrow, its size and its direction as indicated
in the following code snippet::

   g.plot(graph.data.file("datafile.dat"), x=1, y=2, size=3, angle=4),
              [graph.style.arrow()]
          )

Complete code examples can be found in ``examples/graphs/mandel.py`` and
``examples/graphs/arrows.py`` .

.. _problemcoord:

How can I access points in problem coordinates of a graph?
----------------------------------------------------------

Sometimes it may be necessary to add graphical elements to a graph in addition
to the data or function(s) which have been plotted as described in 
:ref:`mingraphdata` and :ref:`mingraphfunc`. For a graph instance 
``g`` the positioning can easily be done in canvas coordinates by making
use of the origin (``g.xpos``, ``g.ypos``) and the width 
(``g.width``) and height (``g.height``) of the graph. 

Occasionally, it may be more convenient to specify the position of the
additional material in terms of problem coordinates. However, this requires
that the mapping from problem coordinates to canvas coordinates is known.  By
default this is not the case before the content of the canvas is written to the
output which is too late for our purpose. One therefore needs to explicitly
instruct PyX to determine this mapping. One possibility is to ask PyX to finish
the graph by means of ``g.finish()``. Now, problem coordinates can be used to
insert additional material which will end up in front of the graph. If this is
not desired, one should only fix the layout of the graph by means of
``g.dolayout()``. Then, the additional material can be put onto the canvas
before the graph is drawn and it will therefore appear behind the graph.

The conversion of problem coordinates (``px``, ``py``) to canvas coordinates
(``x``, ``y``) is performed as follows::

   x, y = g.pos(px, py)

By default, the problem coordinates will refer to the ranges of the *x* and *y*
axes. If several axes with different ranges exist, the instances of the desired
axes should be passed to the ``pos`` method by means of the keyword arguments
``xaxis`` and ``yaxis``.

We remark that the drawing of lines parallel to one of the axes at specific
problem coordinates can also be done by adapting the method described in
:ref:`zeroline`.

I would like a key for only some of my data sets. How do I do that?
-------------------------------------------------------------------

.. todo::

   This still needs to be answered.

Axis properties
===============

How do I specify the tick increment?
------------------------------------

In the partition of a linear axis, the increments associated with ticks,
subticks etc. can be specified as argument of ``parter.linear``. In the
following example, ticks will be drawn at even values while subticks will be
drawn at all integers::

   from pyx.graph import axis

   tg = graph.graphxy(width=10,
                      x=axis.linear(min=1, max=10,
                                    parter=axis.parter.linear(tickdists=[2,1]))
                      )

.. _zeroline:

How do I plot the zero line?
----------------------------

PyX releases before 0.6 offered the possibility to stroke a zero line by 
specifying ``zeropathattrs`` in the painter constructor. In more recent 
releases, one proceeds as follows. First one has to fix the layout information 
of the graph by means of the ``finish`` or ``dolayout`` method (see 
:ref:`problemcoord` for a more detailed explanation). Then, the 
``xgridpath`` or ``ygridpath`` method of a graph will return a grid 
path parallel to the *y* or *x* axis, respectively, at the specified *y* value. 
As an example, a zero line in *x* direction can be drawn as follows::

   g.finish()
   g.stroke(g.ygridpath(0))

How can I add grid lines to a graph?
------------------------------------

Specifying ``gridattrs`` for the painter of an axis will generate grid lines
orthogonal to this axis. At least an empty list is needed like in ::

   g = graph.graphxy(width=10,
                     x=graph.axis.linear(painter=graph.axis.painter.regular(gridattrs=[])),
                     y=graph.axis.linear()
                     )

where grid lines in vertical direction are drawn in default style.

Occassionally, one might want to draw grid lines corresponding to ticks and
subticks in a different style. This can be achieved by specifiying changeable
attributes using ``changelist``. The following code ::

   my_xpainter = graph.axis.painter.regular(gridattrs=
                       [attr.changelist([style.linestyle.solid, style.linestyle.dashed])]
                                            )
   my_ypainter = graph.axis.painter.regular(gridattrs=
                       [attr.changelist([color.rgb.red, color.rgb.blue])]
                                            )

   g = graph.graphxy(width=10,
                     x=graph.axis.linear(painter=my_xpainter),
                     y=graph.axis.linear(painter=my_ypainter)
                     )

will create vertical solid and dashed grid lines for ticks and subticks,
respectively. The horizontal grid lines will be red for ticks and blue for
subticks. The changeable attributes are applied in a cyclic manner. Therefore,
in this example grid lines at subsubticks would be plotted in the same style as
for ticks. If this is not desired, the list of attributes should be extended by
an appropriate third style. The keyword ``None`` will switch off the respective
level of grid lines in case you want to draw them only e.g.  for ticks but not
subticks.

Data properties
===============

How do I choose the symbol and its attributes?
----------------------------------------------

Suppose a graph called ``g`` has been initialized, e.g. by using
``graph.graphxy``. Then, data and the style of their representation in the
graph are defined by calling ``g.plot`` like in the following example in which
filled circles are requested::

   g.plot(graph.data.file("test.dat"),
          [graph.style.symbol(graph.style.symbol.circle, symbolattrs=[deco.filled])]
          )

As another example, if the linewidth of the symbol is too thin for your
purposes, you could use something like::

   [graph.style.symbol(graph.style.symbol.plus, symbolattrs=[style.linewidth.Thick])]

How do I choose the color of the symbols?
-----------------------------------------

Colors are not properties of the symbol as such and can therefore not be
specified in ``symbolattrs`` directly. The color is rather related to the
plotting of the symbol as defined by ``deco.stroked`` or ``deco.filled``. 
With ::

   graph.style.symbol(graph.style.symbol.circle,
                      symbolattrs=[deco.stroked([color.rgb.red]),
                                   deco.filled([color.rgb.green])]
                      )

you will obtain a circle filled in green with a red borderline.

How do I choose the line style?
-------------------------------

If you do not want to use symbols, you can set the line style as in this
example ::

   g.plot(graph.data.file("test.dat"),
          [graph.style.line([style.linewidth.Thin])]
          )

where the linewidth is set.

If you also want to use symbols, you can combine the symbol and the
line style as in ::

   g.plot(graph.data.file("test.dat"),
          [graph.style.line(lineattrs=[style.linewidth.Thin,
                                       style.linestyle.dashed]),
           graph.style.symbol(graph.style.symbolline.circle,
                              symbolattrs=[deco.filled])
           ]
          )

to plot the symbols on top of a thin, dashed line. You may alter the
order of the styles to plot the line on top of the symbols.

How can I change the color of symbols or lines according to a palette?
----------------------------------------------------------------------

If several data sets should be plotted in different colors, one can specify in
``symbolattrs`` and/or ``lineattrs`` a palette like ``color.palette.Rainbow``.
Equidistant colors are chosen spanning the palette from one end to the other.
For example, for three data sets the colors are chosen from the palette at 0,
0.5, and 1. For the rainbow palette, this would correspond to red, green, and
blue, respectively.

In the following example, symbols vary in form and change their color according 
to the rainbow palette at the same time as the connecting lines::

   mystyle = [graph.style.symbol(graph.style.symbol.changecircle,
                                 symbolattrs=[color.palette.Rainbow]),
              graph.style.line(lineattrs=[color.palette.Rainbow])]

See question :ref:`changelist` for a more complete example demonstrating how to
use this style definition and for a comment on the necessity of defining
``mystyle`` (you are of course free to choose a different name).

.. _changelist:

How can I specify changing colors (or other attributes) for symbols or lines?
-----------------------------------------------------------------------------

In ``symbolattrs`` and/or ``lineattrs`` so-called changelist can be used. As an
example ::

   mystyle = graph.style.symbol(symbolattrs=
                                [attr.changelist([color.rgb.red, color.rgb.green])])
   g.plot(graph.data.file("x.dat", x=1, y=2), [mystyle])
   g.plot(graph.data.file("y.dat", x=1, y=2), [mystyle])
   g.plot(graph.data.file("z.dat", x=1, y=2), [mystyle])

will switch between red and green symbols each time a new data set is plotted.
Several changelists can be specified. They are cycled independently and need
not be of the same length. It should be noted that the definition of
``mystyle`` in this example ensures that there is only one instance of the
definition of ``symbolattrs``. Putting an explicit definition of
``symbolattrs`` in each call to ``plot`` would not lead to the desired result
because each time a new instance would be created which then starts with the
first item in the changelist.

It may be necessary to repeat attributes in order that several changelists
cooperate to produce the desired result.  A common situation is that one would
like to cycle through a list of symbols which should be used in alternating
colors. This can be achieved with the following code::

   mystyle = graph.style.symbol(
                   graph.style.symbol.changetriangletwice,
                   symbolattrs=[attr.changelist([color.rgb.red, color.rgb.green])])

which will produce a red triangle, a green triangle, a red circle, a green
circle and so on for diamond and square because ``changetriangletwice`` lists
each symbol twice. If instead of changing between colors one would like to
change between filled and open symbols, one can make use of a predefined
changelist ::

   mystyle = graph.style.symbol(
                   graph.style.symbol.changetriangletwice,
                   symbolattrs=[graph.style.symbol.changefilledstroked])