4.3 Module `graph.graph`: Graphs

The classes graphxy and graphxyz are part of the module graph.graph. However, there are shortcuts to access the classes via graph.graphxy and graph.graphxyz, respectively.

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)

This class provides an x-y-graph. A graph instance is also a fully functional canvas.

The position of the graph on its own canvas is specified by xpos and ypos. The size of the graph is specified by width, height, and ratio. These parameters define the size of the graph area not taking into account the additional space needed for the axes. Note that you have to specify at least width or height. ratio will be used as the ratio between width and height when only one of these is provided.

key can be set to a graph.key.key instance to create an automatic graph key. None omits the graph key.

backgroundattrs is a list of attributes for drawing the background of the graph. Allowed are decorators, strokestyles, and fillstyles. None disables background drawing.

axisdist is the distance between axes drawn at the same side of a graph.

xaxisat and yaxisat specify a value at the y and x axis, where the corresponding axis should be moved to. It's a shortcut for corresonding calls of axisatv() described below. Moving an axis by xaxisat or yaxisat disables the automatic creation of a linked axis at the opposite side of the graph.

**axes receives axes instances. Allowed keywords (axes names) are x, x2, x3, etc. and y, y2, y3, etc. When not providing an x or y axis, linear axes instances will be used automatically. When not providing a x2 or y2 axis, linked axes to the x and y axes are created automatically and vice versa. As an exception, a linked axis is not created automatically when the axis is placed at a specific position by xaxisat or yaxisat. You can disable the automatic creation of axes by setting the linked axes to None. The even numbered axes are plotted at the top (x axes) and right (y axes) while the others are plotted at the bottom (x axes) and left (y axes) in ascending order each.

Some instance attributes might be useful for outside read-access. Those are:

axes: A dictionary mapping axes names to the anchoredaxis instances.

To actually plot something into the graph, the following instance method plot() is provided:

plot( data, styles=None)

Adds data to the list of data to be plotted. Sets styles to be used for plotting the data. When styles is None, the default styles for the data as provided by data is used.

data should be an instance of any of the data described in section 4.4.

When the same combination of styles (i.e. the same references) are used several times within the same graph instance, the styles are kindly asked by the graph to iterate their appearance. Its up to the styles how this is performed.

Instead of calling the plot method several times with different data but the same style, you can use a list (or something iterateable) for data.

While a graph instance only collects data initially, at a certain point it must create the whole plot. Once this is done, further calls of plot() will fail. Usually you do not need to take care about the finalization of the graph, because it happens automatically once you write the plot into a file. However, sometimes position methods (described below) are nice to be accessible. For that, at least the layout of the graph must have been finished. By calling the do-methods yourself you can also alter the order in which the graph components are plotted. Multiple calls to any of the do-methods have no effect (only the first call counts). The orginal order in which the do-methods are called is:

dolayout( ): Fixes the layout of the graph. As part of this work, the ranges of the axes are fitted to the data when the axes ranges are allowed to adjust themselves to the data ranges. The other do-methods ensure, that this method is always called first.

dobackground( ): Draws the background.

doaxes( ): Inserts the axes.

doplot( plotitem): Plots the plotitem as returned by the graphs plot method.

dodata( ): Plots the data.

dokey( ): Inserts the graph key.

finish( ): Finishes the graph by calling all pending do-methods. This is done automatically, when the output is created.

The graph provides some methods to access its geometry:

pos( x, y, xaxis=None, yaxis=None): Returns the given point at x and y as a tuple (xpos, ypos) at the graph canvas. x and y are anchoredaxis instances for the two axes xaxis and yaxis. When xaxis or yaxis are None, the axes with names x and y are used. This method fails if called before dolayout().

vpos( vx, vy): Returns the given point at vx and vy as a tuple (xpos, ypos) at the graph canvas. vx and vy are graph coordinates with range [0:1].

vgeodesic( vx1, vy1, vx2, vy2): Returns the geodesic between points vx1, vy1 and vx2, vy2 as a path. All parameters are in graph coordinates with range [0:1]. For graphxy this is a straight line.

vgeodesic_el( vx1, vy1, vx2, vy2): Like vgeodesic() but this method returns the path element to connect the two points.

Further geometry information is available by the axes instance variable, with is a dictionary mapping axis names to anchoredaxis instances. Shortcuts to the anchoredaxis positioner methods for the x- and y-axis become available after dolayout() as graphxy methods Xbasepath, Xvbasepath, Xgridpath, Xvgridpath, Xtickpoint, Xvtickpoint, Xtickdirection, and Xvtickdirection where the prefix X stands for x and y.

axistrafo( axis, t): This method can be used to apply a transformation t to an anchoredaxis instance axis to modify the axis position and the like. This method fails when called on a not yet finished axis, i.e. it should be used after dolayout().

axisatv( axis, v): This method calls axistrafo() with a transformation to move the axis axis to a graph position v (in graph coordinates).

The class graphxyz is very similar to the graphxy class, except for its additional dimension. In the following documentation only the differences to the graphxy class are described.

class graphxyz( xpos=0, ypos=0, size=None, xscale=1, yscale=1, zscale=1/goldenmean, projector=central(10, -30, 30), key=None, **axes)

This class provides an x-y-z-graph.

The position of the graph on its own canvas is specified by xpos and ypos. The size of the graph is specified by size and the length factors xscale, yscale, and zscale. The final size of the graph depends on the projector projector, which is called with x, y, and z values up to xscale, yscale, and zscale respectively and scaling the result by size. For a parallel projector changing size is thus identical to changing xscale, yscale, and zscale by the same factor. For the central projector the projectors internal distance would also need to be changed by this factor. Thus size changes the size of the whole graph without changing the projection.

projector defines the conversion of 3d coordinates to 2d coordinates. It can be an instance of central or parallel described below.

**axes receives axes instances as for graphxyz. The graphxyz allows for 4 axes per graph dimension x, x2, x3, x4, y, y2, y3, y4, z, z2, z3, and z4. The x-y-plane is the horizontal plane at the bottom and the x, x2, y, and y2 axes are placed at the boundary of this plane with x and y always being in front. x3, x4, y3, and y4 are handled similar, but for the top plane of the graph. The z axis is placed at the origin of the x and y dimension, whereas z2 is placed at the final point of the x dimension, z3 at the final point of the y dimension and z4 at the final point of the x and y dimension together.

central: The central attribute of the graphxyz is the central class. See the class description below.

parallel: The parallel attribute of the graphxyz is the parallel class. See the class description below.

Regarding the 3d to 2d transformation the methods pos, vpos, vgeodesic, and vgeodesic_el are available as for class graphxy and just take an additional argument for the dimension. Note that a similar transformation method (3d to 2d) is available as part of the projector as well already, but only the graph acknowledges its size, the scaling and the internal tranformation of the graph coordinates to the scaled coordinates. As the projector also implements a zindex and a angle method, those are also available at the graph level in the graph coordinate variant (i.e. having an additional v in its name and using values from 0 to 1 per dimension).

vzindex( vx, vy, vz): The depths of the point defined by vx, vy, and vz scaled to a range [-1:1] where 1 in closed to the viewer. All arguments passed to the method are in graph coordinates with range [0:1].

vangle( vx1, vy1, vz1, vx2, vy2, vz2, vx3, vy3, vz3): The cosine of the angle of the view ray thru point (vx1, vy1, vz1) and the plane defined by the points (vx1, vy1, vz1), (vx2, vy2, vz2), and (vx3, vy3, vz3). All arguments passed to the method are in graph coordinates with range [0:1].

There are two projector classes central and parallel:

class central( distance, phi, theta, anglefactor=math.pi/180)

Instances of this class implement a central projection for the given parameters.

distance is the distance of the viewer from the origin. Note that the graphxyz class uses the range -xscale to xscale, -yscale to yscale, and -zscale to zscale for the coordinates x, y, and z. As those scales are of the order of one (by default), the distance should be of the order of 10 to give nice results. Smaller distances increase the central projection character while for huge distances the central projection becomes identical to the parallel projection.

phi is the angle of the viewer in the x-y-plane and theta is the angle of the viewer to the x-y-plane. The standard notation for spheric coordinates are used. The angles are multiplied by anglefactor which is initialized to do a degree in radiant transformation such that you can specify phi and theta in degree while the internal computation is always done in radiants.

class parallel( phi, theta, anglefactor=math.pi/180): Instances of this class implement a parallel projection for the given parameters. There is no distance for that transformation (compared to the central projection). All other parameters are identical to the central class.

4.3 Module graph.graph: Graphs

4.3 Module `graph.graph`: Graphs