Creating a Toolbox¶

The Toolbox.for_file classmethod creates a Toolbox object that can be used to render static images to files. The Toolbox.for_gui classmethod creates a Toolbox object that can render visualizations to a GUI canvas. (The only supported GUI toolkit at this time is wxPython.)

Using a Toolbox¶

The Toolbox object consists of a number of factory methods. These methods are all prefixed with new_. When multiple types or styles of a given object (e.g., plots) are available, the first argument to a factory method is a nickname, a string label identifying the requested variant (e.g., new_plot("scatter",...). Subsequent arguments vary, and are described in the documentation for the various objects.

The following example illustrates the use of the Toolbox object:

from rayon import toolbox

def build_chart(t):
    d = t.dataset_from_filename("sample_in.txt")
    c = t.new_chart("square")

    p = t.new_plot("scatter",
                   x_data=d.column(0),
                   y_data=d.column(1))
    c.add_plot(p)

    b1 = t.new_border("hlabel", label="Title")
    c.add_bottom_border(b, height=.05)

    c.set_chart_background("white")
    return c

t = toolbox.Toolbox.for_file()
page = t.new_page_from_filename(
    "sample_out.png", 800, 600)
page.write(build_chart(t))

The Toolbox object¶

class rayon.toolbox.Toolbox(backend)¶

A factory object for creating most of the objects available in Rayon. See Toolbox — Creating objects in Rayon for more information.

Toolbox objects should be created with one of the Toolbox.for_file or Toolbox.for_gui methods, which will properly associate the Toolbox object with a rendering backend.

classmethod for_file()¶

Creates a Toolbox object appropriate for rendering static visualizations to a file.

classmethod for_gui(gui='wx')¶

Create a Toolbox object with a backend for rendering to a GUI.

gui is a string label identifying the GUI backend to use. At this time, specifying any value except wx will raise an exception.

new_border(nickname[, ...]) → border¶

Creates a border from nickname. Additional arguments will be passed to the border subtype referred to by nickname.

The nickname argument may be one of the following values:

• hlabel
• hline
• horizontal
• hsplit
• none
• vertical
• vlabel
• vline
• vsplit

new_chart(nickname[, ...]) → chart¶

Creates a chart from nickname. Additional arguments will be passed to the chart subtype referred to by nickname.

The nickname argument may be one of the following values:

• square
• tiled
• tiled_adv

new_column_from_constant(constant, length) → column¶

Creates a Column object from a constant value and a length.

constant will be returned for all elements in this column.

length is the length of the column.

new_column_from_data(data : iterable) → column¶

Creates a new Column object from a set of data.

raw_data is an iterable (list, tuple, iterator, etc.) containing single values of the same data type.

new_dataset_from_filename(fname[, colnames, typemap, delimiter]) → Dataset¶

Creates a Dataset from a file. The format of the file is described On-disk format.

If supplied, colnames is a sequence of strings containing column names for the data. There must be as many names in the sequence as there are columns in the data. If not specified, column names from the file will be used; if the file contains no column names, the Dataset will be created without column names.

If supplied, typemap is a list of functions that take a string representation of an object and return the object. There must be as many functions in the sequence as there are columns in the data. If not specified, strings composed entirely of numbers (optionally with a single period) will be converted to numbers, and everything else will be left as strings.

If supplied, delimiter is the character used in the file to delimit fields in a record. The default delimiter is the pipe (|) character. The delimiter may also be specified in the file format; in that case, this argument is ignored.

If first_line_is_colnames is True and no other column names are supplied in the file (i.e., with a header or a specially-commented first line), assume the first line of the input is a delimited list of column names. Use this when parsing input from external programs (such as the SiLK tools) which pass their column names as the first line in a file but do not indicate them in any other way.

new_dataset_from_stream(stream[, colnames, typemap, delimiter]) → Dataset¶

Creates a Dataset from data read from an input stream. The format of the streamed data is described in On-disk format.

If supplied, colnames is a sequence of strings containing column names for the data. There must be as many names in the sequence as there are columns in the data. If not specified, column names from the file will be used; if the file contains no column names, the Dataset will be created without column names.

If supplied, typemap is a list of functions that take a string representation of an object and return the object. There must be as many functions in the sequence as there are columns in the data. If not specified, strings composed entirely of numbers (optionally with a single period) will be converted to numbers, and everything else will be left as strings.

If supplied, delimiter is the character used in the file to delimit fields in a record. The default delimiter is the pipe (|) character. The delimiter may also be specified in the file format; in that case, this argument is ignored.

If first_line_is_colnames is True and no other column names are supplied in the file (i.e., with a header or a specially-commented first line), assume the first line of the input is a delimited list of column names. Use this when parsing input from external programs (such as the SiLK tools) which pass their column names as the first line in a file but do not indicate them in any other way.

new_dataset_from_columns(columns[, colnames, header, sort_key]) → Dataset¶

Creates a Dataset from an iterable (list, tuple, iterator, etc.) of columns.

columns is an iterable containing columns of data. The columns may be lists, tuples, other iterables, or Column objects. All elements in columns must be of equal length.

If specified, colnames is an iterable of strings. Each item represents the name of the corresponding column in the dataset. The number of elements in colnames should be equal to the number of items in columns.

If specified, header is a dictionary whose keys and values are both strings containing mostly arbitrary metadata about the dataset. Some header names, however, are reserved; see Special Headers.

If specified, sortkey is a function that takes a row and returns a comparable. (See the sort method for a more precise definition.) This function will be used to determine the current sort order of the dataset. If not supplied, the current sort order will be the order of the items as they appear in columns.

new_dataset_from_rows(rows[, colnames, header, sort_key]) → Dataset¶

Creates a Dataset from an iterable (list, tuple, iterator, etc.) of rows.

rows is an iterable containing rows of data. The rows may be lists, tuples, other iterables or dictionaries. All elements in rows must be of equal length. If rows contains dictionaries, they must additionally all have the same keys.

If specified, colnames is an iterable of strings . Each item represents the name of the corresponding column in the dataset. The number of elements in colnames should be equal to the number of elements in any record in rows.

If rows contains dictionaries and colnames is supplied, every element in colnames must be a key in the dictionary contents of rows. If colnames is not supplied, the order of columns in the dataset will be the alphanumeric sort order of the keys of the dictionaries in rows.

If specified, header is a dictionary whose keys and values are both strings containing mostly arbitrary metadata about the dataset. Some header names, however, are reserved; see Special Headers.

If specified, sortkey is a function that takes a Row object and returns a comparable. (See the sort method for a more precise definition.) This function will be used to determine the current sort order of the dataset. If not supplied, the current sort order will be insert order.

new_gridlines(nickname[, ...]) → gridlines¶

Creates a gridlines from nickname. The nickname argument may be one of the following values:

• horizontal
• vertical

Additional arguments beyond nickname are scale or data specifications as they would be given to plots. (See Creating grid lines and Creating Plots.)

new_gridlines_from_border(nickname, border[, tickset_idx=0, ...]) → gridlines¶

Creates grid lines from nickname. The ticksets in border will be used to generate the positions for the lines.

The nickname argument may be one of the following values:

• horizontal
• vertical

border is a tickable border containing at least one tick set.

If supplied, tickset_idx is the index of the tickset to use to generate grid lines in border.

Additional arguments are scale or data specifications as they would be given to plots. (See Creating grid lines and Creating Plots.)

new_gridlines_from_tick_tuples(nickname, scale, tick_tuples[, ...]) → gridlines¶

Creates grid lines from nickname. The tick positions in tick_tuples will be used to generate the positions for the lines

The nickname argument may be one of the following values:

• HorizontalGridLines
• VerticalGridLines

tick_tuples will be used to generate the data for the pos axis of the grid lines.

scale will be used as the scale for the pos axis of the grid lines.

Additional arguments are scale or data specifications as they would be given to plots. (See Creating grid lines and Creating Plots.)

new_labeler([txt, font_size="normal", font_family="default", font_style="normal", font_weight="normal", halign="left", valign="center", color="#000000FF", bgcolor, angle, border : border spec, border_top : border spec, border_bottom : border spec, border_left : border spec, border_right : border spec]) → labeler¶

Creates a new labeler.

If txt is supplied, the labeler will be static – it will only ever render txt. Static labelers are convenient to use for simple labels that will be drawn only once, such as chart titles and captions. If txt is not supplied, the labeler can be drawn many times with different text. In this case, the labeler is used as a template of text properties.

The remaining arguments are described in detail in Specifying Text Properties.

new_labeled_marker(marker, labeler[, label_position="n", label_spacing=5]) → labeled marker¶

Creates a new labeled marker.

marker is a marker that will be used to generate the marked part of the labeled marker.

labeler is a labeler that will be used to generate the labeled part of the labeled marker.

If supplied, label_position describes the position of the label relative to the marker. Valid values are n (above), s (below), e (to the left) and w (to the right).

If supplied, label_spacing is the amount of space between the label and the marker, in device units (points or pixels).

new_line(nickname, color, width[, fixup=True]) → line¶

Creates Rayon line from nickname.

The nickname argument may be one of the following values:

• dashed
• dotdash
• dotted
• none
• solid

color is the color of the line.

width is the width of the line in pixels/points.

If fixup is True, Rayon will attempt to “fix up” perfectly horizontal and vertical lines to avoid anti-aliasing. This behavior is disabled if fixup is False. (See Lines and antialiasing.)

new_line_from_spec(spec[, fixup=True]) → line¶

Creates a Rayon line from spec, as described in Specifying Line Styles.

spec is a string line specification.

If fixup is True, Rayon will attempt to “fix up” perfectly horizontal and vertical lines to avoid anti-aliasing. This behavior is disabled if fixup is False. (See Lines and antialiasing.)

new_marker(nickname[, ...]) → marker¶

Creates a marker from nickname. Additional arguments will be passed to the marker subtype referred to by nickname.

The nickname argument may be one of the following values:

• darrow
• circle
• cross
• dot
• hline
• none
• vline

new_page_from_buffer(buff) → page¶

Create a page that can be used to render a chart into buff. buff should be an in-memory buffer object from the system associated with the rendering backend, representing a 2-dimensional pixel surface.

The rendering backend must support rendering to memory.

new_page_from_filename(filename, width, height) → page¶

Create a page that can be used to render a chart to filename with dimensions width and height. The type of file will be selected based on file extension. Currently supported file formats are SVG, PDF and PNG.

new_plot(nickname[, ...]) → plot¶

Creates a plot from nickname. Additional arguments will be passed to the plot subtype referred to by nickname.

The nickname argument may be one of the following values:

• bar
• field
• filledline
• hbar
• labeledscatter
• line
• scatter

new_scale(nickname[, ...]) → scale¶

Creates a scale from nickname. Additional arguments will be passed to the scale subtype referred to by nickname.

The nickname argument may be one of the following values:

• categorical
• catrange
• clog
• cloggrad
• gradient
• linear
• linbins
• log
• loggrad
• timebins

new_tickset_from_tuples(nickname[, tick_tuples, scale, labeledmarker, alignment=.5]) → tickset¶

Creates a tick set from a set of tick tuples representing where and how ticks should be created.

The nickname argument may be one of the following values:

• default
• ranged

tick_tuples is an iterable of 2-tuples (value, label). value should be a valid input to scale. label is a string representation of value. If label is None, Rayon will convert value to a string using str and use that as the label.

scale is a Rayon scale or a function that can serve as a scale. The output of scale should be a number between 0 and 1 if nickname is default. If nickname is ranged, scale should output a tuple (min, max) describing the minimum and maximum bounds of a range between 0 and 1. (See Range Scales)

labeledmarker is a labeled marker that will be used to draw the tick mark.

If nickname is ranged and if supplied, alignment is a number between 0 and 1 specifying the alignment of the tick mark within the allotted range. A value of 0 for alignment will put the tick mark at the leftmost point in the range; a value of 1 will put it at the rightmost point.

new_tickset_from_spec(nickname[, tick_spec, col, formatter, scale, marker, alignment=.5]) → tickset¶

Creates a tick set from a string specification and a set of sortable data.

The nickname argument may be one of the following values:

• default
• ranged

tick_spec is a string of tick specifications, separated by commas. A tick specification may be one of the following:

Spec	Definition
at(N,M)	The literal value N, M, etc.. (‘Put a tick at N‘)
every(N)	The first point in the data, and every subsequent point at interval N (‘Put a tick every N (e.g., every 10 minutes)’)
ge(N)	All points in the data greater than or equal to N
gt(N)	All points in the data greater than N
le(N)	All points in the data less than or equal to N
lt(N)	All points in the data less than N
max	The largest value in the data
med	The median value in the data (a synonym for p(50))
min	The smallest value in the data
n(N)	Place N ticks evenly along the scale, at ‘nice’ places
p(N)	The value for percentile N
smax	The largest value on the scale
smin	The smallest value on the scale

col is a column of data. (Either an iterable or a Column object.) This data will be used with the specifications to determine the tick positions.

scale is the scale to use to place the tickmark. (See Scales.) It will also be used, if necessary, to compute the smax and smin tick specifications.The output of scale should be a number between 0 and 1 if nickname is default. If nickname is ranged, scale should output a tuple (min, max) describing the minimum and maximum bounds of a range between 0 and 1. (See Range Scales).

labeledmarker is a labeled marker that will be used to draw the tick marks.

If supplied, formatter is either a printf-style format string or a function that takes a value in col and returns a string that will be used to label the tick mark with that value. If formatter is None, Rayon supply a formatter that converts the input value to a string using str and use that as the label.

If nickname is ranged and if supplied, alignment is a number between 0 and 1 specifying the alignment of the tick mark within the allotted range. A value of 0 for alignment will put the tick mark at the leftmost point in the range; a value of 1 will put it at the rightmost point.