4.5 Module `graph.style`: Styles

Please note that we are talking about graph styles here. Those are responsible for plotting symbols, lines, bars and whatever else into a graph. Do not mix it up with path styles like the line width, the line style (solid, dashed, dotted etc.) and others.

The following classes provide styles to be used at the plot() method of a graph. The plot method accepts a list of styles. By that you can combine several styles at the very same time.

Some of the styles below are hidden styles. Those do not create any output, but they perform internal data handling and thus help on modularization of the styles. Usually, a visible style will depend on data provided by one or more hidden styles but most of the time it is not necessary to specify the hidden styles manually. The hidden styles register themself to be the default for providing certain internal data.

class pos( epsilon=1e-10): This class is a hidden style providing a position in the graph. It needs a data column for each graph dimension. For that the column names need to be equal to an axis name. Data points are considered to be out of graph when their position in graph coordinates exceeds the range [0:1] by more than epsilon.

class range( usenames=, epsilon=1e-10)

This class is a hidden style providing an errorbar range. It needs data column names constructed out of a axis name X for each dimension errorbar data should be provided as follows:

data name	description
`Xmin`	minimal value
`Xmax`	maximal value
`dX`	minimal and maximal delta
`dXmin`	minimal delta
`dXmax`	maximal delta

When delta data are provided the style will also read column data for the axis name X itself. usenames allows to insert a translation dictionary from axis names to the identifiers X.

epsilon is a comparison precision when checking for invalid errorbar ranges.

class symbol( symbol=changecross, size=0.2*unit.v_cm, symbolattrs=[]): This class is a style for plotting symbols in a graph. symbol refers to a (changeable) symbol function with the prototype symbol(c, x_pt, y_pt, size_pt, attrs) and draws the symbol into the canvas c at the position (x_pt, y_pt) with size size_pt and attributes attrs. Some predefined symbols are available in member variables listed below. The symbol is drawn at size size using symbolattrs. symbolattrs is merged with defaultsymbolattrs which is a list containing the decorator deco.stroked. An instance of symbol is the default style for all graph data classes described in section 4.4 except for function and paramfunction.

The class symbol provides some symbol functions as member variables, namely:

cross: A cross. Should be used for stroking only.

plus: A plus. Should be used for stroking only.

square: A square. Might be stroked or filled or both.

triangle: A triangle. Might be stroked or filled or both.

circle: A circle. Might be stroked or filled or both.

diamond: A diamond. Might be stroked or filled or both.

symbol provides some changeable symbol functions as member variables, namely:

changecross: attr.changelist([cross, plus, square, triangle, circle, diamond])

changeplus: attr.changelist([plus, square, triangle, circle, diamond, cross])

changesquare: attr.changelist([square, triangle, circle, diamond, cross, plus])

changetriangle: attr.changelist([triangle, circle, diamond, cross, plus, square])

changecircle: attr.changelist([circle, diamond, cross, plus, square, triangle])

changediamond: attr.changelist([diamond, cross, plus, square, triangle, circle])

changesquaretwice: attr.changelist([square, square, triangle, triangle, circle, circle, diamond, diamond])

changetriangletwice: attr.changelist([triangle, triangle, circle, circle, diamond, diamond, square, square])

changecircletwice: attr.changelist([circle, circle, diamond, diamond, square, square, triangle, triangle])

changediamondtwice: attr.changelist([diamond, diamond, square, square, triangle, triangle, circle, circle])

The class symbol provides two changeable decorators for alternated filling and stroking. Those are especially useful in combination with the change-twice-symbol methods above. They are:

changestrokedfilled: attr.changelist([deco.stroked, deco.filled])

changefilledstroked: attr.changelist([deco.filled, deco.stroked])

class line( lineattrs=[]): This class is a style to stroke lines in a graph. lineattrs is merged with defaultlineattrs which is a list containing the member variable changelinestyle as described below. An instance of line is the default style of the graph data classes function and paramfunction described in section 4.4.

The class line provides a changeable line style. Its definition is:

changelinestyle: attr.changelist([style.linestyle.solid, style.linestyle.dashed, style.linestyle.dotted, style.linestyle.dashdotted])

class impulses( lineattrs=[], fromvalue=0, frompathattrs=[], valueaxisindex=1): This class is a style to plot impulses. lineattrs is merged with defaultlineattrs which is a list containing the member variable changelinestyle of the line class. fromvalue is the baseline value of the impulses. When set to None, the impulses will start at the baseline. When fromvalue is set, frompathattrs are the stroke attributes used to show the impulses baseline path.

class errorbar( size=0.1*unit.v_cm, errorbarattrs=[], epsilon=1e-10): This class is a style to stroke errorbars in a graph. size is the size of the caps of the errorbars and errorbarattrs are the stroke attributes. Errorbars and error caps are considered to be out of the graph when their position in graph coordinates exceeds the range [0:1] by more that epsilon. Out of graph caps are omitted and the errorbars are cut to the valid graph range.

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=[]): This class is a style to stroke text in a graph. The text to be written has to be provided in the data column named textname. textdx and textdy are the position of the text with respect to the position in the graph. Alternatively you can specify a dxname and a dyname and provide appropriate data in those columns to be taken in units of dxunit and dyunit to specify the position of the text for each point separately. textattrs are text attributes for the output of the text. Those attributes are merged with the default attributes textmodule.halign.center and textmodule.vshift.mathaxis.

class arrow( linelength=0.25*unit.v_cm, arrowsize=0.15*unit.v_cm, lineattrs=[], arrowattrs=[], arrowpos=0.5, epsilon=1e-10): This class is a style to plot short lines with arrows into a two-dimensional graph to a given graph position. The arrow parameters are defined by two additional data columns named size and angle define the size and angle for each arrow. size is taken as a factor to arrowsize and linelength, the size of the arrow and the length of the line the arrow is plotted at. angle is the angle the arrow points to with respect to a horizontal line. The angle is taken in degrees and used in mathematically positive sense. lineattrs and arrowattrs are styles for the arrow line and arrow head, respectively. arrowpos defines the position of the arrow line with respect to the position at the graph. The default 0.5 means centered at the graph position, whereas 0 and 1 creates the arrows to start or end at the graph position, respectively. epsilon is used as a cutoff for short arrows in order to prevent numerical instabilities.

class rect( gradient=color.gradient.Grey): This class is a style to plot colored rectangles into a two-dimensional graph. The size of the rectangles is taken from the data provided by the range style. The additional data column named color specifies the color of the rectangle defined by gradient. The valid color range is [0:1].

$\begin{note} Although this style can be used for plotting colored surfaces, it ... ...s. Improved support for colored surfaces is planned for the future. \end{note}$

class histogram( lineattrs=[], steps=0, fromvalue=0, frompathattrs=[], fillable=0, rectkey=0, autohistogramaxisindex=0, autohistogrampointpos=0.5, epsilon=1e-10)

This class is a style to plot histograms. lineattrs is merged with defaultlineattrs which is [deco.stroked]. When steps is set, the histrogram is plotted as steps instead of the default being a boxed histogram. fromvalue is the baseline value of the histogram. When set to None, the histogram will start at the baseline. When fromvalue is set, frompathattrs are the stroke attributes used to show the histogram baseline path.

The fillable flag changes the stoke line of the histogram to make it fillable properly. This is important on non-steped histograms or on histograms, which hit the graph boundary. rectkey can be set to generate a rectanglar area instead of a line in the graph key.

Usually, a histogram wants a range specification (like for an errorbar) in one graph dimension and a value for the other graph dimension. By that, the widths of the histogram boxes might be variable. But a typical use case is, that you just provide graph positions for both graph dimensions. Then autohistogramaxisindex defines the graph dimension where the histogram should be plotted on top of it. (0 thus means a histogram at the x axes and 1 for the y axes.) The style will then demand equal spaced values on this axis. The histogram boxes are usually centered on those values for autohistogrampointpos equals 0.5, but they can also be aligned at the right side or left side of this value for autohistogrampointpos being 0 or 1.

Positions of the histograms are considered to be out of graph when they exceed the graph coordinate range [0:1] by more than epsilon.

class barpos( fromvalue=None, frompathattrs=[], epsilon=1e-10): This class is a hidden style providing position information in a bar graph. Those graphs need to contain a specialized axis, namely a bar axis. The data column for this bar axis is named Xname where X is an axis name. In the other graph dimension the data column name must be equal to an axis name. To plot several bars in a single graph side by side, you need to have a nested bar axis and provide a tuple as data for nested bar axis.
The bars start at fromvalue when provided. The fromvalue is marked by a gridline stroked using frompathattrs. Thus this hidden style might actually create some output. The value of a bar axis is considered to be out of graph when its position in graph coordinates exceeds the range [0:1] by more than epsilon.

class stackedbarpos( stackname, addontop=0, epsilon=1e-10): This class is a hidden style providing position information in a bar graph by stacking a new bar on top of another bar. The value of the new bar is taken from the data column named stackname. When addontop is set, the values is taken relative to the previous top of the bar.

class bar( barattrs=[]): This class draws bars in a bar graph. The bars are filled using barattrs. barattrs is merged with defaultbarattrs which is a list containing [color.gradient.Rainbow, deco.stroked([color.grey.black])].

class changebar( barattrs=[]): This style works like the bar style, but instead of the barattrs to be changed on subsequent data instances the barattrs are changed for each value within a single data instance. In the result the style can't be applied to several data instances. The style raises an error instead.

class gridpos( index1=0, index2=1, gridlines1=1, gridlines2=1, gridattrs=[], epsilon=1e-10): This class is a hidden style providing rectangular grid information out of graph positions for graph dimensions index1 and index2. Data points are considered to be out of graph when their position in graph coordinates exceeds the range [0:1] by more than epsilon. Data points are merged to a single graph coordinate value when their difference in graph coordinates is below epsilon.

class grid( gridlines1=1, gridlines2=1, gridattrs=[]): Strokes a rectangular grid in the first grid direction, when gridlines1 is set and in the second grid direction, when gridlines2 is set. gridattrs is merged with defaultgridattrs which is a list containing the member variable changelinestyle of the line class.

class surface( colorname="color", gradient=color.gradient.Grey, mincolor=None, maxcolor=None, gridlines1=0.05, gridlines2=0.05, gridcolor=None, backcolor=color.gray.black)

Draws a surface of a rectangular grid. Each rectangle is divided into 4 triangles.

The grid can be colored using values provided by the data column named columnname. The values are rescaled to the range [0:1] using mincolor and maxcolor (which are taken from the minimal and maximal values, but larger bounds could be set).

If no columnname column exists, the surface style falls back to a lightning coloring taking into account the angle between the view ray and the triangle and the distance between viewer and triangle. The precise conversion is defined in the lightning method.

If a gridcolor is set, the rectangular grid is marked by small stripes of the relative (compared to each rectangle) size of gridlines1 and gridlines2 for the first and second grid direction, respectively.

backcolor is used to fill triangles shown from the back. If backcolor is set to None, back sides are not drawn differently from the front sides.

The surface is encoded using a single mesh. While this is quite space efficient, it has the following implications:

All colors must use the same color space.
HSB colors are not allowed, whereas Gray, RGB, and CMYK are allowed. You can convert HSB colors into a different color space before passing them to the surface.
The grid itself is also constructed out of triangles. The grid is transformed along with the triangles thus looking quite different from a stroked grid (as done by the grid style).
Occlusion is handled by proper painting order.
Color changes are continuous (in the selected color space) for each triangle.

4.5 Module graph.style: Styles

4.5 Module `graph.style`: Styles