# 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, hyperlink=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. hyperlink (string, optional) – When specified, the entire canvas is hyperlinked to the given URI. Note that hyperlinks set on other entities (such as axes, marks, or text) will override this. autorender (boolean, optional) – Turn autorendering on / off for this canvas. Defaults to the value in toyplot.config.autorender. autoformat (string, optional) – Specify the format (“html” or “png”) to be used for autorendering this canvas. Defaults to the value in toyplot.config.autoformat.

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 for this canvas. Defaults to the value in toyplot.config.autorender. format (string, optional) – Specify the format (“html” or “png”) to be used for autorendering this canvas. Defaults to the value in toyplot.config.autoformat.
cartesian(aspect=None, bounds=None, corner=None, grid=None, hyperlink=None, label=None, margin=50, padding=10, palette=None, rect=None, show=True, xlabel=None, xmax=None, xmin=None, xscale='linear', xshow=True, xticklocator=None, ylabel=None, ymax=None, ymin=None, yscale='linear', yshow=True, yticklocator=None)[source]

Add a set of Cartesian axes to the canvas.

Parameters: aspect (string, optional) – Set to “fit-range” to automatically expand the domain so that its aspect ratio matches the aspect ratio of the range. 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. 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. hyperlink (string, optional) – When specified, the range (content area of the axes) is hyperlinked to the given URI. Note that this overrides the canvas hyperlink, if any, and is overridden by hyperlinks set on other entities such as marks or text. label (string, optional) – Human-readable axes label. margin (number, (top, side) tuple, (top, side, bottom) tuple, or (top, right, bottom, left) tuple, optional) – Specifies the amount of empty space to leave between the axes contents and the containing grid cell When using the grid parameter for positioning. Assumes CSS pixels by default, and supports all of the absolute units described in Units. 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. palette (toyplot.color.Palette, optional) – Specifies a palette to be used when automatically assigning per-series colors. 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. show (bool, optional) – Set to False to hide the axes (the axes contents will still be visible). xmin, xmax, ymin, ymax (float, optional) – Used to explicitly override the axis domain (normally, the domain is implicitly defined by the marks added to the axes). xshow, yshow (bool, optional) – Set to False to hide individual axes. 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. See Logarithmic Scales for examples. axes toyplot.coordinates.Cartesian
color_scale(colormap, x1=None, y1=None, x2=None, y2=None, bounds=None, corner=None, grid=None, label=None, margin=50, max=None, min=None, offset=None, padding=10, rect=None, scale='linear', show=True, ticklocator=None, width=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.

URI that will be hyperlinked from the entire canvas.

image(data, bounds=None, corner=None, grid=None, margin=50, rect=None)[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. margin (size of the margin 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, corner=None, grid=None, label=None, margin=50, rect=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 “%”. 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. label (str, optional) – Optional human-readable label for the legend. margin (number, (top, side) tuple, (top, side, bottom) tuple, or (top, right, bottom, left) tuple, optional) – Specifies the amount of empty space to leave between legend and the containing grid cell when using the grid parameter for positioning. 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 “%”. legend toyplot.coordinates.Table
matrix(data, blabel=None, blocator=None, bounds=None, bshow=None, colorshow=False, corner=None, filename=None, grid=None, label=None, llabel=None, llocator=None, lshow=None, margin=50, rect=None, rlabel=None, rlocator=None, rshow=None, step=1, tlabel=None, tlocator=None, tshow=None)[source]

Add a matrix visualization to the canvas.

Parameters: data (array-like matrix, or (matrix, toyplot.color.Map) tuple, required) – The given data will be used to populate the visualization, using either the given colormap or a default. blabel (str, optional) – Human readable label along the bottom of the matrix. blocator (toyplot.locator.TickLocator, optional) – Supplies column labels along the bottom of the matrix. 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 “%”. bshow (bool, optional) – Set to False to hide column labels along the bottom of the matrix. colorshow (bool, optional) – Set to True to add a color scale to the visualization. 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. filename (str, optional) – Supplies a default filename for users who choose to download the matrix contents. Note that users and web browsers are free to ignore or override this. 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. label (str, optional) – Optional human-readable label for the matrix. llabel (str, optional) – Human readable label along the left side of the matrix. llocator (toyplot.locator.TickLocator, optional) – Supplies row labels along the left side of the matrix. lshow (bool, optional) – Set to False to hide row labels along the left side of the matrix. margin (number, (top, side) tuple, (top, side, bottom) tuple, or (top, right, bottom, left) tuple, optional) – Specifies the amount of empty space to leave between the matrix and the containing grid cell when using the grid parameter for positioning. 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 “%”. rlabel (str, optional) – Human readable label along the right side of the matrix. rlocator (toyplot.locator.TickLocator, optional) – Supplies row labels along the right side of the matrix. rshow (bool, optional) – Set to False to hide row labels along the right side of the matrix. step (integer, optional) – Specifies the number of rows or columns to skip between indices. This is useful when the matrix cells become too small relative to the index text. tlabel (str, optional) – Human readable label along the top of the matrix. tlocator (toyplot.locator.TickLocator, optional) – Supplies column labels along the top of the matrix. tshow (bool, optional) – Set to False to hide column labels along the top of the matrix. axes toyplot.coordinates.Table
numberline(x1=None, y1=None, x2=None, y2=None, bounds=None, corner=None, grid=None, label=None, margin=50, max=None, min=None, padding=None, palette=None, rect=None, scale='linear', show=True, spacing=None, ticklocator=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

Collection of CSS styles that will be applied to the canvas.

table(data=None, rows=None, columns=None, annotation=False, bounds=None, brows=None, corner=None, filename=None, grid=None, label=None, lcolumns=None, margin=50, rcolumns=None, rect=None, trows=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