toyplot.canvas module

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

class toyplot.canvas.Canvas(width=None, height=None, style=None, hyperlink=None, autorender=None, autoformat=None)

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"})

autorender(enable=None, autoformat=None)

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)

Add a set of Cartesian axes to the canvas.

See also

Cartesian Coordinates

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)

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

property height

Height of the canvas in CSS pixels.

property hyperlink

URI that will be hyperlinked from the entire canvas.

image(data, bounds=None, corner=None, grid=None, margin=50, rect=None)

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)

Add a legend to the canvas.

See also

Labels and Legends

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)

Add a matrix visualization to the canvas.

See also

Matrix Visualization

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)

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)

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)

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.