toyplot.canvas module

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

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

Bases: object

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

Do not create AnimationFrame instances yourself, use toyplot.canvas.Canvas.frame() and toyplot.canvas.Canvas.frames() instead.

property begin

Beginning of the current frame in seconds.

property count

Total number of frames in the current animation.

property end

End of the current frame in seconds.

property length

Duration of the current frame in seconds.

property number

Current animation frame number (zero-based).

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, required) – Mark containing the datum to modify.

  • series (int, required) – Zero-based index of the series containing the datum to modify.

  • datum (int, required) – Zero-based index of the datum to modify.

  • style (dict, required) – Python dict containing CSS style information to be assigned to the datum.

set_datum_text(mark, series, datum, text, style=None)[source]

Change the text in a toyplot.mark.Text at the current frame.

Note

Currently, animated text completely overwrites the original - thus, it cannot inherit style (including color) information, which you will have to re-specify explicitly.

Parameters
  • mark (toyplot.mark.Text, required) – Mark containing the text to modify.

  • series (int, required) – Zero-based index of the series containing the datum to modify.

  • datum (int, required) – Zero-based index of the datum to modify.

  • text (str, required) – String containing the new text to be assigned to the datum.

  • style (dict, optional) – Python dict containing CSS style information to be assigned to the datum.

  • angle (float, optional) – Angle for the new text.

set_mark_style(mark, style)[source]

Change the style of a mark.

Parameters
  • mark (toyplot.mark.Mark instance) –

  • style (dict containing CSS style information) –

set_text(mark, text, style=None)[source]

Warning

method ‘toyplot.canvas.AnimationFrame.set_text’ undocumented

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"})
animation()[source]

Return a summary of the canvas animation state.

Returns

  • begin (float) – Start-time of the animation in seconds.

  • end (float) – End-time of the animation in seconds.

  • changes (object) – Opaque collection of data structures that describe changes to the canvas state during animation (if any).

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 (float, optional) – Used to explicitly override the axis domain (normally, the domain is implicitly defined by the marks added to the axes).

  • xmax (float, optional) – Used to explicitly override the axis domain (normally, the domain is implicitly defined by the marks added to the axes).

  • ymin (float, optional) – Used to explicitly override the axis domain (normally, the domain is implicitly defined by the marks added to the axes).

  • ymax (float, optional) – Used to explicitly override the axis domain (normally, the domain is implicitly defined by the marks added to the axes).

  • xshow (bool, optional) – Set to False to hide individual axes.

  • yshow (bool, optional) – Set to False to hide individual axes.

  • xlabel (string, optional) – Human-readable axis labels.

  • ylabel (string, optional) – Human-readable axis labels.

  • xticklocator (toyplot.locator.TickLocator, optional) – Controls the placement and formatting of axis ticks and tick labels.

  • yticklocator (toyplot.locator.TickLocator, optional) – Controls the placement and formatting of axis ticks and tick labels.

  • xscale ("linear", "log", "log10", "log2", or a ("log", <base>) tuple, optional) – Specifies the mapping from data to canvas coordinates along an axis. See Logarithmic Scales for examples.

  • yscale ("linear", "log", "log10", "log2", or a ("log", <base>) tuple, optional) – Specifies the mapping from data to canvas coordinates along an axis. See Logarithmic Scales for examples.

Returns

axes

Return type

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 (float, optional) – Used to explicitly override the domain that will be shown.

  • 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", <base>) tuple, optional) – Specifies the mapping from data to canvas coordinates along an axis.

Returns

axes

Return type

toyplot.coordinates.Numberline

frame(begin, end=None, number=None, count=None)[source]

Return a single animation frame that can be used to animate the canvas contents.

Parameters
  • begin (float) – Specify the frame start time (in seconds).

  • end (float, optional) – Specify the frame end time (in seconds).

  • number (integer, optional) – Specify a number for this frame.

  • count (integer, optional) – Specify the total number of frames of which this frame is one.

Returns

frame

Return type

toyplot.canvas.AnimationFrame instance.

frames(frames)[source]

Return a sequence of animation frames that can be used to animate the canvas contents.

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.

Yields

frames (toyplot.canvas.AnimationFrame) – Use the methods and properties of each frame object to modify the state of the canvas over time.

property 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 “%”.

Returns

legend

Return type

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 (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.

Returns

axes

Return type

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 (float, optional) – Used to explicitly override the numberline domain (normally, the domain is implicitly defined by any marks added to the numberline).

  • 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", <base>) 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.

Returns

axes

Return type

toyplot.coordinates.Cartesian

property 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

Return type

toyplot.coordinates.Table

text(x, y, text, angle=0.0, fill=None, opacity=1.0, title=None, style=None)[source]

Add text to the canvas.

Parameters
  • x (float) – Coordinates of the text anchor in canvas drawing units. Note that canvas Y coordinates increase from top-to-bottom.

  • 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.

Returns

text

Return type

toyplot.mark.Text

property width

Width of the canvas in CSS pixels.