Reference

Winston Reference Guide

Overview

Winston provides a set of objects for constructing 2d vector plots.

Winston objects fall into two categories: containers and components. Containers are things like plots and tables, and can be turned into graphical output. Components can't be visualized on their own, but only when added to containers. Containers can contain other containers.

Containers	Components
FramedArray FramedPlot Plot Table	Circle(s) Curve DataBox DataInset DataLabel/Label DataLine/Line Ellipse(s) ErrorBarsX ErrorBarsY FillAbove FillBelow FillBetween	Legend LineX LineY PlotBox PlotInset/Inset PlotLabel PlotLine Point(s) Slope SymmetricErrorBarsX SymmetricErrorBarsY

TeX emulation

Winston includes a simple TeX emulator which recognizes subscripts, superscripts, and many of the math symbol definitions from Appendix F of The TeXbook. All text strings passed to Winston are interpreted as TeX.

PlotContainer

Methods

file( container, filename, options... )

Save container to a file. Valid filename extensions are "eps", "png", and "svg".

getattr( container, key [, notfound] )

Returns the value of the attribute named key if found, otherwise notfound.

setattr( container, key, val )

Sets the attribute named key to val.

x11( container )

Plot the container in an X window.

Attributes

The following attributes are common to all containers.

aspect_ratio	Nothing | Real	Force the aspect ratio (height divided by width) to be a particular value. If `Nothing` the container fills the available space.
page_margin	Real	Extra padding applied when rendering the head container (ie, the container from which show(), write(), etc was called).
title	Nothing | String	Draw a plot-centered supertitle.
title_offset	Real	The distance between the title and the container's contents.
title_style	Style

FramedPlot() <: PlotContainer

This object represents a framed plot, where the axes surround the plotting region, instead of intersecting it. You build a plot by adding components:

p = FramedPlot()
add( p, component... )

Components are rendered in the order they're added.

Basic Attributes

xlabel	String	The x-axis label (bottom of the frame).
xlog	Bool	If true use log scaling, otherwise linear.
xrange	(Real,Real)
ylabel	String	The y-axis label (left of the frame).
ylog	Bool	If true use log scaling, otherwise linear.
yrange	(Real,Real)

These should be sufficient for casual use, but often you'll want greater control over the frame.

Axis Attributes

Each side of the frame is an independent axis object: p.x1 (bottom), p.y1 (left), p.x2 (top), and p.y2 (right). The axis attributes below apply to each of these objects. So for example, to label the right side of the frame, you would say:

setattr( p.y2, "label", "something" )

The label, log, and range attributes are the same as the ones above. For instance, when you set p.xlog you're actually setting p.x1.log.

draw_axis	Bool	If false the spine, ticks, and subticks are not drawn; otherwise it has no effect.
draw_grid	Bool	Grid lines are parallel to and coincident with the ticks.
draw_nothing	Bool	If true nothing is drawn; otherwise it has no effect.
draw_spine	Bool	The spine is the line perpendicular to the ticks.
draw_subticks	Nothing | Bool	If set to `nothing` subticks will be drawn only if ticks are drawn.
draw_ticks	Bool
draw_ticklabels	Bool
grid_style	Style
label	String
label_offset	Real
label_style	Style
log	Bool
range	(Real, Real)
spine_style	Style
subticks	Nothing | Integer | Real[]	Similar to `ticks\*`, except when set to an integer it sets the number of subticks drawn between ticks, not the total number of subticks.
subticks_size	Real
subticks_style	Style
ticks	Nothing | Integer | Real[]	If set to `nothing` ticks will be automagically generated. If set to an integer n, n equally spaced ticks will be drawn. You can provide your own values by setting `ticks` to a sequence.
ticks_size	Real
ticks_style	Style
tickdir	+1 | -1	This controls the direction the ticks and subticks are drawn in. If +1 they point toward the ticklabels and if -1 they point away from the ticklabels.
ticklabels	Nothing | String[]	Ticklabels are the labels marking the values of the ticks. You can provide your own labels by setting `ticklabels` to a list of strings.
ticklabels_dir	+1 | -1
ticklabels_offset	Real
ticklabels_style	Style

So let's say you wanted to color all the ticks red. You could write:

# XXX:doesn't work yet
p.x1.ticks_style["color"] = "red"
p.x2.ticks_style["color"] = "red"
p.y1.ticks_style["color"] = "red"
p.y2.ticks_style["color"] = "red"

but it's tedious, and hazardous for your hands. FramedPlot provides a mechanism for manipulating groups of axes, through the use of the following pseudo-attributes:

frame          ==>     .x1, .x2, .y1, .y2
frame1         ==>     .x1, .y1
frame2         ==>     .x2, .y2
x              ==>     .x1, .x2
y              ==>     .y1, .y2

which lets you write

# XXX:doesn't work yet
p.frame.ticks_style["color"] = "red"

instead.

FramedArray( nrows, ncols ) <: PlotContainer

Use this container if you want to plot an array of similar plots. To add a component to a specific cell, use

add( a[i,j], component... )

where a is a FramedArray object, i is the row number, and j is the column number. You can also add a component to all the cells at once using:

add( a, component... )

Attributes: (in addition to the basic FramedPlot ones)

cellspacing	Real
uniform_limits	Bool	If set to 1 every cell will have the same limits. Otherwise they are only forced to be the same across rows and down columns.

Plot() <: PlotContainer

Plot behaves the same as FramedPlot, except no axes, axis labels, or titles are drawn.

Attributes

(same as FramedPlot, minus the title/label options)

Table( nrows, ncols ) <: PlotContainer

This container allows you to arrange other containers in a grid. To add a container to a specific cell, use

t = Table(nrows, ncols)
t[i,j] = container

where t is the Table object, i is the row number, and j is the column number.

Attributes

cellpadding	Real
cellspacing	Real

Components

Components named Data* take data coordinates, while Plot* objects take plot coordinates, where the lower-left corner of the plot is at (0,0) and the upper-right corner is at (1,1).

Circle( x, y, r )
Circles( x, y, r )

Draw circles centered at (x,y) with radius r.

Curve( x, y )

Draw lines connecting (x[i],y[i]) to (x[i+1],y[i+1]).

Ellipse( x, y, rx, ry, angle )
Ellipses( x, y, rx, ry, angle )

Draw ellipses centered at (x,y), with x-radius rx, y-radius ry, and rotated counterclockwise by angle.

ErrorBarsX( y, xerr_lo, xerr_hi )
ErrorBarsY( x, yerr_lo, yerr_hi )

Draw [XY] error bars. Specifically, the bars extend from (xerr_lo[i],y[i]) to (xerr_hi[i],y[i]) for ErrorBarsX, and (x[i],yerr_lo[i]) to (x[i],yerr_hi[i]) for ErrorBarsY.

FillAbove( x, y )
FillBelow( x, y )

FillAbove/Below fills the region bounded below/above, respectively, by the curve {x,y}.

FillBetween( xA, yA, xB, yB )

Fill the region bounded by the curves {xA,yA} and {xB,yB}.

LineX( x )
LineY( y )

Draw a line of constant [xy].

Point( x, y )
Points( x, y )

Draw symbols at the set of points (x,y).

Slope( slope, p )

Draw the line y = p[2] + slope*(x - p[1]).

SymmetricErrorBarsX( x, y, err )
SymmetricErrorBarsY( x, y, err )

Draw error bars extending from (x[i]-err[i],y[i]) to (x[i]+err[i],y[i]) for SymmetricErrorBarsX, and (x[i],y[i]-err[i]) to (x[i],y[i]+err[i]) for SymmetricErrorBarsY.

DataBox( p, q ) [aka Box]
PlotBox( p, q )

Draws the rectangle defined by points p and q.

DataInset( p, q, container )
PlotInset( p, q, container ) [aka Inset]

Draws container in the rectangle defined by points p and q.

DataLabel( x, y, "label" ) [aka Label]
PlotLabel( x, y, "label" )

Write the text string at the point (x,y). Alignment is governed by halign and valign.

DataLine( p, q ) [aka Line]
PlotLine( p, q )

Draws a line connecting points p and q.

Legend( x, y, components )

TBD. See example 2.

Style

The style properties of components (e.g., color) are controlled through a common set of keyword options passed during object creation. For example,

c = Curve( x, y, "color", "red" )

Keywords which are not relevant (for instance, setting fontface for a Line object) are ignored. After creation, style keywords can be set using the style member function:

style( c, "linetype", "dotted" )

color fillcolor linecolor	Integer | String	Set line or fill color (`color` sets both). A six digit hexadecimal integer, `0xRRGGBB`, is interpreted as an RGB triple. Strings specify color names (eg "red", "lightgrey"). A list of acceptable names can be found in `rgb.txt` (usually found in `/usr/lib/X11/`) and `colors.txt` (usually found in `/usr/share/libplot/`).
linetype	String	Line types are specified by name. Valid names include: "solid" "dotted" "dotdashed" "shortdashed" "longdashed" "dotdotdashed" "dotdotdotdashed"
linewidth	Real
symbolsize	Real
symboltype	Char | String	Symbol types can be specified by name or by character. If a character the font character is used as the plot symbol. Valid symbol names include: "none" "filled circle" "dot" "filled square" "plus" "filled triangle" "asterisk" "filled diamond" "circle" "filled inverted triangle" "cross" "filled fancy square" "square" "filled fancy diamond" "triangle" "half filled circle" "diamond" "half filled square" "star" "half filled triangle" "inverted triangle" "half filled diamond" "starburst" "half filled inverted triangle" "fancy plus" "half filled fancy square" "fancy cross" "half filled fancy diamond" "fancy square" "octagon" "fancy diamond" "filled octagon"
textangle	Real	Rotate text counterclockwise by this number of degrees.
texthalign	"left" "center" "right"	Where to horizontally anchor text strings.
textvalign	"top" "center" "bottom"	Where to vertically anchor text strings.

Config

Winston looks for the site-wide winston.ini configuration file (located in the same directory as the winston source files) when it loads. There are quite a few parameters in winston.ini, but most don't need to be changed. Here's a few you might want to change:

[default]

fontface	HersheySans	Sets the default font face. `HersheySerif` or `HersheySans` is recommended if you have any TeX math-mode material.
fontsize_min	1.25	Sets the minimum fontsize (relative to the size of the plotting window).
symboltype	diamond	Sets the default symbol type.
symbolsize	2.0	Sets the default symbol size.

[window]

width	720	The width (in pixels) of the X window produced by `x11()`.
height	540	The height (in pixels) of the X window produced by `x11()`.
reuse	true	Normally every invocation of `x11()` creates a new X window. This can be annoying during interactive use, so winston reuses the X window when it thinks it's not being called by a script. Set this to `no` to disable this behavior.

---