5.2 Module `graph.axis.axis`: Axes

The following classes are part of the module graph.axis.axis. However, there is a shortcut to access those classes via graph.axis directly.

Instances of the following classes can be passed to the **axes keyword arguments of a graph. Those instances should only be used once.

class linear( min=None, max=None, reverse=0, divisor=None, title=None, parter=parter.autolinear(), manualticks=[], density=1, maxworse=2, rater=rater.linear(), texter=texter.mixed(), painter=painter.regular(), linkpainter=painter.linked())

This class provides a linear axis. min and max define the axis range. When not set, they are adjusted automatically by the data to be plotted in the graph. Note, that some data might want to access the range of an axis (e.g. the function class when no range was provided there) or you need to specify a range when using the axis without plugging it into a graph (e.g. when drawing an axis along a path).

reverse can be set to indicate a reversed axis starting with bigger values first. Alternatively you can fix the axis range by min and max accordingly. When divisor is set, it is taken to divide all data range and position informations while creating ticks. You can create ticks not taking into account a factor by that. title is the title of the axis.

parter is a partitioner instance, which creates suitable ticks for the axis range. Those ticks are merged with ticks manually given by manualticks before proceeding with rating, painting etc. Manually placed ticks win against those created by the partitioner. For automatic partitioners, which are able to calculate several possible tick lists for a given axis range, the density is a (linear) factor to favour more or less ticks. It should not be stressed to much (its likely, that the result would be unappropriate or not at all valid in terms of rating label distances). But within a range of say 0.5 to 2 (even bigger for large graphs) it can help to get less or more ticks than the default would lead to. maxworse is the number of trials with more and less ticks when a better rating was already found. rater is a rater instance, which rates the ticks and the label distances for being best suitable. It also takes into account density. The rater is only needed, when the partitioner creates several tick lists.

texter is a texter instance. It creates labels for those ticks, which claim to have a label, but do not have a label string set already. Ticks created by partitioners typically receive their label strings by texters. The painter is finally used to construct the output. Note, that usually several output constructions are needed, since the rater is also used to rate the distances between the labels for an optimum. The linkedpainter is used as the axis painter, when automatic link axes are created by the createlinked() method.

class lin( ...): This class is an abbreviation of linear described above.

class logarithmic( min=None, max=None, reverse=0, divisor=None, title=None, parter=parter.autologarithmic(), manualticks=[], density=1, maxworse=2, rater=rater.logarithmic(), texter=texter.mixed(), painter=painter.regular(), linkpainter=painter.linked()): This class provides a logarithmic axis. All parameters work like linear. Only two parameters have a different default: parter and rater. Furthermore and most importantly, the mapping between data and graph coordinates is logarithmic.

class log( ...): This class is an abbreviation of logarithmic described above.

class bar( subaxes=None, defaultsubaxis=linear(painter=None, linkpainter=None, parter=None, texter=None), dist=0.5, firstdist=None, lastdist=None, title=None, reverse=0, painter=painter.bar(), linkpainter=painter.linkedbar())

This class provides an axis suitable for a bar style. It handles a discrete set of values and maps them to distinct ranges in graph coordinates. For that, the axis gets a tuple of two values.

The first item is taken to be one of the discrete values valid on this axis. The discrete values can be any hashable type and the order of the subaxes is defined by the order the data is received or the inverse of that when reverse is set.

The second item is passed to the corresponding subaxis. The result of the conversion done by the subaxis is mapped to the graph coordinate range reserved for this subaxis. This range is defined by a size attribute of the subaxis, which can be added to any axis. (see the sized linear axes described below for some axes already having a size argument). When no size information is available for a subaxis, a size value of 1 is used. The baraxis itself calculates its size by suming up the sizes of its subaxes plus firstdist, lastdist and dist times the number of subaxes minus 1.

subaxes should be a list or a dictionary mapping a discrete value of the bar axis to the corresponding subaxis. When no subaxes are set or data is received for an unknown discrete axis value, instances of defaultsubaxis are used as the subaxis for this discrete value.

dist is used as the spacing between the ranges for each distinct value. It is measured in the same units as the subaxis results, thus the default value of 0.5 means half the width between the distinct values as the width for each distinct value. firstdist and lastdist are used before the first and after the last value. When set to None, half of dist is used.

title is the title of the split axes and painter is a specialized painter for an bar axis and linkpainter is used as the painter, when automatic link axes are created by the createlinked() method.

class nestedbar( subaxes=None, defaultsubaxis=bar(dist=0, painter=None, linkpainter=None), dist=0.5, firstdist=None, lastdist=None, title=None, reverse=0, painter=painter.bar(), linkpainter=painter.linkedbar()): This class is identical to the bar axis except for the different default value for defaultsubaxis.

class split( subaxes=None, defaultsubaxis=linear(), dist=0.5, firstdist=0, lastdist=0, title=None, reverse=0, painter=painter.split(), linkpainter=painter.linkedsplit()): This class is identical to the bar axis except for the different default value for defaultsubaxis, firstdist, lastdist, painter, and linkedpainter.

Sometimes you want to alter the default size of 1 of the subaxes. For that you have to add a size attribute to the axis data. The two classes sizedlinear and autosizedlinear do that for linear axes. Their short names are sizedlin and autosizedlin. sizedlinear extends the usual linear axis by an first argument size. autosizedlinear creates the size out of its data range automatically but sets an autolinear parter with extendtick being None in order to disable automatic range modifications while painting the axis.

The axis module also contains classes implementing so called anchored axes, which combine an axis with an positioner and a storage place for axis related data. Since these features are not interesting for the average PyX user, we'll not go into all the details of their parameters and except for some handy axis position methods:

basepath( x1=None, x2=None): Returns a path instance for the base path. x1 and x2 define the axis range, the base path should cover. For None the beginning and end of the path is taken, which might cover a longer range, when the axis is embedded as a subaxis. For that case, a None value extends the range to the point of the middle between two subaxes or the beginning or end of the whole axis, when the subaxis is the first or last of the subaxes.

vbasepath( v1=None, v2=None): Like basepath but in graph coordinates.

gridpath( x): Returns a path instance for the grid path at position x. Might return None when no grid path is available.

vgridpath( v): Like gridpath but in graph coordinates.

tickpoint( x): Returns the position of x as a tuple "(x, y)".

vtickpoint( v): Like tickpoint but in graph coordinates.

tickdirection( x): Returns the direction of a tick at x as a tuple "(dx, dy)". The tick direction points inside of the graph.

vtickdirection( v): Like tickdirection but in graph coordinates.

vtickdirection( v): Like tickdirection but in graph coordinates.

However, there are two anchored axes implementations linkedaxis and anchoredpathaxis which are available to the user to create special forms of anchored axes.

class linkedaxis( linkedaxis=None, errorname="manual-linked", painter=_marker): This class implements an anchored axis to be passed to a graph constructor to manually link the axis to another anchored axis instance linkedaxis. Note that you can skip setting the value of linkedaxis in the constructor, but set it later on by the setlinkedaxis method described below. errorname is printed within error messages when the data is used and some problem occurs. painter is used for painting the linked axis instead of the linkedpainter provided by the linkedaxis.

setlinkedaxis( linkedaxis): This method can be used to set the linkedaxis after constructing the axis. By that you can create several graph instances with cycled linked axes.

class anchoredpathaxis( path, axis, direction=1): This class implements an anchored axis the path path. direction defines the direction of the ticks. Allowed values are 1 (left) and -1 (right).

The anchoredpathaxis contains as any anchored axis after calling its create method the painted axis in the canvas member attribute. The function pathaxis has the same signature like the anchoredpathaxis class, but immediately creates the axis and returns the painted axis.

5.2 Module graph.axis.axis: Axes

5.2 Module `graph.axis.axis`: Axes