# toyplot.canvas module¶

Implements the toyplot.canvas.Canvas class, which defines the space that is available for creating plots.

class toyplot.canvas.AnimationFrame(index, begin, end, changes)[source]

Bases: object

Used to specify modifications to a toyplot.canvas.Canvas during animation.

Do not create AnimationFrame instances yourself, an instance of AnimationFrame is automatically created by toyplot.canvas.Canvas.animate() or toyplot.canvas.Canvas.time() and passed to your callback.

duration()[source]

Return the duration of the current animation frame, in seconds.

index()[source]

Return the current animation frame index.

set_datum_style(mark, series, datum, style)[source]

Change the style of one datum in a toyplot.mark.Mark at the current frame.

Parameters: mark (toyplot.mark.Mark instance) index (zero-based index of the datum to modify) style (dict containing CSS style information)
set_mark_style(mark, style)[source]

Change the style of a mark.

Parameters: mark (toyplot.mark.Mark instance) style (dict containing CSS style information)
time()[source]

Return the current animation time, in seconds.

class toyplot.canvas.Canvas(width=None, height=None, style=None, autorender=None, autoformat=None)[source]

Bases: object

Top-level container for Toyplot drawings.

Parameters: width (number, string, or (number, string) tuple, optional) – Width of the canvas. Assumes CSS pixels if units aren’t provided. Defaults to 600px (6.25”) if unspecified. See Units for details on how Toyplot handles real world units. height (number, string, or (number, string) tuple, optional) – Height of the canvas. Assumes CSS pixels if units aren’t provided. Defaults to the canvas width if unspecified. See Units for details on how Toyplot handles real world units. style (dict, optional) – Collection of CSS styles to apply to the canvas. autorender (boolean, optional) – Turn autorendering on / off for this canvas. Default: use the global autorender flag.

Examples

The following would create a Canvas 8 inches wide and 6 inches tall, with a yellow background:

>>> canvas = toyplot.Canvas("8in", "6in", style={"background-color":"yellow"})

animate(frames, callback=None)[source]

Generate a collection of animation frames, calling a callback to store an explicit representation of what changes at each frame.

Parameters: frames (integer, tuple, or sequence) – Pass a sequence of values that specify the time (in seconds) of the beginning / end of each frame. Note that the number of frames will be the length of the sequence minus one. Alternatively, you can pass a 2-tuple containing the number of frames and the frame rate in frames-per-second. Finally, you may simply specify the number of frames, in which case the rate will default to 30 frames-per-second. callback (function) – The callback function will be called once per frame, and will receive an instance of toyplot.canvas.AnimationFrame as its sole argument. The callback function can access the frame number, time, and duration from the state object, and should use the other methods provided by the state object to make changes to the canvas.
autorender(enable=None, autoformat=None)[source]

Enable / disable canvas autorendering.

Autorendering - which is enabled by default when a canvas is created - controls how the canvas should be displayed automatically without caller intervention in certain interactive environments, such as Jupyter notebooks.

Note that autorendering is disabled when a canvas is explicitly shown using any of the rendering backends.

Parameters: enable (boolean, optional) – Turn autorendering on / off. Defaults to the value at toyplot.config.autorender. format (string, optional) – Specify the format (“html” or “png”) to be used for autorendering. Defaults to the value at toyplot.config.autoformat.
axes(bounds=None, rect=None, corner=None, grid=None, gutter=50, xmin=None, xmax=None, ymin=None, ymax=None, aspect=None, show=True, xshow=True, yshow=True, label=None, xlabel=None, ylabel=None, xticklocator=None, yticklocator=None, xscale='linear', yscale='linear', padding=10)[source]
cartesian(bounds=None, rect=None, corner=None, grid=None, gutter=50, xmin=None, xmax=None, ymin=None, ymax=None, aspect=None, show=True, xshow=True, yshow=True, label=None, xlabel=None, ylabel=None, xticklocator=None, yticklocator=None, xscale='linear', yscale='linear', padding=10)[source]

Add a set of Cartesian axes to the canvas.

Parameters: bounds ((xmin, xmax, ymin, ymax) tuple, optional) – Use the bounds property to position / size the axes by specifying the position of each of its boundaries. Assumes CSS pixels if units aren’t provided, and supports all units described in Units, including percentage of the canvas width / height. rect ((x, y, width, height) tuple, optional) – Use the rect property to position / size the axes by specifying its upper-left-hand corner, width, and height. Assumes CSS pixels if units aren’t provided, and supports all units described in Units, including percentage of the canvas width / height. corner ((corner, inset, width, height) tuple, optional) – Use the corner property to position / size the axes by specifying its width and height, plus an inset from a corner of the canvas. Allowed corner values are “top-left”, “top”, “top-right”, “right”, “bottom-right”, “bottom”, “bottom-left”, and “left”. The width and height may be specified using absolute units as described in Units, or as a percentage of the canvas width / height. The inset only supports absolute drawing units. All units default to CSS pixels if unspecified. grid ((rows, columns, index) tuple, or (rows, columns, i, j) tuple, or (rows, columns, i, rowspan, j, columnspan) tuple, optional) – Use the grid property to position / size the axes using a collection of grid cells filling the canvas. Specify the number of rows and columns in the grid, then specify either a zero-based cell index (which runs in left-ot-right, top-to-bottom order), a pair of i, j cell coordinates, or a set of i, column-span, j, row-span coordinates so the legend can cover more than one cell. gutter (size of the gutter around grid cells, optional) – Specifies the amount of empty space to leave between grid cells When using the grid parameter for positioning. Assumes CSS pixels by default, and supports all of the absolute units described in Units. xmin, xmax, ymin, ymax (float, optional) – Used to explicitly override the axis domain (normally, the domain is implicitly defined by any marks added to the axes). aspect (string, optional) – Set to “fit-range” to automatically expand the domain so that its aspect ratio matches the aspect ratio of the range. show (bool, optional) – Set to False to hide the axes (the axes contents will still be visible). xshow, yshow (bool, optional) – Set to False to hide individual axes. label (string, optional) – Human-readable axes label. xlabel, ylabel (string, optional) – Human-readable axis labels. xticklocator, yticklocator (toyplot.locator.TickLocator, optional) – Controls the placement and formatting of axis ticks and tick labels. xscale, yscale (“linear”, “log”, “log10”, “log2”, or a (“log”, ) tuple, optional) – Specifies the mapping from data to canvas coordinates along an axis. padding (number, string, or (number, string) tuple, optional) – Distance between the axes and plotted data. Assumes CSS pixels if units aren’t provided. See Units for details on how Toyplot handles real-world units. axes toyplot.coordinates.Cartesian
color_scale(colormap, x1=None, y1=None, x2=None, y2=None, width=10, offset=None, bounds=None, rect=None, corner=None, grid=None, gutter=50, min=None, max=None, show=True, label=None, ticklocator=None, scale='linear', padding=10)[source]

Add a color scale to the canvas.

The color scale displays a mapping from scalar values to colors, for the given colormap. Note that the supplied colormap must have an explicitly defined domain (specified when the colormap was created), otherwise the mapping would be undefined.

Parameters: colormap (toyplot.color.Map, required) – Colormap to be displayed. min, max (float, optional) – Used to explicitly override the domain that will be shown. show (bool, optional) – Set to False to hide the axis (the color bar will still be visible). label (string, optional) – Human-readable label placed below the axis. ticklocator (toyplot.locator.TickLocator, optional) – Controls the placement and formatting of axis ticks and tick labels. scale (“linear”, “log”, “log10”, “log2”, or a (“log”, ) tuple, optional) – Specifies the mapping from data to canvas coordinates along an axis. axes toyplot.coordinates.Numberline
height

Height of the canvas in CSS pixels.

image(data, bounds=None, rect=None, corner=None, grid=None, gutter=50)[source]

Add an image to the canvas.

Parameters: data (image, or (image, colormap) tuple) bounds ((xmin, xmax, ymin, ymax) tuple, optional) – Use the bounds property to position / size the image by specifying the position of each of its boundaries. Assumes CSS pixels if units aren’t provided, and supports all units described in Units, including percentage of the canvas width / height. rect ((x, y, width, height) tuple, optional) – Use the rect property to position / size the image by specifying its upper-left-hand corner, width, and height. Assumes CSS pixels if units aren’t provided, and supports all units described in Units, including percentage of the canvas width / height. corner ((corner, inset, width, height) tuple, optional) – Use the corner property to position / size the image by specifying its width and height, plus an inset from a corner of the canvas. Allowed corner values are “top-left”, “top”, “top-right”, “right”, “bottom-right”, “bottom”, “bottom-left”, and “left”. The width and height may be specified using absolute units as described in Units, or as a percentage of the canvas width / height. The inset only supports absolute drawing units. All units default to CSS pixels if unspecified. grid ((rows, columns, index) tuple, or (rows, columns, i, j) tuple, or (rows, columns, i, rowspan, j, columnspan) tuple, optional) – Use the grid property to position / size the image using a collection of grid cells filling the canvas. Specify the number of rows and columns in the grid, then specify either a zero-based cell index (which runs in left-ot-right, top-to-bottom order), a pair of i, j cell coordinates, or a set of i, column-span, j, row-span coordinates so the legend can cover more than one cell. gutter (size of the gutter around grid cells, optional) – Specifies the amount of empty space to leave between grid cells When using the grid parameter for positioning. Assumes CSS pixels by default, and supports all of the absolute units described in Units.
legend(entries, bounds=None, rect=None, corner=None, grid=None, gutter=50, style=None, label_style=None)[source]

Add a legend to the canvas.

Parameters: entries (sequence of entries to add to the legend Each entry to be) – displayed in the legend must be either a (label, mark) tuple or a (label, marker) tuple. Labels are human-readable text, markers are specified using the syntax described in Markers, and marks can be any instance of toyplot.mark.Mark. bounds ((xmin, xmax, ymin, ymax) tuple, optional) – Use the bounds property to position / size the legend by specifying the position of each of its boundaries. The boundaries may be specified in absolute drawing units, or as a percentage of the canvas width / height using strings that end with “%”. rect ((x, y, width, height) tuple, optional) – Use the rect property to position / size the legend by specifying its upper-left-hand corner, width, and height. Each parameter may be specified in absolute drawing units, or as a percentage of the canvas width / height using strings that end with “%”. corner ((corner, inset, width, height) tuple, optional) – Use the corner property to position / size the legend by specifying its width and height, plus an inset from a corner of the canvas. Allowed corner values are “top-left”, “top”, “top-right”, “right”, “bottom-right”, “bottom”, “bottom-left”, and “left”. The width and height may be specified in absolute drawing units, or as a percentage of the canvas width / height using strings that end with “%”. The inset is specified in absolute drawing units. grid ((rows, columns, index) tuple, or (rows, columns, i, j) tuple, or (rows, columns, i, rowspan, j, columnspan) tuple, optional) – Use the grid property to position / size the legend using a collection of grid cells filling the canvas. Specify the number of rows and columns in the grid, then specify either a zero-based cell index (which runs in left-ot-right, top-to-bottom order), a pair of i, j cell coordinates, or a set of i, column-span, j, row-span coordinates so the legend can cover more than one cell. gutter (size of the gutter around grid cells, optional) – Specifies the amount of empty space to leave between grid cells When using the grid parameter to position the legend. style (dict, optional) id (string, optional) legend toyplot.mark.Legend
matrix(data, label=None, tlabel=None, llabel=None, rlabel=None, blabel=None, step=1, tshow=None, lshow=None, rshow=None, bshow=None, tlocator=None, llocator=None, rlocator=None, blocator=None, colorshow=False, bounds=None, rect=None, corner=None, grid=None, gutter=50, filename=None)[source]

Add a matrix visualization to the canvas.

Returns: axes toyplot.coordinates.Table
numberline(x1=None, y1=None, x2=None, y2=None, bounds=None, rect=None, corner=None, grid=None, gutter=50, min=None, max=None, show=True, label=None, ticklocator=None, scale='linear', spacing=None, padding=None)[source]

Add a 1D numberline to the canvas.

Parameters: min, max (float, optional) – Used to explicitly override the numberline domain (normally, the domain is implicitly defined by any marks added to the numberline). show (bool, optional) – Set to False to hide the numberline (the numberline contents will still be visible). label (string, optional) – Human-readable label placed below the numberline axis. ticklocator (toyplot.locator.TickLocator, optional) – Controls the placement and formatting of axis ticks and tick labels. See Tick Locators. scale (“linear”, “log”, “log10”, “log2”, or a (“log”, ) tuple, optional) – Specifies the mapping from data to canvas coordinates along the axis. See Logarithmic Scales. spacing (number, string, or (number, string) tuple, optional) – Distance between plotted data added to the numberline. Assumes CSS pixels if units aren’t provided. See Units for details on how Toyplot handles real-world units. padding (number, string, or (number, string) tuple, optional) – Distance between the numberline axis and plotted data. Assumes CSS pixels if units aren’t provided. See Units for details on how Toyplot handles real-world units. Defaults to the same value as spacing. axes toyplot.coordinates.Cartesian
style

Canvas style.

table(data=None, rows=None, columns=None, trows=None, brows=None, lcolumns=None, rcolumns=None, label=None, bounds=None, rect=None, corner=None, grid=None, gutter=50, filename=None)[source]

Add a set of table axes to the canvas.

Returns: axes toyplot.coordinates.Table
text(x, y, text, angle=0.0, fill=None, opacity=1.0, title=None, style=None)[source]

Parameters: x, y (float) – Coordinates of the text anchor in canvas drawing units. Note that canvas Y coordinates increase from top-to-bottom. text (string) – The text to be displayed. title (string, optional) – Human-readable title for the mark. The SVG / HTML backends render the title as a tooltip. style (dict, optional) – Collection of CSS styles to apply to the mark. See toyplot.mark.Text for a list of useful styles. text toyplot.mark.Text
time(begin, end, index=None)[source]
Return a toyplot.canvas.AnimationFrame with the given start and end time, ready to store animated canvas modifications.
width