_images/toyplot.png

Welcome!

Welcome to Toyplot, the kid-sized plotting toolkit for Python with grownup-sized goals:

  • Develop beautiful interactive, animated plots that embrace the unique capabilities of electronic publishing and support reproducibility.
  • Create the best possible data graphics “out-of-the-box”, maximizing data ink and minimizing chartjunk.
  • Provide a clean, minimalist interface that scientists and engineers will love.

Read more about our ideas for Toyplot and scientific publishing here.

Documentation

_images/toyplot.png

The Toyplot Ethos

Always look your best.
Share your things.
Play well with others.
Never tell a lie.

What began as a quick workaround to produce better figures for some experiments in machine learning has quickly grown into Toyplot, “the kid-sized plotting toolkit with grownup-sized goals”. In a nutshell, we think that scientists and engineers should expect more from their plots, from explicit support for reproducibility and open science to greater clarity and better aesthetics.

We especially feel that, in an age of ubiquitous electronic media and the web, it makes little sense to publish using media (like PDF) designed to mimic the limitations of static paper. Toyplot embraces the standards of the internet - HTML, SVG, and Javascript - as its primary medium, so we can make useful new interactions part of the everyday experiences of data graphic users. Because we’re passionate about publishing and sharing results, Toyplot graphics will always be completely self-contained and embeddable, without the need for a server. All of the Toyplot graphics you will see in this documentation are live and interactive, despite the fact that they were created offline in a Jupyter notebook and passed through several publishing steps on the way to becoming our documentation. Of course, we provide backends to publish Toyplot figures to legacy formats including PDF, PNG, and MP4 (Play well with others).

With most toolkits, interactivity means throwaway features like pan-and-zoom. For Toyplot, we’re exploring simple-but-effective ideas to address the questions a colleague might ask when viewing a graphic in the real world: “What’s the value at this weird peak?” “Where do those two series cross?” “Can I get a copy of the data?” We’re working on efficient animation that doesn’t compromise the quality of your graphic with compression artifacts; and interactive data cursors that display quantities of interest and descriptive statistics just by hovering the mouse. And since the raw data is already implicitly embedded in a graphic, why not support reproducibility by making it easy to export, so the viewer can work with it themselves? That’s why Toyplot figures can export their underlying raw data in CSV format (Share your things).

Last but definitely not least: Toyplot fully embraces principles and best practices for clarity and aesthetics in data graphics that are well-established by the visualization community, yet sadly lacking in contemporary plotting libraries (Always look your best). Toyplot has beautiful color palettes and sensible default styling that minimize chartjunk and maximize data ink out of the box, not as afterthoughts or addons.

_images/toyplot.png

Features

  • Plot types: bar plots, ellipse visualizations, region visualizations, graph visualizations, image visualizations, line plots, matrix plots, numberline plots, scatter plots, tabular plots, text plots.
  • Styling: standard CSS, rich text with HTML markup.
  • Integrates with Jupyter without any need for plugins, magics, etc.
  • Interaction types: hyperlinking, interactive mouse coordinates, export figure data to CSV.
  • Interactive output formats: Embeddable, self-contained HTML.
  • Static output formats: SVG, PDF, PNG, MP4.
  • Portability: single code base for Python 2.7 / Python 3.6.
  • Testing: greater-than-95% regression test coverage.
_images/toyplot.png

Compatibility

A quick disclaimer on backwards-compatibility for Toyplot users:

Toyplot follows the Semantic Versioning standard for assigning version numbers in a way that has specific meaning. As of this writing Toyplot releases are still in the 0.y.z development phase, which means (among other things) that the API may change at any time. We try not to be abusive about it, and there have been a handful of breaking changes in Toyplot’s history, but you should be prepared for the occasional bump on the road to the 1.0 release.

_images/toyplot.png

Portability

Toyplot has supported Python 2 and Python 3 with a single code base since very early in its development, and the current release (0.18.0 as of this writing) is no exception.

However, you should be aware that Python 2 will no longer be maintained past 2020 (https://pythonclock.org), and Toyplot is a member of a significant group of projects that have pledged to end support for Python 2 soon (https://python3statement.org). In particular, Toyplot will no longer support Python 2 after December 31st, 2018.

What this means

The Toyplot 0.18 branch will be the final release with Python 2 support. Toyplot releases after December 31st, 2018 will have portability code removed, and our automated regression testing will be Python 3 only after that date. We will consider pull requests for the 0.18 branch on a case-by-case basis.

_images/toyplot.png

Installation

Using a Package Manager

A package manager (conda, apt, yum, MacPorts, etc) should generally be your first stop for installing Toyplot - it will make it easy to install Toyplot and its dependencies, keep them up-to-date, and even (gasp!) uninstall them cleanly. If your package manager doesn’t support Toyplot yet, drop them a line and let them know you’d like them to add it!

If you’re new to Python or unsure where to start, we strongly recommend taking a look at Anaconda, which the Toyplot developers use during their day-to-day work.

_images/toyplot.png

Anaconda Installation

Whether you’re new to Python or an old hand, we highly recommend installing Anaconda. Anaconda includes and conveniently installs Python and other commonly used packages for scientific computing and data science, including most of Toyplot’s dependencies.

With Anaconda installed, do the following to install Toyplot:

$ conda install pip numpy multipledispatch reportlab
$ pip install toyplot

Note that there is a Conda package for Toyplot, but as with all packaged software installations, it may or may not be up-to-date … see the package information at

https://binstar.org/melund/toyplot

and be sure to let the Anaconda maintainers know (in the nicest way possible) that you’re using Toyplot!

_images/toyplot.png

FreeBSD Installation

There is a FreeBSD port for Toyplot, but as with any packaged software it may-or-may-not be up-to-date … see the port information at

http://www.freshports.org/graphics/py-toyplot/

and be sure to let the FreeBSD maintainers know (in the nicest way possible) that you’re using Toyplot!

_images/toyplot.png

MacPorts Installation

Required

There isn’t a MacPorts package for Toyplot yet, but you can still use MacPorts to install the Dependencies before installing Toyplot using pip:

$ sudo port install py-multipledispatch
$ sudo port install py-numpy
$ sudo port install py-pip
$ sudo port install py-reportlab
$ sudo port select --set pip pip27
$ sudo pip install toyplot
PNG Export

To generate static PNG versions of your Toyplot figures, you’ll need Ghostscript:

$ sudo port install ghostscript
MP4 Export

If you plan to render animated Toyplot figures as MP4 files, you’ll need all the above for exporting PNG images, plus ffmpeg:

$ sudo port install ffmpeg

Using Pip / Easy Install

If your package manager doesn’t support Toyplot, or doesn’t have the latest version, your next option should be Python setup tools like pip. You can always install the latest stable version of toyplot and its required dependencies using:

$ pip install toyplot

… following that, you’ll be able to use all of Toyplot’s features, and export figures to all of Toyplot’s preferred file formats, including HTML, SVG, and PDF.

For export to other formats like PNG or MP4, you’ll have to install additional resources listed in the Dependencies section of the manual.

From Source

Finally, if you want to work with the latest, bleeding-edge Toyplot goodness, you can install it using the source code:

$ git clone https://github.com/sandialabs/toyplot
$ cd toyplot
$ sudo python setup.py install

The setup script installs Toyplot’s required dependencies and copies Toyplot into your Python site-packages directory, ready to go.

Once again, export to other formats like PNG or MP4, wil require additional resources listed in Dependencies.

_images/toyplot.png

Dependencies

Minimum Requirements

To use Toyplot you will need, at a minimum, Python 2 or 3 (duh):

plus the following (if you install Toyplot using pip, these are automatically installed for you):

Timestamp Labels

To display datetime information using the toyplot.locator.Timestamp locator, the following is required (if you install Toyplot using pip, it’s automatically installed for you):

Bitmap Images

To add bitmap images to your figures, you’ll need the following (if you install Toyplot using pip, it’s automatically installed for you):

PDF Export

Generating static PDF versions of your Toyplot figures requires the following (if you install Toyplot using pip, it’s automatically installed for you):

If your Toyplot figures contain bitmap images, ReportLab also requires the following:

PNG Export

To generate static PNG versions of your Toyplot figures, you’ll need the PDF Export dependencies, plus Ghostscript:

MP4 Export

If you plan to render animated Toyplot figures as MP4 videos, you’ll need the PNG Export dependencies for exporting PNG files, plus ffmpeg:

Source Installation

If you’re installing Toyplot from source, you’ll need setuptools to run the Toyplot setup.py script:

Regression Testing

The following are required to run Toyplot’s regression tests and view code coverage:

Generating Documentation

And you’ll need to following to generate this documentation:

_images/toyplot.png

The Toyplot Tutorial

Getting Started

Welcome! This tutorial will introduce you to the basics of working with Toyplot.

Note: this tutorial was created in a Jupyter notebook and assumes that you’re following-along in a notebook of your own. If you aren’t using a notebook, you should read the user guide section on Rendering for some important information on how to display your figures.

To begin, we’re going to import numpy (so we can create data to use for our figures), and the main toyplot module:

import numpy
import toyplot

For our first figure, let’s create a simple set of X and Y coordinates that we can plot:

x = numpy.linspace(0, 10)
y = x ** 2

Now, let’s put Toyplot to work …

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
mark = axes.plot(x, y)
0510050100

Short as it is, this example demonstrates several key features of Toyplot:

  • Toyplot figures are beautiful, scalable, embeddable, and interactive. For example:
    • Click or tap anywhere in the figure, and note the coordinates that update along each axis.
    • Carefully place the cursor on top of the plotted line, and open a context menu - in the popup that appears, you can choose to save the figure data to a CSV file from your browser.
    • Note that Toyplot produces a clean, aesthetically pleasing figure that is crisp at any scale and free of chartjunk “out-of-the-box”.
  • Every Toyplot figure begins with a canvas - a drawing area upon which the caller adds marks. Note that the width and height of the canvas have been specified in CSS pixels, which are always equal to 1/96th of an inch, and converted to device units when the canvas is rendered.
  • A Toyplot figure typically contains one-or-more coordinate systems which map a data domain to a range of canvas pixels.
  • Marks are added to coordinate systems using the factory functions they provide. In this example, the plot function adds a plot mark using the supplied coordinates. Note that the cartesian axes been automatically sized to the data’s domain.

Styles

Let’s say that you wanted to alter the above figure to make the plotted line blue and dashed. To do so, simply override the default style information when creating the plot:

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
mark = axes.plot(x, y, style={"stroke":"blue", "stroke-dasharray":"2, 2"})
0510050100

In this case, you can see that the style information is a dictionary of key-value properties that alter how a mark is rendered. To avoid reinventing the wheel, Toyplot uses Cascading Style Sheets (CSS) to specify styles. If you’re familiar with web development, you already know CSS. If not, this tutorial will cover many of most useful CSS properties for Toyplot as we go, and there are many learning resources for CSS online.

Every mark you add to a figure will have at least one (and possibly more than one) set of styles that control its appearance.

Plotting

Let’s continue with the previous example. As a shortcut, you can omit the X coordinates when using the plot command, and a set of coordinates in the range \([0, M)\) will be provided (compare the following X axis with the previous two plots to see the difference):

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
mark = axes.plot(y)
01020304050050100

If you add multiple plots to a set of axes, each automatically receives a different color:

x = numpy.linspace(0, 10, 100)
y1 = numpy.sin(x)
y2 = numpy.cos(x)
y3 = numpy.sin(x) + numpy.cos(x)

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian()
mark1 = axes.plot(x, y1)
mark2 = axes.plot(x, y2)
mark3 = axes.plot(x, y3)
0510-101

As we’ve already seen, we can use the “stroke” style to override the default color of each plot; in addition, the “stroke-width” and “stroke-opacity” styles are useful properties for (de)emphasizing individual plots:

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian()
mark1 = axes.plot(x, y1, style={"stroke-width":1, "stroke-opacity":0.6})
mark2 = axes.plot(x, y2, style={"stroke-width":1, "stroke-opacity":0.6})
mark3 = axes.plot(x, y3, style={"stroke":"blue"})
0510-101

Palettes

Before proceeding, let’s take a moment to look at how the default color for a mark is assigned. When we add multiple marks to a set of axes, each mark gets a different color. These default colors are all drawn from a palette - an ordered collection of RGBA colors. For example, here’s Toyplot’s default palette:

import toyplot.color
toyplot.color.Palette()

Note: Like canvases, palettes are automatically rendered in Jupyter notebooks, in this case as a collection of color swatches.

You should observe that the order of colors in the palette match the order of the colors that were assigned to our plots as they were added to their axes. You could create a custom palette by passing a sequence of colors to the toyplot.color.Palette constructor, but Toyplot already comes with a builtin collection of high-quality palettes from Color Brewer, which we will use in the examples that follow.

For more detail on colors in Toyplot, see the Colors section of the user guide.

Filled Regions

You can use fill to display a region bounded by two sets of Y coordinates. This can be a handy way to visualize data distributions:

numpy.random.seed(1234)
observations = numpy.random.normal(size=(50, 50))

x = numpy.linspace(0, 1, len(observations))
y1 = numpy.min(observations, axis=1)
y2 = numpy.max(observations, axis=1)

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(x, y1, y2)
0.00.51.0-4-2024

Use the “fill” style (not to be confused with the fill command) to control the color of the shaded region. You might also want to change the fill-opacity or add a stroke using styles:

style={"fill":"steelblue", "fill-opacity":0.5, "stroke":toyplot.color.black}
canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(x, y1, y2, style=style)
0.00.51.0-4-2024

If you omit one of the boundaries it will default to \(y = 0\):

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(x, y2)
0.00.51.00123

As with plots, if you omit the X coordinates, they will default to the range \([0, M)\):

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(y2)
010203040500123

Toyplot also makes it easy to define multiple sets of boundaries, by passing an \(M \times N\) matrix as input, where \(M\) is the number of observations, and \(N\) is the number of boundaries:

boundaries = numpy.column_stack(
    (numpy.min(observations, axis=1),
     numpy.percentile(observations, 25, axis=1),
     numpy.percentile(observations, 50, axis=1),
     numpy.percentile(observations, 75, axis=1),
     numpy.max(observations, axis=1)))

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(boundaries)
01020304050-4-2024

This introduces an important new concept: you can think of fill (and other types of) marks as containers for collections of series, where in this case, \(N\) boundaries define \(N-1\) series.

This distinction is important because we can control the styles of individual series, not just the mark as a whole. So, if we want to override the default colors for the fill regions, we can do it using the mark’s global “fill” style (with a contrasting stroke to display the boundaries between series):

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(boundaries, style={"fill":"steelblue", "stroke":"white"})
01020304050-4-2024

… or we can do it using the “color” argument:

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(boundaries, color="steelblue", style={"stroke":"white"})
01020304050-4-2024

The advantage of the latter is that the “color” argument can specify a single color value as we’ve seen, or a sequence of color values, one-per-series. And, you can combine those per-series color values with global styles in intuitive ways:

color = ["red", "green", "blue", "yellow"]

canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(boundaries, color=color, style={"stroke":toyplot.color.black})
01020304050-4-2024

The “opacity” and “title” arguments can also be specified on a per-series basis (hover the mouse over the fill regions in the following figure to see the title as a popup):

color = ["blue", "blue", "red", "red"]
opacity = [0.1, 0.2, 0.2, 0.1]
title = ["1st Quartile", "2nd Quartile", "3rd Quartile", "4th Quartile"]

style={"stroke":toyplot.color.black}
canvas = toyplot.Canvas(width=400, height=300)
axes = canvas.cartesian()
mark = axes.fill(boundaries, color=color, opacity=opacity, title=title, style=style)
1st Quartile2nd Quartile3rd Quartile4th Quartile01020304050-4-2024

In the preceding examples you defined the fill regions by explicitly specifying their boundaries … as an alternative, you can generate fills by specifying the magnitudes (the heights) of each region (note that in this case \(N\) heights define \(N\) series):

numpy.random.seed(1234)

samples = numpy.linspace(0, 4 * numpy.pi, 100)
frequency = lambda: numpy.random.normal()
phase = lambda: numpy.random.normal()
amplitude = lambda: numpy.random.uniform(0.1, 1)
wave = lambda: numpy.sin(phase() + (frequency() * samples))
signal = lambda: amplitude() * (2 + wave())
heights = numpy.column_stack([signal() for i in range(10)])

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
m = axes.fill(heights, baseline="stacked")
05010004812

If you pass a sequence of scalar values instead of colors to the “color” argument, the values will be mapped to colors using a linear mapping and a default diverging colormap:

color = numpy.arange(heights.shape[1])

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
m = axes.fill(heights, baseline="stacked", color=color)
05010004812

Of course, you’re free to supply your own colormap instead:

colormap = toyplot.color.brewer.map("BlueGreenBrown")

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
m = axes.fill(heights, baseline="stacked", color=(color, colormap))
05010004812

… note that the baseline parameter is what signals that the inputs are magnitudes instead of boundaries. You can also change the baseline parameter to create various types of streamgraph:

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
m = axes.fill(heights, baseline="symmetric", color=(color, colormap))
050100-505
canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
m = axes.fill(heights, baseline="wiggle", color=(color, colormap))
050100-4048

Barplots

Of course, you can’t have a plotting library without barplots …

heights = numpy.linspace(1, 10, 10) ** 2

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
mark = axes.bars(heights)
0510050100

By default the bars are centered on integer X coordinates in the range \([0, M)\) - but we can specify our own X coordinates to suit:

x = numpy.linspace(-2, 2, 20)
y = 5 - (x ** 2)

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
mark = axes.bars(x, y)
-2-1012012345

As a convenience, you can pass the output from numpy.histogram() directly to toyplot.coordinates.Cartesian.bars():

numpy.random.seed(1234)
population = numpy.random.normal(size=10000)

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
bars = axes.bars(numpy.histogram(population, 20))
-4-2024050010001500

As with fill marks, Toyplot allows you to stack multiple sets of bars by passing an \(M \times N\) matrix as input, where \(M\) is the number of observations, and \(N\) is the number of series:

heights1 = numpy.linspace(1, 10, 10) ** 1.1
heights2 = numpy.linspace(1, 10, 10) ** 1.3
heights3 = numpy.linspace(1, 10, 10) ** 1.4
heights4 = numpy.linspace(1, 10, 10) ** 1.5
heights = numpy.column_stack((heights1, heights2, heights3, heights4))

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
mark = axes.bars(heights)
05100306090

As before, we can style the bars globally and use the “color”, “opacity”, and “title” arguments to specify constant or per-series behavior:

color = ["red", "green", "blue", "yellow"]
title = ["Series 1", "Series 2", "Series 3", "Series 4"]
style = {"stroke":toyplot.color.black}

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
bars = axes.bars(heights, color=color, title=title, style=style)
Series 1Series 1Series 1Series 1Series 1Series 1Series 1Series 1Series 1Series 1Series 2Series 2Series 2Series 2Series 2Series 2Series 2Series 2Series 2Series 2Series 3Series 3Series 3Series 3Series 3Series 3Series 3Series 3Series 3Series 3Series 4Series 4Series 4Series 4Series 4Series 4Series 4Series 4Series 4Series 405100306090

However, with bars we can take these concepts even further to specify per-datum quantities. That is, the color, opacity, and title arguments can accept data that will apply to every individual bar in the plot. For the following example, we generate a per-datum set of random values to map to the color, and also use them as the bar titles (hover over the bars to see the titles):

color = numpy.random.random(heights.shape)
colormap = toyplot.color.diverging.map("BlueRed")

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian()
bars = axes.bars(heights, color=(color, colormap), title=color, style=style)
0.67118036648983960.13353263377375880.55412057397844470.2517039739568080.9205897480108480.77592886655769640.134720437282634830.482583685071390160.081889934512397340.39266590330550820.8883088878666120.99016632507060750.91241807754267120.198153492970711050.95201763426371810.82833044540538880.37730210263434040.172044457353380250.002482950217814750.46287873941816460.54245296548769330.93596020752660720.60521806523591790.163638000510371140.5212729044717140.0211591344525621230.71548917955084880.50532696678809940.9288410165949360.068287323219613170.94501106294256520.352675253593171760.40210944677195470.86786506873755210.5422079096985740.78017114356485420.96096493887867630.187286086371211470.66407839036065690.3565513450276580605100306090

Scatterplots

Next on our whirlwind tour of marks is the scatterplot:

x = numpy.linspace(0, 2 * numpy.pi)
y1 = numpy.sin(x)
y2 = numpy.cos(x)

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
mark = axes.scatterplot(x, y1)
0246-1.0-0.50.00.51.0

As you might expect, you can omit the X coordinates for a scatterplot, and they will fall in to the range \([0, M)\):

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
mark = axes.scatterplot(y1)
01020304050-1.0-0.50.00.51.0

And as we’ve seen before, you can pass multiple series in a single call:

series = numpy.column_stack((y1, y2))

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
mark = axes.scatterplot(series)
01020304050-1.0-0.50.00.51.0

And as expected, you can control attributes like color, size, and opacity on a global, per-series, or per-datum basis:

color = numpy.random.random(series.shape)
palette = toyplot.color.brewer.map("Oranges")
size = [16, 9]

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
mark = axes.scatterplot(series, color=(color, palette), size=size)
01020304050-1.0-0.50.00.51.0

Markers

You can choose from a variety of marker shapes for scatterplots and line plots, also specified either globally, per-series, or per-datum, and specify styles for the markers:

mstyle={"stroke":toyplot.color.black}
canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
mark = axes.scatterplot(series, size=10, marker=["^", "o"], mstyle=mstyle)
01020304050-1.0-0.50.00.51.0

In addition to the basic marker shapes, you can create your own by adding text labels, also with their own styles:

marker = [
    toyplot.marker.create(shape="o", label="1"),
    toyplot.marker.create(shape="o", label="2"),
    ]
mlstyle = {"fill":"white"}

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian()
mark = axes.scatterplot(series, size=15, marker=marker, mstyle=mstyle, mlstyle=mlstyle)
111111111111111111111111111111111111111111111111112222222222222222222222222222222222222222222222222201020304050-1.0-0.50.00.51.0

See the user guide section on Markers for additional detail on the available marker shapes, styles, and how to create your own custom markers.

Plots Revisited

Now that we’ve seen how bar, fill, and scatter plots can accept multiple series’ worth of data in a single call, let’s revisit our earlier line plots, and see that the same is true:

x = numpy.linspace(0, 10, 100)
y1 = numpy.sin(x)
y2 = numpy.cos(x)
y3 = numpy.sin(x) + numpy.cos(x)
series = numpy.column_stack((y1, y2, y3))

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian()
mark = axes.plot(x, series)
0510-101

Axes

So far, we’ve created a default set of axes in each of the preceeding examples, and called methods on the axes to add marks to the canvas. The reason we explicitly create axes in Toyplot (instead of simply adding marks to the canvas directly) is that it allows us to have multiple axes on a single canvas:

canvas = toyplot.Canvas(600, 300)
axes = canvas.cartesian(grid=(1, 2, 0))
mark = axes.plot(x, y1)
axes = canvas.cartesian(grid=(1, 2, 1))
mark = axes.plot(x, y2)
0510-1.0-0.50.00.51.00510-1.0-0.50.00.51.0

In addition to positioning axes on the canvas, there are many properties that control their behavior. For example, Toyplot axes include builtin support for labels:

canvas = toyplot.Canvas(300, 300)
axes = canvas.cartesian(label="Toyplot User Growth", xlabel="Days", ylabel="Users")
mark = axes.plot(x, 40 + x ** 2)
0510Days50100150UsersToyplot User Growth

Similarly, we can specify minimum and maximum values for each axis - for example, if we wanted the previous figure to include \(y = 0\):

canvas = toyplot.Canvas(300, 300)
axes = canvas.cartesian(label="Toyplot User Growth", xlabel="Days", ylabel="Users", ymin=0)
mark = axes.plot(x, 40 + x ** 2)
0510Days050100150UsersToyplot User Growth

We can also specify logarithmic scales for axes:

x = numpy.linspace(-1000, 1000)

toyplot.plot(x, x, marker="o", xscale="linear", yscale="log", width=500);
-1000-50005001000-10 3-10 2-10 1-10 0010 010 110 210 3

There are many more properties that control axes positioning and behavior - for more details, see Canvas Layout and Cartesian Coordinates in the user guide.

Animation

Toyplot can also create animated figures, by recording changes to a figure over time. Assume you’ve setup the following scatterplot:

x = numpy.random.normal(size=100)
y = numpy.random.normal(size=len(x))

canvas = toyplot.Canvas(300, 300)
axes = canvas.cartesian()
mark = axes.scatterplot(x, y, size=10)
-202-2-1012

Suppose we want to show the order in which the samples were drawn from some distribution. We could use the fill parameter to map each sample’s index to a color, but an animation can be more intuitive. We can use toyplot.canvas.Canvas.frames() to add a sequence of animation frames to the canvas. We pass the desired number of frames as an argument, iterate over the results which are instances of frame. We can use the frame objects to retrieve information about each frame and specify changes to be made to the canvas at that frame. In the example below, we set the opacity of each scatterplot datum to 10% in the first frame, then change them back to 100% over the course of the animation:

canvas = toyplot.Canvas(300, 300)
axes = canvas.cartesian()
mark = axes.scatterplot(x, y, size=10)

for frame in canvas.frames(len(x) + 1):
    if frame.number == 0:
        for i in range(len(x)):
            frame.set_datum_style(mark, 0, i, style={"opacity":0.1})
    else:
        frame.set_datum_style(mark, 0, frame.number - 1, style={"opacity":1.0})
-202-2-1012
_images/toyplot.png

User Guide

Contents:

_images/toyplot.png

Canvas Layout

In Toyplot, coordinate systems (including Cartesian Coordinates, Numberline Coordinates, Table Coordinates, and others) are used to map data values into canvas coordinates. The coordinate system ranges (the area on the canvas that they occupy) is specified when they are created. By default, cartesian and table coordinates are sized to fill the entire canvas:

import numpy
y = numpy.linspace(0, 1, 20) ** 2

import toyplot
toyplot.plot(y, width=300);
051015200.00.51.0

If you need greater control over their positioning within the canvas, or want to add multiple coordinate systems to one canvas, it’s necessary to create the canvas and coordinate systems explicitly, then use the coordinate systems to plot your data. For example, you can use the bounds argument to specify explicit (xmin, xmax, ymin, ymax) bounds for cartesian axes using canvas coordinates (note that canvas coordinates always increase from top to bottom, unlike cartesian coordinates):

canvas = toyplot.Canvas(width=600, height=300)
axes1 = canvas.cartesian(bounds=(30, 270, 30, 270))
axes1.plot(y)
axes2 = canvas.cartesian(bounds=(330, 570, 30, 270))
axes2.plot(1 - y);
051015200.00.51.0051015200.00.51.0

You can also use negative values to specify values relative to the right and bottom sides of the canvas, instead of the (default) left and top sides, greatly simplifying the layout:

canvas = toyplot.Canvas(width=600, height=300)
axes1 = canvas.cartesian(bounds=(30, 270, 30, -30))
axes1.plot(y)
axes2 = canvas.cartesian(bounds=(-270, -30, 30, -30))
axes2.plot(1 - y);
051015200.00.51.0051015200.00.51.0

Furthermore, the bounds parameters can use any Units, including “%” units, so you can use real-world units and relative dimensioning in any combination that makes sense:

canvas = toyplot.Canvas(width="20cm", height="2in")
axes1 = canvas.cartesian(bounds=("1cm", "5cm", "10%", "80%"))
axes1.plot(y)
axes2 = canvas.cartesian(bounds=("6cm", "-1cm", "10%", "80%"))
axes2.plot(1 - y);
051015200.00.51.0051015200.00.51.0

Of course, most of the time this level of control isn’t necessary. Instead, the grid argument allows us to easily position each set of axes on a regular grid that covers the canvas. Note that you can control the axes position on the grid in a variety of ways:

  • (rows, columns, n)
    • fill cell \(n\) (in left-to-right, top-to-bottom order) of an \(M \times N\) grid.
  • (rows, columns, i, j)
    • fill cell \(i,j\) of an \(M \times N\) grid.
  • (rows, columns, i, rowspan, j, colspan)
    • fill cells \([i, i + rowspan), [j, j + colspan)\) of an \(M \times N\) grid.
canvas = toyplot.Canvas(width=600, height=300)
axes1 = canvas.cartesian(grid=(1, 2, 0))
axes1.plot(y)
axes2 = canvas.cartesian(grid=(1, 2, 1))
axes2.plot(1 - y);
051015200.00.51.0051015200.00.51.0

You can also use the margin argument to control the space between cells in the grid:

canvas = toyplot.Canvas(width=600, height=300)
axes1 = canvas.cartesian(grid=(1, 2, 0), margin=25)
axes1.plot(y)
axes2 = canvas.cartesian(grid=(1, 2, 1), margin=25)
axes2.plot(1 - y);
051015200.00.51.0051015200.00.51.0

Sometimes, particularly when embedding axes to produce a figure-within-a-figure, the corner argument can be used to position axes relative to one of eight “corner” positions within the canvas. The corner argument takes a (position, inset, width, height) tuple:

x = numpy.random.normal(size=100)
y = numpy.random.normal(size=100)

canvas = toyplot.Canvas(width="5in")
canvas.cartesian().plot(numpy.linspace(0, 1) ** 0.5)
canvas.cartesian(corner=("bottom-right", "1in", "1.5in", "1.5in")).scatterplot(x, y);
010203040500.00.51.0-4-202-202

Here are all the positions supported by the corner argument:

canvas = toyplot.Canvas(width="12cm")
for position in [
    "top-left",
    "top",
    "top-right",
    "right",
    "bottom-right",
    "bottom",
    "bottom-left",
    "left",
    ]:
    canvas.cartesian(corner=(position, "1cm", "2cm", "2cm"), label=position)
-0.50.00.5-0.50.00.5top-left-0.50.00.5-0.50.00.5top-0.50.00.5-0.50.00.5top-right-0.50.00.5-0.50.00.5right-0.50.00.5-0.50.00.5bottom-right-0.50.00.5-0.50.00.5bottom-0.50.00.5-0.50.00.5bottom-left-0.50.00.5-0.50.00.5left
_images/toyplot.png

Cartesian Coordinates

In Toyplot, cartesian coordinates provide a traditional mapping of two-dimensional data values on the plane to canvas coordinates. The axes range (the area on the canvas that they occupy) is specified when they are created (see Canvas Layout). Their domain is implicitly defined to include all of the data in the plot (but can be manually overridden by the caller if desired).

If your data is one-dimensional, you should consider using Numberline Coordinates instead.

Cartesian coordinates are either created for you implicitly when using the Convenience API:

import numpy
y = numpy.linspace(0, 1, 20) ** 2

import toyplot
canvas, axes, mark = toyplot.plot(y, width=300)
051015200.00.51.0

… or explicitly using toyplot.canvas.Canvas.cartesian():

canvas = toyplot.Canvas(width=300)
axes = canvas.cartesian()
axes.plot(y);
051015200.00.51.0

Properties

Axes objects contain sets of nested properties that can be used to adjust behavior. The list of available properties includes the following:

  • axes.show - set to False to hide the axes completely (the plotted data will still be visible).
  • axes.aspect - set to “fit-range” to alter the domain so that its aspect ratio matches the aspect ratio of the range.
  • axes.padding - a small gap between the axes and their contents. Defaults to CSS pixels, supports all Units.
  • axes.label.text - optional label at the top of the axes.
  • axes.label.style - styles the axes label text.
  • axes.coordinates.show - set to False to disable interactive mouse coordinates.
  • axes.coordinates.style - styles the interactive mouse coordinates background.
  • axes.coordinates.label.style - styles the interactive mouse coordinates text.
  • axes.x.show - set to False to hide the X axis completely.
  • axes.x.scale - “linear”, “log” (base 10), “log10”, “log2”, or a (“log”, base) tuple. See Logarithmic Scales for details.
  • axes.x.domain.min - override the minimum domain value for the axis.
  • axes.x.domain.max - override the maximum domain value for the axis.
  • axes.x.label.location - “above” or “below”, to specify on which side of the axis the label is placed.
  • axes.x.label.offset - offsets the label from the axis. Defaults to CSS pixels, supports all Units.
  • axes.x.label.text - optional label below the X axis.
  • axes.x.label.style - styles the X axis label.
  • axes.x.spine.show - set to False to hide the X axis spine.
  • axes.x.spine.position - set to “low”, “high”, or a Y axis domain value to position the spine. Defaults to “low”.
  • axes.x.spine.style - styles the X axis spine.
  • axes.x.ticks.show - set to True to display X axis tick marks.
  • axes.x.ticks.locator - assign an instance of toyplot.locator.TickLocator to control the positioning and formatting of ticks and tick labels. By default, an appropriate locator is automatically chosen based on the axis scale and domain. See Tick Locators for details.
  • axes.x.ticks.location - “above” or “below”, to specify on which side of the axis the ticks and labels are placed.
  • axes.x.ticks.near - length of X axis ticks on the same side of the axis as the tick labels. Defaults to CSS pixels, supports all Units.
  • axes.x.ticks.far - length of X axis ticks on the opposite side of the axis as the tick labels. Defaults to CSS pixels, supports all Units.
  • axes.x.ticks.style - styles the X axis ticks.
  • axes.x.ticks.labels.angle - set the angle of X axis tick labels in degrees.
  • axes.x.ticks.labels.offset - offsets labels from the axis. Defaults to CSS pixels, supports all Units.
  • axes.x.ticks.labels.show - set to False to hide X axis tick labels.
  • axes.x.ticks.labels.style - style X axis tick label text.
  • … and equivalent properties for the Y axis.

In the following example we override several of the defaults:

x = numpy.linspace(0, 2 * numpy.pi)
y = numpy.sin(x)

import toyplot.locator

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian()
axes.label.text = "Trigonometry 101"
axes.x.label.text = "x"
axes.y.label.text = "sin(x)"
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Explicit(
    [0, numpy.pi / 2, numpy.pi, 3 * numpy.pi / 2, 2 * numpy.pi],
    ["0", u"\u03c0 / 2", u"\u03c0", u"3 \u03c0 / 2", u"2 \u03c0"])
mark = axes.plot(x, y)
0π / 2π3 π / 22 πx-1.0-0.50.00.51.0sin(x)Trigonometry 101

As a convenience, some of the most common properties can also be set when the axes are created:

x = numpy.linspace(0, 10, 100)
y = 40 + x ** 2

canvas = toyplot.Canvas(300, 300)
axes = canvas.cartesian(label="Toyplot Users", xlabel="Days", ylabel="Users")
mark = axes.plot(x, y)
0510Days50100150UsersToyplot Users

And the same properties can be used with the Convenience API, as in the following example where we specify a minimum value for an axis - for example, if we wanted the previous figure to include \(y = 0\):

toyplot.plot(
    x,
    y,
    label="Toyplot Users",
    xlabel="Days",
    ylabel="Users",
    ymin=0,
    width=300);
0510Days050100150UsersToyplot Users

Shared Axes

It may occasionally be useful to display multiple domains in a single plot, although this is a technique that should be used with care to avoid confusion when your plot is viewed by others. For example, consider the following data:

import toyplot.data
data = toyplot.data.deliveries()
data[5:10]
DateDeliveredOn Time
15jul20053061.0000
15aug20053230.9905
15sep20055310.9959
15oct20056770.9600
15nov20056950.9624

The Delivered and On Time series have completely different domains, and it would make little sense to plot counts and percentages on a single set of axes. But with shared axes you can display the data using a separate Y axis for each series:

data["Delayed"] = 1.0 - data["On Time"].astype("float64")

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(xlabel="Date", ylabel="Deliveries", ymin=0)
axes.plot(data["Delivered"], color="darkred", marker="o")
axes.y.spine.style = {"stroke":"darkred"}

axes = axes.share("x", ylabel="% Delayed", ymax=0.1)
axes.plot(data["Delayed"].astype("float64"), color="steelblue", marker="o")
axes.y.spine.style = {"stroke":"steelblue"}
048120300600900Deliveries0.000.050.10% Delayed

For this example, we created a set of coordinates for the first series, then used the toyplot.coordinates.Cartesian.share() function to create a second set of overlapping coordinates for the second series. Axis sharing in this case means that Toyplot has created two pairs of overlapping Cartesian coordinates, but with a shared X axis. This ensures that any changes that affect the X axis are reflected in both plots.

Note that we have used color to help reinforce the relationship between the plots and their axes to avoid confusion.

_images/toyplot.png

Colors

Color choices are critical in visualization because good color choices can reveal or emphasize patterns in your data while poor choices will obscure them. This section of the user guide will introduce Toyplot’s basic functionality for creating and manipulating colors. See Color Mapping for details on how to represent your data using color.

Color Values

Colors in Toyplot are represented as red-green-blue-alpha (RGBA) tuples, where each component can range from zero (off) to one (full strength). Alpha is used to represent the opacity of a color, from zero (completely transparent) to one (completely opaque). There are a variety of functions in Toyplot for creating color tuples using CSS strings, RGBA data, and even other color spaces:

import toyplot.color
toyplot.color.rgb(1, 0, 0)

# Note: transparent red is *not* the same as opaque pink!
toyplot.color.rgba(1, 0, 0, 0.5)

toyplot.color.css("mediumseagreen")

toyplot.color.css("#248")

# CIE Lab color space:
toyplot.color.lab(75, 0, -100)

# Toyplot uses this as a default instead of pure black:
toyplot.color.black

'#292724'

Color Palettes

In practice you should rarely need to manipulate individual color values as much of the color management in Toyplot centers around palette objects, which store ordered collections of colors. For example, consider Toyplot’s default palette:

toyplot.color.Palette()

You will likely recognize the colors in the default palette, since they are used to specify per-series colors when adding multiple data series to a figure. Although you can create your own custom palettes by passing a sequence of color values to the toyplot.color.Palette constructor, we strongly recommend that you use the high-quality palettes from Color Brewer which are included with Toyplot and ideal for visualization. As we will see shortly, the Toyplot default palette is itself an example of a Color Brewer palette.

Each of the Color Brewer palettes is assigned to one of three categories, “sequential”, “diverging”, or “qualitative”, which we will discuss in-turn:

Color Brewer Sequential Palettes

Sequential color palettes are designed to visualize magnitudes for some quantity of interest. Colors at one end of the palette are mapped to low values and colors at the opposite end map to high values. Toyplot includes the complete set of Color Brewer sequential palettes, ordered so that colormaps based on these palettes always map low values to low luminance and high values to high luminance:

import IPython.display
for name, palette in toyplot.color.brewer.palettes("sequential"):
    IPython.display.display_html(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(palette)
BlueGreen
BlueGreenYellow
BluePurple
Blues
BrownOrangeYellow
GreenBlue
GreenBluePurple
GreenYellow
Greens
Greys
Oranges
PurpleBlue
PurpleRed
Purples
RedOrange
RedOrangeYellow
RedPurple
Reds
Color Brewer Diverging Palettes

Diverging palettes are especially useful when visualizing signed magnitudes, or magnitudes relative to some well-defined reference point, such as a mean, median, or domain-specific critical value. Once again, Toyplot includes the complete set of Color Brewer diverging palettes, ordered consistent so that low/negative values map to cooler colors and high/positive values map to warmer colors:

for name, palette in toyplot.color.brewer.palettes("diverging"):
    IPython.display.display_html(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(palette)
BlueGreenBrown
BlueRed
BlueYellowRed
GrayRed
GreenYellowRed
PinkGreen
PurpleGreen
PurpleOrange
Spectral
Color Brewer Qualitative (Categorical) Palettes

Qualitative or categorical palettes are designed for visualizing unordered information. Adjacent colors typically have high contrast in hue or luminance, to emphasize boundaries between values. Toyplot includes the full set of qualitative palettes from Color Brewer, without modification:

for name, palette in toyplot.color.brewer.palettes("qualitative"):
    IPython.display.display_html(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(palette)
Accent
Dark2
Paired
Pastel1
Pastel2
Set1
Set2
Set3
Usage

Color brewer palettes are created by name. For example, the following is the equivalent of Toyplot’s default palette:

toyplot.color.brewer.palette("Set2")

And here is a palette that is commonly used for diverging data:

toyplot.color.brewer.palette("BlueRed")

You can lookup the set of all available palette names:

toyplot.color.brewer.names()

['Accent',
 'BlueGreen',
 'BlueGreenBrown',
 'BlueGreenYellow',
 'BluePurple',
 'BlueRed',
 'BlueYellowRed',
 'Blues',
 'BrownOrangeYellow',
 'Dark2',
 'GrayRed',
 'GreenBlue',
 'GreenBluePurple',
 'GreenYellow',
 'GreenYellowRed',
 'Greens',
 'Greys',
 'Oranges',
 'Paired',
 'Pastel1',
 'Pastel2',
 'PinkGreen',
 'PurpleBlue',
 'PurpleGreen',
 'PurpleOrange',
 'PurpleRed',
 'Purples',
 'RedOrange',
 'RedOrangeYellow',
 'RedPurple',
 'Reds',
 'Set1',
 'Set2',
 'Set3',
 'Spectral']

Or you can lookup names for a specific category:

toyplot.color.brewer.names("diverging")

['BlueGreenBrown',
 'BlueRed',
 'BlueYellowRed',
 'GrayRed',
 'GreenYellowRed',
 'PinkGreen',
 'PurpleGreen',
 'PurpleOrange',
 'Spectral']

Alternatively, given a palette name, you can lookup its category:

toyplot.color.brewer.category("BlueRed")

'diverging'

When creating a palette, you can reverse the order of its color values (though this should almost never be necessary, thanks to the careful ordering of the palettes):

toyplot.color.brewer.palette("BlueRed", reverse=True)

Each of the Color Brewer palettes comes in multiple variants with different numbers of colors. By default, when you create a Color Brewer palette, the one with the maximum number of colors is returned. However, you can query for all of the available variants, and request one with fewer colors if necessary:

toyplot.color.brewer.counts("BlueRed")

[3, 4, 5, 6, 7, 8, 9, 10, 11]

toyplot.color.brewer.palette("BlueRed", count=5)
Palette Manipulation

Sometimes you’ll find yourself needing categorical palettes with more categories than the existing Color Brewer palettes provide. For these cases, you’ll have to create larger palettes on your own, but Toyplot can still help. First, the toyplot.color.spread() function can create a family of colors based on a single color value:

toyplot.color.spread("mediumseagreen", lightness=0.9)

toyplot.color.spread(toyplot.color.rgb(1, 0.8, .05), lightness=0.2, count=6)

Of course, this isn’t a complete solution, because you can only create so many colors of a single hue before they become indistinguishable. However, Toyplot makes it easy to concatenate palettes:

toyplot.color.spread("steelblue", count=6) + toyplot.color.spread("crimson", count=5)

Using this approach, you can, within reason, build-up arbitrarily large palettes. Often, the two-level hierarchy created by the combination of palette hues and lightness is useful for visually grouping families of related categories.

Color Maps

While palettes group together related collections of color values, Toyplot uses color maps to perform the real work of mapping data values to colors. Some color maps are based on the colors contained in a palette, while others calculate color values based on the subtleties of the human visual cortex; regardless, all color maps perform the basic function of mapping a collection of scalar values to a collection of colors.

Categorical Color Maps

The simplest type of color map in Toyplot is a toyplot.color.CategoricalMap, which uses scalar values as an index to lookup color values from a palette. As you might have guessed, if you create a default categorical map, it uses Toyplot’s default palette:

toyplot.color.CategoricalMap()

However, you can create a categorical map explicitly using any palette:

toyplot.color.CategoricalMap(toyplot.color.brewer.palette("Set1"))

As a convenience, toyplot.color.BrewerFactory.map() can be used to create a map from any categorical Color Brewer palette:

toyplot.color.brewer.map("Set1")

Although a palette contains a finite number of colors, a categorical map “wraps” out-of-range scalar values so that any scalar value can be mapped to a color, albeit causing the colors to repeat:

colormap = toyplot.color.brewer.map("Set1", count=3)
colormap

colormap.colors([-1, 0, 1, 2, 3, 4, 5])

Categorical maps are primarily designed to be used with integers; however, floating point values are automatically truncated to integers during mapping:

colormap.colors([0, 0.25, 0.75, 1, 1.25])
Linear Color Maps

The most used type of color map in Toyplot is a toyplot.color.LinearMap, which uses linear interpolation to map a continuous range of data values to a continuous range of colors, specified using a palette. Unsurprisingly, Toyplot provides a default linear colormap, which is based on a diverging palette:

toyplot.color.LinearMap()

And as before, you can create linear maps either explicitly using palettes, or using the toyplot.color.BrewerFactory.map() convenience function:

toyplot.color.LinearMap(toyplot.color.brewer.palette("BlueRed"))

toyplot.color.brewer.map("BlueRed")

Here are complete lists of the linear maps that can be created from the sequential and diverging Color Brewer palettes:

for name, colormap in toyplot.color.brewer.maps("sequential"):
    IPython.display.display(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(colormap)
BlueGreen
BlueGreenYellow
BluePurple
Blues
BrownOrangeYellow
GreenBlue
GreenBluePurple
GreenYellow
Greens
Greys
Oranges
PurpleBlue
PurpleRed
Purples
RedOrange
RedOrangeYellow
RedPurple
Reds
for name, colormap in toyplot.color.brewer.maps("diverging"):
    IPython.display.display(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(colormap)
BlueGreenBrown
BlueRed
BlueYellowRed
GrayRed
GreenYellowRed
PinkGreen
PurpleGreen
PurpleOrange
Spectral
Miscellaneous Linear Maps

In addition to linear maps based on the Color Brewer palettes, Toyplot provides a handful of additional high-quality color maps that can be created by name using toyplot.color.LinearFactory.map(), for example:

toyplot.color.linear.map("Blackbody")

Here is the full list of additional linear maps:

toyplot.color.linear.names()

['Blackbody', 'ExtendedBlackbody', 'Kindlmann', 'ExtendedKindlmann']

for name, colormap in toyplot.color.linear.maps():
    IPython.display.display(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(colormap)
Blackbody
ExtendedBlackbody
Kindlmann
ExtendedKindlmann
Moreland Diverging Maps

As an alternative to linear maps, Toyplot also provides a set of nonlinear diverging color maps based on “Diverging Color Maps for Scientific Visualization” by Ken Moreland at http://www.sandia.gov/~kmorel/documents/ColorMaps. The Moreland maps are carefully crafted to provide a perceptually uniform mapping that takes both color and luminance into account to eliminate Mach banding effects. Unsurprisingly, they are created by name using toyplot.color.DivergingFactory.map():

toyplot.color.diverging.map("PurpleOrange")

And here are examples of the available maps:

toyplot.color.diverging.names()

['BlueBrown', 'BlueRed', 'GreenRed', 'PurpleGreen', 'PurpleOrange']

for name, colormap in toyplot.color.diverging.maps():
    IPython.display.display(IPython.display.HTML("<b>%s</b>" % name))
    IPython.display.display(colormap)
BlueBrown
BlueRed
GreenRed
PurpleGreen
PurpleOrange

Color Maps and Perception

What do we mean when we speak of “high quality” color palettes and maps? While the choice of color palettes and interpolations may seem to be one of personal taste, not all color pairings are equal! The human visual system is much more sensitive to changes in luminance than changes in hue, so we typically want to use color maps that create linear changes in luminance where there are linear changes in the underlying data. To illustrate this point, the following figures will plot the relationship between data and luminance for all of the colormaps we’ve seen.

First, we will look at colormaps based on the Color Brewer sequential palettes:

import docs
docs.plot_luma(toyplot.color.brewer.maps("sequential"))
0.00.51.0050100BlueGreen0.00.51.0050100BlueGreenYellow0.00.51.0050100BluePurple0.00.51.0050100Blues0.00.51.0050100BrownOrangeYellow0.00.51.0050100GreenBlue0.00.51.0050100GreenBluePurple0.00.51.0050100GreenYellow0.00.51.0050100Greens0.00.51.0050100Greys0.00.51.0050100Oranges0.00.51.0050100PurpleBlue0.00.51.0050100PurpleRed0.00.51.0050100Purples0.00.51.0050100RedOrange0.00.51.0050100RedOrangeYellow0.00.51.0050100RedPurple0.00.51.0050100Reds

Note that for each of the maps, the relationship between data and luminance is close to linear (the ideal). Similarly, here are the other linear color maps provided by Toyplot, which provide nearly perfect luminance:

docs.plot_luma(toyplot.color.linear.maps())
0.00.51.0050100Blackbody0.00.51.0050100ExtendedBlackbody0.00.51.0050100Kindlmann0.00.51.0050100ExtendedKindlmann

Finally, here are the Color Brewer diverging colormaps which, once again, are close to linear, while providing a crisp transition between positive and negative slopes:

docs.plot_luma(toyplot.color.brewer.maps("diverging"))
0.00.51.0050100BlueGreenBrown0.00.51.0050100BlueRed0.00.51.0050100BlueYellowRed0.00.51.0050100GrayRed0.00.51.0050100GreenYellowRed0.00.51.0050100PinkGreen0.00.51.0050100PurpleGreen0.00.51.0050100PurpleOrange0.00.51.0050100Spectral

In most situations, the preceding colormaps should be ideal. However, there are some circumstances where you will need to account for more than just luminance. In particular, some data may trigger an optical illusion called “Mach Bands” that can exaggerate contrasts in color. In this case, the Moreland diverging color maps may be a good choice:

docs.plot_luma(toyplot.color.diverging.maps())
0.00.51.0050100BlueBrown0.00.51.0050100BlueRed0.00.51.0050100GreenRed0.00.51.0050100PurpleGreen0.00.51.0050100PurpleOrange

Although the diverging colormaps use a much narrower range of available luminance that isn’t linear, they provide a perceptually uniform mapping that takes both color and luminance into account to eliminate Mach banding effects.

When we say that a palettes and colormaps in Toyplot are “high quality”, this is what we mean - they provide perceptually uniform relationships between data and color, so that viewers can intuitively relate changes in color to changes in magnitude for the underyling data.

As a counterexample, here is a low-quality colormap (mis)used by many mainstream visualization libraries:

import numpy
jet = toyplot.color.Palette(numpy.load("jet.npy"))
docs.plot_luma("jet", jet)
0.00.51.0050100jet

Note that this palette provides a complex, nonlinear luminance profile that makes it a poor choice no matter what type of data you wish to display, sequential or diverging!

Now that you are familiar with palettes and colormaps, see Color Mapping to see how they are used to display data in a plot.

_images/toyplot.png

Color Mapping

Color mapping is the process of mapping values in your data to colors in a plot. It allows you to increase the dimensionality of a graphic - for example, adding a third dimension to the two-dimensional x, y coordinates in a scatterplot. Good color mapping choices can reveal or emphasize patterns in your data while poor choices will obscure them, making color mapping an essential part of the Toyplot API.

If you haven’t already, see Colors for information on basic color management in Toyplot for creating and manipulating color values, color palettes, and color maps.

Mapping Data to Color

There are a few decisions to make whenever you map colors in Toyplot:

First, what is the cardinality of your data? Will you be specifying:

  • A constant color?
  • Per-series colors?
  • Per-datum colors?

Second, for per-series or per-datum colors, will you specify:

  • A custom palette?
  • Explicit colors?
  • Scalar values that are mapped to colors?

Third, if you choose to map scalars, will you provide:

  • Just scalar values?
  • Just a color map?
  • Both scalar values and a color map?

We will examine all of these options in the examples that follow. To begin, let’s create some random data series to use in our sample figures:

import numpy
numpy.random.seed(1234)

samples = numpy.linspace(0, 4 * numpy.pi, 100)
frequency = lambda: numpy.random.normal()
phase = lambda: numpy.random.normal()
amplitude = lambda: numpy.random.uniform(0.1, 1)
wave = lambda: numpy.sin(phase() + (frequency() * samples))
signal = lambda: amplitude() * (2 + wave())

series = numpy.column_stack([signal() for i in range(10)])
single_series = series[:, 1]

Next, we’ll display the data without specifying any color information. Here is a plot with a single series:

import toyplot
toyplot.fill(single_series, baseline="stacked", width=600, height=200);
0501000.00.51.01.52.02.5

And here’s the same plot with multiple series:

toyplot.fill(series, baseline="stacked", width=600, height=300);
05010004812

These examples allow us to see the answers to the questions posed above: by default, Toyplot generates per-series colors, using the default palette:

toyplot.color.Palette()

In the examples that follow, we will explore how to override these defaults.

Default Palettes

First, let’s specify an alternate palette to be used when assigning default per-series colors. The default color palette is a property of a coordinate system, so to change it we have to specify the palette when the coordinate system is created:

palette = toyplot.color.brewer.palette("Set1")
palette

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(palette=palette)
axes.fill(series, baseline="stacked");
05010004812

Because the palette is a part of a coordinate system, it affects only those marks that you add to that system - if your plot contained multiple sets of axes, they can have any combination of default palettes that you like (although we always recommend that you find ways to use consistent color schemes in your plots!)

In the examples that follow, we will begin to override the colors provided by the axes palettes on a per-mark basis.

Constant Colors

Next, you can specify a single color value, which overrides the default palette and will be applied to all your data:

toyplot.fill(single_series, color="steelblue", baseline="stacked", width=600, height=200);
0501000.00.51.01.52.02.5
toyplot.fill(series, color="steelblue", baseline="stacked", width=600, height=300);
05010004812

As you can see above, combining constant color and multiple series can obscure the series boundaries. In this case, you might use additional styling to make the boundaries visible again:

style = {"stroke": "white"}
toyplot.fill(series, color="steelblue", style=style, baseline="stacked", width=600, height=300);
05010004812

Of course, there are many ways that you could specify a constant color value. See Colors for details.

Per-Series Colors

More often than not, you will want to specify per-series colors to make the series in your data easy to differentiate - which is why Toyplot defaults to per-series colors. To specify per-series colors for any plot that contains \(N\) series, you can use any of the following with the color argument:

Alternate Color Maps

When you supply just a color map to the color argument, Toyplot applies it to a set of implicit color values in the range \([0, N)\) to generate colors for each of the \(N\) series in the plot. This can create duplicate colors if a categorical map doesn’t have enough colors in its palette, as in the following example:

palette = toyplot.color.brewer.palette("BrownOrangeYellow", count=5)
colormap = toyplot.color.CategoricalMap(palette)
colormap

style = {"stroke" : toyplot.color.black, "stroke-width":0.5}
toyplot.fill(series, color=colormap, style=style, baseline="stacked", width=600, height=300);
05010004812

A good way to avoid duplicates is to use a linear map instead of a categorical map - then, colors will be sampled across the full range of the palette without repetition, and assigned to each series:

colormap = toyplot.color.brewer.map("BrownOrangeYellow")
colormap

toyplot.fill(series, color=colormap, style=style, baseline="stacked", width=600, height=300);
05010004812
Scalar Values Plus Color Map

If you want more control over the mapping, you can replace the implicit \([0, N)\) values provided by Toyplot with your own range of \(N\) values to be mapped, passing a (values, colormap) tuple to color:

values = numpy.linspace(0, 1, series.shape[1]) ** 0.5
toyplot.fill(series, color=(values, colormap), style=style, baseline="stacked", width=600, height=300);
05010004812
Scalar Values Alone

As a special-case, if you supply just a set of \(N\) scalar values to color, they will be mapped with a default diverging color map:

toyplot.fill(series, color=values, baseline="stacked", width=600, height=300);
05010004812
Explicit Colors

Finally, for complete control over color, you can bypass the mapping entirely, and provide a sequence of explicit color values, one per series. As an example, suppose you wanted to highlight one of the series in the following example:

colormap = toyplot.color.brewer.map("BlueGreenBrown")
toyplot.fill(series, color=colormap, baseline="stacked", width=600, height=300);
05010004812

Rather than manually create an explicit array of per-series colors from scratch, you can use toyplot.color.broadcast():

colors = toyplot.color.broadcast(colormap, shape=series.shape[1])
colors

The toyplot.color.broadcast() function is used internally by Toyplot to implement the logic for mapping values to colors for varying data shapes, and returns a numpy array of RGBA colors when called. This allows us to generate the same set of colors as in the previous example. Then, we can manually modify the colors to suit our needs:

colors[2] = toyplot.color.css("rgb(255, 235, 10)")
colors

Finally, we pass the explicit list of colors to the color argument when plotting the data:

toyplot.fill(series, color=colors, baseline="stacked", width=600, height=300);
05010004812

Of course, you are free to generate color data from scratch, as a numpy array of CSS color strings, or a list containing an arbitrary sequence of CSS color strings, RGB, and RGBA tuples. This is useful when you have an explicit color scheme dictated by your data and you don’t wish to create a Toyplot palette to match. For example:

colors = ["crimson", "mediumseagreen", "royalblue"]
toyplot.fill(series[:,:3], color=colors, baseline="stacked", width=600, height=300);
05010001234

Per-Datum Colors

For plot types that support it - such as bar plots and scatter plots - you can choose to map colors to individual datums instead of entire series. To enable per-datum color with a plot that takes an \(M \times N\) matrix containing \(M\) datums and \(N\) series, you simply provide an \(M \times N\) matrix of color values or scalars. As a special case, when your plot only contains a single series you can enable per-datum color by providing an array of \(M\) color values or scalars.

Scalar Values Plus Color Map

As with per-series data, you can specify a set of per-datum scalars and a color map:

toyplot.bars(single_series, color=(single_series, colormap), width=600, height=200);
0501000.00.51.01.52.02.5
toyplot.bars(series, color=(series, colormap), baseline="stacked", width=600, height=300);
05010004812
Scalar Values Alone

And as before, you can supply just the per-datum scalars, and they will be mapped using a default diverging color map:

toyplot.bars(single_series, color=single_series, width=600, height=200);
0501000.00.51.01.52.02.5
toyplot.bars(series, color=series, baseline="stacked", width=600, height=300);
05010004812
Explicit Colors

Finally, you can still supply explicit per-datum color values using toyplot.color.broadcast(). In the following example we will use it to highlight the ten largest values in the data:

colors = toyplot.color.broadcast((single_series, colormap), shape=single_series.shape)

order = numpy.argsort(single_series, axis=None)
colors.flat[order[-10:]] = toyplot.color.css("yellow")

toyplot.bars(single_series, color=colors, baseline="stacked", width=600, height=200);
0501000.00.51.01.52.02.5
colors = toyplot.color.broadcast((series, colormap), shape=series.shape)

order = numpy.argsort(series, axis=None)
colors.flat[order[-10:]] = toyplot.color.css("yellow")

toyplot.bars(series, color=colors, baseline="stacked", width=600, height=300);
05010004812

Color Arguments

In the preceeding examples we used the color argument to supply color mapping data for various types of visualization. Keep in mind that many plot types provide more than one color argument, depending on the structure of the plot. For example, you can use color mapping to control the per-series color of a set of line plots:

colormap = toyplot.color.brewer.map("Dark2")
toyplot.plot(series[::3,:2], color=colormap, width=600, height=200);
01020300.00.51.01.52.02.5

… but you can also apply color mapping to per-datum markers in the plot:

toyplot.plot(series[::3,:2], color=colormap, mfill=series[::3,:2], marker="o", size=8, width=600, height=200);
01020300.00.51.01.52.02.5

See the reference documentation for the individual plot types for information on which arguments accept color mapping parameters.

_images/toyplot.png

Convenience API

With Toyplot, a figure always consists of three parts:

Creating these entities separately gives you the maximum flexibility, allowing you to add multiple (even overlapping) coordinate systems to one canvas, splitting the marks among the different coordinate systems, etc. However for simple figures containing a single coordinate system and a single mark, this way of working can be tedious. Toyplot’s convenience API combines the three calls to create canvas, coordinate system, and mark into a single function that can handle many of your plotting needs with a minimum of code.

Consider the following verbose example:

import numpy
y = numpy.linspace(0, 1, 20) ** 2

import toyplot
canvas = toyplot.Canvas(width=300)
axes = canvas.cartesian()
axes.plot(y);
051015200.00.51.0

Using the convenience API, it can be reduced to a single call to toyplot.plot():

canvas, axes, mark = toyplot.plot(y, width=300)
051015200.00.51.0

Of course, if you’re using the convenience API there’s a good chance you don’t need the function’s return value (a (canvas, axes, mark) tuple) at all, making it even more compact:

toyplot.plot(y, width=300);
051015200.00.51.0

If you check the reference documentation for toyplot.plot(), you will see that its parameters include the union of the parameters for toyplot.canvas.Canvas, toyplot.canvas.Canvas.cartesian(), and toyplot.coordinates.Cartesian.plot(), except where parameter names might conflict.

Similar convenience API functions are provided for bar, fill, and scatter plots:

toyplot.bars(y, width=300);
010200.00.51.0
toyplot.fill(numpy.column_stack((y, y*2)), width=300);
051015200.00.51.01.52.0
numpy.random.seed(1234)
toyplot.scatterplot(numpy.random.normal(size=50), width=300);
01020304050-202
toyplot.matrix(numpy.random.normal(size=(10, 10)), width=300);
012345678900.841009-1.445810-1.401973-0.100918-0.548242-0.1446200.354020-0.0355130.5657381.5456591-0.974236-0.0703450.307969-0.2084991.033801-2.4004542.030604-1.1426310.2118830.7047212-0.7854350.4620600.7042280.523508-0.9262542.0078430.226963-1.1526590.6319790.03951330.464392-3.5635171.3211060.1526310.164530-0.4300960.7673690.9849200.2708361.39198640.079842-0.399965-1.027851-0.5847180.816594-0.081947-0.3447660.528288-1.068989-0.51188150.2912050.5665340.5035920.2852960.4842881.363482-0.781105-0.4680181.224574-1.28110860.875476-1.710715-0.4507650.749164-0.203933-0.1821750.680656-1.8184990.0470720.3948447-0.248432-0.617707-0.6828840.436258-1.7030130.393711-0.479324-0.2990160.6941030.67863080.2395560.1512270.8161271.8935340.639633-0.962029-2.0852661.930247-1.7353491.21038490.797435-0.3798110.702562-0.8503461.176812-0.5243360.7009080.984188-0.1217282.365769
data = toyplot.data.cars()
columns = ["Year", "MPG", "Model"]
canvas, table = toyplot.table(data[:10, columns], width=300)
table.cells.column[2].width = 130
YearMPGModel7018chevrolet chevelle malibu7015buick skylark 3207018plymouth satellite7016amc rebel sst7017ford torino7015ford galaxie 5007014chevrolet impala7014plymouth fury iii7014pontiac catalina7015amc ambassador dpl

If you need greater control over the positioning of the axes within the canvas, need to add multiple axes to one canvas, or need to add multiple marks to one set of axes, you’ll have to create the canvas and axes explicitly.

_images/toyplot.png

Data Tables

Overview

Data tables, with rows containing observations and columns containing variables or series, are arguably the cornerstone of science. Much of the functionality of Toyplot or any other plotting package can be reduced to a process of mapping data series from tables to properties like coordinates and colors. To facilitate this, Toyplot provides toyplot.data.Table - an ordered, heterogeneous collection of named, equal-length columns, where each column is a Numpy masked array. Toyplot data tables are used for internal storage and manipulation by all of the individual types of plot, and can be useful for managing data prior to ingestion into Toyplot.

Be careful not to confuse the data tables described in this section with Table Coordinates, which are used to visualize tabular data.

import toyplot.data
import numpy

table = toyplot.data.Table()
table["x"] = numpy.arange(10)
table["x*2"] = table["x"] * 2
table["x^2"] = table["x"] ** 2
table
xx*2x^2
000
121
244
369
4816
51025
61236
71449
81664
91881

You can see from this small example that Toyplot tables provide automatic pretty-printing when used with Jupyter notebooks, like other Toyplot objects (Jupyter pretty-printing is provided as a convenience - to create tabular data graphics, you will likely want the additional control provided by Table Coordinates).

A Toyplot table behaves like a Python dict that maps column names (keys) to the column values (1D arrays). For example, you assign and access individual columns using normal indexing notation with column names:

print(table["x"])
print(table["x*2"])
print(table["x^2"])

[0 1 2 3 4 5 6 7 8 9]
[ 0  2  4  6  8 10 12 14 16 18]
[ 0  1  4  9 16 25 36 49 64 81]

In addition, the keys(), values(), and items() methods also act like their standard library counterparts, providing column-oriented access to the table contents. However, unlike a normal Python dict, a Toyplot table remembers the order in which columns were added to the table, and always returns them in the same order:

for name in table.keys():
    print(name)

x
x*2
x^2

for column in table.values():
    print(column)

[0 1 2 3 4 5 6 7 8 9]
[ 0  2  4  6  8 10 12 14 16 18]
[ 0  1  4  9 16 25 36 49 64 81]

for name, column in table.items():
    print(name, column)

x [0 1 2 3 4 5 6 7 8 9]
x*2 [ 0  2  4  6  8 10 12 14 16 18]
x^2 [ 0  1  4  9 16 25 36 49 64 81]

That’s all straightforward, but Toyplot tables also behave like Python lists. For example, you can use the normal Python length function to get the number of rows:

len(table)

10

And you can access a single row using its integer index:

table[3]
xx*2x^2
369

And you can retrieve a range of rows using slice notation:

table[2:5]
xx*2x^2
244
369
4816

You can also retrieve a noncontiguous range of rows using Numpy advanced slicing:

table[[1, 3, 4]]
xx*2x^2
121
369
4816

Finally, you can mix both forms of indexing (rows and columns) to retrieve arbitrary subsets of a table:

table[3, "x*2"]
x*2
6
table[3:6, ["x", "x*2"]]
xx*2
36
48
510
table[[1, 3, 4], ["x", "x*2"]]
xx*2
12
36
48

Passing a sequence of column names allows you to reorder the columns in a table if necessary:

table[["x*2", "x"]]
x*2x
00
21
42
63
84
105
126
147
168
189

Note that all of these operations are taking views into the underlying column storage, so no data is copied.

Initialization

In the above example, we created a data table from scratch, adding data one-column-at-a-time to an empty table. However, there are many different ways to create a table. For example, you can pass a dictionary that maps column names to column values:

data = dict()
data["Name"] = ["Tim", "Fred", "Jane"]
data["Age"] = [45, 32, 43]
toyplot.data.Table(data)
AgeName
45Tim
32Fred
43Jane

You can also pass any other object that implements Python’s collections.abc.Mapping protocol. Note that the columns are inserted into the table in alphabetical order, since Python dictionaries / maps do not have an explicit ordering.

If column order matters to you, you can use an instance of collections.OrderedDict instead, which remembers the order in which data was added:

import collections
data = collections.OrderedDict()
data["Name"] = ["Tim", "Fred", "Jane"]
data["Age"] = [45, 32, 43]
toyplot.data.Table(data)
NameAge
Tim45
Fred32
Jane43

Another way to add ordered data to a data table would be to use a sequence of (column name, column values) tuples:

data = [("Name", ["Tim", "Fred", "Jane"]), ("Age", [45, 32, 43])]
toyplot.data.Table(data)
NameAge
Tim45
Fred32
Jane43

Again, you can use any collections.abc.Sequence type, not just a Python list as in this example.

You can also treat any two-dimensional numpy array (matrix) as a table:

data = numpy.array([["Tim", 45],["Fred", 32], ["Jane", 43]])
toyplot.data.Table(data)
01
Tim45
Fred32
Jane43

… Note that the ordering of the matrix columns is retained, and column names are created for you.

You can also convert a Pandas data frame into a table:

import pandas
df = pandas.read_csv(toyplot.data.temperatures.path)
toyplot.data.Table(df)[0:5]
STATIONSTATION_NAMEDATETMAXTMINTOBS
GHCND:USC00294366JEMEZ DAM NM US2013010139-72-67
GHCND:USC00294366JEMEZ DAM NM US201301020-133-133
GHCND:USC00294366JEMEZ DAM NM US2013010311-139-89
GHCND:USC00294366JEMEZ DAM NM US2013010411-139-89
GHCND:USC00294366JEMEZ DAM NM US2013010522-144-111

By default, the data frame index isn’t included in the conversion to a table, but you can override this if you wish:

toyplot.data.Table(df, index=True)[0:5]
index0STATIONSTATION_NAMEDATETMAXTMINTOBS
0GHCND:USC00294366JEMEZ DAM NM US2013010139-72-67
1GHCND:USC00294366JEMEZ DAM NM US201301020-133-133
2GHCND:USC00294366JEMEZ DAM NM US2013010311-139-89
3GHCND:USC00294366JEMEZ DAM NM US2013010411-139-89
4GHCND:USC00294366JEMEZ DAM NM US2013010522-144-111

If you don’t like the auto generated name of the index column, you can provide an alternate name of your own:

toyplot.data.Table(df, index="INDEX")[0:5]
INDEXSTATIONSTATION_NAMEDATETMAXTMINTOBS
0GHCND:USC00294366JEMEZ DAM NM US2013010139-72-67
1GHCND:USC00294366JEMEZ DAM NM US201301020-133-133
2GHCND:USC00294366JEMEZ DAM NM US2013010311-139-89
3GHCND:USC00294366JEMEZ DAM NM US2013010411-139-89
4GHCND:USC00294366JEMEZ DAM NM US2013010522-144-111

Note that hierarchical data frame indices will be converted to multiple table columns.

Demonstration

As a convenience, for pedagogical purposes only, Toyplot provides basic functionality to load a table from a CSV file - but please note that Toyplot is emphatically not a data manipulation library! For real work you should use the Python standard library csv module to load data, or functionality provided by libraries such as Numpy or Pandas. In the following example, we will load a set of temperature readings into a data table to use for a visualization:

table = toyplot.data.read_csv(toyplot.data.temperatures.path)
table[0:10]
STATIONSTATION_NAMEDATETMAXTMINTOBS
GHCND:USC00294366JEMEZ DAM NM US2013010139-72-67
GHCND:USC00294366JEMEZ DAM NM US201301020-133-133
GHCND:USC00294366JEMEZ DAM NM US2013010311-139-89
GHCND:USC00294366JEMEZ DAM NM US2013010411-139-89
GHCND:USC00294366JEMEZ DAM NM US2013010522-144-111
GHCND:USC00294366JEMEZ DAM NM US2013010644-122-100
GHCND:USC00294366JEMEZ DAM NM US2013010756-122-11
GHCND:USC00294366JEMEZ DAM NM US20130108100-83-78
GHCND:USC00294366JEMEZ DAM NM US2013010972-83-33
GHCND:USC00294366JEMEZ DAM NM US2013011189-5022

Then, we convert the readings (which are stored as tenths of a degree Celsius) to Fahrenheit:

table["TMAX_F"] = ((table["TMAX"].astype("float64") * 0.1) * 1.8) + 32
table["TMIN_F"] = ((table["TMIN"].astype("float64") * 0.1) * 1.8) + 32

Finally, we can pass table columns directly to Toyplot for plotting:

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(xlabel="Day", ylabel=u"Temperature \u00b0F")
axes.plot(table["TMAX_F"], color="red", stroke_width=1)
axes.plot(table["TMIN_F"], color="blue", stroke_width=1);
0100200300400Day050100Temperature °F
_images/toyplot.png

Ellipse Visualization

Toyplot supports drawing oriented ellipses using toyplot.coordinates.Cartesian.ellipse(). Ellipses are defined using their center, x and y radius, and angle with respect to the X axis. For example, to create an unrotated ellipse centered at the origin:

import toyplot

canvas = toyplot.Canvas(width=400)
axes = canvas.cartesian(aspect="fit-range")
axes.ellipse(0, 0, 5, 2);
-505-505

When rotating ellipses, angles are specified in degrees with positive angles leading to clockwise rotation:

canvas = toyplot.Canvas(width=400)
axes = canvas.cartesian(aspect="fit-range")
axes.ellipse(0, 0, 5, 2, 45);
-4-2024-4-2024

Of course, you can use color, opacity, and style to alter the appearance of an ellipse:

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(grid=(1, 2, 0), aspect="fit-range")
axes.ellipse(0, 0, 5, 2, 45, color="crimson", opacity=0.5)
axes = canvas.cartesian(grid=(1, 2, 1), aspect="fit-range")
axes.ellipse(0, 0, 5, 2, 45, style={"stroke": "black", "fill":"none"});
-4-2024-4-2024-4-2024-4-2024

One thing to keep in mind when working with ellipses is that, if you don’t specify an explicit domain for your axes, Toyplot’s default axis scaling will tend to turn an ellipse into a circle:

canvas = toyplot.Canvas(width=300)
axes = canvas.cartesian() # Allow Toyplot to choose the domain
axes.ellipse(0, 0, 5, 2);
-505-2-1012

This is because Toyplot treats your ellipses as data - that is, ellipses aren’t just symbols drawn atop the canvas, they are embedded in the space defined by the axes. Thus, an ellipse will be distorted when viewed using a nonlinear projection such as log axes. This is by design:

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(grid=(1, 2, 0), label="Linear Y projection")
axes.ellipse(20, 15, 20, 5, 30)
axes = canvas.cartesian(grid=(1, 2, 1), yscale="log", label="Nonlinear Y projection")
axes.ellipse(20, 15, 20, 5, 30);
010203040510152025Linear Y projection01020304010 010 110 2Nonlinear Y projection

The distortion can become even more extreme if the ellipse straddles the origin:

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(grid=(1, 2, 0), label="Linear Y projection")
axes.ellipse(0, 0, 20, 5, 30)
axes = canvas.cartesian(grid=(1, 2, 1), yscale="log", label="Nonlinear Y projection")
axes.ellipse(0, 0, 20, 5, 30);
-20-1001020-10010Linear Y projection-20-1001020-10 2-10 1-10 0010 010 110 2Nonlinear Y projection

While this behavior may seem nonintuitive at first, it makes sense when you’re using an ellipse to visualize confidence or other bounds for sampled data. For example, suppose you’re drawing samples from a bivariate normal distribution:

import numpy
numpy.random.seed(1234)

mean = numpy.array([3, 5])
covariance = numpy.array([[3, 1], [1, 1]])

samples = numpy.random.multivariate_normal(mean, covariance, size=1000)

canvas = toyplot.Canvas()
axes = canvas.cartesian(aspect="fit-range")
axes.scatterplot(samples[:,0], samples[:,1]);
05100510

If you wanted to draw ellipses at 1, 2, and 3-\(\sigma\) intervals, you might do the following:

eigenvalues, eigenvectors = numpy.linalg.eig(covariance)
angle = numpy.degrees(numpy.arctan2(eigenvectors[1, 0], eigenvectors[0, 0]))

xsigma = numpy.sqrt(eigenvalues[0])
ysigma = numpy.sqrt(eigenvalues[1])

canvas = toyplot.Canvas()
axes = canvas.cartesian(aspect="fit-range")
axes.scatterplot(samples[:,0], samples[:,1])
axes.ellipse(mean[0], mean[1], xsigma, ysigma, angle, style={"stroke":"black", "fill":"none"})
axes.ellipse(mean[0], mean[1], xsigma * 2, ysigma * 2, angle, style={"stroke":"black", "fill":"none"})
axes.ellipse(mean[0], mean[1], xsigma * 3, ysigma * 3, angle, style={"stroke":"black", "fill":"none"});
-303690510

However, if you use a nonlinear projection on the Y axis, the ellipse needs to deform along with the rest of the data:

canvas = toyplot.Canvas(width=600, height=400)
axes = canvas.cartesian(aspect="fit-range", yscale="log")
axes.scatterplot(samples[:,0], samples[:,1])
axes.ellipse(mean[0], mean[1], xsigma, ysigma, angle, style={"stroke":"black", "fill":"none"})
axes.ellipse(mean[0], mean[1], xsigma * 2, ysigma * 2, angle, style={"stroke":"black", "fill":"none"})
axes.ellipse(mean[0], mean[1], xsigma * 3, ysigma * 3, angle, style={"stroke":"black", "fill":"none"});
-3036910 010 1

Finally, as with other Toyplot visualizations, you are not limited to creating individual ellipses one-at-a-time - you can create a series of ellipses in a single call:

numpy.random.seed(14)

x = numpy.random.uniform(-6, 6, size=10)
y = numpy.random.uniform(-4, 4, size=10)
rx = numpy.random.uniform(0.1, 1, size=10)
ry = numpy.random.uniform(0.1, 1, size=10)
angle = numpy.random.uniform(0, 180, size=10)

canvas = toyplot.Canvas(width=600, height=400)
axes = canvas.cartesian(aspect="fit-range")
axes.ellipse(x, y, rx, ry, angle, color=toyplot.color.brewer.map("Set1"), style={"stroke":"white"});
-505-4-2024
_images/toyplot.png

Embedding

We like to say that “Toyplot figures are beautiful, scalable, embeddable, and interactive”, but what does embeddable really mean, anyway? Scientists and engineers are already accustomed to embedding static images in their publications and presentations, so what does embedding in Toyplot have to offer that other tools don’t?

In a word: interaction.

In their preferred HTML format, Toyplot figures are interactive - users can mouse over the figure to see interactive coordinates and even extract the data from a figure in CSV format using a context menu. This is just scratching the surface of what we want to achieve in interactivity, but the key point is that each figure is completely self contained and can be distributed as a single file without any need for a server, libraries, stylesheets, or even a network connection.

Here are some examples of Toyplot embedding in-action:

Jupyter (IPython) Notebooks

To use Toyplot in a Jupyter (IPython) notebook, simply import the library and create a plot - no extra statements, “magics”, or backend configuration required. The library knows that it’s being executed in the Jupyter environment, and automatically renders the plot into your notebook using the interactive HTML format:

_images/jupyter-embedding.png

“This is all well and good”, you may say, “and the interaction is nice, but it’s hardly a game-changer”.

But wait! This is where the self-contained nature of Toyplot figures really starts to shine. For example, if you use the notebook’s File > Download as > HTML (.html) menu command, your browser will download an HTML copy of the notebook, with the Toyplot figures embedded, as you might expect. What you might not expect is that the figures will still be live and interactive!

Slides

As another example, you can convert your Jupyter notebook into an interactive Reveal.js presentation using the nbconvert utility, and the embedded Toyplot figures in your slides will still be interactive during your presentation:

ipython nbconvert mynotebook.ipynb --to slides --post serve

Imagine being able to respond to audience questions with a live figure that was authored in a completely separate environment!

Documentation

Similarly, you can convert a Jupyter notebook to restructured text (the markup of choice for most Python documentation):

$ ipython nbconvert mynotebook.ipynb --to rst --output mynotebook.rst

and the HTML Toyplot figures will be embedded in the restructured text and remain fully-interactive in the generated docs. This, by the way, is how much of the Toyplot documentation you’re reading right now is written - we author examples using Jupyter notebooks, which are converted to .rst files, then compiled into HTML documentation using Sphinx:

_images/documentation-embedding.png

Electronic Publication

This leads to one of our key goals for Toyplot: supporting electronic publication, and changing what people expect from data graphics. Many scientific and engineering journals have begun to experiment with HTML-based publishing formats, and figures created with Toyplot are uniquely suited to the HTML publishing environment, providing useful interaction in a completely self-contained “package” that can be trivially inserted into an HTML document without introducing any other dependencies. Because Toyplot figures don’t rely on external servers, libraries or stylesheets, they can be embedded, copied, and moved from place-to-place where they will continue to Just Work without modification - properties that are critical for archival and accessibility.

E-Mail

Because a Toyplot figure is fully self-contained, it can be easily shared through e-mail or other electronic communication channels. You can e-mail a Toyplot figure to a colleague as an HTML file, and they will be able to easily view and interact with the file, in many cases right inside their e-mail client!

PyQT / PySide

Because the Qt graphical user interface includes a fully-featured WebKit browser and Python bindings (PyQt or PySide, take your pick), you can embed interactive Toyplot plots in just a few lines of code, with all the interaction intact:

window = QWebView()
canvas, axes, mark = toyplot.plot(x, y)
window.setHtml(xml.etree.ElementTree.tostring(toyplot.html.render(canvas), method="html"))

If you prefer, you could also embed static plots using the SVG or PNG backends:

window.setContent(xml.tostring(toyplot.svg.render(canvas)), "image/svg+xml")

or

window.setContent(toyplot.png.render(canvas), "image/png")

Programmatic Embedding

Toyplot provides a wide variety of Rendering backends in addition to the preferred, interactive HTML backend. The API implemented by the backends has been carefully crafted to support embedding and maximize consistency:

  • Most backends take a fileobj parameter in their render method. If you pass a string fileobj, the canvas will be written to the given filename on disk.
  • If you pass a file-like object as the fileobj parameter, the canvas will be written directly to the object. So you could store any figure to an in-memory io.StringIO buffer for subsequent processing, for example.
  • If you don’t supply the fileobj parameter when rendering, the canvas will be returned to the caller in whatever high-level form is most appropriate for that backend:
_images/toyplot.png

Graph Visualization

Overview

Toyplot now includes support for visualizing graphs - in the mathematical sense of vertices connected by edges - using the toyplot.coordinates.Cartesian.graph() and toyplot.graph() functions. As we will see, graph visualizations combine many of the aspects and properties of line plots (for drawing the edges), scatterplots (for drawing the vertices), and text (for drawing labels).

At a minimum, a graph can be specified as a collection of edges. For example, consider a trivial social network:

sources = ["Tim", "Tim", "Fred", "Janet"]
targets = ["Fred", "Janet", "Janet", "Pam"]

… here, we have specified a sequence of source (start) vertices and target (end) vertices for each edge in the graph, which we can pass directly to Toyplot for rendering:

import toyplot
toyplot.graph(sources, targets, width=300);
FredJanetPamTim

Simple as it is, Toyplot had to perform many steps to arrive at this figure:

  • We specified a set of edges as input, and Toyplot induced a set of unique vertices from them.
  • Used a layout algorithm to calculate coordinates for each vertex.
  • Rendered the vertices.
  • Rendered a set of vertex labels.
  • Rendered an edge (line) between each pair of connected vertices.

We will examine each of these concepts in depth over the course of this guide.

Inputs

At a minimum, you must specify the edges in a graph to create a visualization. In the above example, we specified a sequence of edge sources and a sequence of edge targets. We could also specify the edges as a numpy matrix (2D array) containing a column of sources and a column of targets:

import numpy
edges = numpy.array([["Tim", "Fred"], ["Tim", "Janet"], ["Fred", "Janet"], ["Janet", "Pam"]])
toyplot.graph(edges, width=300);
FredJanetPamTim

In either case, Toyplot creates (induces) vertices using the edge source / target values. Specifically, the source / target values are used as vertex identifiers, with a vertex created for each unique identifier. Note that vertex identifiers don’t have to be strings, as in the following example:

edges = numpy.array([[0, 1], [0, 2], [1, 2], [2, 3]])
toyplot.graph(edges, width=300);
0123

Inducing vertices from edge data is sufficient for many problems, but there may be occaisions when your graph contains disconnected vertices without any edge connections. For this case, you may specify an optional collection of extra vertex identifiers to add to your graph:

extra_vertices=[10]
toyplot.graph(edges, extra_vertices, width=300);
012310

Layout Algorithms

The next step in rendering a graph is using a layout algorithm to determine the locations of the vertices and routing of edges. Graph layout is an active area of research and there are many competing ideas about what constitutes a good layout, so Toyplot provides a variety of layouts to meet individual needs. By default, graphs are layed-out using the classic force-directed layout of Fruchterman and Reingold:

import docs
edges = docs.barabasi_albert_graph()
toyplot.graph(edges, width=500);
01234567891011121314151617181920212223242526272829

To explicitly specify the layout, use the toyplot.layout module:

import toyplot.layout
layout = toyplot.layout.FruchtermanReingold()
toyplot.graph(edges, layout=layout, width=500);
01234567891011121314151617181920212223242526272829

Note that by default most layouts produce straight-line edges, but this can be overridden by supplying an alternate edge-layout algorithm:

layout = toyplot.layout.FruchtermanReingold(edges=toyplot.layout.CurvedEdges())
toyplot.graph(edges, layout=layout, width=500);
01234567891011121314151617181920212223242526272829

If your graph is a tree, there are also tree-specific layouts to choose from:

numpy.random.seed(1234)
edges = docs.prufer_tree(numpy.random.choice(4, 12))
layout = toyplot.layout.Buchheim()
toyplot.graph(edges, layout=layout, width=500, height=200);
012345678910111213

When computing a layout, Toyplot doesn’t have to compute the coordinates for every vertex … you can explicitly specify some or all of the coordinates yourself. To do so, you can pass a matrix containing X and Y coordinates for the vertices you want to control, that is masked everywhere. Suppose we rendered our tree with the default force directed layout:

toyplot.graph(edges, width=500);
012345678910111213

… but we want to force vertices 0, 1, and 3 to lie on the X axis:

vcoordinates = numpy.ma.masked_all((14, 2)) # We know in advance there are 14 vertices
vcoordinates[0] = (-1, 0)
vcoordinates[1] = (0, 0)
vcoordinates[3] = (1, 0)

toyplot.graph(edges, vcoordinates=vcoordinates, width=500);
012345678910111213

Note that we’ve “pinned” our three vertices of interest, and the layout algorithm has placed the other vertices around them as normal. This is particularly useful when there are vertices of special significance that we wish to place explicitly, either to steer the layout, or to work with a narrative flow.

Keep in mind that we aren’t limited to explicitly constraining both coordinates for a vertex. For example, if we had some other per-vertex variable that we wanted to use for the visualization, we might map it to the X axis:

numpy.random.seed(1234)
data = numpy.random.uniform(0, 1, size=14)

vcoordinates = numpy.ma.masked_all((14, 2))
vcoordinates[:,0] = data

canvas, axes, mark = toyplot.graph(edges, vcoordinates=vcoordinates, width=500)
axes.show = True
axes.aspect = None
axes.y.show = False
0123456789101112130.20.50.81.0

Now, the X coordinate of every vertex is constrained, while the force-directed layout places just the Y coordinates.

Vertex Rendering

As you might expect, you can treat graph vertices as a single series of markers for rendering purposes. For example, you could specify a custom vertex color, marker, size, and label style:

edges = docs.barabasi_albert_graph(n=10)
layout = toyplot.layout.FruchtermanReingold()
#layout = toyplot.layout.FruchtermanReingold(edges=toyplot.layout.CurvedEdges())
vlstyle = {"fill":"white"}

toyplot.graph(edges, layout=layout, vcolor="steelblue", vmarker="d", vsize=30, vlstyle=vlstyle, width=500);
0123456789

Of course, you can assign a \([0, N)\) colormap to the vertices based on their index, or some other variable:

colormap = toyplot.color.LinearMap(toyplot.color.Palette(["white", "yellow", "red"]))
vstyle = {"stroke":toyplot.color.black}

toyplot.graph(edges, layout=layout, vcolor=colormap, vsize=30, vstyle=vstyle, width=500);
0123456789

Edge Rendering

Much like vertices, there are color, width, and style controls for edges:

estyle = {"stroke-dasharray":"3,3"}
toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    ewidth=3,
    eopacity=0.4,
    estyle=estyle,
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
0123456789

Edges can also be rendered with per-edge head, middle, and tail markers. For example, if you wish to show the directionality of the edges in a graph, it is customary to add an arrow at the end of each edge:

toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    tmarker=">",
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
0123456789

Of course, you are free to use any of the properties that are available to control the marker appearance:

toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    tmarker=toyplot.marker.create(shape=">", mstyle={"fill":"white"}),
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
0123456789

You might also want to place markers at the beginning of each edge:

toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    hmarker=toyplot.marker.create(shape="d", mstyle={"fill":"white"}),
    tmarker=toyplot.marker.create(shape=">", mstyle={"fill":"white"}),
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
0123456789

Or you might want to mark the middle of an edge:

toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    mmarker=toyplot.marker.create(shape="r3x1", size=15, label="1.2", mstyle={"fill":"white"}),
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
1.21.21.21.21.21.21.21.21.21.21.21.21.21.21.21.20123456789

Note that markers are aligned with the edge by default, which can make reading text difficult. In many cases you may wish to specify the orientation of each marker as an absolute angle from horizontal:

toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    mmarker=toyplot.marker.create(shape="r3x1", angle=0, size=15, label="1.2", mstyle={"fill":"white"}),
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
1.21.21.21.21.21.21.21.21.21.21.21.21.21.21.21.20123456789

Alternatively, you may wish to specify the orientation of markers relative to their edges:

toyplot.graph(
    edges,
    layout=layout,
    ecolor="black",
    mmarker=toyplot.marker.create(shape="r3x1", angle="r90", size=15, label="1.2", mstyle={"fill":"white"}),
    vcolor=colormap,
    vsize=30,
    vstyle=vstyle,
    width=500,
);
1.21.21.21.21.21.21.21.21.21.21.21.21.21.21.21.20123456789
_images/toyplot.png

Image Visualization

It is often useful to incorporate bitmap images into a visualization. To facilitate this, Toyplot provides toyplot.canvas.Canvas.image() and toyplot.image() functions, which can display image data supplied in a couple of different formats. Note that as a visualization library Toyplot does not provide functionality for reading, writing, or manipulating images - you should do that with libraries such as PIL or scikit-image instead.

For example, you can pass any PIL.Image.Image directly to Toyplot:

import PIL.Image
import toyplot

image = PIL.Image.open("../artwork/toyplot.png")
canvas, mark = toyplot.image(image, width=300)

As always, the width parameter in the above example is the width of the Toyplot canvas. The image is then scaled uniformly to fit. Of course, you can use any Canvas Layout method you like to combine images and marks together on the canvas:

import numpy

canvas = toyplot.Canvas(width=600, height=300)
mark = canvas.image(image, grid=(1,2,0))
axes = canvas.cartesian(grid=(1,2,1))
axes.plot(numpy.linspace(0, 1) ** 2)
canvas.text(150, 250, "( Toyplot Logo )", style={"font-size":"14px"});
010203040500.00.51.0( Toyplot Logo )

In addition to PIL images, Toyplot can display any scikit-images compatible image, i.e. any numpy array with appropriate shape and data type. For example, the following sample data provided with scikit-images is a \(512 \times 512\) image containing three-channel 8-bit RGB color:

import skimage.data
image = skimage.data.astronaut()
image.shape, image.dtype

((512, 512, 3), dtype('uint8'))

canvas, mark = toyplot.image(image, width=300)

This is especially useful when working with scikit-images in a Jupyter notebook.

There are many combinations of channel, data type, and bit depth than can be displayed. The following example converts the data to a single channel containing floating-point grayscale color:

import skimage.color
gray = skimage.color.rgb2gray(image)
gray.shape, gray.dtype

((512, 512), dtype('float64'))

canvas, mark = toyplot.image(gray, width=300)

You can even display one-bit images:

import skimage.filters
binary = gray > skimage.filters.threshold_isodata(gray)
binary.shape, binary.dtype

((512, 512), dtype('bool'))

canvas, mark = toyplot.image(binary, width=300)

Grayscale data can also be mapped using Toyplot’s usual Color Mapping functionality:

colormap = toyplot.color.linear.map("Blackbody")
canvas, mark = toyplot.image((gray, colormap), width=300)
_images/toyplot.png

Interaction

A key goal for the Toyplot team is to explore interactive features for plots, making them truly useful and embeddable, so that they become a ubiquitous part of every data graphic user’s experience. The following examples of interaction are just scratching the surface of what we have planned for Toyplot:

Titles

Most of the visualization types in Toyplot accept a title parameter, allowing you to specify per-series or per-datum titles for a figure. With Toyplot’s preferred embeddable HTML output, those titles are displayed via a popup when hovering over the data. For example, the following figure has a global title “Employee Schedule”, which you should see as a popup when you hover the mouse over any of the bars:

import numpy
numpy.random.seed(1234)
start = numpy.random.normal(loc=8, scale=1, size=20)
end = numpy.random.normal(loc=16, scale=1, size=20)
boundaries = numpy.column_stack((start, end))
title = "Employee Schedule"

import toyplot
toyplot.bars(boundaries, baseline=None, title=title, width=500, height=300);
Employee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee ScheduleEmployee Schedule010205101520

If your plot includes multiple series, you can assign a per-series title instead. Hover the mouse over both series in the following plot to see “Morning Schedule” and “Afternoon Schedule”:

lunch = numpy.random.normal(loc=12, scale=0.5, size=20)
boundaries = numpy.column_stack((start, lunch, end))
title = ["Morning Schedule", "Afternoon Schedule"]

toyplot.bars(boundaries, baseline=None, title=title, width=500, height=300);
Morning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleMorning ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon ScheduleAfternoon Schedule010205101520

Finally, you can assign a title for every datum:

title = numpy.column_stack((
        ["Employee %s Morning" % i for i in range(20)],
        ["Employee %s Afternoon" % i for i in range(20)]
        ))

toyplot.bars(boundaries, baseline=None, title=title, width=500, height=300);
Employee 0 MorningEmployee 1 MorningEmployee 2 MorningEmployee 3 MorningEmployee 4 MorningEmployee 5 MorningEmployee 6 MorningEmployee 7 MorningEmployee 8 MorningEmployee 9 MorningEmployee 10 MorningEmployee 11 MorningEmployee 12 MorningEmployee 13 MorningEmployee 14 MorningEmployee 15 MorningEmployee 16 MorningEmployee 17 MorningEmployee 18 MorningEmployee 19 MorningEmployee 0 AfternoonEmployee 1 AfternoonEmployee 2 AfternoonEmployee 3 AfternoonEmployee 4 AfternoonEmployee 5 AfternoonEmployee 6 AfternoonEmployee 7 AfternoonEmployee 8 AfternoonEmployee 9 AfternoonEmployee 10 AfternoonEmployee 11 AfternoonEmployee 12 AfternoonEmployee 13 AfternoonEmployee 14 AfternoonEmployee 15 AfternoonEmployee 16 AfternoonEmployee 17 AfternoonEmployee 18 AfternoonEmployee 19 Afternoon010205101520

Of course, the title attribute works with all types of visualizations.

Coordinates

When you click or tap the above figures, you should also see the domain values for the point you chose displayed along each of the axes. If you wish to disable display of either or both of the values, you can do so using the individual axes:

canvas, axes, mark = toyplot.bars(boundaries, baseline=None, title=title, width=500, height=300)
axes.x.interactive.coordinates.show = False
axes.y.interactive.coordinates.show = False
Employee 0 MorningEmployee 1 MorningEmployee 2 MorningEmployee 3 MorningEmployee 4 MorningEmployee 5 MorningEmployee 6 MorningEmployee 7 MorningEmployee 8 MorningEmployee 9 MorningEmployee 10 MorningEmployee 11 MorningEmployee 12 MorningEmployee 13 MorningEmployee 14 MorningEmployee 15 MorningEmployee 16 MorningEmployee 17 MorningEmployee 18 MorningEmployee 19 MorningEmployee 0 AfternoonEmployee 1 AfternoonEmployee 2 AfternoonEmployee 3 AfternoonEmployee 4 AfternoonEmployee 5 AfternoonEmployee 6 AfternoonEmployee 7 AfternoonEmployee 8 AfternoonEmployee 9 AfternoonEmployee 10 AfternoonEmployee 11 AfternoonEmployee 12 AfternoonEmployee 13 AfternoonEmployee 14 AfternoonEmployee 15 AfternoonEmployee 16 AfternoonEmployee 17 AfternoonEmployee 18 AfternoonEmployee 19 Afternoon010205101520

Now when you click or tap, nothing happens.

Data Export

If you right-click the mouse over any of the above plots, a small popup menu will appear, giving you the option to “Save as .csv”. If you choose that option, the raw data from the plot will be extracted in CSV format and you can save it.

Note that different browsers, browser versions, and platforms will behave differently when extracting the file:

  • Safari on OSX will open the file in a separate tab, which you can save to disk using File > Save As.
  • Chrome on OSX will immediately open a file dialog, prompting you to save the file.
  • Firefox on OSX will prompt you to open the file with Microsoft Excel (if installed), or save it to disk.

Note that, on the browsers that support it, the default filename for the saved data is toyplot.csv. You can override this default on a per-data-table basis by specifying the filename when you create your figure. For example, when exporting data from the following figure (again, for browsers that support setting a default filename), the filename will default to employee-schedules.csv:

toyplot.bars(boundaries, baseline=None, filename="employee-schedules", title=title, width=500, height=300);
Employee 0 MorningEmployee 1 MorningEmployee 2 MorningEmployee 3 MorningEmployee 4 MorningEmployee 5 MorningEmployee 6 MorningEmployee 7 MorningEmployee 8 MorningEmployee 9 MorningEmployee 10 MorningEmployee 11 MorningEmployee 12 MorningEmployee 13 MorningEmployee 14 MorningEmployee 15 MorningEmployee 16 MorningEmployee 17 MorningEmployee 18 MorningEmployee 19 MorningEmployee 0 AfternoonEmployee 1 AfternoonEmployee 2 AfternoonEmployee 3 AfternoonEmployee 4 AfternoonEmployee 5 AfternoonEmployee 6 AfternoonEmployee 7 AfternoonEmployee 8 AfternoonEmployee 9 AfternoonEmployee 10 AfternoonEmployee 11 AfternoonEmployee 12 AfternoonEmployee 13 AfternoonEmployee 14 AfternoonEmployee 15 AfternoonEmployee 16 AfternoonEmployee 17 AfternoonEmployee 18 AfternoonEmployee 19 Afternoon010205101520

Note that the filename you specify should not include a file extension, as the file extension is added for you (and other file formats may become available in the future).

_images/toyplot.png

Labels and Legends

Of course, most figures must be properly labelled before they can be of value, so Toyplot provides several mechanisms to help:

Coordinate System Labels

First, Cartesian Coordinates, Numberline Coordinates, and Table Coordinates provide labels that can be specified when they are created. In all cases the label parameter provides a top-level label for the coordinate system:

import numpy
import toyplot

canvas = toyplot.Canvas(width=600, height=600)
canvas.cartesian(grid=(2,2,0), label="Cartesian Coordinates").plot(numpy.linspace(0, 1)**2)
canvas.numberline(grid=(2,2,1), label="Numberline Coordinates").scatterplot(numpy.random.normal(size=100))
canvas.table(grid=(2,2,2), label="Table Coordinates", data = numpy.random.random((4, 3)));
010203040500.00.51.0Cartesian Coordinates-2-10123Numberline CoordinatesTable Coordinates0120.1929790.8032980.2972420.2793750.3902430.5728560.3774160.9509520.357010.2764340.4737630.85141

Naturally, some coordinate systems - such as Cartesian - allow you to specify additional, axis-specific labels:

canvas = toyplot.Canvas(width=300, height=300)
axes = canvas.cartesian(label="Cartesian Coordinates", xlabel="Days", ylabel="Users")
axes.plot(numpy.linspace(0, 1)**2);
01020304050Days0.00.51.0UsersCartesian Coordinates

Coordinate System Text

Another option for labelling a figure is to insert text using the same domain as the data. For example, we can label individual series in a plot:

def series(x):
    return numpy.cumsum(numpy.random.normal(loc=0.05, size=len(x)))

numpy.random.seed(1234)
x = numpy.arange(100)
y = numpy.column_stack([series(x) for i in range(5)])

label_style = {"text-anchor":"start", "-toyplot-anchor-shift":"5px"}
canvas, axes, mark = toyplot.plot(x, y)
for i in range(y.shape[1]):
    axes.text(x[-1], y[-1,i], "Series %s" % i, style=label_style)
Series 0Series 1Series 2Series 3Series 4050100-1001020

Note that we are using the last point in each series as the anchor for the corresponding label - by default, Toyplot renders text centered on its anchor, so in this case we’ve chosen a text style that left-aligns the text and offsets it slightly to avoid overlapping the data.

Canvas Text

When adding text to axes, you specify the text coordinates using the same domain as your data. Naturally, this limits the added text to the bounds defined by the axes. For the ultimate in labeling flexibility, you can add text to the canvas directly, using canvas units, outside and/or overlapping coordinate systems:

label_style={"font-size":"18px", "font-weight":"bold"}

canvas = toyplot.Canvas(width=600, height=300)
canvas.cartesian(grid=(1,2,0)).plot(numpy.linspace(1, 0)**2)
canvas.cartesian(grid=(1,2,1), yshow=False).plot(numpy.linspace(0, 1)**2)
canvas.text(300, 120, "This label overlaps two sets of axes!", style=label_style);
010203040500.00.51.001020304050This label overlaps two sets of axes!

… remember when placing labels directly on the canvas that, unlike Cartesian coordinates, canvas coordinates increase from top-to-bottom.

Coordinate System Color Scales

Since we often use color in visualization to add an additional dimension to our plots, we need a way to help viewers map between colors and values. For this case, Toyplot allows a color scale to be added to a set of Cartesian Coordinates:

data = toyplot.data.cars()

colormap = toyplot.color.brewer.map(
    name="BlueGreenBrown",
    reverse=True,
    domain_min = data["MPG"].min(),
    domain_max = data["MPG"].max(),
)
canvas = toyplot.Canvas(width=600, height=400)
axes = canvas.cartesian(xlabel="Year", ylabel="Horsepower", margin=75)
axes.scatterplot(
    data["Year"],
    data["Horsepower"],
    color=(data["MPG"], colormap),
    size=8,
    mstyle={"stroke":"black", "stroke-opacity":0.3}
)
axes.color_scale(colormap, label="MPG");
70747882Year50100150200250Horsepower1020304050MPG

Note that a colormap must be explicitly specified when creating a color scale - this is necessary to avoid ambiguity when a single coordinate system contains multiple visualizations or data series.

Canvas Color Scales

For situations where displaying a vertical color scale with a single set of Cartesian axes is too limiting, you can add horizontal color scales directly to a canvas using any Canvas Layout that makes sense. For example, the following figure uses a single horizontal color scale to display a colormap that is shared between two coordinate systems:

canvas = toyplot.Canvas(width=600, height=400)

axes = canvas.cartesian(bounds=("10%", "45%", "10%", "65%"), xlabel="Year", ylabel="Horsepower")
axes.scatterplot(
    data["Year"],
    data["Horsepower"],
    color=(data["MPG"], colormap),
    size=8,
    mstyle={"stroke":"black", "stroke-opacity":0.3}
)

axes = canvas.cartesian(bounds=("-45%", "-10%", "10%", "65%"), xlabel="Weight", ylabel="Horsepower")
axes.y.spine.position="high"
axes.scatterplot(
    data["Weight"],
    data["Horsepower"],
    color=(data["MPG"], colormap),
    size=8,
    mstyle={"stroke":"black", "stroke-opacity":0.3}
)

canvas.color_scale(colormap, bounds=("10%", "-10%", "75%", "90%"), label="MPG");
70747882Year50100150200250Horsepower2000300040005000Weight50100150200250Horsepower1020304050MPG

Note that when manually adding a color scale to a canvas, you can orient it any way you like (including diagonally!) by explicitly specifying the endpoints in canvas coordinates:

colormap = toyplot.color.brewer.map(
    name="Spectral",
    domain_min=0,
    domain_max=1,
)
canvas = toyplot.Canvas(width=400)
canvas.color_scale(colormap, x1=50, y1=-50, x2=50, y2=50, label="Bottom to Top")
canvas.color_scale(colormap, x1=150, y1=50, x2=150, y2=-50, label="Top to Bottom")
canvas.color_scale(colormap, x1=200, y1=150, x2=350, y2=150, label="Left to Right")
canvas.color_scale(colormap, x1=350, y1=250, x2=200, y2=250, label="Right to Left");
0.00.51.0Bottom to Top0.00.51.0Top to Bottom0.00.51.0Left to Right0.00.51.0Right to Left

Canvas Legends

Last-but-not-least, Toyplot provides basic support for graphical legends:

observations = numpy.random.power(2, size=(50, 50))

x = numpy.arange(len(observations))

boundaries = numpy.column_stack(
    (numpy.min(observations, axis=1),
     numpy.percentile(observations, 25, axis=1),
     numpy.percentile(observations, 50, axis=1),
     numpy.percentile(observations, 75, axis=1),
     numpy.max(observations, axis=1)))

color = ["blue", "blue", "red", "red"]
opacity = [0.1, 0.2, 0.2, 0.1]

canvas = toyplot.Canvas(800, 400)
axes = canvas.cartesian(grid=(1,5,0,1,0,4))
fill = axes.fill(x, boundaries, color=color, opacity=opacity)
mean = axes.plot(x, numpy.mean(observations, axis=1), color="blue")

canvas.legend([
    ("Mean", mean),
    ("Quartiles", fill),
    ],
    corner=("right", 100, 100, 50),
    );
010203040500.00.51.0Mean Quartiles

The call to toyplot.canvas.Canvas.legend() always includes an explicit list of entries to add to the legend, plus a Canvas Layout specification of where the layout should appear on the canvas. Currently, each entry to be displayed in a legend must be one of the following:

  • A (label, mark) tuple, which will get its appearance from the mark, or:
  • A (label, marker) tuple, which can be used to specify an arbitrary Marker.

Of course, label is the human-readable text to be displayed next to an item in the legend, while mark is a mark that has been added to the canvas. However, not all marks can map cleanly to a single entry in the legend - note in the example above that the fill mark added multiple markers to the “Quartiles” entry in the legend, one for each data series. While the interpretation is reasonably clear in this case, there will be occasions when there isn’t a sensible one-to-one mapping between a mark and an entry in the legend. For example, the meaning of multiple series may not be clear, or you may be plotting categorical information using custom markers in a line or scatter plot. In these cases use the second form of legend entry to specify as many explicit Markers as needed.

There are some subtleties here worth noting, many of which are driven by Toyplot’s deliberate embrace of the philosophy that explicit is better than implicit:

  • You can have as many or as few legends on your canvas as you like.
  • Callers explicitly specify the order and contents of each legend.
  • There is no relationship between axes and legends - you can combine marks from multiple axes in a single legend.

Here’s an example with all these ideas at work. Note that the legend overlaps two coordinate systems and its first entry derives directly from the mark in the first coordinate system, while the second and third entries document the individual series in the second mark:

x = numpy.linspace(0, 1)
y1 = (1 - x) ** 2
y2 = numpy.column_stack((1 - (x ** 2), x ** 2))

canvas = toyplot.Canvas(width=600, height=300)
m1 = canvas.cartesian(grid=(1,2,0), margin=25).scatterplot(x, y1, marker="o", color="rgb(255,0,0)")
m2 = canvas.cartesian(grid=(1,2,1), margin=25, yshow=False).scatterplot(x, y2, marker="s", color=["green", "blue"])

if True:
    canvas.legend([
        ("Experiment 1", m1),
        ("Experiment 2", m2.markers[0]),
        ("Experiment 3", m2.markers[1]),
        ],
        corner=("top", 100, 100, 70),
        );
0.00.51.00.00.51.00.00.51.0Experiment 1Experiment 2Experiment 3
_images/toyplot.png

Logarithmic Scales

In Toyplot, individual axes supplied by toyplot.coordinates.Cartesian and toyplot.coordinates.Numberline provide mappings from data values to canvas coordinates. An important property of each axis is its scale, used to specify linear or logarithmic mappings from domain to range:

import numpy
x = numpy.linspace(-1000, 1000, 51)

import toyplot
canvas = toyplot.Canvas(width=600, height=200)

numberline = canvas.numberline(grid=(2, 1, 0, 0), scale="linear")
numberline.scatterplot(x)

numberline = canvas.numberline(grid=(2, 1, 1, 0), scale="log")
numberline.scatterplot(x);
-1000-50005001000-10 3-10 2-10 1-10 0010 010 110 210 3

Or in two dimensions:

canvas = toyplot.Canvas(width=700)

axes = canvas.cartesian(grid=(2, 2, 0, 0), xscale="linear", yscale="linear")
axes.plot(x, x, marker="o")

axes = canvas.cartesian(grid=(2, 2, 0, 1), xscale="log", yscale="linear")
axes.plot(x, x, marker="o")

axes = canvas.cartesian(grid=(2, 2, 1, 0), xscale="linear", yscale="log")
axes.plot(x, x, marker="o")

axes = canvas.cartesian(grid=(2, 2, 1, 1), xscale="log", yscale="log")
axes.plot(x, x, marker="o");
-1000-50005001000-1000-50005001000-10 3-10 2-10 1-10 0010 010 110 210 3-1000-50005001000-1000-50005001000-10 3-10 2-10 1-10 0010 010 110 210 3-10 3-10 2-10 1-10 0010 010 110 210 3-10 3-10 2-10 1-10 0010 010 110 210 3

Note that Toyplot handles negative values correctly, and provides sensible results for values near zero by rendering them using a small linear region around the origin.

The scale can be specified in two ways:

  • As a string - “linear”, “log” (base 10), “log10” (base 10), or “log2” (base 2).
  • As a tuple - (“log”, 2), (“log”, 10).

For example, the following are all equivalent

canvas = toyplot.Canvas(width=600, height=300)

numberline = canvas.numberline(grid=(3,1,0), scale="log")
numberline.scatterplot(x)

numberline = canvas.numberline(grid=(3,1,1), scale="log10")
numberline.scatterplot(x)

numberline = canvas.numberline(grid=(3,1,2), scale=("log", 10))
numberline.scatterplot(x);
-10 3-10 2-10 1-10 0010 010 110 210 3-10 3-10 2-10 1-10 0010 010 110 210 3-10 3-10 2-10 1-10 0010 010 110 210 3

Of course, you are free to specify any base you like, using the tuple notation:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline(scale=("log", 4))
numberline.scatterplot(x);
-4 5-4 4-4 3-4 2-4 1-4 004 04 14 24 34 44 5
_images/toyplot.png

Markers

In Toyplot, markers are used to show the individual datums in scatterplots:

import numpy
import toyplot

import logging
logging.basicConfig()

y = numpy.linspace(0, 1, 20) ** 2
toyplot.scatterplot(y, width=300);
051015200.00.51.0

Markers can also be added to regular plots to highlight the datums (they are turned-off by default):

canvas = toyplot.Canvas(600, 300)
canvas.cartesian(grid=(1, 2, 0)).plot(y)
canvas.cartesian(grid=(1, 2, 1)).plot(y, marker="o");
051015200.00.51.0051015200.00.51.0

You can use the size argument to control the size of the markers:

canvas = toyplot.Canvas(600, 300)
canvas.cartesian(grid=(1, 2, 0)).plot(y, marker="o", size=6)
canvas.cartesian(grid=(1, 2, 1)).plot(y, marker="o", size=10);
051015200.00.51.0051015200.00.51.0

Or you can use the area argument instead to control the approximate area of the markers (this is recommended if you’re using per-datum marker sizes to display data).

By default, plot and scatterplot markers are small circles, but many other shapes can be specified using a string shape code:

canvas = toyplot.Canvas(600, 300)
canvas.cartesian(grid=(1, 2, 0)).scatterplot(y, marker="x", size=10)
canvas.cartesian(grid=(1, 2, 1)).scatterplot(y, marker="^", size=10, mstyle={"stroke":toyplot.color.black});
051015200.00.51.0051015200.00.51.0

Note the use of the mstyle argument to override the appearance of the marker in the second example. For line plots, this allows you to style the lines and the markers separately:

canvas = toyplot.Canvas(600, 300)
canvas.cartesian(grid=(1, 2, 0)).plot(y, marker="o", size=8, style={"stroke":"darkgreen"})
canvas.cartesian(grid=(1, 2, 1)).plot(y, marker="o", size=8, mstyle={"stroke":"darkgreen"});
051015200.00.51.0051015200.00.51.0

Note that you can pass a sequence of shape codes to the marker argument, to specify markers on a per-series or per-datum basis.

The string shape code is actually a shortcut for a full marker specification, which is an instance of toyplot.marker.Marker that contains a set of explicit marker attributes:

  • “shape” - marker shape code.
  • “mstyle” - dictionary of CSS styles to apply to the marker shape.
  • “size” - size of the marker.
  • “angle” - angle (in degrees) to rotate the marker.
  • “label” - text label superimposed on the marker.
  • “lstyle” - dictionary of CSS styles to apply to the marker label.

Using the full marker specification allows you to override the size, style, and appearance of individual markers in a series, if necessary.

You can use toyplot.marker.create() to create instances of toyplot.marker.Marker, as in the following examples:

import toyplot.marker

marker_a = toyplot.marker.create(shape="^", angle=-30, size=15)
marker_b = toyplot.marker.create(shape="o", label="B", lstyle={"fill":"white"})

canvas = toyplot.Canvas(600, 300)
canvas.cartesian(grid=(1, 2, 0)).scatterplot(y, marker=marker_a, size=10)
canvas.cartesian(grid=(1, 2, 1)).scatterplot(y, marker=marker_b, size=15);
051015200.00.51.0BBBBBBBBBBBBBBBBBBBB051015200.00.51.0

In addition to using markers in plots and scatterplots, markers can be embedded in any figure text, using custom HTML markup. The markup itself can be fairly verbose, so toyplot.marker.Marker provides API to make it easier:

marker_a = toyplot.marker.create(shape="s", label="A", mstyle={"fill":"none"})
marker_b = toyplot.marker.create(shape="*")
text = marker_a + " is a marker and so is " + marker_b

style = {"font-size": "18px"}

canvas = toyplot.Canvas(width="5in", height="1.25in")
axes = canvas.cartesian(show=False)
axes.text(0, 0, text=text, style=style);
A is a marker and so is

You can also convert markers to HTML explicitly, if you prefer:

print(marker_a.to_html())

<marker shape='s' mstyle='fill:none' label='A'/>

This makes it easy to create a table documenting all of the available marker shape codes:

markers = [None, "|","/","-","\\","+","x","*","^",">","v","<","s","d",
           "o","oo","o|", "o/", "o-", "o\\", "o+","ox","o*","r3x1","r2x1","r1x1", "r1x2", "r0.5x1.5"]
mstyle = {"stroke":toyplot.color.black, "fill":"#feb"}
labels = [str(marker) for marker in markers]
markers = [toyplot.marker.create(shape=marker, mstyle=mstyle, size=15).to_html() for marker in markers]

# This is necessary because "<" and ">" are interpreted as tags when rendering text.
from xml.sax.saxutils import escape
labels = [escape(label) for label in labels]

canvas, table = toyplot.table(trows=1, rows=len(markers), columns=2, width=400, height=1200)
table.cells.grid.vlines[...,1] = "single"
table.cells.grid.hlines[1,...] = "single"
table.top.cell[0,...].data = ["Shape Code", "Marker"]
table.top.cell[0,...].lstyle = {"font-size":"16px", "font-weight":"bold"}
table.body.column[0].data = labels
table.body.column[0].lstyle = {"font-size":"16px", "font-family":"monospace"}
table.body.column[1].data = markers
Shape CodeMarkerNone|/-\+x*^>v<sdoooo|o/o-o\o+oxo*r3x1r2x1r1x1r1x2r0.5x1.5

There are several items here worth noting - first, you can pass None or an empty string to produce an invisible marker, if you need to hide a datum or declutter the display. Second, observe that several of the marker shapes contain internal details that require a contrasting stroke and fill to be visible. Finally, the rectangular rWxH markers can be specified using any values (including floating point values) for their width and height.

Keep in mind that you can embed markers in any text string in Toyplot, including labels, tick marks, and more. And because toyplot.mark.Mark objects have a public markers attribute that is used when creating legends, you can be very creative when annotating figures:

import toyplot.data
data = toyplot.data.deliveries()
data
DateDeliveredOn Time
15feb20055531.0000
15mar20055071.0000
15apr20055861.0000
15may20054881.0000
15jun20054041.0000
15jul20053061.0000
15aug20053230.9905
15sep20055310.9959
15oct20056770.9600
15nov20056950.9624
15dec20058670.9229
15jan20065570.9888
canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(xlabel="Date", ylabel="Deliveries", ymin=0)
deliveries = axes.plot(data["Delivered"], color="darkred")

axes = axes.share("x", ylabel="On Time")
on_time = axes.plot(data["On Time"], color="steelblue")

axes.label.text = "Deliveries (" + deliveries.markers[0] + ") vs. On Time (" + on_time.markers[0] + ")"
048120300600900Deliveries0.930.950.981.00On TimeDeliveries () vs. On Time ()
_images/toyplot.png

Matrix Visualization

It is often useful to render a two-dimensional matrix as a regular grid, colored by the matrix values, as a way to look for patterns in data. To facilitate this, Toyplot provides toyplot.canvas.Canvas.matrix() and toyplot.matrix() functions. To demonstrate, let’s begin with a visualization of a matrix containing values from a normal distribution centered around 1.0:

import numpy
numpy.random.seed(1234)
matrix = numpy.random.normal(loc=1.0, size=(20, 20))

import toyplot
toyplot.matrix(matrix, label="A matrix");
A matrix01234567891011121314151617181901.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.54690610.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.39096121.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.54565930.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.03951341.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.48811951.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.39484460.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.21038471.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.33419881.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.4229869-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.051539100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.688972110.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.668488120.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.211560132.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.724406140.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.680702151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.022774161.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.434437171.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.270338182.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.318119192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.932178

By default, the matrix is rendered using a Color Brewer diverging “BlueRed” linear map, mapped to the minimum and maximum values in the matrix. Thus, dark blue represents the minimum value and dark red is the maximum value. If you hover the mouse over the cells in the matrix you can see their values with a popup.

You can also display an optional color scale that shows the mapping from matrix values to colors:

toyplot.matrix(matrix, label="A matrix", colorshow=True);
A matrix01234567891011121314151617181901.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.54690610.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.39096121.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.54565930.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.03951341.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.48811951.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.39484460.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.21038471.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.33419881.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.4229869-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.051539100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.688972110.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.668488120.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.211560132.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.724406140.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.680702151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.022774161.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.434437171.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.270338182.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.318119192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.932178-2024

Note that, because our minimum and maximum data values aren’t symmetric around the origin, the white section of the color map doesn’t map to zero, and some values greater than zero are mapped to the cool blue portion of the spectrum. Let’s fix this and force our our colormap to be symmetric around zero so all blue colors are negative and all red colors are positive. To do so, we simply create a custom toyplot.color.LinearMap, specifying explicit minimum and maximum domain values and using it in the call to create the matrix visualization:

colormap = toyplot.color.brewer.map("BlueRed", domain_min=-4, domain_max=4)
toyplot.matrix((matrix, colormap), label="A matrix", colorshow=True);
A matrix01234567891011121314151617181901.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.54690610.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.39096121.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.54565930.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.03951341.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.48811951.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.39484460.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.21038471.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.33419881.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.4229869-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.051539100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.688972110.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.668488120.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.211560132.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.724406140.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.680702151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.022774161.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.434437171.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.270338182.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.318119192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.932178-4-2024

Now we see that the color map is nicely symmetric around the origin, making it clear which values are positive and which are negative.

In addition to the top-level label, you can specify labels on any side of the matrix. Note the convention in the parameter names: t for “top”, l for “left”, r for “right”, and b for “bottom”:

toyplot.matrix((matrix, colormap), label="A matrix", tlabel="Top", llabel="Left", rlabel="Right", blabel="Bottom");
A matrix01234567891011121314151617181901.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.54690610.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.39096121.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.54565930.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.03951341.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.48811951.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.39484460.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.21038471.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.33419881.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.4229869-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.051539100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.688972110.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.668488120.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.211560132.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.724406140.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.680702151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.022774161.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.434437171.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.270338182.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.318119192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.932178TopLeftRightBottom

Note that by default, Toyplot provides row and column indices for the matrix, along the top and left sides. As your matrix sizes grow, you may need to thin-out the indices to avoid overlap:

big_matrix = numpy.random.normal(loc=1, size=(50, 50))
toyplot.matrix((big_matrix, colormap), step=5, label="A matrix");
A matrix05101520253035404500.7733680.0761691.355839-0.2700630.8045280.5365811.9894152.3886472.0877141.4388010.0383982.2456101.5029260.3686010.2957480.7595171.5855991.352801-0.8155580.0898760.2514720.8918751.2747791.2373500.7401560.6875581.4485100.9404680.5299851.349567-0.0274690.6933622.406176-0.249697-0.5601492.5573980.4066440.8297112.6726270.4592000.3158721.5999620.7828011.3315270.6166350.2181841.2662371.279428-0.2196260.276051-0.7347781.2716611.0991120.6369100.4117731.0259420.4276982.105587-0.208016-0.3397013.075185-0.489410-0.1509531.4190601.4134051.7175771.2617250.7572290.4987320.3018712.3845800.7135751.5000702.9511030.7216331.0367861.445853-0.4103511.4500011.515480-0.154084-0.3801730.5041670.586721-0.7193170.9704390.2339601.0998820.286976-1.2261181.7257141.9169760.436110-0.5221800.9857210.7532790.8346711.119114-1.074980-0.0027551.5235461.8215170.8512580.9546300.2955072.7303161.2289272.0927410.6464280.9693410.7998280.5186902.7114262.435387-0.1675201.0408431.3620181.5725922.1044600.5743281.7556891.0102811.224586-0.1347080.0484790.8728701.0289443.1040772.5675140.3757700.599356-0.1370620.096841-0.0972780.928691-0.3193390.4399071.1649550.3684140.132930-0.0025632.2073482.7119870.3754110.787854-0.1935641.6575861.2000802.0912600.5109782.3682201.8916251.8375661.5141450.9499501.743953-0.7240501.0899021.3227400.6228510.9997792.0501140.8313011.7978761.552524-0.1530932.641552-0.4389783.027740-0.3653171.0721491.6131522.4891661.221297-0.5308921.8018880.5755332.1188552.5695482.427732-0.3718380.7335821.7792150.8971860.4135351.2402530.0019441.1911700.0471972.4709971.7189050.8334401.764611-0.1894430.4651430.978402-0.105192-0.0559462.0213562.7096561.0295621.1238421.2894300.6985081.4144351.9498581.521849-0.9692631.5028100.6455780.553010-0.1169780.2117342.055752-0.3045411.5397351.3469911.874193-0.5751790.8400160.3566670.2846292.6994592.2828370.5474421.3938001.4257410.8699530.6062670.3589401.1719640.1598511.8649980.7951390.8929270.7578930.0975171.7978710.7109041.6769780.6568161.4872101.765665-1.200564-1.5960621.475675-0.594886-0.1100770.001594-1.27580752.552807-0.1492991.1885311.988964-0.5861360.5276190.8111541.2111272.6117221.5667300.3588232.5387741.3096640.5511512.7691011.268200-0.4622252.8508102.7007701.3533911.3364892.0571052.198679-1.5946540.2852551.8043462.1916550.872635-0.0749752.4482690.721646-0.0368191.2014511.5017562.613335-0.8977112.2990831.5531840.7996381.5456701.2622871.2190701.9323532.7430520.8752961.9540321.7120510.4206630.2381812.6615023.5476920.9610880.643591-0.8625693.6519990.8637701.1037491.1154321.2586702.4877432.4543431.7043082.4663511.353622-0.0855231.363210-0.8132770.8020891.4328750.4594341.2956313.079844-0.8424330.4888340.4190652.0627361.0180551.022798-0.6797911.8124230.374111-0.2502711.6151350.878605-0.2808951.3246101.6705691.1491611.3270640.6470380.0944722.6761851.6809960.2962821.1020802.1950560.7220410.9478351.3536840.591689-0.8104300.0966922.0540450.0191231.3520791.6659822.0655020.7715661.364484-0.5148470.9247390.7029420.2725860.7541250.8720510.630689-1.6230043.1158511.6855620.8425562.3812881.0684271.3125361.4542530.2115280.934160-0.4184800.8602470.4446450.4980821.6931190.754640-0.2694320.7376763.3375980.2182831.080100-0.3394111.4134511.2044521.4784531.0295810.8175581.0174673.054290-1.5318831.4238150.0443160.866326-0.0774032.2499031.5711491.2970481.8718650.8362891.6895232.9845900.8817181.955130-0.1805532.4704740.9784421.7108610.188165-1.251213-0.1261000.6921330.0381151.6708261.0633830.3432040.7116370.7802071.2002480.1545003.6429230.6662550.8544921.8933692.2885551.3311980.9246320.9388522.8560570.2469590.6597740.4490040.3959633.1225901.0203060.1337400.6441120.0456582.5914641.0005870.535968-0.5237111.1548700.1593511.0106860.4562601.6754550.0266581.8183480.8839830.3091422.0389551.9812721.6166210.2125131.0208571.5993400.6218050.9445312.9834881.0778881.4045840.1509900.9219100.4726880.7573122.1069500.9644700.0400850.3710491.2685151.4883611.5868390.8246070.5665741.043672-1.368893-0.592721-1.4416710.7372660.1773820.9577320.6087301.2305801.3285641.8380490.0921180.958254-0.9943361.1081640.4107140.015020-0.0361773.0396860.341243100.3920161.8664530.258531-0.4705611.7084740.8714880.8393602.0771700.3866030.2882361.0654390.5785290.6587832.312037-0.8229321.2153760.3292871.2597171.4695491.4922331.512171-0.1420200.8851062.2659750.0707701.1909152.0015560.902579-1.119597-1.1969222.1222683.0118421.3020110.5103380.486451-0.0739213.2035150.7011722.3460981.6268200.934189-0.8438651.1099733.0065610.2421492.015998-0.5924931.2923672.3370320.7567460.7689760.6610711.3186162.3970390.1201871.1118201.4315682.6137850.7026152.6389621.1340971.172037-0.3650170.5787341.880640-0.4725671.7577100.3633950.9841620.6121851.8896632.1341572.7316300.294480-0.2858100.3617901.7007851.8811410.346796-0.3199660.1812871.1627021.6697600.4259201.7436871.6167131.9718670.2880960.2643070.0365361.4591381.6562381.751503-0.8721840.4437201.2721641.9315461.3275321.7408140.198095-0.582208-0.6201901.046562-0.6798292.3958920.1550291.8140070.9502581.5342470.1929911.8416410.4418270.3708432.1776670.1549190.7185612.719957-0.077500-0.3782820.7048562.6288560.6225621.0267580.077762-0.4167571.8635280.795594-1.1098400.4739161.052376-0.7441941.0552191.4334730.9499410.3494881.897314-0.3712611.2529580.5119881.637370-0.889504-0.7218510.5097561.8762310.5013931.6836031.3677242.0722991.0365801.1602242.3054872.282103-0.3244251.2205221.1645572.6594670.0271510.2510951.7648091.0066201.1917001.029017-0.889223-0.5861751.7582501.2380231.0878330.2496731.4801030.2412870.6503591.0271350.3926351.0474791.2265370.7714750.3606741.969798-0.088442-1.1789201.0537770.7806620.3936331.6947050.830573-1.530858-1.0969861.0236901.2826840.2078470.6350450.5827150.6747941.3153591.0219952.1081601.3429690.7561242.8415100.5417192.571396-0.4059071.0072652.8300121.6478541.5065932.6306593.2290050.6334401.0679110.7143381.2499710.5957120.0033980.1896010.2895860.1474413.7103621.0309510.0942690.907970-0.4114060.7207131.8588501.9894190.7804551.2889892.5663333.444560-0.2869182.1785050.6397022.8724200.5685262.4018422.2408452.069111-0.0900761.0514780.1094101.9995921.778719-0.2400270.2234910.0932621.4323270.5824030.9745760.2622991.650904151.4583421.567962-0.1106530.5657561.835327-0.9085231.4474740.4432991.295618-0.9895431.8795341.2990690.8709681.0381541.6854481.3478280.1658771.885075-0.0680981.0215282.5716611.8839560.8319050.2600792.3937631.0612170.9361570.0678982.2921183.4181411.344858-0.2546743.3889141.6686241.2327980.5364960.8140340.7641690.7643702.4915330.003828-0.4390310.3296821.5523351.002698-0.1353401.060521-1.120442-1.1922940.8883990.5213260.581075-0.7827763.0209941.6523780.1421102.8745862.5929463.295964-0.2101322.4580110.8393011.2010931.3861771.3818300.348081-0.4876612.5167180.7708811.1639202.4965290.4007500.2398310.9297430.8557371.1930980.9963341.764705-0.0285510.5754031.7629211.5151203.577900-0.0635491.1837120.6997730.1468312.1204381.1203122.2025880.5900911.4341981.597371-0.6114020.5942501.385086-1.0196520.087703-0.3192151.0505713.5255291.578073-0.1266080.8249730.9105141.5019651.3577870.123323-0.5200621.5448111.8925590.3785070.9212410.8424191.1898731.8191020.3263452.181818-0.511219-0.4378482.7074140.3890230.3083720.4508731.7066010.1071552.2091361.5397850.5255101.3818650.7889970.6421631.9601062.9298750.882717-0.0439273.3048651.7401410.7188292.0973781.8750880.1805101.6297981.6380990.8723711.5726911.3412063.105784-0.770872-0.5677172.0406990.6104323.4786810.1482551.175091-0.2411381.6143584.1256351.6543703.0953452.0477110.339269-0.9789952.5102551.5719100.766056-0.3838601.7394482.4089723.1183331.580307-0.1070420.8362341.5067430.9714110.4943720.9986870.2386180.5121851.2211240.984714-0.5690140.6319154.1096350.3767931.9777181.1533070.0183750.6398992.4951671.1817090.2324510.6591421.3724091.3059222.4395551.2860173.1038830.3463701.7783530.3171691.0469100.2559001.3107400.7175102.587269-0.0138022.3736541.6579781.5557340.5696901.0933200.7100550.4134621.1237680.3456831.9377871.8392410.3326691.3419140.0023600.1064413.364698-0.8614240.3640290.3076950.814741-0.8974211.5807171.0269151.7165081.615566-0.090433-0.5082892.1333792.0229340.6786470.4615410.9161770.6025280.6807091.9485340.4603020.7036640.9280332.3990511.7188060.1363290.9532810.249165200.3648450.318980-0.5015860.6310750.6470011.1273841.5175311.7478370.1906220.3673140.5533450.3130801.2093101.4803081.1385170.2099000.6141501.5576661.3433471.0673440.3841950.0893973.1710430.9494452.5523521.7961560.454831-0.8707030.437635-0.7835951.0706340.5254631.252306-0.1109250.9101960.1634510.5855931.8533091.6142270.761433-0.0552881.4334352.7641192.1976460.0511320.531348-0.2601912.5802850.4443071.6498151.8379682.8300091.269306-0.8487560.2501950.7322671.6312700.9128570.9307510.8321771.6494991.6204351.1444082.160046-0.0543721.2647780.3253852.3208730.0400950.1925690.6717771.9170880.6832321.9228130.1070232.9350441.9198612.066228-0.941028-0.4080262.6725062.1357761.3443230.352906-0.027926-0.8707841.661100-0.8046332.1655361.6638581.1560781.4136142.2111160.8238791.9424381.6334360.8861201.4579970.3844391.3852861.2914950.7758412.0892702.0113882.124646-0.8708441.1757390.2234140.696135-0.2404020.4924280.645523-0.0460101.3936730.6543522.3131702.6083190.7807910.6515191.3013500.7747030.3375661.9117142.1908240.8903010.6416621.5703101.3916861.4101691.707859-0.1007972.5648501.5622430.2626370.4109771.4579471.0052720.8790200.6466452.5530441.0751311.9958230.8770532.0002190.5890131.1722561.8440842.1763471.5384641.4719651.0125641.0926330.5044130.0313491.2969830.9983202.0297063.0892540.809142-0.5846593.511215-0.239234-0.2236680.6647711.4599300.3594462.7625680.9143272.6361780.455892-0.0499991.254617-0.7501231.5513422.4128622.321717-1.1444522.0237221.8239230.365007-1.2183810.0324941.6047652.9296710.1763591.3120290.2149261.7400890.563660-0.3852220.9450480.2411610.3366430.7686081.3131501.4105881.9631782.214784-0.3010822.5970010.2632761.705918-0.0316392.0913471.4955702.3264801.8411501.0924092.0899413.0696231.9581880.5070980.1799800.014196-0.6052822.4879431.908157-1.4240031.3341261.4752201.2057201.2128302.9680233.071340-0.1554080.1378860.1785180.3320060.6318251.0201190.1767920.8345191.7208662.2959190.4722330.5366070.849208-0.1393410.0456131.0518370.8529520.6160222.2090251.2139230.8860201.9449450.8166072.7143231.0246001.454133251.2722781.3058230.6095871.4241651.2085131.4293862.3576970.8343880.9590942.836982-1.0803220.9618700.3344850.7943201.705880-1.6127910.9747060.8217340.935362-0.204956-2.8808981.9744701.4151602.7519671.4850110.8291061.7488701.6297931.8110533.1337761.2384592.798873-0.6046481.1187151.7622382.8364310.4410260.8166790.0109501.7750320.4066722.208619-0.588639-0.2366602.2738041.0616411.388053-0.8607710.2182920.6312632.1376770.8826791.7749451.1811070.0838901.3950830.8175080.2096922.2310650.7242541.0685521.9110621.2067040.303506-0.9544900.6366200.0216741.8773320.587610-1.1315222.403688-0.4794250.4558580.6081130.7312412.0344000.2836861.373861-0.3252182.2768332.0410671.1194440.9548911.3387290.7857920.2753181.0316821.6768151.4483061.3542272.7967620.3157060.1910590.3760841.0840442.3280160.5247480.8897041.3659870.297568-0.203936-0.0768530.0920531.956434-0.3450170.1393920.1327751.3233160.178800-1.1218922.1997860.5840661.2486721.4077342.1547171.6742820.0363681.6982001.1284450.7372111.2711320.759561-0.4621582.0220491.749334-0.0897602.2103992.7304250.0158241.4426020.8282231.9526950.9230771.7988640.1051321.306630-0.186454-0.5553320.8384662.8177271.0233612.0830200.9542121.2997501.6667521.032851-1.3340471.277205-0.7120973.1881391.6716661.1433551.3457841.9945341.7016671.6282180.9492050.8349120.8116020.907897-0.2441831.4873271.7059271.8893862.0075650.0124570.1025681.3704730.8218930.6021211.7674442.6782101.6585001.382663-0.098943-0.109420-0.3949062.1786200.4711981.6800762.2524041.670394-0.5397212.1887470.680183-0.2572091.4051211.4309172.2428780.2444431.3936330.0913482.4997580.6375090.378049-0.114230-0.8674801.0588390.3649520.7251681.4366730.5813531.0411540.1912370.9559531.2814330.0603172.9809102.4525381.2693541.287561-0.171541-0.1604661.2368780.2443210.3715361.608779-0.6700842.4561391.4052312.7321130.0639900.6162931.8289510.2336853.0357031.0444720.3471450.3201950.1271270.350406-0.0798430.8930761.5859863.2171381.8986443.5507841.1648581.1949460.1961120.6352461.1551450.7521430.3823161.7111631.1502630.7591730.1410131.7650421.672174301.0276940.772201-0.9200560.8144660.8511512.2420062.0295741.3960240.1137171.4292361.6919931.2426942.5240331.3039210.8879510.7031621.1485901.7650401.7791282.4702801.1734581.1066710.1816361.6716491.0873421.8764690.7335363.1534412.2493521.2420060.1672713.454219-0.2926591.3530560.9021731.4911210.4847152.0320580.695333-0.2397970.5649910.4277060.6522370.353043-0.0601291.4011980.1964660.6753511.7006001.7654900.4922270.9755051.7607472.3812411.384539-0.0743451.3001551.5132620.4576181.0786240.5150000.9135442.3157101.208128-0.4018510.1755311.2004170.8715831.4484282.2112081.5934361.647215-0.0819790.9544811.3113160.145772-1.5694581.1447420.7038650.6708322.1085491.322386-0.9559771.3712840.2962231.5566222.9570041.8410301.5625521.4423170.7349282.2222521.166502-0.2434291.3485791.6325793.0133821.7814633.1471520.091649-0.1870412.6170820.9573191.3679842.8091852.0200682.5897212.2381170.0234760.1122500.4226741.8029551.760488-0.585657-0.6914152.0547370.4980070.7053130.4986120.3679971.1059371.5808870.972431-1.467703-0.1261650.7308120.4170331.3126161.3946901.3157260.080757-1.2471560.7065213.0536831.5294051.4286600.4925501.5305791.3261880.4051041.4269220.9352010.6926592.0124731.3382691.7460891.1797730.0826271.2561081.0847890.615494-0.2972422.148495-2.277304-0.3639462.5646870.2071831.3454762.6682191.6787512.1642260.5532351.5981281.192059-1.1469260.1147730.505608-0.024987-0.8928350.6886110.8813331.8333550.0711552.5812530.2801241.6712382.1212932.1710971.1384322.0452120.6567110.1580830.3906530.8404860.3535410.7723090.5737621.3776501.1411580.9649060.1103560.2532351.6126043.0803202.4988650.806225-0.3566232.332053-0.2062110.5325882.155392-0.4819181.8206041.0730511.3134312.818929-0.2539672.5583851.9608920.0643090.8212920.7312331.3020251.615806-0.3008901.0181041.1642882.3330503.6039181.3970130.5223300.8965861.2300210.1322910.8755160.2387571.3244231.340493-0.1394990.6376470.3874220.9395122.092638-1.0460931.4190312.0996861.2186570.151767-0.656613-0.0246102.3352261.8506582.2950281.0502981.3495471.0872751.8187100.5251240.4312441.058626350.5108930.6431270.5629290.7564660.9062220.3840171.4146491.2020960.7024391.6816611.5383110.3859491.7690583.0632422.5247191.389534-0.4419411.8456720.554687-0.4922661.2117850.6328170.025948-0.341869-0.5496321.3135350.596445-0.0741800.9985882.0977131.872332-0.7551801.795485-1.0075312.1861341.6285610.9421582.8559021.0284840.8185661.6123990.2366760.6450380.7382241.8121261.4826150.1134880.9622430.4370471.8977061.383232-0.3248062.1392690.9445191.5337851.4907331.9728231.8069091.3175461.0514780.0278831.1598361.765861-0.7338630.7005072.908761-0.2121210.8777181.2260621.424852-0.3029611.2448671.6790172.660738-1.0312700.5646700.1201641.1288321.0553412.4720331.525388-0.1109560.8104341.8256403.4702421.3110870.4162811.5805091.8326130.4617691.2613261.4573320.790342-0.7331991.5765541.073786-0.6025571.547602-0.9683220.7804450.7506651.9983150.9421720.0150990.9655231.3805861.4745050.4444960.6070660.4387020.7480261.566106-0.0537680.6410681.6532920.9306332.1199342.8416471.3047810.1809681.8758940.8271942.2498400.0776930.8693102.3045471.6046920.7679561.1815851.4639230.7954832.4628241.506149-0.9868851.5610831.3431160.9661470.9384440.2887964.2205680.8798881.3429582.8102501.6107870.6264420.9977101.4767211.6181530.765184-1.1013050.512504-1.3027431.9348492.367166-0.1805750.709087-0.9392871.6287050.7774481.2231081.0516491.4991670.1887520.6006541.5149780.9130791.5601570.8464231.2275892.3023040.8568871.6146500.9579141.789137-0.8173630.4189421.3698050.5660872.2070472.456715-0.5426861.7780652.0058631.5131521.7741162.3002891.9135601.4568162.1523891.7415003.1620581.5179102.7897671.3750400.9240310.3219971.6005411.4934771.3938540.0935911.3191510.5008560.3396011.0774701.3875521.9763530.1587010.8540641.8548230.7144591.0538420.396418-0.1603750.187902-0.1958491.5625160.7631330.780326-0.6233220.3656041.3408773.8336830.9237300.0017540.5650980.1706991.8410791.2700512.6127061.5681963.6078410.8934263.0178290.1597420.9138360.2137311.5884880.6534020.465684-0.0890141.2917691.2538020.4193130.786949-0.6868110.1429270.1988382.3862270.4834340.809592402.446356-1.098420-0.1698590.581206-1.9445730.9014460.7192181.7398512.6271821.0301320.8543991.2275302.0488562.7739392.1168872.0812512.5094160.5013060.0868450.8730551.0796862.0203450.209890-0.1554470.6324952.2639141.8270490.4275312.2116782.7929882.3791253.0499171.9920110.0699650.750606-0.002895-1.5727070.9539202.3591821.0209710.7895272.5972611.9261910.8634572.168163-0.0062450.3832411.2189401.7178381.0133332.3480601.662176-0.050645-0.0348700.7567580.246634-0.454329-0.0229200.5230111.199096-0.0610831.8178402.5507952.2257682.5225411.1374871.4484781.952170-0.1150691.6514120.8078981.3376231.0475442.4715791.4769313.0102091.1358240.1718680.0246542.2497011.9775510.4441800.8326462.8106481.7462352.477640-0.4366501.9548723.1168541.3686001.4316701.8821430.973787-0.941880-0.1068250.3321651.2107120.4698050.7048090.8272781.6384542.8076222.0089001.6728221.7706582.5330021.5763210.180219-0.3020522.5994771.6768752.3240621.3108131.5044872.260332-0.2584682.1810682.2329530.9930721.3674491.6521861.2471312.5432642.3267891.6113160.3170980.0795891.9389841.2814482.1621630.9648990.1743850.6908400.7478431.7808441.3440652.2752472.3037632.8170051.4655890.013795-0.719758-1.2300790.560894-1.3972421.1245082.4939950.762942-0.4820141.4298890.2178141.3896660.519694-0.0519030.0122640.8179400.6205331.2732480.8614441.8819040.4851030.8822040.891094-0.142649-0.3491201.3168800.871155-0.3526441.1614581.7390641.165377-0.495080-0.7136393.0505991.7721673.2712430.0261641.4741690.3719791.5812381.2419880.8590760.3467452.7358561.4932231.6997610.5097851.2962811.5747740.4948401.7025480.4454151.728336-0.243858-0.1078220.573302-1.755651-0.148347-0.2346770.410550-0.3132480.5052861.6699890.8619061.0582060.2195021.3375420.8330801.1057661.0444860.6310540.9260490.2003311.124687-0.2897282.292333-0.2921472.3225682.593849-1.597720-1.1684340.4376301.6737512.223847-0.0526301.9850490.082005-0.0164551.352714-0.6089203.0116470.0362870.8259170.7006541.4492060.6140311.3572241.6099831.8248931.1015781.4180880.225700-0.8698661.8127371.6477671.4986892.1371330.9831601.5882311.124584450.9055991.9533801.8377393.563993-0.3079081.7818660.3558890.0754420.941566-0.239361-0.0632272.7883242.3764922.7866911.0795562.1930141.0784932.3704790.2991860.1276161.4876891.584534-0.7538731.6456512.551776-0.224763-0.2212691.6033331.1597971.9737760.042913-0.3940830.0294480.0516270.5039581.4152240.9682360.4100071.6803200.628430-0.3465700.0033901.835854-0.2033471.466395-0.090401-0.0219631.5716282.0524812.7847322.364528-0.8840160.7262320.7648671.1717920.0934081.8737990.5355230.9003920.0903652.7097461.853469-0.4985452.5791672.3627262.2862560.9447901.1533980.0570571.1031401.8991351.1638511.0225561.9859812.2418041.2465650.9696870.1980110.3934072.1519961.746980-0.2039381.987448-0.9068331.4313460.839038-0.1908290.8147020.2759450.0317692.0625611.0431920.7850981.1059381.3876930.9996821.3437930.0344581.0340860.6282420.1707711.9294971.1969610.7244961.0622481.249923-0.5244080.9096232.8462902.0416411.2627920.6399172.3989480.9377910.2417830.9142531.2093460.8505272.2065391.1206041.937266-0.332153-0.0012921.0660090.7592811.4003060.7292481.783116-0.1516782.271785-1.1527071.2612401.8199380.6872241.2810810.5711750.8084830.3014271.2861921.5763771.210853-1.026796-0.3712001.9399681.4904371.5697440.6385962.8085901.3283760.5075230.3095981.2971382.0377191.0266021.4482362.0249180.5304450.6766280.9133570.1375722.1559860.416356-0.4164611.799196-1.0638560.5423271.3157950.9860410.6239310.2846442.802760-0.5395262.1443821.1375980.2897340.520737-0.0009711.4479790.9613560.5335881.6683393.2431600.8029800.3322640.4093172.6884401.9153961.7505530.0852660.3960630.0211071.5596641.0551292.063743-0.9109792.1018290.7266290.7689390.2214650.121983-0.0028121.4865851.2612450.6850051.5062801.7878231.467778-0.4809241.2190481.7755721.1383772.5378530.8122802.1950941.0749163.3572660.9235961.3226660.7663740.3658860.6644510.636817-0.261115-0.5625120.781340-0.1231340.771261-0.036545-1.1915390.3268390.849196-0.2011961.0835512.8192170.443742-0.0137511.8049582.1388490.0867883.0474930.1052172.0591030.394143-0.0968321.2176433.1220472.121491-0.101166-0.2725711.843459

Or, you may wish to leave off the indices altogether:

toyplot.matrix((big_matrix, colormap), tshow=False, lshow=False, label="A matrix");
A matrix0.7733680.0761691.355839-0.2700630.8045280.5365811.9894152.3886472.0877141.4388010.0383982.2456101.5029260.3686010.2957480.7595171.5855991.352801-0.8155580.0898760.2514720.8918751.2747791.2373500.7401560.6875581.4485100.9404680.5299851.349567-0.0274690.6933622.406176-0.249697-0.5601492.5573980.4066440.8297112.6726270.4592000.3158721.5999620.7828011.3315270.6166350.2181841.2662371.279428-0.2196260.276051-0.7347781.2716611.0991120.6369100.4117731.0259420.4276982.105587-0.208016-0.3397013.075185-0.489410-0.1509531.4190601.4134051.7175771.2617250.7572290.4987320.3018712.3845800.7135751.5000702.9511030.7216331.0367861.445853-0.4103511.4500011.515480-0.154084-0.3801730.5041670.586721-0.7193170.9704390.2339601.0998820.286976-1.2261181.7257141.9169760.436110-0.5221800.9857210.7532790.8346711.119114-1.074980-0.0027551.5235461.8215170.8512580.9546300.2955072.7303161.2289272.0927410.6464280.9693410.7998280.5186902.7114262.435387-0.1675201.0408431.3620181.5725922.1044600.5743281.7556891.0102811.224586-0.1347080.0484790.8728701.0289443.1040772.5675140.3757700.599356-0.1370620.096841-0.0972780.928691-0.3193390.4399071.1649550.3684140.132930-0.0025632.2073482.7119870.3754110.787854-0.1935641.6575861.2000802.0912600.5109782.3682201.8916251.8375661.5141450.9499501.743953-0.7240501.0899021.3227400.6228510.9997792.0501140.8313011.7978761.552524-0.1530932.641552-0.4389783.027740-0.3653171.0721491.6131522.4891661.221297-0.5308921.8018880.5755332.1188552.5695482.427732-0.3718380.7335821.7792150.8971860.4135351.2402530.0019441.1911700.0471972.4709971.7189050.8334401.764611-0.1894430.4651430.978402-0.105192-0.0559462.0213562.7096561.0295621.1238421.2894300.6985081.4144351.9498581.521849-0.9692631.5028100.6455780.553010-0.1169780.2117342.055752-0.3045411.5397351.3469911.874193-0.5751790.8400160.3566670.2846292.6994592.2828370.5474421.3938001.4257410.8699530.6062670.3589401.1719640.1598511.8649980.7951390.8929270.7578930.0975171.7978710.7109041.6769780.6568161.4872101.765665-1.200564-1.5960621.475675-0.594886-0.1100770.001594-1.2758072.552807-0.1492991.1885311.988964-0.5861360.5276190.8111541.2111272.6117221.5667300.3588232.5387741.3096640.5511512.7691011.268200-0.4622252.8508102.7007701.3533911.3364892.0571052.198679-1.5946540.2852551.8043462.1916550.872635-0.0749752.4482690.721646-0.0368191.2014511.5017562.613335-0.8977112.2990831.5531840.7996381.5456701.2622871.2190701.9323532.7430520.8752961.9540321.7120510.4206630.2381812.6615023.5476920.9610880.643591-0.8625693.6519990.8637701.1037491.1154321.2586702.4877432.4543431.7043082.4663511.353622-0.0855231.363210-0.8132770.8020891.4328750.4594341.2956313.079844-0.8424330.4888340.4190652.0627361.0180551.022798-0.6797911.8124230.374111-0.2502711.6151350.878605-0.2808951.3246101.6705691.1491611.3270640.6470380.0944722.6761851.6809960.2962821.1020802.1950560.7220410.9478351.3536840.591689-0.8104300.0966922.0540450.0191231.3520791.6659822.0655020.7715661.364484-0.5148470.9247390.7029420.2725860.7541250.8720510.630689-1.6230043.1158511.6855620.8425562.3812881.0684271.3125361.4542530.2115280.934160-0.4184800.8602470.4446450.4980821.6931190.754640-0.2694320.7376763.3375980.2182831.080100-0.3394111.4134511.2044521.4784531.0295810.8175581.0174673.054290-1.5318831.4238150.0443160.866326-0.0774032.2499031.5711491.2970481.8718650.8362891.6895232.9845900.8817181.955130-0.1805532.4704740.9784421.7108610.188165-1.251213-0.1261000.6921330.0381151.6708261.0633830.3432040.7116370.7802071.2002480.1545003.6429230.6662550.8544921.8933692.2885551.3311980.9246320.9388522.8560570.2469590.6597740.4490040.3959633.1225901.0203060.1337400.6441120.0456582.5914641.0005870.535968-0.5237111.1548700.1593511.0106860.4562601.6754550.0266581.8183480.8839830.3091422.0389551.9812721.6166210.2125131.0208571.5993400.6218050.9445312.9834881.0778881.4045840.1509900.9219100.4726880.7573122.1069500.9644700.0400850.3710491.2685151.4883611.5868390.8246070.5665741.043672-1.368893-0.592721-1.4416710.7372660.1773820.9577320.6087301.2305801.3285641.8380490.0921180.958254-0.9943361.1081640.4107140.015020-0.0361773.0396860.3412430.3920161.8664530.258531-0.4705611.7084740.8714880.8393602.0771700.3866030.2882361.0654390.5785290.6587832.312037-0.8229321.2153760.3292871.2597171.4695491.4922331.512171-0.1420200.8851062.2659750.0707701.1909152.0015560.902579-1.119597-1.1969222.1222683.0118421.3020110.5103380.486451-0.0739213.2035150.7011722.3460981.6268200.934189-0.8438651.1099733.0065610.2421492.015998-0.5924931.2923672.3370320.7567460.7689760.6610711.3186162.3970390.1201871.1118201.4315682.6137850.7026152.6389621.1340971.172037-0.3650170.5787341.880640-0.4725671.7577100.3633950.9841620.6121851.8896632.1341572.7316300.294480-0.2858100.3617901.7007851.8811410.346796-0.3199660.1812871.1627021.6697600.4259201.7436871.6167131.9718670.2880960.2643070.0365361.4591381.6562381.751503-0.8721840.4437201.2721641.9315461.3275321.7408140.198095-0.582208-0.6201901.046562-0.6798292.3958920.1550291.8140070.9502581.5342470.1929911.8416410.4418270.3708432.1776670.1549190.7185612.719957-0.077500-0.3782820.7048562.6288560.6225621.0267580.077762-0.4167571.8635280.795594-1.1098400.4739161.052376-0.7441941.0552191.4334730.9499410.3494881.897314-0.3712611.2529580.5119881.637370-0.889504-0.7218510.5097561.8762310.5013931.6836031.3677242.0722991.0365801.1602242.3054872.282103-0.3244251.2205221.1645572.6594670.0271510.2510951.7648091.0066201.1917001.029017-0.889223-0.5861751.7582501.2380231.0878330.2496731.4801030.2412870.6503591.0271350.3926351.0474791.2265370.7714750.3606741.969798-0.088442-1.1789201.0537770.7806620.3936331.6947050.830573-1.530858-1.0969861.0236901.2826840.2078470.6350450.5827150.6747941.3153591.0219952.1081601.3429690.7561242.8415100.5417192.571396-0.4059071.0072652.8300121.6478541.5065932.6306593.2290050.6334401.0679110.7143381.2499710.5957120.0033980.1896010.2895860.1474413.7103621.0309510.0942690.907970-0.4114060.7207131.8588501.9894190.7804551.2889892.5663333.444560-0.2869182.1785050.6397022.8724200.5685262.4018422.2408452.069111-0.0900761.0514780.1094101.9995921.778719-0.2400270.2234910.0932621.4323270.5824030.9745760.2622991.6509041.4583421.567962-0.1106530.5657561.835327-0.9085231.4474740.4432991.295618-0.9895431.8795341.2990690.8709681.0381541.6854481.3478280.1658771.885075-0.0680981.0215282.5716611.8839560.8319050.2600792.3937631.0612170.9361570.0678982.2921183.4181411.344858-0.2546743.3889141.6686241.2327980.5364960.8140340.7641690.7643702.4915330.003828-0.4390310.3296821.5523351.002698-0.1353401.060521-1.120442-1.1922940.8883990.5213260.581075-0.7827763.0209941.6523780.1421102.8745862.5929463.295964-0.2101322.4580110.8393011.2010931.3861771.3818300.348081-0.4876612.5167180.7708811.1639202.4965290.4007500.2398310.9297430.8557371.1930980.9963341.764705-0.0285510.5754031.7629211.5151203.577900-0.0635491.1837120.6997730.1468312.1204381.1203122.2025880.5900911.4341981.597371-0.6114020.5942501.385086-1.0196520.087703-0.3192151.0505713.5255291.578073-0.1266080.8249730.9105141.5019651.3577870.123323-0.5200621.5448111.8925590.3785070.9212410.8424191.1898731.8191020.3263452.181818-0.511219-0.4378482.7074140.3890230.3083720.4508731.7066010.1071552.2091361.5397850.5255101.3818650.7889970.6421631.9601062.9298750.882717-0.0439273.3048651.7401410.7188292.0973781.8750880.1805101.6297981.6380990.8723711.5726911.3412063.105784-0.770872-0.5677172.0406990.6104323.4786810.1482551.175091-0.2411381.6143584.1256351.6543703.0953452.0477110.339269-0.9789952.5102551.5719100.766056-0.3838601.7394482.4089723.1183331.580307-0.1070420.8362341.5067430.9714110.4943720.9986870.2386180.5121851.2211240.984714-0.5690140.6319154.1096350.3767931.9777181.1533070.0183750.6398992.4951671.1817090.2324510.6591421.3724091.3059222.4395551.2860173.1038830.3463701.7783530.3171691.0469100.2559001.3107400.7175102.587269-0.0138022.3736541.6579781.5557340.5696901.0933200.7100550.4134621.1237680.3456831.9377871.8392410.3326691.3419140.0023600.1064413.364698-0.8614240.3640290.3076950.814741-0.8974211.5807171.0269151.7165081.615566-0.090433-0.5082892.1333792.0229340.6786470.4615410.9161770.6025280.6807091.9485340.4603020.7036640.9280332.3990511.7188060.1363290.9532810.2491650.3648450.318980-0.5015860.6310750.6470011.1273841.5175311.7478370.1906220.3673140.5533450.3130801.2093101.4803081.1385170.2099000.6141501.5576661.3433471.0673440.3841950.0893973.1710430.9494452.5523521.7961560.454831-0.8707030.437635-0.7835951.0706340.5254631.252306-0.1109250.9101960.1634510.5855931.8533091.6142270.761433-0.0552881.4334352.7641192.1976460.0511320.531348-0.2601912.5802850.4443071.6498151.8379682.8300091.269306-0.8487560.2501950.7322671.6312700.9128570.9307510.8321771.6494991.6204351.1444082.160046-0.0543721.2647780.3253852.3208730.0400950.1925690.6717771.9170880.6832321.9228130.1070232.9350441.9198612.066228-0.941028-0.4080262.6725062.1357761.3443230.352906-0.027926-0.8707841.661100-0.8046332.1655361.6638581.1560781.4136142.2111160.8238791.9424381.6334360.8861201.4579970.3844391.3852861.2914950.7758412.0892702.0113882.124646-0.8708441.1757390.2234140.696135-0.2404020.4924280.645523-0.0460101.3936730.6543522.3131702.6083190.7807910.6515191.3013500.7747030.3375661.9117142.1908240.8903010.6416621.5703101.3916861.4101691.707859-0.1007972.5648501.5622430.2626370.4109771.4579471.0052720.8790200.6466452.5530441.0751311.9958230.8770532.0002190.5890131.1722561.8440842.1763471.5384641.4719651.0125641.0926330.5044130.0313491.2969830.9983202.0297063.0892540.809142-0.5846593.511215-0.239234-0.2236680.6647711.4599300.3594462.7625680.9143272.6361780.455892-0.0499991.254617-0.7501231.5513422.4128622.321717-1.1444522.0237221.8239230.365007-1.2183810.0324941.6047652.9296710.1763591.3120290.2149261.7400890.563660-0.3852220.9450480.2411610.3366430.7686081.3131501.4105881.9631782.214784-0.3010822.5970010.2632761.705918-0.0316392.0913471.4955702.3264801.8411501.0924092.0899413.0696231.9581880.5070980.1799800.014196-0.6052822.4879431.908157-1.4240031.3341261.4752201.2057201.2128302.9680233.071340-0.1554080.1378860.1785180.3320060.6318251.0201190.1767920.8345191.7208662.2959190.4722330.5366070.849208-0.1393410.0456131.0518370.8529520.6160222.2090251.2139230.8860201.9449450.8166072.7143231.0246001.4541331.2722781.3058230.6095871.4241651.2085131.4293862.3576970.8343880.9590942.836982-1.0803220.9618700.3344850.7943201.705880-1.6127910.9747060.8217340.935362-0.204956-2.8808981.9744701.4151602.7519671.4850110.8291061.7488701.6297931.8110533.1337761.2384592.798873-0.6046481.1187151.7622382.8364310.4410260.8166790.0109501.7750320.4066722.208619-0.588639-0.2366602.2738041.0616411.388053-0.8607710.2182920.6312632.1376770.8826791.7749451.1811070.0838901.3950830.8175080.2096922.2310650.7242541.0685521.9110621.2067040.303506-0.9544900.6366200.0216741.8773320.587610-1.1315222.403688-0.4794250.4558580.6081130.7312412.0344000.2836861.373861-0.3252182.2768332.0410671.1194440.9548911.3387290.7857920.2753181.0316821.6768151.4483061.3542272.7967620.3157060.1910590.3760841.0840442.3280160.5247480.8897041.3659870.297568-0.203936-0.0768530.0920531.956434-0.3450170.1393920.1327751.3233160.178800-1.1218922.1997860.5840661.2486721.4077342.1547171.6742820.0363681.6982001.1284450.7372111.2711320.759561-0.4621582.0220491.749334-0.0897602.2103992.7304250.0158241.4426020.8282231.9526950.9230771.7988640.1051321.306630-0.186454-0.5553320.8384662.8177271.0233612.0830200.9542121.2997501.6667521.032851-1.3340471.277205-0.7120973.1881391.6716661.1433551.3457841.9945341.7016671.6282180.9492050.8349120.8116020.907897-0.2441831.4873271.7059271.8893862.0075650.0124570.1025681.3704730.8218930.6021211.7674442.6782101.6585001.382663-0.098943-0.109420-0.3949062.1786200.4711981.6800762.2524041.670394-0.5397212.1887470.680183-0.2572091.4051211.4309172.2428780.2444431.3936330.0913482.4997580.6375090.378049-0.114230-0.8674801.0588390.3649520.7251681.4366730.5813531.0411540.1912370.9559531.2814330.0603172.9809102.4525381.2693541.287561-0.171541-0.1604661.2368780.2443210.3715361.608779-0.6700842.4561391.4052312.7321130.0639900.6162931.8289510.2336853.0357031.0444720.3471450.3201950.1271270.350406-0.0798430.8930761.5859863.2171381.8986443.5507841.1648581.1949460.1961120.6352461.1551450.7521430.3823161.7111631.1502630.7591730.1410131.7650421.6721741.0276940.772201-0.9200560.8144660.8511512.2420062.0295741.3960240.1137171.4292361.6919931.2426942.5240331.3039210.8879510.7031621.1485901.7650401.7791282.4702801.1734581.1066710.1816361.6716491.0873421.8764690.7335363.1534412.2493521.2420060.1672713.454219-0.2926591.3530560.9021731.4911210.4847152.0320580.695333-0.2397970.5649910.4277060.6522370.353043-0.0601291.4011980.1964660.6753511.7006001.7654900.4922270.9755051.7607472.3812411.384539-0.0743451.3001551.5132620.4576181.0786240.5150000.9135442.3157101.208128-0.4018510.1755311.2004170.8715831.4484282.2112081.5934361.647215-0.0819790.9544811.3113160.145772-1.5694581.1447420.7038650.6708322.1085491.322386-0.9559771.3712840.2962231.5566222.9570041.8410301.5625521.4423170.7349282.2222521.166502-0.2434291.3485791.6325793.0133821.7814633.1471520.091649-0.1870412.6170820.9573191.3679842.8091852.0200682.5897212.2381170.0234760.1122500.4226741.8029551.760488-0.585657-0.6914152.0547370.4980070.7053130.4986120.3679971.1059371.5808870.972431-1.467703-0.1261650.7308120.4170331.3126161.3946901.3157260.080757-1.2471560.7065213.0536831.5294051.4286600.4925501.5305791.3261880.4051041.4269220.9352010.6926592.0124731.3382691.7460891.1797730.0826271.2561081.0847890.615494-0.2972422.148495-2.277304-0.3639462.5646870.2071831.3454762.6682191.6787512.1642260.5532351.5981281.192059-1.1469260.1147730.505608-0.024987-0.8928350.6886110.8813331.8333550.0711552.5812530.2801241.6712382.1212932.1710971.1384322.0452120.6567110.1580830.3906530.8404860.3535410.7723090.5737621.3776501.1411580.9649060.1103560.2532351.6126043.0803202.4988650.806225-0.3566232.332053-0.2062110.5325882.155392-0.4819181.8206041.0730511.3134312.818929-0.2539672.5583851.9608920.0643090.8212920.7312331.3020251.615806-0.3008901.0181041.1642882.3330503.6039181.3970130.5223300.8965861.2300210.1322910.8755160.2387571.3244231.340493-0.1394990.6376470.3874220.9395122.092638-1.0460931.4190312.0996861.2186570.151767-0.656613-0.0246102.3352261.8506582.2950281.0502981.3495471.0872751.8187100.5251240.4312441.0586260.5108930.6431270.5629290.7564660.9062220.3840171.4146491.2020960.7024391.6816611.5383110.3859491.7690583.0632422.5247191.389534-0.4419411.8456720.554687-0.4922661.2117850.6328170.025948-0.341869-0.5496321.3135350.596445-0.0741800.9985882.0977131.872332-0.7551801.795485-1.0075312.1861341.6285610.9421582.8559021.0284840.8185661.6123990.2366760.6450380.7382241.8121261.4826150.1134880.9622430.4370471.8977061.383232-0.3248062.1392690.9445191.5337851.4907331.9728231.8069091.3175461.0514780.0278831.1598361.765861-0.7338630.7005072.908761-0.2121210.8777181.2260621.424852-0.3029611.2448671.6790172.660738-1.0312700.5646700.1201641.1288321.0553412.4720331.525388-0.1109560.8104341.8256403.4702421.3110870.4162811.5805091.8326130.4617691.2613261.4573320.790342-0.7331991.5765541.073786-0.6025571.547602-0.9683220.7804450.7506651.9983150.9421720.0150990.9655231.3805861.4745050.4444960.6070660.4387020.7480261.566106-0.0537680.6410681.6532920.9306332.1199342.8416471.3047810.1809681.8758940.8271942.2498400.0776930.8693102.3045471.6046920.7679561.1815851.4639230.7954832.4628241.506149-0.9868851.5610831.3431160.9661470.9384440.2887964.2205680.8798881.3429582.8102501.6107870.6264420.9977101.4767211.6181530.765184-1.1013050.512504-1.3027431.9348492.367166-0.1805750.709087-0.9392871.6287050.7774481.2231081.0516491.4991670.1887520.6006541.5149780.9130791.5601570.8464231.2275892.3023040.8568871.6146500.9579141.789137-0.8173630.4189421.3698050.5660872.2070472.456715-0.5426861.7780652.0058631.5131521.7741162.3002891.9135601.4568162.1523891.7415003.1620581.5179102.7897671.3750400.9240310.3219971.6005411.4934771.3938540.0935911.3191510.5008560.3396011.0774701.3875521.9763530.1587010.8540641.8548230.7144591.0538420.396418-0.1603750.187902-0.1958491.5625160.7631330.780326-0.6233220.3656041.3408773.8336830.9237300.0017540.5650980.1706991.8410791.2700512.6127061.5681963.6078410.8934263.0178290.1597420.9138360.2137311.5884880.6534020.465684-0.0890141.2917691.2538020.4193130.786949-0.6868110.1429270.1988382.3862270.4834340.8095922.446356-1.098420-0.1698590.581206-1.9445730.9014460.7192181.7398512.6271821.0301320.8543991.2275302.0488562.7739392.1168872.0812512.5094160.5013060.0868450.8730551.0796862.0203450.209890-0.1554470.6324952.2639141.8270490.4275312.2116782.7929882.3791253.0499171.9920110.0699650.750606-0.002895-1.5727070.9539202.3591821.0209710.7895272.5972611.9261910.8634572.168163-0.0062450.3832411.2189401.7178381.0133332.3480601.662176-0.050645-0.0348700.7567580.246634-0.454329-0.0229200.5230111.199096-0.0610831.8178402.5507952.2257682.5225411.1374871.4484781.952170-0.1150691.6514120.8078981.3376231.0475442.4715791.4769313.0102091.1358240.1718680.0246542.2497011.9775510.4441800.8326462.8106481.7462352.477640-0.4366501.9548723.1168541.3686001.4316701.8821430.973787-0.941880-0.1068250.3321651.2107120.4698050.7048090.8272781.6384542.8076222.0089001.6728221.7706582.5330021.5763210.180219-0.3020522.5994771.6768752.3240621.3108131.5044872.260332-0.2584682.1810682.2329530.9930721.3674491.6521861.2471312.5432642.3267891.6113160.3170980.0795891.9389841.2814482.1621630.9648990.1743850.6908400.7478431.7808441.3440652.2752472.3037632.8170051.4655890.013795-0.719758-1.2300790.560894-1.3972421.1245082.4939950.762942-0.4820141.4298890.2178141.3896660.519694-0.0519030.0122640.8179400.6205331.2732480.8614441.8819040.4851030.8822040.891094-0.142649-0.3491201.3168800.871155-0.3526441.1614581.7390641.165377-0.495080-0.7136393.0505991.7721673.2712430.0261641.4741690.3719791.5812381.2419880.8590760.3467452.7358561.4932231.6997610.5097851.2962811.5747740.4948401.7025480.4454151.728336-0.243858-0.1078220.573302-1.755651-0.148347-0.2346770.410550-0.3132480.5052861.6699890.8619061.0582060.2195021.3375420.8330801.1057661.0444860.6310540.9260490.2003311.124687-0.2897282.292333-0.2921472.3225682.593849-1.597720-1.1684340.4376301.6737512.223847-0.0526301.9850490.082005-0.0164551.352714-0.6089203.0116470.0362870.8259170.7006541.4492060.6140311.3572241.6099831.8248931.1015781.4180880.225700-0.8698661.8127371.6477671.4986892.1371330.9831601.5882311.1245840.9055991.9533801.8377393.563993-0.3079081.7818660.3558890.0754420.941566-0.239361-0.0632272.7883242.3764922.7866911.0795562.1930141.0784932.3704790.2991860.1276161.4876891.584534-0.7538731.6456512.551776-0.224763-0.2212691.6033331.1597971.9737760.042913-0.3940830.0294480.0516270.5039581.4152240.9682360.4100071.6803200.628430-0.3465700.0033901.835854-0.2033471.466395-0.090401-0.0219631.5716282.0524812.7847322.364528-0.8840160.7262320.7648671.1717920.0934081.8737990.5355230.9003920.0903652.7097461.853469-0.4985452.5791672.3627262.2862560.9447901.1533980.0570571.1031401.8991351.1638511.0225561.9859812.2418041.2465650.9696870.1980110.3934072.1519961.746980-0.2039381.987448-0.9068331.4313460.839038-0.1908290.8147020.2759450.0317692.0625611.0431920.7850981.1059381.3876930.9996821.3437930.0344581.0340860.6282420.1707711.9294971.1969610.7244961.0622481.249923-0.5244080.9096232.8462902.0416411.2627920.6399172.3989480.9377910.2417830.9142531.2093460.8505272.2065391.1206041.937266-0.332153-0.0012921.0660090.7592811.4003060.7292481.783116-0.1516782.271785-1.1527071.2612401.8199380.6872241.2810810.5711750.8084830.3014271.2861921.5763771.210853-1.026796-0.3712001.9399681.4904371.5697440.6385962.8085901.3283760.5075230.3095981.2971382.0377191.0266021.4482362.0249180.5304450.6766280.9133570.1375722.1559860.416356-0.4164611.799196-1.0638560.5423271.3157950.9860410.6239310.2846442.802760-0.5395262.1443821.1375980.2897340.520737-0.0009711.4479790.9613560.5335881.6683393.2431600.8029800.3322640.4093172.6884401.9153961.7505530.0852660.3960630.0211071.5596641.0551292.063743-0.9109792.1018290.7266290.7689390.2214650.121983-0.0028121.4865851.2612450.6850051.5062801.7878231.467778-0.4809241.2190481.7755721.1383772.5378530.8122802.1950941.0749163.3572660.9235961.3226660.7663740.3658860.6644510.636817-0.261115-0.5625120.781340-0.1231340.771261-0.036545-1.1915390.3268390.849196-0.2011961.0835512.8192170.443742-0.0137511.8049582.1388490.0867883.0474930.1052172.0591030.394143-0.0968321.2176433.1220472.121491-0.101166-0.2725711.843459

As you might expect, you can enable and disable the indices along all four sides of the matrix:

toyplot.matrix((matrix, colormap), rshow=True, bshow=True, label="A matrix");
A matrix01234567891011121314151617181901.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.546906010.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.390961121.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.545659230.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.039513341.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.488119451.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.394844560.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.210384671.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.334198781.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.42298689-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.0515399100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.68897210110.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.66848811120.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.21156012132.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.72440613140.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.68070214151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.02277415161.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.43443716171.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.27033817182.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.31811918192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.93217819012345678910111213141516171819

The indices along each side of the matrix are generated by Tick Locators, and you can provide your own custom locators if needed:

tlocator = toyplot.locator.Explicit([5, 10, 15])
llocator = toyplot.locator.Explicit([1, 5, 13], ["One", "Five", "Evil"])
toyplot.matrix((matrix, colormap), tlocator=tlocator, llocator=llocator, label="A matrix");
A matrix510151.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.546906One0.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.3909611.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.5456590.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.0395131.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.488119Five1.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.3948440.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.2103841.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.3341981.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.422986-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.0515390.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.6889720.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.6684880.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.211560Evil2.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.7244060.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.6807021.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.0227741.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.4344371.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.2703382.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.3181192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.932178

Note that the matrix visualization in Toyplot is actually just a factory function that creates and populates a set of Table Coordinates, so you can use the full toyplot.coordinates.Table API to configure it however you like. For example, you could highlight the maximum value in the matrix using a contrasting color:

i, j = numpy.unravel_index(numpy.argmax(matrix), matrix.shape)

canvas, table = toyplot.matrix((matrix, colormap), label="A matrix")
table.body.cell[i, j].style = {"fill":"yellow"}
A matrix01234567891011121314151617181901.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.54690610.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.39096121.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.54565930.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.03951341.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.48811951.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.39484460.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.21038471.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.33419881.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.4229869-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.051539100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.688972110.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.668488120.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.211560132.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.724406140.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.680702151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.022774161.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.434437171.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.270338182.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.318119192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.932178

Or you could use the table API to overwrite or replace the default labels:

x = numpy.arange(-5, 5, 0.2)
y = numpy.arange(-5, 5, 0.2)
xx, yy = numpy.meshgrid(x, y, sparse=True)
z = xx ** 2 - yy ** 2

canvas, table = toyplot.matrix(z, step=5, width=400)
table.left.cell[25, 1].lstyle = {"fill":"red"}
table.top.cell[1, 25].lstyle = {"fill":"red"}
table.right.cell[25, 0].data = "Saddle"
table.bottom.cell[0, 25].data = "Saddle"
05101520253035404500.000000-1.960000-3.840000-5.640000-7.360000-9.000000-10.560000-12.040000-13.440000-14.760000-16.000000-17.160000-18.240000-19.240000-20.160000-21.000000-21.760000-22.440000-23.040000-23.560000-24.000000-24.360000-24.640000-24.840000-24.960000-25.000000-24.960000-24.840000-24.640000-24.360000-24.000000-23.560000-23.040000-22.440000-21.760000-21.000000-20.160000-19.240000-18.240000-17.160000-16.000000-14.760000-13.440000-12.040000-10.560000-9.000000-7.360000-5.640000-3.840000-1.9600001.9600000.000000-1.880000-3.680000-5.400000-7.040000-8.600000-10.080000-11.480000-12.800000-14.040000-15.200000-16.280000-17.280000-18.200000-19.040000-19.800000-20.480000-21.080000-21.600000-22.040000-22.400000-22.680000-22.880000-23.000000-23.040000-23.000000-22.880000-22.680000-22.400000-22.040000-21.600000-21.080000-20.480000-19.800000-19.040000-18.200000-17.280000-16.280000-15.200000-14.040000-12.800000-11.480000-10.080000-8.600000-7.040000-5.400000-3.680000-1.8800000.0000003.8400001.8800000.000000-1.800000-3.520000-5.160000-6.720000-8.200000-9.600000-10.920000-12.160000-13.320000-14.400000-15.400000-16.320000-17.160000-17.920000-18.600000-19.200000-19.720000-20.160000-20.520000-20.800000-21.000000-21.120000-21.160000-21.120000-21.000000-20.800000-20.520000-20.160000-19.720000-19.200000-18.600000-17.920000-17.160000-16.320000-15.400000-14.400000-13.320000-12.160000-10.920000-9.600000-8.200000-6.720000-5.160000-3.520000-1.8000000.0000001.8800005.6400003.6800001.8000000.000000-1.720000-3.360000-4.920000-6.400000-7.800000-9.120000-10.360000-11.520000-12.600000-13.600000-14.520000-15.360000-16.120000-16.800000-17.400000-17.920000-18.360000-18.720000-19.000000-19.200000-19.320000-19.360000-19.320000-19.200000-19.000000-18.720000-18.360000-17.920000-17.400000-16.800000-16.120000-15.360000-14.520000-13.600000-12.600000-11.520000-10.360000-9.120000-7.800000-6.400000-4.920000-3.360000-1.7200000.0000001.8000003.6800007.3600005.4000003.5200001.7200000.000000-1.640000-3.200000-4.680000-6.080000-7.400000-8.640000-9.800000-10.880000-11.880000-12.800000-13.640000-14.400000-15.080000-15.680000-16.200000-16.640000-17.000000-17.280000-17.480000-17.600000-17.640000-17.600000-17.480000-17.280000-17.000000-16.640000-16.200000-15.680000-15.080000-14.400000-13.640000-12.800000-11.880000-10.880000-9.800000-8.640000-7.400000-6.080000-4.680000-3.200000-1.6400000.0000001.7200003.5200005.40000059.0000007.0400005.1600003.3600001.6400000.000000-1.560000-3.040000-4.440000-5.760000-7.000000-8.160000-9.240000-10.240000-11.160000-12.000000-12.760000-13.440000-14.040000-14.560000-15.000000-15.360000-15.640000-15.840000-15.960000-16.000000-15.960000-15.840000-15.640000-15.360000-15.000000-14.560000-14.040000-13.440000-12.760000-12.000000-11.160000-10.240000-9.240000-8.160000-7.000000-5.760000-4.440000-3.040000-1.5600000.0000001.6400003.3600005.1600007.04000010.5600008.6000006.7200004.9200003.2000001.5600000.000000-1.480000-2.880000-4.200000-5.440000-6.600000-7.680000-8.680000-9.600000-10.440000-11.200000-11.880000-12.480000-13.000000-13.440000-13.800000-14.080000-14.280000-14.400000-14.440000-14.400000-14.280000-14.080000-13.800000-13.440000-13.000000-12.480000-11.880000-11.200000-10.440000-9.600000-8.680000-7.680000-6.600000-5.440000-4.200000-2.880000-1.4800000.0000001.5600003.2000004.9200006.7200008.60000012.04000010.0800008.2000006.4000004.6800003.0400001.4800000.000000-1.400000-2.720000-3.960000-5.120000-6.200000-7.200000-8.120000-8.960000-9.720000-10.400000-11.000000-11.520000-11.960000-12.320000-12.600000-12.800000-12.920000-12.960000-12.920000-12.800000-12.600000-12.320000-11.960000-11.520000-11.000000-10.400000-9.720000-8.960000-8.120000-7.200000-6.200000-5.120000-3.960000-2.720000-1.4000000.0000001.4800003.0400004.6800006.4000008.20000010.08000013.44000011.4800009.6000007.8000006.0800004.4400002.8800001.4000000.000000-1.320000-2.560000-3.720000-4.800000-5.800000-6.720000-7.560000-8.320000-9.000000-9.600000-10.120000-10.560000-10.920000-11.200000-11.400000-11.520000-11.560000-11.520000-11.400000-11.200000-10.920000-10.560000-10.120000-9.600000-9.000000-8.320000-7.560000-6.720000-5.800000-4.800000-3.720000-2.560000-1.3200000.0000001.4000002.8800004.4400006.0800007.8000009.60000011.48000014.76000012.80000010.9200009.1200007.4000005.7600004.2000002.7200001.3200000.000000-1.240000-2.400000-3.480000-4.480000-5.400000-6.240000-7.000000-7.680000-8.280000-8.800000-9.240000-9.600000-9.880000-10.080000-10.200000-10.240000-10.200000-10.080000-9.880000-9.600000-9.240000-8.800000-8.280000-7.680000-7.000000-6.240000-5.400000-4.480000-3.480000-2.400000-1.2400000.0000001.3200002.7200004.2000005.7600007.4000009.12000010.92000012.8000001016.00000014.04000012.16000010.3600008.6400007.0000005.4400003.9600002.5600001.2400000.000000-1.160000-2.240000-3.240000-4.160000-5.000000-5.760000-6.440000-7.040000-7.560000-8.000000-8.360000-8.640000-8.840000-8.960000-9.000000-8.960000-8.840000-8.640000-8.360000-8.000000-7.560000-7.040000-6.440000-5.760000-5.000000-4.160000-3.240000-2.240000-1.1600000.0000001.2400002.5600003.9600005.4400007.0000008.64000010.36000012.16000014.04000017.16000015.20000013.32000011.5200009.8000008.1600006.6000005.1200003.7200002.4000001.1600000.000000-1.080000-2.080000-3.000000-3.840000-4.600000-5.280000-5.880000-6.400000-6.840000-7.200000-7.480000-7.680000-7.800000-7.840000-7.800000-7.680000-7.480000-7.200000-6.840000-6.400000-5.880000-5.280000-4.600000-3.840000-3.000000-2.080000-1.0800000.0000001.1600002.4000003.7200005.1200006.6000008.1600009.80000011.52000013.32000015.20000018.24000016.28000014.40000012.60000010.8800009.2400007.6800006.2000004.8000003.4800002.2400001.0800000.000000-1.000000-1.920000-2.760000-3.520000-4.200000-4.800000-5.320000-5.760000-6.120000-6.400000-6.600000-6.720000-6.760000-6.720000-6.600000-6.400000-6.120000-5.760000-5.320000-4.800000-4.200000-3.520000-2.760000-1.920000-1.0000000.0000001.0800002.2400003.4800004.8000006.2000007.6800009.24000010.88000012.60000014.40000016.28000019.24000017.28000015.40000013.60000011.88000010.2400008.6800007.2000005.8000004.4800003.2400002.0800001.0000000.000000-0.920000-1.760000-2.520000-3.200000-3.800000-4.320000-4.760000-5.120000-5.400000-5.600000-5.720000-5.760000-5.720000-5.600000-5.400000-5.120000-4.760000-4.320000-3.800000-3.200000-2.520000-1.760000-0.9200000.0000001.0000002.0800003.2400004.4800005.8000007.2000008.68000010.24000011.88000013.60000015.40000017.28000020.16000018.20000016.32000014.52000012.80000011.1600009.6000008.1200006.7200005.4000004.1600003.0000001.9200000.9200000.000000-0.840000-1.600000-2.280000-2.880000-3.400000-3.840000-4.200000-4.480000-4.680000-4.800000-4.840000-4.800000-4.680000-4.480000-4.200000-3.840000-3.400000-2.880000-2.280000-1.600000-0.8400000.0000000.9200001.9200003.0000004.1600005.4000006.7200008.1200009.60000011.16000012.80000014.52000016.32000018.2000001521.00000019.04000017.16000015.36000013.64000012.00000010.4400008.9600007.5600006.2400005.0000003.8400002.7600001.7600000.8400000.000000-0.760000-1.440000-2.040000-2.560000-3.000000-3.360000-3.640000-3.840000-3.960000-4.000000-3.960000-3.840000-3.640000-3.360000-3.000000-2.560000-2.040000-1.440000-0.7600000.0000000.8400001.7600002.7600003.8400005.0000006.2400007.5600008.96000010.44000012.00000013.64000015.36000017.16000019.04000021.76000019.80000017.92000016.12000014.40000012.76000011.2000009.7200008.3200007.0000005.7600004.6000003.5200002.5200001.6000000.7600000.000000-0.680000-1.280000-1.800000-2.240000-2.600000-2.880000-3.080000-3.200000-3.240000-3.200000-3.080000-2.880000-2.600000-2.240000-1.800000-1.280000-0.6800000.0000000.7600001.6000002.5200003.5200004.6000005.7600007.0000008.3200009.72000011.20000012.76000014.40000016.12000017.92000019.80000022.44000020.48000018.60000016.80000015.08000013.44000011.88000010.4000009.0000007.6800006.4400005.2800004.2000003.2000002.2800001.4400000.6800000.000000-0.600000-1.120000-1.560000-1.920000-2.200000-2.400000-2.520000-2.560000-2.520000-2.400000-2.200000-1.920000-1.560000-1.120000-0.6000000.0000000.6800001.4400002.2800003.2000004.2000005.2800006.4400007.6800009.00000010.40000011.88000013.44000015.08000016.80000018.60000020.48000023.04000021.08000019.20000017.40000015.68000014.04000012.48000011.0000009.6000008.2800007.0400005.8800004.8000003.8000002.8800002.0400001.2800000.6000000.000000-0.520000-0.960000-1.320000-1.600000-1.800000-1.920000-1.960000-1.920000-1.800000-1.600000-1.320000-0.960000-0.5200000.0000000.6000001.2800002.0400002.8800003.8000004.8000005.8800007.0400008.2800009.60000011.00000012.48000014.04000015.68000017.40000019.20000021.08000023.56000021.60000019.72000017.92000016.20000014.56000013.00000011.52000010.1200008.8000007.5600006.4000005.3200004.3200003.4000002.5600001.8000001.1200000.5200000.000000-0.440000-0.800000-1.080000-1.280000-1.400000-1.440000-1.400000-1.280000-1.080000-0.800000-0.4400000.0000000.5200001.1200001.8000002.5600003.4000004.3200005.3200006.4000007.5600008.80000010.12000011.52000013.00000014.56000016.20000017.92000019.72000021.6000002024.00000022.04000020.16000018.36000016.64000015.00000013.44000011.96000010.5600009.2400008.0000006.8400005.7600004.7600003.8400003.0000002.2400001.5600000.9600000.4400000.000000-0.360000-0.640000-0.840000-0.960000-1.000000-0.960000-0.840000-0.640000-0.3600000.0000000.4400000.9600001.5600002.2400003.0000003.8400004.7600005.7600006.8400008.0000009.24000010.56000011.96000013.44000015.00000016.64000018.36000020.16000022.04000024.36000022.40000020.52000018.72000017.00000015.36000013.80000012.32000010.9200009.6000008.3600007.2000006.1200005.1200004.2000003.3600002.6000001.9200001.3200000.8000000.3600000.000000-0.280000-0.480000-0.600000-0.640000-0.600000-0.480000-0.2800000.0000000.3600000.8000001.3200001.9200002.6000003.3600004.2000005.1200006.1200007.2000008.3600009.60000010.92000012.32000013.80000015.36000017.00000018.72000020.52000022.40000024.64000022.68000020.80000019.00000017.28000015.64000014.08000012.60000011.2000009.8800008.6400007.4800006.4000005.4000004.4800003.6400002.8800002.2000001.6000001.0800000.6400000.2800000.000000-0.200000-0.320000-0.360000-0.320000-0.2000000.0000000.2800000.6400001.0800001.6000002.2000002.8800003.6400004.4800005.4000006.4000007.4800008.6400009.88000011.20000012.60000014.08000015.64000017.28000019.00000020.80000022.68000024.84000022.88000021.00000019.20000017.48000015.84000014.28000012.80000011.40000010.0800008.8400007.6800006.6000005.6000004.6800003.8400003.0800002.4000001.8000001.2800000.8400000.4800000.2000000.000000-0.120000-0.160000-0.1200000.0000000.2000000.4800000.8400001.2800001.8000002.4000003.0800003.8400004.6800005.6000006.6000007.6800008.84000010.08000011.40000012.80000014.28000015.84000017.48000019.20000021.00000022.88000024.96000023.00000021.12000019.32000017.60000015.96000014.40000012.92000011.52000010.2000008.9600007.8000006.7200005.7200004.8000003.9600003.2000002.5200001.9200001.4000000.9600000.6000000.3200000.1200000.000000-0.0400000.0000000.1200000.3200000.6000000.9600001.4000001.9200002.5200003.2000003.9600004.8000005.7200006.7200007.8000008.96000010.20000011.52000012.92000014.40000015.96000017.60000019.32000021.12000023.0000002525.00000023.04000021.16000019.36000017.64000016.00000014.44000012.96000011.56000010.2400009.0000007.8400006.7600005.7600004.8400004.0000003.2400002.5600001.9600001.4400001.0000000.6400000.3600000.1600000.0400000.0000000.0400000.1600000.3600000.6400001.0000001.4400001.9600002.5600003.2400004.0000004.8400005.7600006.7600007.8400009.00000010.24000011.56000012.96000014.44000016.00000017.64000019.36000021.16000023.040000Saddle24.96000023.00000021.12000019.32000017.60000015.96000014.40000012.92000011.52000010.2000008.9600007.8000006.7200005.7200004.8000003.9600003.2000002.5200001.9200001.4000000.9600000.6000000.3200000.120000-0.000000-0.0400000.0000000.1200000.3200000.6000000.9600001.4000001.9200002.5200003.2000003.9600004.8000005.7200006.7200007.8000008.96000010.20000011.52000012.92000014.40000015.96000017.60000019.32000021.12000023.00000024.84000022.88000021.00000019.20000017.48000015.84000014.28000012.80000011.40000010.0800008.8400007.6800006.6000005.6000004.6800003.8400003.0800002.4000001.8000001.2800000.8400000.4800000.200000-0.000000-0.120000-0.160000-0.1200000.0000000.2000000.4800000.8400001.2800001.8000002.4000003.0800003.8400004.6800005.6000006.6000007.6800008.84000010.08000011.40000012.80000014.28000015.84000017.48000019.20000021.00000022.88000024.64000022.68000020.80000019.00000017.28000015.64000014.08000012.60000011.2000009.8800008.6400007.4800006.4000005.4000004.4800003.6400002.8800002.2000001.6000001.0800000.6400000.280000-0.000000-0.200000-0.320000-0.360000-0.320000-0.2000000.0000000.2800000.6400001.0800001.6000002.2000002.8800003.6400004.4800005.4000006.4000007.4800008.6400009.88000011.20000012.60000014.08000015.64000017.28000019.00000020.80000022.68000024.36000022.40000020.52000018.72000017.00000015.36000013.80000012.32000010.9200009.6000008.3600007.2000006.1200005.1200004.2000003.3600002.6000001.9200001.3200000.8000000.360000-0.000000-0.280000-0.480000-0.600000-0.640000-0.600000-0.480000-0.2800000.0000000.3600000.8000001.3200001.9200002.6000003.3600004.2000005.1200006.1200007.2000008.3600009.60000010.92000012.32000013.80000015.36000017.00000018.72000020.52000022.4000003024.00000022.04000020.16000018.36000016.64000015.00000013.44000011.96000010.5600009.2400008.0000006.8400005.7600004.7600003.8400003.0000002.2400001.5600000.9600000.440000-0.000000-0.360000-0.640000-0.840000-0.960000-1.000000-0.960000-0.840000-0.640000-0.3600000.0000000.4400000.9600001.5600002.2400003.0000003.8400004.7600005.7600006.8400008.0000009.24000010.56000011.96000013.44000015.00000016.64000018.36000020.16000022.04000023.56000021.60000019.72000017.92000016.20000014.56000013.00000011.52000010.1200008.8000007.5600006.4000005.3200004.3200003.4000002.5600001.8000001.1200000.520000-0.000000-0.440000-0.800000-1.080000-1.280000-1.400000-1.440000-1.400000-1.280000-1.080000-0.800000-0.4400000.0000000.5200001.1200001.8000002.5600003.4000004.3200005.3200006.4000007.5600008.80000010.12000011.52000013.00000014.56000016.20000017.92000019.72000021.60000023.04000021.08000019.20000017.40000015.68000014.04000012.48000011.0000009.6000008.2800007.0400005.8800004.8000003.8000002.8800002.0400001.2800000.600000-0.000000-0.520000-0.960000-1.320000-1.600000-1.800000-1.920000-1.960000-1.920000-1.800000-1.600000-1.320000-0.960000-0.5200000.0000000.6000001.2800002.0400002.8800003.8000004.8000005.8800007.0400008.2800009.60000011.00000012.48000014.04000015.68000017.40000019.20000021.08000022.44000020.48000018.60000016.80000015.08000013.44000011.88000010.4000009.0000007.6800006.4400005.2800004.2000003.2000002.2800001.4400000.680000-0.000000-0.600000-1.120000-1.560000-1.920000-2.200000-2.400000-2.520000-2.560000-2.520000-2.400000-2.200000-1.920000-1.560000-1.120000-0.6000000.0000000.6800001.4400002.2800003.2000004.2000005.2800006.4400007.6800009.00000010.40000011.88000013.44000015.08000016.80000018.60000020.48000021.76000019.80000017.92000016.12000014.40000012.76000011.2000009.7200008.3200007.0000005.7600004.6000003.5200002.5200001.6000000.760000-0.000000-0.680000-1.280000-1.800000-2.240000-2.600000-2.880000-3.080000-3.200000-3.240000-3.200000-3.080000-2.880000-2.600000-2.240000-1.800000-1.280000-0.6800000.0000000.7600001.6000002.5200003.5200004.6000005.7600007.0000008.3200009.72000011.20000012.76000014.40000016.12000017.92000019.8000003521.00000019.04000017.16000015.36000013.64000012.00000010.4400008.9600007.5600006.2400005.0000003.8400002.7600001.7600000.840000-0.000000-0.760000-1.440000-2.040000-2.560000-3.000000-3.360000-3.640000-3.840000-3.960000-4.000000-3.960000-3.840000-3.640000-3.360000-3.000000-2.560000-2.040000-1.440000-0.7600000.0000000.8400001.7600002.7600003.8400005.0000006.2400007.5600008.96000010.44000012.00000013.64000015.36000017.16000019.04000020.16000018.20000016.32000014.52000012.80000011.1600009.6000008.1200006.7200005.4000004.1600003.0000001.9200000.920000-0.000000-0.840000-1.600000-2.280000-2.880000-3.400000-3.840000-4.200000-4.480000-4.680000-4.800000-4.840000-4.800000-4.680000-4.480000-4.200000-3.840000-3.400000-2.880000-2.280000-1.600000-0.8400000.0000000.9200001.9200003.0000004.1600005.4000006.7200008.1200009.60000011.16000012.80000014.52000016.32000018.20000019.24000017.28000015.40000013.60000011.88000010.2400008.6800007.2000005.8000004.4800003.2400002.0800001.000000-0.000000-0.920000-1.760000-2.520000-3.200000-3.800000-4.320000-4.760000-5.120000-5.400000-5.600000-5.720000-5.760000-5.720000-5.600000-5.400000-5.120000-4.760000-4.320000-3.800000-3.200000-2.520000-1.760000-0.9200000.0000001.0000002.0800003.2400004.4800005.8000007.2000008.68000010.24000011.88000013.60000015.40000017.28000018.24000016.28000014.40000012.60000010.8800009.2400007.6800006.2000004.8000003.4800002.2400001.080000-0.000000-1.000000-1.920000-2.760000-3.520000-4.200000-4.800000-5.320000-5.760000-6.120000-6.400000-6.600000-6.720000-6.760000-6.720000-6.600000-6.400000-6.120000-5.760000-5.320000-4.800000-4.200000-3.520000-2.760000-1.920000-1.0000000.0000001.0800002.2400003.4800004.8000006.2000007.6800009.24000010.88000012.60000014.40000016.28000017.16000015.20000013.32000011.5200009.8000008.1600006.6000005.1200003.7200002.4000001.160000-0.000000-1.080000-2.080000-3.000000-3.840000-4.600000-5.280000-5.880000-6.400000-6.840000-7.200000-7.480000-7.680000-7.800000-7.840000-7.800000-7.680000-7.480000-7.200000-6.840000-6.400000-5.880000-5.280000-4.600000-3.840000-3.000000-2.080000-1.0800000.0000001.1600002.4000003.7200005.1200006.6000008.1600009.80000011.52000013.32000015.2000004016.00000014.04000012.16000010.3600008.6400007.0000005.4400003.9600002.5600001.240000-0.000000-1.160000-2.240000-3.240000-4.160000-5.000000-5.760000-6.440000-7.040000-7.560000-8.000000-8.360000-8.640000-8.840000-8.960000-9.000000-8.960000-8.840000-8.640000-8.360000-8.000000-7.560000-7.040000-6.440000-5.760000-5.000000-4.160000-3.240000-2.240000-1.1600000.0000001.2400002.5600003.9600005.4400007.0000008.64000010.36000012.16000014.04000014.76000012.80000010.9200009.1200007.4000005.7600004.2000002.7200001.320000-0.000000-1.240000-2.400000-3.480000-4.480000-5.400000-6.240000-7.000000-7.680000-8.280000-8.800000-9.240000-9.600000-9.880000-10.080000-10.200000-10.240000-10.200000-10.080000-9.880000-9.600000-9.240000-8.800000-8.280000-7.680000-7.000000-6.240000-5.400000-4.480000-3.480000-2.400000-1.2400000.0000001.3200002.7200004.2000005.7600007.4000009.12000010.92000012.80000013.44000011.4800009.6000007.8000006.0800004.4400002.8800001.400000-0.000000-1.320000-2.560000-3.720000-4.800000-5.800000-6.720000-7.560000-8.320000-9.000000-9.600000-10.120000-10.560000-10.920000-11.200000-11.400000-11.520000-11.560000-11.520000-11.400000-11.200000-10.920000-10.560000-10.120000-9.600000-9.000000-8.320000-7.560000-6.720000-5.800000-4.800000-3.720000-2.560000-1.3200000.0000001.4000002.8800004.4400006.0800007.8000009.60000011.48000012.04000010.0800008.2000006.4000004.6800003.0400001.480000-0.000000-1.400000-2.720000-3.960000-5.120000-6.200000-7.200000-8.120000-8.960000-9.720000-10.400000-11.000000-11.520000-11.960000-12.320000-12.600000-12.800000-12.920000-12.960000-12.920000-12.800000-12.600000-12.320000-11.960000-11.520000-11.000000-10.400000-9.720000-8.960000-8.120000-7.200000-6.200000-5.120000-3.960000-2.720000-1.4000000.0000001.4800003.0400004.6800006.4000008.20000010.08000010.5600008.6000006.7200004.9200003.2000001.560000-0.000000-1.480000-2.880000-4.200000-5.440000-6.600000-7.680000-8.680000-9.600000-10.440000-11.200000-11.880000-12.480000-13.000000-13.440000-13.800000-14.080000-14.280000-14.400000-14.440000-14.400000-14.280000-14.080000-13.800000-13.440000-13.000000-12.480000-11.880000-11.200000-10.440000-9.600000-8.680000-7.680000-6.600000-5.440000-4.200000-2.880000-1.4800000.0000001.5600003.2000004.9200006.7200008.600000459.0000007.0400005.1600003.3600001.640000-0.000000-1.560000-3.040000-4.440000-5.760000-7.000000-8.160000-9.240000-10.240000-11.160000-12.000000-12.760000-13.440000-14.040000-14.560000-15.000000-15.360000-15.640000-15.840000-15.960000-16.000000-15.960000-15.840000-15.640000-15.360000-15.000000-14.560000-14.040000-13.440000-12.760000-12.000000-11.160000-10.240000-9.240000-8.160000-7.000000-5.760000-4.440000-3.040000-1.5600000.0000001.6400003.3600005.1600007.0400007.3600005.4000003.5200001.720000-0.000000-1.640000-3.200000-4.680000-6.080000-7.400000-8.640000-9.800000-10.880000-11.880000-12.800000-13.640000-14.400000-15.080000-15.680000-16.200000-16.640000-17.000000-17.280000-17.480000-17.600000-17.640000-17.600000-17.480000-17.280000-17.000000-16.640000-16.200000-15.680000-15.080000-14.400000-13.640000-12.800000-11.880000-10.880000-9.800000-8.640000-7.400000-6.080000-4.680000-3.200000-1.6400000.0000001.7200003.5200005.4000005.6400003.6800001.800000-0.000000-1.720000-3.360000-4.920000-6.400000-7.800000-9.120000-10.360000-11.520000-12.600000-13.600000-14.520000-15.360000-16.120000-16.800000-17.400000-17.920000-18.360000-18.720000-19.000000-19.200000-19.320000-19.360000-19.320000-19.200000-19.000000-18.720000-18.360000-17.920000-17.400000-16.800000-16.120000-15.360000-14.520000-13.600000-12.600000-11.520000-10.360000-9.120000-7.800000-6.400000-4.920000-3.360000-1.7200000.0000001.8000003.6800003.8400001.880000-0.000000-1.800000-3.520000-5.160000-6.720000-8.200000-9.600000-10.920000-12.160000-13.320000-14.400000-15.400000-16.320000-17.160000-17.920000-18.600000-19.200000-19.720000-20.160000-20.520000-20.800000-21.000000-21.120000-21.160000-21.120000-21.000000-20.800000-20.520000-20.160000-19.720000-19.200000-18.600000-17.920000-17.160000-16.320000-15.400000-14.400000-13.320000-12.160000-10.920000-9.600000-8.200000-6.720000-5.160000-3.520000-1.8000000.0000001.8800001.960000-0.000000-1.880000-3.680000-5.400000-7.040000-8.600000-10.080000-11.480000-12.800000-14.040000-15.200000-16.280000-17.280000-18.200000-19.040000-19.800000-20.480000-21.080000-21.600000-22.040000-22.400000-22.680000-22.880000-23.000000-23.040000-23.000000-22.880000-22.680000-22.400000-22.040000-21.600000-21.080000-20.480000-19.800000-19.040000-18.200000-17.280000-16.280000-15.200000-14.040000-12.800000-11.480000-10.080000-8.600000-7.040000-5.400000-3.680000-1.8800000.000000Saddle

If you want to combine a matrix with additional plots on a canvas, you use the same Canvas Layout mechanisms as usual:

canvas = toyplot.Canvas(width=600, height=400)
table = canvas.matrix(matrix, label="Matrix", bounds=(50, -250, 50, -50), step=5)
axes = canvas.cartesian(bounds=(-200, -50, 50, -50), label="Distribution", xlabel="Count", ylabel="Value")
axes.bars(numpy.histogram(matrix, 20), along="y");
Matrix05101501.471435-0.1909762.4327070.6873480.2794111.8871631.8595880.3634761.015696-1.2426852.1500361.9919461.953324-1.0212550.6659231.0021181.4054531.2890922.321158-0.5469060.7973540.3440311.1934211.5534392.3181520.5306951.675554-0.8170270.8168912.0589690.6021601.3374382.0475792.0459381.8637170.8779081.1247130.6772051.8416753.3909611.0762000.4335541.036142-1.0749781.2477920.1028430.8632051.0182891.7554141.2152691.841009-0.445810-0.4019730.8990820.4517580.8553801.3540200.9644871.5657382.5456590.0257640.9296551.3079690.7915012.033801-1.4004543.030604-0.1426311.2118831.7047210.2145651.4620601.7042281.5235080.0737463.0078431.226963-0.1526591.6319791.0395131.464392-2.5635172.3211061.1526311.1645300.5699041.7673691.9849201.2708362.3919861.0798420.600035-0.0278510.4152821.8165940.9180530.6552341.528288-0.0689890.48811951.2912051.5665341.5035921.2852961.4842882.3634820.2188950.5319822.224574-0.2811081.875476-0.7107150.5492351.7491640.7960670.8178251.680656-0.8184991.0470721.3948440.7515680.3822930.3171161.436258-0.7030131.3937110.5206760.7009841.6941031.6786301.2395561.1512271.8161272.8935341.6396330.037971-1.0852662.930247-0.7353492.2103841.7974350.6201891.7025620.1496542.1768120.4756641.7009081.9841880.8782723.3657691.4961431.7965950.5259790.9433042.3577970.195166-1.1236200.6664980.1132811.3341981.5367840.2561700.6797960.0838010.1403321.2259851.6287761.1864941.9524781.9881380.9273920.4493970.061847-0.2390721.1396830.7769813.1236921.122273-0.4094322.422986-1.147855-0.3475331.3635650.9852482.272395-0.449567-0.1955240.4081370.585495-0.4257951.2093950.407114-0.4731160.1034192.1043520.5684500.8388631.8891571.288377-0.051539100.6804390.3800071.1569980.4285452.0576330.2085110.4753731.0718782.9107591.7879651.5130820.4535842.0439453.1077852.4599272.0154051.7491850.3244791.4402661.6889720.7233542.9245331.4112041.8907651.226363-1.0786180.6121140.9128932.1263861.2471121.1211721.2989840.8429010.259531-0.2476531.2494551.5810733.7638441.3993251.6684880.7242261.5004831.863065-0.051628-0.3920542.1539222.1819441.3913710.1189531.2950802.863801-0.712274-0.4070851.1267811.003760-0.2689940.1611571.5539210.4959570.2115602.5294011.2054551.3130131.8665211.2990712.0765411.3631772.8936800.5142471.3876741.0235580.3397700.6813150.2773381.1773871.9835131.0235051.5537771.3537690.7244060.5095160.625563-1.3975042.5410301.0630850.715559-0.2656012.7879800.6454910.8952391.3862541.8227750.3162102.0572031.0318802.3431820.9494600.635990-0.5533420.680702151.5270461.7111120.7824553.637791-0.7421380.9055652.4311841.5927581.170297-0.7517061.2885810.4574201.1716021.9828180.9746510.7124481.9244430.9387540.268967-0.0227741.9959931.9555581.7138411.1333710.1929620.6579892.9087801.1559231.7596530.5769941.1816731.2744931.0679120.9630170.8291991.2669732.3829970.9775391.1313951.4344371.2645341.5656581.5850840.825702-0.0713690.9515390.1547101.4151011.4255310.0192760.5721742.4985700.6398430.541760-0.3379680.9586131.8210483.0978012.2829331.2703382.0031402.0786741.3407530.8019253.4814582.385255-0.154601-0.2680691.607862-0.0800960.3887181.102035-0.4365741.2107170.103096-0.7243932.792339-0.3127131.5558770.3181192.5727430.8953482.8503980.6666501.1934640.5032552.032723-0.7398040.2441380.1188881.3938920.0499741.3325071.528944-0.1205211.0482641.061988-0.0275160.7616652.9321780204060Count-2024ValueDistribution
_images/toyplot.png

Numberline Coordinates

The toyplot.coordinates.Numberline class provides a single axis that maps one-dimensional data values to canvas coordinates. The numberline range (its coordinates on the Toyplot the canvas) is specified at creation time (see Canvas Layout), while the domain is implicitly defined to include all displayed data (but can be manually overridden by the caller if desired).

If your data is two-dimensional, you should use Cartesian Coordinates instead.

Typically, you create numberlines explicitly using toyplot.canvas.Canvas.numberline():

import numpy
numpy.random.seed(1234)
events = numpy.random.uniform(size=(25, 4))

import toyplot
canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.scatterplot(events.T[0]);
0.00.51.0

Note that when you add scatterplots to numberlines, they are one-dimensional scatterplots, so you only supply one set of coordinates.

When you add multiple marks to a numberline, they “stack up” on top of each other:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.scatterplot(events.T[0])
numberline.scatterplot(events.T[1]);
0.00.51.0

You can specify the default spacing between marks (and the axis spine) when you create the numberline:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline(spacing=10)
numberline.scatterplot(events.T[0])
numberline.scatterplot(events.T[1]);
0.00.51.0

And you can individually control the offset of the individual marks, as well as the padding (distance between the axis spine and the first mark):

canvas = toyplot.Canvas(width=600, height=200)
numberline = canvas.numberline(spacing=10, padding=20)
numberline.scatterplot(events.T[0])
numberline.scatterplot(events.T[1])
numberline.scatterplot(events.T[2], offset=40)
numberline.scatterplot(events.T[3], offset=50);
0.00.51.0

Of course, you have control over all the normal parameters of a scatterplot, such as color and marker type:

timestamps = numpy.random.uniform(size=40)
event_types = numpy.random.choice(2, size=timestamps.shape)

colormap = toyplot.color.CategoricalMap()

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.scatterplot(
    timestamps,
    color=(event_types, colormap),
    marker="|",
    size=15,
    mstyle={"stroke-width":1.5},
);
0.00.51.0

Along with scatterplots, numberlines can be used to show data ranges:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.range(2, 3);
2.02.53.0

You can place multiple ranges on the numberline:

start = [2, 5]
end = [3, 6.2]

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.range(start, end);
23456

Of course, you can control color and style for each range, and stack multiple ranges on one numberline:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline(min=-1, max=11)
numberline.range(start, end, color=["crimson", "blue"])
numberline.range(0, 10, color="white", style={"stroke":"black", "stroke-width":0.5});
0510

In addition to scatterplots and ranges, numberlines can be used to display any toyplot.color.Map:

colormap = toyplot.color.diverging.map("BlueRed", domain_min=0, domain_max=1)
canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.colormap(colormap, style={"stroke-width":1})
0.00.51.0

Keep in mind that to display most color maps on a numberline, you must specify their domain (otherwise, there would be no way to map the colors to coordinates on the axis). You can see above that we specified \([0, 1]\) as the domain.

toyplot.color.CategoricalMap is the one exception to this rule, since it has an implicit \([0, N)\) domain where \(N\) is the number of colors in the map:

colormap = toyplot.color.brewer.map("Set1")
canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.colormap(colormap)
0369

Note that, unlike a scatterplot, a color map has a width that can be varied:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.colormap(colormap, width=20)
0369

Also note that some colors may tend to blend-in with the canvas background:

colormap = toyplot.color.brewer.map("Greys", domain_min=0, domain_max=1)
canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.colormap(colormap)
0.00.51.0

To make the color map stand out from the background, you can use the style parameter to add a border:

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline()
numberline.colormap(colormap, style={"stroke":"lightgrey"})
0.00.51.0

Functions like toyplot.coordinates.Cartesian.color_scale(), toyplot.canvas.Canvas.color_scale(), and toyplot.canvas.Canvas.matrix() use numberlines to conveniently add color scales to visualizations, but by creating a numberline object of your own, you can create more complex scales. For example, you could define a multi-range scale, or add marks to highlight critical values:

colormap1 = toyplot.color.diverging.map("BlueRed", domain_min=-1, domain_max=1)
colormap2 = toyplot.color.diverging.map("PurpleGreen", domain_min=-0.5, domain_max=1.5)

canvas = toyplot.Canvas(width=600, height=100)
numberline = canvas.numberline(spacing=15, padding=10)
numberline.colormap(colormap1)
numberline.colormap(colormap2)
numberline.scatterplot([0], marker="d", color="black");
-1.0-0.50.00.51.01.5

Properties

Numberline objects contain sets of nested properties that can be used to adjust their behavior. The list of available properties includes the following:

  • numberline.show - set to False to hide the numberline completely (the plotted data will still be visible).
  • numberline.spacing - the space between each mark added to the numberline. Defaults to CSS pixels, supports all Units.
  • numberline.padding - the space between the axis spine and the first mark. Defaults to the same value as spacing. Uses CSS pixels as the default unit, supports all Units.
  • numberline.axis.show - set to False to hide the axis completely.
  • numberline.axis.scale - “linear”, “log” (base 10), “log10”, “log2”, or a (“log”, base) tuple. See Logarithmic Scales for details.
  • numberline.axis.domain.min - override the minimum domain value for the axis.
  • numberline.axis.domain.max - override the maximum domain value for the axis.
  • numberline.axis.label.location - “above” or “below”, to specify on which side of the axis the label will be placed.
  • numberline.axis.label.offset - offsets the label from the axis. Defaults to CSS pixels, supports all Units.
  • numberline.axis.label.text - optional label below the axis.
  • numberline.axis.label.style - styles the axis label.
  • numberline.axis.spine.show - set to False to hide the axis spine.
  • numberline.axis.spine.style - styles the axis spine.
  • numberline.axis.ticks.show - set to True to display axis tick marks.
  • numberline.axis.ticks.locator - assign an instance of toyplot.locator.TickLocator to control the positioning and formatting of ticks and tick labels. By default, an appropriate locator is automatically chosen based on the axis scale and domain. See Tick Locators for details.
  • numberline.axis.ticks.location - “above” or “below”, to specify on which side of the axis the ticks and labels are placed.
  • numberline.axis.ticks.near - length of axis ticks on the same side of the axis as the labels. Defaults to CSS pixels, supports all Units.
  • numberline.axis.ticks.far - length of axis ticks on the side of the axis opposite the labels. Defaults to CSS pixels, supports all Units.
  • numberline.axis.ticks.style - styles the axis ticks.
  • numberline.axis.ticks.labels.angle - angle of axis tick labels in degrees.
  • numberline.axis.ticks.labels.offset - offsets labels from the axis. Defaults to CSS pixels, supports all Units.
  • numberline.axis.ticks.labels.show - set to False to hide axis tick labels.
  • numberline.axis.ticks.labels.style - style axis tick label text.

As a convenience, some of the most common properties can also be set when the numberline is created.

Layout

Unlike cartesian or table coordinates that are defined over an area of the canvas, numberlines are defined by two endpoints in canvas coordinates. When you use Canvas Layout functions, you create numberlines that are horizontal and centered within the bounds of the area you define:

canvas = toyplot.Canvas(width=600, height=200, style={"background-color":"#f8f8f8"})

numberline = canvas.numberline(grid=(2, 1, 0))
numberline.scatterplot(numpy.linspace(0, 1))

numberline = canvas.numberline(grid=(2, 1, 1))
numberline.scatterplot(numpy.linspace(0, 1));
0.00.51.00.00.51.0

If you look carefully at the above plot, you will see that the data is centered within each cell in the \(2 \times 1\) grid defined by the layout.

However, you can also specify the endpoints of a numberline explicitly, which allows you to create numberlines in any orientation including diagonal:

canvas = toyplot.Canvas(width=600)

numberline = canvas.numberline(x1=-50, x2=50, y1=100, y2=100, label="Right to left")
numberline.scatterplot(numpy.linspace(0, 1), marker="|", size=15)

numberline = canvas.numberline(x1=50, x2=-50, y1=150, y2=150, label="Left to right")
numberline.scatterplot(numpy.linspace(0, 1), marker="|", size=15)

numberline = canvas.numberline(x1=100, x2=100, y1=250, y2=-50, label="Top to bottom")
numberline.scatterplot(numpy.linspace(0, 1), marker="|", size=15)

numberline = canvas.numberline(x1=150, x2=150, y1=-50, y2=250, label="Bottom to top")
numberline.scatterplot(numpy.linspace(0, 1), marker="|", size=15)

numberline = canvas.numberline(x1=250, x2=-50, y1=-50, y2=250, label="Diagonal")
numberline.scatterplot(numpy.linspace(0, 1), marker="|", size=15);
0.00.51.0Right to left0.00.51.0Left to right0.00.51.0Top to bottom0.00.51.0Bottom to top0.00.51.0Diagonal
_images/toyplot.png

Null Data

“Never tell a lie” is an integral part of The Toyplot Ethos - and Toyplot’s handling of null data is one of the ways that we honor it. Consider the following data, in which several datums contain floating-point NaN values:

import numpy
x = numpy.linspace(0, 2 * numpy.pi)
y = numpy.sin(x)
y[6:20] = numpy.nan

When we plot this data, Toyplot carefully takes the NaN values into account:

import toyplot.data
toyplot.plot(x, y, ymax=1, marker="o", width=600, height=300);
0246-1.0-0.50.00.51.0

Note that the Y axis domain reflects the lack of data where there are NaN values, and there are no markers for the NaN datams. Note too that the plot has been broken into two segments - drawing a segment through the NaN region might mislead viewers about the shape of the curve, while breaking the plot unambiguously communicates the absence of data.

Of course NaN values can only be used with floating-point arrays, so there must be alternate ways to represent null values for other data types such as integers. To address this, Toyplot uses masked arrays for all its internal data structures, and accepts masked arrays for its inputs, allowing you to define null values in your data explicitly:

numpy.random.seed(1234)
y = numpy.ma.array(numpy.random.choice(numpy.arange(3, 10), size=50))
y[5:15] = numpy.ma.masked
toyplot.bars(y, width=600, height=300);
010203040500369

You might feel that masking null values in the above example is needlessly complex, when a special value of “zero” could accomplish the same thing. But consider what happens if there is more than one series:

magnitudes = numpy.ma.column_stack((
        numpy.random.choice(numpy.arange(5, 10), size=50),
        numpy.random.choice(numpy.arange(5, 10), size=50),
    ))
magnitudes[5:15,0] = 0
toyplot.bars(magnitudes, width=600, height=300);
0102030405005101520

The position of the bars in the second series suggest that the null values in the first series actually have a value of zero, when in reality we want to communicate that they have no value at all. Contrast this with what Toyplot produces when you correctly mark the values as null instead of zero:

magnitudes[5:15,0] = numpy.ma.masked
toyplot.bars(magnitudes, width=600, height=300);
0102030405005101520

Toyplot now removes entire observations that contain null values. Note that this behavior is dictated by the structure of the visualization - because we use stacked bars to represent data where the sum of the magnitudes is significant, a null anywhere in that sum makes the entire sum null and void.

This is not the case for all visualizations, of course. Consider what happens when rendering a set of bar boundaries, rather than a set of bar magnitudes:

observations = numpy.random.normal(size=(50, 50))
boundaries = numpy.ma.column_stack((
    numpy.min(observations, axis=1),
    numpy.median(observations, axis=1),
    numpy.max(observations, axis=1),
    ))

toyplot.bars(boundaries, baseline=None, width=600, height=300);
01020304050-4-2024

Now, suppose that some of the lower boundaries in the plot are null:

boundaries[5:10, 0] = numpy.ma.masked
toyplot.bars(boundaries, baseline=None, width=600, height=300);
01020304050-4-2024

In this case, the position of each bar is defined by two boundaries. Only those bars with missing boundaries are left out - the adjacent bars are still visible because they are still unambigously well-defined. The same would be true if some of the top boundary values were null:

boundaries[40:45, 2] = numpy.ma.masked
toyplot.bars(boundaries, baseline=None, width=600, height=300);
01020304050-4-2024

Finally, as you might imagine, null values in the middle boundary affect both sets of adjacent bars:

boundaries[20:30, 1] = numpy.ma.masked
toyplot.bars(boundaries, baseline=None, width=600, height=300);
01020304050-4-2024

Of course, these behaviors extended to other plot types too:

toyplot.fill(magnitudes, baseline="stacked", width=600, height=300);
0102030405005101520
toyplot.fill(boundaries, width=600, height=300);
01020304050-4-2024

Finally, a special-case worth mentioning is Toyplot table visualizations, which can make an explicit distinction between null and NaN values:

data = toyplot.data.Table()
data["a"] = numpy.random.random(11)
data["b"] = numpy.random.random(11)
data["a", 3] = numpy.ma.masked
data["b", 7] = numpy.nan
toyplot.table(data, width=300, height=350);
ab0.8546990.7031960.6521440.2828640.3513560.2678430.2903310.5256420.2521360.6883570.5543380.003597240.243770.464203nan0.361970.4377270.7688920.6299870.648030.0805395

If you would rather not make this distinction, you can specify a table formatter object that will treat NaN and null values the same:

canvas, table = toyplot.table(data, width=300, height=350)
table.cells.column[1].format = toyplot.format.FloatFormatter(nanshow=False)
ab0.8546990.7031960.6521440.2828640.3513560.2678430.2903310.5256420.2521360.6883570.5543380.003597240.243770.4642030.361970.4377270.7688920.6299870.648030.0805395
_images/toyplot.png

Rendering

Of course, any plotting library needs a way to render figures for display, and Toyplot is no exception. To integrate Toyplot into your workflow as easily as possible, we provide three different rendering mechanisms:

Backends

At the lowest level, Toyplot provides a large collection of rendering backends. Each backend knows how to render a Toyplot canvas to a specific file format, and can typically render the canvas directly to disk, to a buffer you provide, or return the raw representation of the canvas for further processing. You choose a backend that provides the file format you want to generate, and use it to explicitly render your canvas. For example, you could use the toyplot.pdf backend to save a figure as a vector PDF image on disk:

import toyplot.pdf
toyplot.pdf.render(canvas, "figure1.pdf")

Similarly, you could substitute the toyplot.png backend to save a PNG bitmap image:

import toyplot.png
toyplot.png.render(canvas, "figure1.png")

You could do the same with the toyplot.svg backend, but suppose you wanted to add a custom CSS class to the SVG markup for inclusion in a publishing workflow. To accomodate this, the SVG backend can return a DOM for further editing, instead of saving it directly to disk:

import toyplot.svg
svg = toyplot.svg.render(canvas)
svg.attrib["class"] = "MyCustomClass"
import xml.etree.ElementTree as xml
with open("figure1.svg", "wb") as file:
    file.write(xml.tostring(svg))

Finally, there is Toyplot’s most important backend, toyplot.html which produces the preferred interactive HTML representation of a canvas. Like the other backends, you can use it to write directly to disk, or return a DOM object for editing as-needed:

import toyplot.html
toyplot.html.render(canvas, "figure1.html")

Note that the file produced by this backend is a completely self-contained HTML fragment that could be emailed directly to a colleague, inserted into a larger HTML document, etc.

Displays

While backends are useful when you wish to save a canvas to disk for incorporation into a paper or some larger workflow, in many cases you may find yourself simply wanting to display the results of some computation. Writing files to disk and opening them in a separate application can be time-consuming and frustrating, particularly when running a script repeatedly during development. For this case, Toyplot provides display modules, which provide convenient ways to display figures interactively. The most portable of these modules is toyplot.browser:

import toyplot.browser
toyplot.browser.show(canvas)

This will open a new browser window containing your figure, with all of Toyplot’s interaction and features intact.

Autorendering

For interactive environments such as Jupyter, Toyplot’s autorender feature automatically renders a canvas into a notebook cell using Toyplot’s preferred interactive HTML representation. We use autorendering with few exceptions throughout this documentation … for example, executing the following automatically inserts a figure into a Jupyter notebook:

import numpy
x = numpy.linspace(0, 1)
y = x ** 2

import toyplot
canvas = toyplot.Canvas(width=300)
canvas.cartesian().plot(x, y);
0.00.51.00.00.51.0

Note that no special import statements, magics, backends, or configuration is required - Toyplot Just Works. In this case, autorendering is enabled by default when you create a new canvas. Toyplot knows that it’s being run in the Jupyter notebook environment, and when you execute a notebook cell that contains a canvas with autorendering enabled, it inserts the rendered canvas in the cell output. Note that this is not the same as Jupyter’s rich output system - a Toyplot canvas doesn’t have to be the result of an expression to be rendered, and you can create multiple Toyplot canvases in a single notebook cell (handy when producing multiple figures in a loop), and they will all be rendered.

Autorendering for a canvas is automatically disabled if you pass it to a rendering backend or a display. So while the above example automatically rendered the canvas into a notebook cell, the following will not:

canvas = toyplot.Canvas(width=300)
canvas.axes().plot(x, y)
toyplot.pdf.render(canvas, "figure2.pdf")

In some circumstances you may want to disable autorendering yourself, which you can do when the canvas is created:

canvas = toyplot.Canvas(width=300, autorender=False)
canvas.cartesian().plot(x, y);
_images/toyplot.png

Table Coordinates

Data tables, with rows containing observations and columns containing (depending on your field) features, dimensions, variables, or series, are arguably the cornerstone of science. Much of the functionality of Toyplot or any other plotting package can be reduced to a process of mapping data series from tables to properties like coordinates and colors. Nevertheless, much tabular information is still best understood in its “native” tabular form, and we believe that even a humble table benefits from good layout and design - which is why Toyplot supports rendering tables as data graphics, treating them as first-class objects instead of specialized markup. This means that you can combine high-quality tables and plots in innovative ways, and save them using any of the formats supported by Toyplot, including HTML, SVG, PDF, and PNG.

To accomplish this, Toyplot provides toyplot.coordinates.Table, which is a specialized coordinate system. Just like Cartesian Coordinates, and Numberline Coordinates, tables map domain coordinates to canvas coordinates. Unlike more traditional coordinate systems, tables map integer coordinates that increase from left-to-right and top-to-bottom to rectangular regions of the canvas called cells.

Be careful not to confuse the table coordinates described in this section with Data Tables, which are purely a data storage mechanism. To make this distinction clear, let’s start by loading some sample data into a data table:

import numpy
import toyplot.data
data_table = toyplot.data.temperatures()
data_table = data_table[:10]

Now, we can display the data using a set of table coordinates:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table)
table.cells.column[[0, 1]].width = 150
STATIONSTATION_NAMEDATETMAXTMINTOBSGHCND:USC00294366JEMEZ DAM NM US2013010139-72-67GHCND:USC00294366JEMEZ DAM NM US201301020-133-133GHCND:USC00294366JEMEZ DAM NM US2013010311-139-89GHCND:USC00294366JEMEZ DAM NM US2013010411-139-89GHCND:USC00294366JEMEZ DAM NM US2013010522-144-111GHCND:USC00294366JEMEZ DAM NM US2013010644-122-100GHCND:USC00294366JEMEZ DAM NM US2013010756-122-11GHCND:USC00294366JEMEZ DAM NM US20130108100-83-78GHCND:USC00294366JEMEZ DAM NM US2013010972-83-33GHCND:USC00294366JEMEZ DAM NM US2013011189-5022

With surprisingly little effort, this produces a very clean, easy to read table. Note that, like regular Cartesian coordinates, the table coordinates fill the available Canvas by default, so you can adjust your canvas width and height to expand or contract the rows and columns in your table. By default, each row and column in the table receives an equal amount of the available space, unless they are individually overridden as we’ve done here. Of course, you’re free to use all of the mechanisms outlined in Canvas Layout to add multiple tables to a canvas.

In this case, the data file contains a series TOBS that we don’t need, so let’s discard it and reorder the TMIN and TMAX columns to put them in a more natural order:

data_table = data_table[["STATION", "STATION_NAME", "DATE", "TMIN", "TMAX"]]

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table)
table.cells.column[[0, 1]].width = 170
STATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7239GHCND:USC00294366JEMEZ DAM NM US20130102-1330GHCND:USC00294366JEMEZ DAM NM US20130103-13911GHCND:USC00294366JEMEZ DAM NM US20130104-13911GHCND:USC00294366JEMEZ DAM NM US20130105-14422GHCND:USC00294366JEMEZ DAM NM US20130106-12244GHCND:USC00294366JEMEZ DAM NM US20130107-12256GHCND:USC00294366JEMEZ DAM NM US20130108-83100GHCND:USC00294366JEMEZ DAM NM US20130109-8372GHCND:USC00294366JEMEZ DAM NM US20130111-5089

As it happens, all of the columns in our data table contain string values. Note that the labels and columns in the graphic are all left-justified, the default for string data. Let’s see what happens when we convert TMIN and TMAX to integers:

data_table["TMIN"] = data_table["TMIN"].astype("int")
data_table["TMAX"] = data_table["TMAX"].astype("int")

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table)
table.cells.column[[0, 1]].width = 170
STATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7239GHCND:USC00294366JEMEZ DAM NM US20130102-1330GHCND:USC00294366JEMEZ DAM NM US20130103-13911GHCND:USC00294366JEMEZ DAM NM US20130104-13911GHCND:USC00294366JEMEZ DAM NM US20130105-14422GHCND:USC00294366JEMEZ DAM NM US20130106-12244GHCND:USC00294366JEMEZ DAM NM US20130107-12256GHCND:USC00294366JEMEZ DAM NM US20130108-83100GHCND:USC00294366JEMEZ DAM NM US20130109-8372GHCND:USC00294366JEMEZ DAM NM US20130111-5089

After converting TMIN and TMAX to integers, they are right-justified within the table, so their digits all align, making it easy to judge magnitudes. It turns out that the data in these columns are actually integers representing tenths-of-a-degree Celsius, so let’s convert them to floating-point Celsius degrees and see what happens:

data_table["TMIN"] = data_table["TMIN"] * 0.1
data_table["TMAX"] = data_table["TMAX"] * 0.1

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table)
table.cells.column[[0, 1]].width = 170
STATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9

Now, all of the decimal points are properly aligned within each column, even for values without a decimal point!

If you ever want to change the way data in a table is formatted, you can do so by assigning a different format object. For example, you could switch to a fixed number of digits to the right of the decimal point:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table)
table.cells.column[[0, 1]].width = 170
table.cells.column[3:5].format = toyplot.format.FloatFormatter("{:.1f}")
STATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30.0GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310.0GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-5.08.9

Next, let’s title our figure. As with the other coordinate systems, tables have a label property that can be set at construction time:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9

You also have complete control over the gridlines that separate the cells in a table:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"
table.cells.grid.hlines[1,...] = "double"
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9

For a table with \(M\) rows and \(N\) columns, the table.cells.grid.hlines matrix controls the appearance of \(M+1 \times N\) horizontal lines, and table.cells.grid.vlines controls \(M \times N+1\) vertical lines. Use “single” for single lines, “double” for double lines, or any value that evaluates to False to hide the lines.

Suppose you wanted to highlight the observations in the dataset with the highest high temperature and the lowest low temperature. You could do so by changing the style of the given rows:

low_index = numpy.argsort(data_table["TMIN"])[0]
high_index = numpy.argsort(data_table["TMAX"])[-1]

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
table.cells.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.cells.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9

Wait a second … those colored rows are both off-by-one! The actual minimum and maximum values are in the rows immediately following the colored rows. What happened? Note that the table has an “extra” row for the column headers, so row zero in the data is actually row one in the table, so that the data rows have “one-based” indices instead of the “zero-based” indices that all good programmers should expect. We could fix the problem by offsetting the indices we calculated from the raw data, but that would be error-prone and annoying. The offset would also change if we ever changed the number of extra rows before the body of the table (which we’ll see an example of in a moment).

What we really need is a way to refer to the “top” rows and the “body” rows in the table separately, using zero-based indices for each. Fortunately, Toyplot does just that - we can use special accessor attributes to target our changes to the top or the body, using coordinates that won’t be affected by changes to other parts of the table:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
table.body.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.body.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9

Now the correct rows have been highlighted. Let’s add another row of headers to verify that the highlighting isn’t affected:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, trows=2, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
table.top.grid.hlines[...] = "single"
table.top.grid.vlines[...] = "single"
table.body.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.body.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9

Sure enough, the correct rows are still highlighted, the top section of the table contains a second row, and we made the extra row obvious with some grid lines. Note that by accessing the grid via the “top” accessor, we were able to easily alter just the grid lines for the top cells. Let’s take things a step further and provide some additional labels in the new top row:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, trows=2, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
table.body.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.body.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
table.top.grid.hlines[...] = "single"
table.top.grid.vlines[...] = "single"
table.top.cell[0, 0:2].merge().data = "Location"
table.top.cell[0, 3:6].merge().data = u"Temperature \u00b0C"
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9LocationTemperature °C

Note the use of merge() to merge together ranges of cells, along with the data attribute to assign new cell contents.

Also, you may have noticed that the merged cells took on the attributes (alignment, style, etc.) of the cells that were merged, which is why the “Location” label is left-justified, while the “Temperature” label is centered. Let’s center-justify the Location label, make both labels a little more prominent, and lose the gridlines:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, trows=2, label="Temperature Readings")
table.cells.column[[0, 1]].width = 170
table.body.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.body.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
merged = table.top.cell[0, 0:2].merge()
merged.data = "Location"
merged.align = "center"
merged.lstyle = {"font-size":"14px"}
merged = table.top.cell[0, 3:6].merge()
merged.data = u"Temperature \u00b0C"
merged.lstyle = {"font-size":"14px"}
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9LocationTemperature °C

Finally, let’s finish-off our grid by plotting the minimum and maximum temperatures vertically along the right-hand side of the table. This will provide an intuitive guide to trends in the data. To do this, we’ll begin by adding two extra columns to the table using the rcolumns parameter, duplicating the TMIN and TMAX data in the new cells, and readjusting column widths to accomodate the new columns:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, trows=2, rcolumns=2, label="Temperature Readings")
table.body.column[[0, 1]].width = 150
table.body.column[2].width = 70
table.body.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.body.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
merged = table.top.cell[0, 0:2].merge()
merged.data = "Location"
merged.align = "center"
merged.lstyle = {"font-size":"14px"}
merged = table.cells.cell[0, 3:6].merge()
merged.data = u"Temperature \u00b0C"
merged.lstyle = {"font-size":"14px"}

table.right.column[0].data = data_table["TMIN"]
table.right.column[1].data = data_table["TMAX"]

# This is to produce a clean figure, we won't need it in the next step.
table.right.column[0:2].format = toyplot.format.FloatFormatter()
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9-58.9LocationTemperature °C

Now, we can replace the new cells with a line plot that uses their data. First, we embed a set of cartesian coordinates in the two columns, then we use cell_plot() to create a line plot based on the data in the underlying cells:

canvas = toyplot.Canvas(width=700, height=400)
table = canvas.table(data_table, trows=2, rcolumns=2, label="Temperature Readings")
table.body.column[[0, 1]].width = 150
table.body.column[2].width = 70
table.body.row[low_index].lstyle = {"font-weight":"bold", "fill":"blue"}
table.body.row[high_index].lstyle = {"font-weight":"bold", "fill":"red"}
merged = table.top.cell[0, 0:2].merge()
merged.data = "Location"
merged.align = "center"
merged.lstyle = {"font-size":"14px"}
merged = table.cells.cell[0, 3:6].merge()
merged.data = u"Temperature \u00b0C"
merged.lstyle = {"font-size":"14px"}

table.right.column[0].data = data_table["TMIN"]
table.right.column[1].data = data_table["TMAX"]
table.right.column[0:2].width = 40

axes = table.right.column[0:2].cartesian()
mark = axes.cell_plot(color=["blue", "red"], marker="o", style={"stroke-width":1.0})
Temperature ReadingsSTATIONSTATION_NAMEDATETMINTMAXGHCND:USC00294366JEMEZ DAM NM US20130101-7.23.9GHCND:USC00294366JEMEZ DAM NM US20130102-13.30GHCND:USC00294366JEMEZ DAM NM US20130103-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130104-13.91.1GHCND:USC00294366JEMEZ DAM NM US20130105-14.42.2GHCND:USC00294366JEMEZ DAM NM US20130106-12.24.4GHCND:USC00294366JEMEZ DAM NM US20130107-12.25.6GHCND:USC00294366JEMEZ DAM NM US20130108-8.310GHCND:USC00294366JEMEZ DAM NM US20130109-8.37.2GHCND:USC00294366JEMEZ DAM NM US20130111-58.9LocationTemperature °C

Because the axes were embedded across two columns, the plot contains two series. When embedding coordinates in table cells the axes, ticks, and labels are hidden by default to avoid visual clutter. The combination of tabular and plotted data demonstrates how Toyplot makes it easy to display data in innovative ways that other libraries can’t.

Regions

In the above examples we accessed four distinct regions of the table:

  • cells - a special region containing every cell in the table.
  • body - to access the cells that make up the bulk of the table.
  • top - to access “header” cells above the body region, typically used for column labels.
  • right - to access additional cells to right of the body region that we used to embed a plot.

As you might imagine, tables actually contain nine distinct regions that include body, top, right, bottom, left, top.left, top.right, bottom.right, and bottom.left. Below, we demonstrate using explicit row and column counts to create an empty table so we can highlight all nine regions:

canvas, table = toyplot.table(rows=4, columns=4, trows=2, brows=2, lcolumns=2, rcolumns=2, width=400, height=400)

table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"

table.top.left.cells.style = {"fill":"red", "opacity":0.5}
table.top.cells.style = {"fill":"orange", "opacity":0.5}
table.top.right.cells.style = {"fill":"yellow", "opacity":0.5}
table.right.cells.style = {"fill":"greenyellow", "opacity":0.5}
table.bottom.right.cells.style = {"fill":"green", "opacity":0.5}
table.bottom.cells.style = {"fill":"aqua", "opacity":0.5}
table.bottom.left.cells.style = {"fill":"blue", "opacity":0.5}
table.left.cells.style = {"fill":"purple", "opacity":0.5}
table.body.cells.style = {"fill":"white"}

Note how the trows, brows, lcolumns, and rcolumns parameters control the number of cells in the top, bottom, left, and right regions respectively. Typically, you would use these regions to display header, label, and summary information for the data in the body region, although you are free to use any region for any purpose you like.

Indexing

When accessing table cells, rows, columns and other objects, you can use any of the indexing techniques provided by numpy, including individual indices, slicing, and advanced indexing. In the following we will call-out examples of each. To begin, you can use individual indices for one-at-a-time indexing of rows, columns, and cells:

canvas, table = toyplot.table(rows=9, columns=9, width=300, height=300)
table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"

table.cells.column[1].style = {"fill":"red", "opacity":0.5}
table.cells.row[2].style = {"fill":"green", "opacity":0.5}
table.cells.cell[4, 3].style = {"fill":"blue", "opacity":0.5}

Note above that overlapping assignments overwrite cell parameters. As is normal in Python, negative indices are interpreted relative to the end of a range:

canvas, table = toyplot.table(rows=9, columns=9, width=300, height=300)
table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"

table.cells.column[-1].style = {"fill":"red", "opacity":0.5}
table.cells.row[-2].style = {"fill":"green", "opacity":0.5}
table.cells.cell[-4, -3].style = {"fill":"blue", "opacity":0.5}

Of course, you can use slices to access ranges of rows, columns, and cells:

canvas, table = toyplot.table(rows=9, columns=9, width=300, height=300)
table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"

table.cells.column[0:2].style = {"fill":"red", "opacity":0.5}
table.cells.row[0:2].style = {"fill":"green", "opacity":0.5}
table.cells.cell[3:5, 3:5].style = {"fill":"blue", "opacity":0.5}

And you can use slicing with steps to access every-other-column, every-third-row, etc:

canvas, table = toyplot.table(rows=9, columns=9, width=300, height=300)
table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"

table.cells.column[0:6:2].style = {"fill":"red", "opacity":0.5}
table.cells.row[0:8:3].style = {"fill":"green", "opacity":0.5}
table.cells.cell[5:9:2, 6:9:2].style = {"fill":"blue", "opacity":0.5}

Plus, you can use advanced slicing, such as an explicit list of indices:

canvas, table = toyplot.table(rows=9, columns=9, width=300, height=300)
table.cells.grid.hlines[...] = "single"
table.cells.grid.vlines[...] = "single"

table.cells.column[[1,2,4]].style = {"fill":"red", "opacity":0.5}
table.cells.row[[1,7,8]].style = {"fill":"green", "opacity":0.5}
table.cells.cell[[3,4,6], 6:9].style = {"fill":"blue", "opacity":0.5}

Of course, you can use any indexing technique to set any property of a cell, and you can use all of these techniques when working with gridlines and other properties of the table:

canvas, table = toyplot.table(rows=9, columns=9, width=300, height=300)

table.cells.column[3].data = "A"
table.cells.column[3].style = {"fill":"red", "opacity":0.5}
table.cells.column[2:5].width = 35

table.cells.row[2:4].data = "B"
table.cells.row[2:4].style = {"fill":"green", "opacity":0.5}

table.cells.cell[1:5, 1:6].lstyle = {"fill":"white"}

table.cells.grid.hlines[..., 3] = "single"
table.cells.grid.hlines[2:5, ...] = "single"

table.cells.grid.vlines[2:4, ...] = "single"
table.cells.grid.vlines[..., 3:5] = "single"
AABBBBBBBBBBBBBBBBBBAAAAA

Grouping Data

It’s common to group-together subsets of data within a table. Toyplot currently provides three mechanisms that you may find useful for grouping. First, as we’ve already seen, you can use horizontal or vertical grid lines to separate groups:

numpy.random.seed(1234)
data = toyplot.data.Table(numpy.random.normal(size=(10, 4)))

canvas, table = toyplot.table(data, width=500, height=400)
table.body.grid.hlines[[3, 7],...] = "single"
01230.471435-1.190981.43271-0.312652-0.7205890.8871630.859588-0.6365240.0156964-2.242681.150040.9919460.953324-2.02125-0.3340770.002118360.4054530.2890921.32116-1.54691-0.202646-0.6559690.1934210.5534391.31815-0.4693050.675554-1.81703-0.1831091.05897-0.397840.3374381.047581.045940.863717-0.1220920.124713-0.3227950.8416752.39096

Second, you could change the background colors of cells to highlight groups:

canvas, table = toyplot.table(data, width=500, height=400)
table.body.row[3:7].style = {"fill":"#eee", "stroke":"none"}
01230.471435-1.190981.43271-0.312652-0.7205890.8871630.859588-0.6365240.0156964-2.242681.150040.9919460.953324-2.02125-0.3340770.002118360.4054530.2890921.32116-1.54691-0.202646-0.6559690.1934210.5534391.31815-0.4693050.675554-1.81703-0.1831091.05897-0.397840.3374381.047581.045940.863717-0.1220920.124713-0.3227950.8416752.39096

Finally, you can use the gaps property to insert whitespace between groups:

canvas, table = toyplot.table(data, width=500, height=400)
table.body.gaps.rows[[2,6]] = "0.5cm"
01230.471435-1.190981.43271-0.312652-0.7205890.8871630.859588-0.6365240.0156964-2.242681.150040.9919460.953324-2.02125-0.3340770.002118360.4054530.2890921.32116-1.54691-0.202646-0.6559690.1934210.5534391.31815-0.4693050.675554-1.81703-0.1831091.05897-0.397840.3374381.047581.045940.863717-0.1220920.124713-0.3227950.8416752.39096

Because a Matrix Visualization is actually a table, you can use gaps to adjust its appearance, too:

canvas, table = toyplot.matrix(data, width=400, height=700)
table.body.gaps.columns[...] = 10
table.body.gaps.rows[...] = 10
012300.471435-1.1909761.432707-0.3126521-0.7205890.8871630.859588-0.63652420.015696-2.2426851.1500360.99194630.953324-2.021255-0.3340770.00211840.4054530.2890921.321158-1.5469065-0.202646-0.6559690.1934210.55343961.318152-0.4693050.675554-1.8170277-0.1831091.058969-0.3978400.33743881.0475791.0459380.863717-0.12209290.124713-0.3227950.8416752.390961

Plot Embedding

Nearly any type of plot can be embedded in a table, but the fact that they’re embedded introduces additional considerations. As an example, assume we have the following table:

data = toyplot.data.Table(numpy.random.normal(loc=4, size=(10, 2)))

canvas, table = toyplot.table(data, width=250, height=400)
table.cells.cell[...].format = toyplot.format.FloatFormatter(format="{:.1f}")
014.13.44.01.94.23.13.94.04.84.24.82.62.63.93.53.94.44.04.65.5

As we saw earlier, we can create a set of axes that are “contained” within a range of cells, and add a plot that uses the underlying data:

canvas, table = toyplot.table(data, width=250, height=400)
table.cells.cell[...].format = toyplot.format.FloatFormatter(format="{:.1f}")

axes = table.body.column[1].cartesian()
axes.cell_plot();
014.14.04.23.94.84.82.63.54.44.6

And as you might imagine, other plot types are supported:

canvas, table = toyplot.table(data, width=250, height=400)
table.cells.cell[...].format = toyplot.format.FloatFormatter(format="{:.1f}")

axes = table.body.column[1].cartesian()
axes.cell_bars();
014.14.04.23.94.84.82.63.54.44.6

You can also plot data along rows instead of columns:

data = toyplot.data.Table(numpy.random.normal(loc=4, size=(2, 10)))

canvas, table = toyplot.table(data, width=500, height=250)
table.cells.cell[...].format = toyplot.format.FloatFormatter(format="{:.1f}")

axes = table.body.row[1].cartesian()
axes.cell_bars(series="rows");
01234567893.03.94.33.85.01.66.02.94.24.7

Most importantly, you will need to decide whether you want to display data stored within the table, or data from without. For example, we can also embed a plot that contains its own, arbitrary data:

plot_data = numpy.random.normal(loc=4, size=(25, 3))

canvas, table = toyplot.table(data, width=500, height=250)
table.cells.cell[...].format = toyplot.format.FloatFormatter(format="{:.1f}")

axes = table.body.row[1].cartesian()
axes.bars(plot_data);
01234567893.03.94.33.85.01.66.02.94.24.7

Note that when you do this there is no-longer any relationship between the plot and the underlying table - you are simply displaying the plot, constrained to fit in the table cells you selected when you created the axes.

_images/toyplot.png

Text

Rich Text

Toyplot provides a limited subset of HTML5 markup that you can use to format your text (technically, Toyplot uses the XHTML5 Syntax for HTML5, but this distinction only shows-up when using the <br/> tag, discussed below). For example, you can create text with superscripts and subscripts:

import toyplot

canvas = toyplot.Canvas(width=600, height=150)
canvas.text(300, 100, "100<sup>-53</sup>", style={"font-size":"32px"});
100-53
canvas = toyplot.Canvas(width=600, height=150)
canvas.text(300, 100, "H<sub>2</sub>O", style={"font-size":"32px"});
H2O

There are a variety of tags to alter the inline appearance of text:

canvas = toyplot.Canvas(width=600, height=150)
canvas.text(
    300,
    100,
    "normal <b>bold</b> <i>italic</i> <strong>strong</strong> <em>emphasis</em> <small>small</small> <code>code</code>",
    style={"font-size":"24px"});
normal bold italic strong emphasis small code

And these tags can be nested to combine effects:

canvas = toyplot.Canvas(width=600, height=150)
canvas.text(
    300,
    100,
    "foo <b>bar <i>baz <code>blah</code></i></b>",
    style={"font-size":"32px"},
);
foo bar baz blah

You can insert line breaks into your text using the <br/> tag:

canvas = toyplot.Canvas(width=600, height=200)
canvas.text(
    300,
    100,
    "0.567832<br/><small>(243, 128, 19)</small>",
    style={"font-size":"16px"},
);
0.567832(243, 128, 19)

And you can apply a limited subset of CSS styles within rich text:

canvas = toyplot.Canvas(width=600, height=200)
canvas.text(
    300,
    100,
    "This is a <span style='fill:red;font-size:120%'>special</span> word.",
    style={"font-size":"16px"},
);
This is a special word.

Finally, you can embed hyperlinks in rich text, using the <a> tag:

canvas = toyplot.Canvas(width=600, height=200)
canvas.text(
    300,
    100,
    "See <a style='fill: steelblue' href='http://toyplot.readthedocs.org'>Toyplot</a> for details.",
    style={"font-size":"16px"},
);
See Toyplot for details.

Note that additional tags or style attributes currently aren’t allowed in rich-text. We expect that rich text capabilities will continue to expand in the future.

Keep in mind that you can use rich text formatting anywhere that text is displayed, including table cells, axis labels and tick labels. You can also use rich text in format strings for tick locators - as an example, the toyplot.locator.Log locator uses the <sup> tag to format tick labels for Logarithmic Scales.

Caveats

Because all text in Toyplot is parsed as XHTML5, there are a few important caveats to be aware of:

  • You must use <br/> or <br></br> to insert a line break … <br> is not allowed.
  • You must escape < as &lt; and > as &gt; because otherwise they will be confused with XHTML5 tags.
  • You must escape & as &amp; because otherwise it will be confused with an XHTML5 entity.
canvas = toyplot.Canvas(width=600, height=200)
canvas.text(300, 100, "3 &lt; 4 &amp; 5 &gt; 6", style={"font-size":"16px"});
3 < 4 & 5 > 6

Alignment

By default, blocks of text in Toyplot are centered vertically and horizontally around their anchor. To illustrate this, the following figures display the anchor as a small black dot:

canvas = toyplot.Canvas(width=500, height=150)
axes = canvas.cartesian(show=False)
axes.text(0, 0, "Text!", style={"font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3);
Text!

To control horizontal alignment, use the CSS text-anchor property to alter the position of a line of text along its baseline, relative to the anchor:

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian(show=False, ymin=-1.5, ymax=1.5)

axes.vlines(0, color="lightgray")

axes.text(0, 1, "Centered", style={"text-anchor":"middle", "font-size":"24px"})
axes.scatterplot(0, 1, color="black", size=3)

axes.text(0, 0, "Left Justified", style={"text-anchor":"start", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes.text(0, -1, "Right Justified", style={"text-anchor":"end", "font-size":"24px"})
axes.scatterplot(0, -1, color="black", size=3);
CenteredLeft JustifiedRight Justified

In addition, the text can be shifted along its baseline in arbitrary amounts, using the -toyplot-anchor-shift property (note that this is non-standard CSS, provided by Toyplot for symmetry with the standard baseline-shift property which we will see below):

canvas = toyplot.Canvas(width=500, height=300)
axes = canvas.cartesian(show=False, ymin=-2.5, ymax=1.5)

axes.vlines(0, color="lightgray")

axes.text(0, 1, "Shifted +0px", style={"-toyplot-anchor-shift":"0", "text-anchor":"start", "font-size":"24px"})
axes.scatterplot(0, 1, color="black", size=3)

axes.text(0, 0, "Shifted +20px", style={"-toyplot-anchor-shift":"20px", "text-anchor":"start", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes.text(0, -1, "Shifted +40px", style={"-toyplot-anchor-shift":"40px", "text-anchor":"start", "font-size":"24px"})
axes.scatterplot(0, -1, color="black", size=3);

axes.text(0, -2, "Shifted -20px", style={"-toyplot-anchor-shift":"-20px", "text-anchor":"start", "font-size":"24px"})
axes.scatterplot(0, -2, color="black", size=3);
Shifted +0pxShifted +20pxShifted +40pxShifted -20px

Vertically, you can use the -toyplot-vertical-align property to alter the vertical position of a block of text relative to its anchor:

canvas = toyplot.Canvas(width=800, height=300)
axes = canvas.cartesian(show=False)

axes.hlines(0, color="lightgray")

axes.text(-1, 0, "Top", style={"-toyplot-vertical-align":"top", "font-size":"24px"})
axes.scatterplot(-1, 0, color="black", size=3)

axes.text(0, 0, "Middle", style={"-toyplot-vertical-align":"middle", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes.text(1, 0, "Bottom", style={"-toyplot-vertical-align":"bottom", "font-size":"24px"})
axes.scatterplot(1, 0, color="black", size=3)

axes.text(2, 0, "1st Baseline", style={"-toyplot-vertical-align":"first-baseline", "font-size":"24px"})
axes.scatterplot(2, 0, color="black", size=3)

axes.text(3, 0, "Last Baseline", style={"-toyplot-vertical-align":"last-baseline", "font-size":"24px"})
axes.scatterplot(3, 0, color="black", size=3);
TopMiddleBottom1st BaselineLast Baseline

Note that to see the difference between first-baseline and last-baseline requires a block of text with more than one line, since they align the anchor with the first and last line’s baselines respectively:

canvas = toyplot.Canvas(width=800, height=300)
axes = canvas.cartesian(show=False)

axes.hlines(0, color="lightgray")

axes.text(-1, 0, "Top<br/>Top", style={"-toyplot-vertical-align":"top", "font-size":"24px"})
axes.scatterplot(-1, 0, color="black", size=3)

axes.text(0, 0, "Middle<br/>Middle", style={"-toyplot-vertical-align":"middle", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes.text(1, 0, "Bottom<br/>Bottom", style={"-toyplot-vertical-align":"bottom", "font-size":"24px"})
axes.scatterplot(1, 0, color="black", size=3)

axes.text(2, 0, "1st Baseline<br/>1st Baseline", style={"-toyplot-vertical-align":"first-baseline", "font-size":"24px"})
axes.scatterplot(2, 0, color="black", size=3)

axes.text(3, 0, "Last Baseline<br/>Last Baseline", style={"-toyplot-vertical-align":"last-baseline", "font-size":"24px"})
axes.scatterplot(3, 0, color="black", size=3);
TopTopMiddleMiddleBottomBottom1st Baseline1st BaselineLast BaselineLast Baseline

As you can see, -toyplot-vertical-align alters the alignment of an entire block of text. If you wish to alter the vertical alignment of text within the block, you can use the standard CSS alignment-baseline property:

text = """<span style="alignment-baseline:alphabetic">Alphabetic</span>"""
text += """  <span style="alignment-baseline:middle">Middle</span>"""
text += """  <span style="alignment-baseline:central">Central</span>"""
text += """  <span style="alignment-baseline:hanging">Hanging</span>"""

canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.cartesian(show=False)

axes.hlines(0, color="lightgray")

axes.text(-1, 0, text, style={"font-size":"24px"})
axes.scatterplot(-1, 0, color="black", size=3);
Alphabetic Middle Central Hanging

As you might expect, you can also shift text perpendicular to its baseline by arbitrary amounts, using baseline-shift. While you are free to use any of Toyplot’s supported CSS length units for the shift, percentages are especially useful, because they represent a distance relative to the font height:

canvas = toyplot.Canvas(width=700, height=300)
axes = canvas.cartesian(show=False)

axes.hlines(0, color="lightgray")

axes.text(-1, 0, "Shift -100%", style={"baseline-shift":"-100%", "font-size":"24px"})
axes.scatterplot(-1, 0, color="black", size=3)

axes.text(0, 0, "Shift 0%", style={"baseline-shift":"0", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes.text(1, 0, "Shift 66%", style={"baseline-shift":"66%", "font-size":"24px"})
axes.scatterplot(1, 0, color="black", size=3)

axes.text(2, 0, "Shift 100%", style={"baseline-shift":"100%", "font-size":"24px"})
axes.scatterplot(2, 0, color="black", size=3);
Shift -100%Shift 0%Shift 66%Shift 100%

Of course, you’re free to combine all these style properties in any way that you like.

One final thing to keep in mind is that -toyplot-anchor-shift and baseline-shift move the text relative to its baseline, not the canvas. This is important because it affects their behavior when text is rotated. In the following example, look carefully and note that the text with -toyplot-anchor-shift is shifted along its rotated baseline, not simply moved left or right on the canvas. Similarly, the baseline-shift text is shifted perpendicular to its rotated baseline, not merely up or down:

canvas = toyplot.Canvas(width=500, height=300)

axes = canvas.cartesian(grid=(1,3,0), xshow=False, yshow=False, label="default")
axes.vlines(0, color="lightgray")
axes.text(0, 0, "a + b", angle=45, style={"font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes = canvas.cartesian(grid=(1,3,1), xshow=False, yshow=False, label="-toyplot-anchor-shift")
axes.vlines(0, color="lightgray")
axes.text(0, 0, "a + b", angle=45, style={"-toyplot-anchor-shift":"20px", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3)

axes = canvas.cartesian(grid=(1,3,2), xshow=False, yshow=False, label="baseline-shift")
axes.vlines(0, color="lightgray")
axes.text(0, 0, "a + b", angle=45, style={"baseline-shift":"-20px", "font-size":"24px"})
axes.scatterplot(0, 0, color="black", size=3);
a + bdefaulta + b-toyplot-anchor-shifta + bbaseline-shift

Coordinate System Text

In addition to all the above, Cartesian Coordinates and Numberline Coordinates provide additional parameters that affect text layout and alignment.

First, ticks and labels have a parameter location that controls whether they appear above or below an axis:

canvas = toyplot.Canvas(width=600, height=200)

numberline1 = canvas.numberline(grid=(2, 1, 0))
numberline1.axis.ticks.location="above"

numberline2 = canvas.numberline(grid=(2, 1, 1))
numberline2.axis.ticks.location="below"
-0.50.00.5-0.50.00.5

Note that although the location can be specified explicitly, in most cases the defaults should just work … note how the location of the Y axis ticks and labels automatically changes from “above” to “below” when the Y axis spine is repositioned in the following example:

canvas = toyplot.Canvas(width=600, height=300)

axis1 = canvas.cartesian(grid=(1, 2, 0))

axis2 = canvas.cartesian(grid=(1, 2, 1))
axis2.y.spine.position="high"
-0.50.00.5-0.50.00.5-0.50.00.5-0.50.00.5

In addition to positioning tick labels above or below an axis, you can also adjust their offset - the distance from the axis spine to the text anchor. The offset parameter is specified so that increasing values move text further from the axis, whether its location is above or below - in the following example, note that both offsets are positive:

canvas = toyplot.Canvas(width=600, height=300)

axis1 = canvas.cartesian(grid=(1, 2, 0))
axis1.y.ticks.labels.offset=30

axis2 = canvas.cartesian(grid=(1, 2, 1))
axis2.y.spine.position="high"
axis2.y.ticks.labels.offset=30
-0.50.00.5-0.50.00.5-0.50.00.5-0.50.00.5

The default text alignment parameters have been carefully chosen to provide good quality layout even if you change the label font size, and regardless of label location:

canvas = toyplot.Canvas(width=600, height=400)

numberline1 = canvas.numberline(grid=(4, 1, 0))
numberline1.axis.ticks.location="above"

numberline2 = canvas.numberline(grid=(4, 1, 1))
numberline2.axis.ticks.location="above"
numberline2.axis.ticks.labels.style = {"font-size":"16px"}

numberline3 = canvas.numberline(grid=(4, 1, 2))
numberline3.axis.ticks.location="below"

numberline4 = canvas.numberline(grid=(4, 1, 3))
numberline4.axis.ticks.location="below"
numberline4.axis.ticks.labels.style = {"font-size":"16px"}
-0.50.00.5-0.50.00.5-0.50.00.5-0.50.00.5

Similarly, alignment parameters are automatically adjusted when you rotate tick labels, adjusting the anchor and baseline to provide good results:

import numpy

colormap = toyplot.color.brewer.map("BlueRed", domain_min=0, domain_max=1)

canvas = toyplot.Canvas()
numberline = canvas.color_scale(x1="50%", x2="50%", y1="-10%", y2="10%", colormap=colormap)
numberline.axis.ticks.show = True
numberline.axis.ticks.labels.angle=-90
0.00.51.0

Of-course, you are free to override any of these behaviors. For example, suppose we use rich text to add multi-line tick labels to the preceding example:

def format_color(color):
    return "(%.2f, %.2f, %.2f)" % (color["r"], color["g"], color["b"])

values = numpy.linspace(colormap.domain.min, colormap.domain.max, 4)
labels = ["%.4f<br/><small>%s</small>" % (value, format_color(colormap.color(value))) for value in values]
locator = toyplot.locator.Explicit(values, labels)

canvas = toyplot.Canvas()
numberline = canvas.color_scale(x1="50%", x2="50%", y1="-10%", y2="10%", colormap=colormap)
numberline.axis.ticks.show = True
numberline.axis.ticks.labels.angle=-90

numberline.axis.ticks.locator = locator
numberline.axis.ticks.labels.style = {"font-size":"16px"}
0.0000(0.02, 0.19, 0.38)0.3333(0.65, 0.81, 0.89)0.6667(0.97, 0.72, 0.60)1.0000(0.40, 0.00, 0.12)

We might choose to override the defaults to center each line of text within the label:

canvas = toyplot.Canvas()
numberline = canvas.color_scale(x1="50%", x2="50%", y1="-10%", y2="10%", colormap=colormap)
numberline.axis.ticks.labels.angle=-90
numberline.axis.ticks.show = True
numberline.axis.ticks.locator = locator
numberline.axis.ticks.labels.style = {"font-size":"16px"}

numberline.axis.ticks.labels.style = {"text-anchor":"middle"}
numberline.axis.ticks.labels.offset = 60
0.0000(0.02, 0.19, 0.38)0.3333(0.65, 0.81, 0.89)0.6667(0.97, 0.72, 0.60)1.0000(0.40, 0.00, 0.12)
_images/toyplot.png

Tick Locators

When you create a figure in Toyplot, you begin by creating a canvas, add coordinate systems, and add data to the coordinate systems in the form of marks. The coordinate system axes map data from its domain to a range on the canvas, and generate ticks in domain-space with tick labels as an integral part of the process.

To generate tick locations and tick labels, individual coordinate system axes delegate to the tick locator classes in the toyplot.locator module. Each tick locator class is responsible for generating a collection of tick locations from the range of values in an axis domain, and there are several different classes available that implement different strategies for generating “good” tick locations. If you don’t specify any tick locators when creating axes, sensible defaults will be chosen for you. For example:

import numpy
x = numpy.arange(20)
y = numpy.linspace(0, 1, len(x)) ** 2

import toyplot
canvas, axes, mark = toyplot.plot(x, y, width=300)
051015200.00.51.0

Note that the X and Y axes in this plot have sensible ticks that use round numbers. In this case the algorithm for identifying “good” tick values is provided by Toyplot’s default toyplot.locator.Extended locator.

However, notice that the X axis has a tick at the value \(20\), even though the domain of the data values is \([0, 19]\). Toyplot always expands the visible domain to include every tick generated by a locator. If you need to change this behavior, there are several approaches: first, you can configure toyplot.locator.Extended to never generate ticks outside the data domain:

canvas, axes, mark = toyplot.plot(x, y, width=300)
axes.x.ticks.locator = toyplot.locator.Extended(only_inside=True)
0612180.00.51.0

Notice that this can have the side effect of altering the number and spacing of ticks. Let’s say instead that we prefer to always have ticks that include the exact minimum and maximum data domain values, and evenly divide the rest of the domain. In this case, we can override the default choice of locator with the toyplot.locator.Uniform tick locator:

canvas, axes, mark = toyplot.plot(x, y, width=300)
axes.x.ticks.locator = toyplot.locator.Uniform(count=5)
04.759.514.25190.00.51.0

A third alternative is to use explicit tick locators to explicitly specify the ticks to generate for an axis. Explicit tick locators are discussed in detail below.

In the meantime, we can also override the default formatting string used to generate the locator labels:

canvas, axes, mark = toyplot.plot(x, y, width=300)
axes.x.ticks.locator = toyplot.locator.Uniform(count=5, format="{:.2f}")
0.004.759.5014.2519.000.00.51.0

Anytime you use log scale axes in a plot, Toyplot automatically uses the toyplot.locator.Log locator to provide ticks that are evenly-spaced in the logarithmic domain:

canvas, axes, mark = toyplot.plot(x, y, xscale="log10", width=300)
010 010 110 20.00.51.0

If you don’t like the “superscript” notation that the Log locator produces, you could replace it with your own locator and custom format:

canvas, axes, mark = toyplot.plot(x, y, xscale="log10", width=300)
axes.x.ticks.locator = toyplot.locator.Log(base=10, format="{base}^{exponent}")
010^010^110^20.00.51.0

Or even display raw tick values:

canvas, axes, mark = toyplot.plot(x, y, xscale="log2", width=300)
axes.x.ticks.locator = toyplot.locator.Log(base=2, format="{:.0f}")
0124816320.00.51.0

Although you might not think of Table Coordinates as needing tick locators, when you use toyplot.matrix() or toyplot.canvas.Canvas.matrix() to visualize a matrix, it generates a table visualization that uses toyplot.locator.Integer locators to generate row and column labels:

numpy.random.seed(1234)
canvas, table = toyplot.matrix(numpy.random.random((5, 5)), width=300)
0123400.1915190.6221090.4377280.7853590.77997610.2725930.2764640.8018720.9581390.87593320.3578170.5009950.6834630.7127020.37025130.5611960.5030830.0137680.7728270.88264140.3648860.6153960.0753810.3688240.933140

By default the Integer locator generates a tick/label for every integer in the range \([0, N)\) … as you visualize larger matrices, you’ll find that a label for every row and column becomes crowded, in which case you can override the default step parameter to space-out the labels:

canvas, table = toyplot.matrix(numpy.random.random((50, 50)), width=400, step=5)
05101520253035404500.6513780.3972030.7887300.3168360.5680990.8691270.4361730.8021480.1437670.7042610.7045810.2187920.9248680.4421410.9093160.0598090.1842870.0473550.6748810.5946250.5333100.0433240.5614330.3296680.5029670.1118940.6071940.5659450.0067640.6174420.9121230.7905240.9920810.9588020.7919640.2852510.6249170.4780940.1956750.3823170.0538740.4516480.9820050.1239430.1193810.7385230.5873040.4716330.1071270.2292190.8999650.4167540.5358520.0062090.3006420.4368930.6121490.9181980.6257370.7059980.1498340.7460630.8310070.6337260.4383100.1525730.5684100.5282240.9514290.4803590.5025600.5368780.8192020.0571160.6694220.7671170.7081150.7968670.5577610.9658370.1471570.0296470.5938930.1140660.9508100.3257070.1936190.4578120.9204030.8790690.2526160.3480090.1825890.9017960.7065280.7266580.9000880.7791640.5991550.2911250.1513950.3351750.6575520.0733430.0550060.3231950.5904820.8538990.2870620.1730670.1340210.9946540.1794980.3175470.5682910.0093490.9006490.9772410.5568950.0847740.3330020.7284290.1424350.5524690.2730430.9744950.6677870.2556530.1083110.7761810.7824780.7616040.9144030.6586230.5683680.2017560.6982960.9521950.8899630.9935670.8187040.5451220.4512540.8905570.9732650.5934110.3660740.3230950.8714230.2156340.7349450.3656190.8016030.7827360.7013550.6227770.4936830.8405380.7120970.4439090.0310350.3632400.7307220.4755670.3444170.6408800.1262050.1714650.7370860.1270290.3696500.6043340.1031040.8023740.9455530.9790390.8812320.6276820.9304870.7247900.7166780.0410790.4394820.2820700.3349960.0835270.7608490.5092720.6610470.6303140.3709270.4467400.4151080.4803890.9833240.3734240.0124070.9219030.8732760.3517470.6301330.3578270.2128200.2233190.4195640.0729100.6508390.7556860.9321010.3764040.2969270.3719440.8276990.9011400.4273040.0021890.0419650.1417870.5982370.1064610.2971590.0583920.6213250.0226800.8550550.3063370.7587830.5632750.0381640.5655170.6588730.1832660.7974110.6123670.5556530.6294920.6861800.2403830.7879280.8564770.7277960.6923450.4723510.8568730.6647430.3333760.5181450.3946890.0310500.57684050.8502520.9514890.6829790.0761630.4100780.0419010.1741870.5654020.1728910.5666100.5140040.8688710.7203470.9035910.2776150.2566650.6997030.9015690.9836920.6409130.3300070.6066750.8221600.6279650.1179230.2858780.9867470.4318010.5742340.5272420.1976530.1657080.5009900.9902040.3939920.7140130.1759040.0706960.1576230.1615580.2836370.5367060.7732390.8803440.6373910.8526020.5979550.6938470.5371770.8892300.0522660.7831840.1451730.0586980.0589950.0519710.5159860.4049960.9996500.1085700.3273840.9978300.4011140.8833360.5691390.9532410.8853870.7792860.0318080.9626190.5196350.2077910.8750980.2241510.1386590.7252390.9737890.5354820.4447980.0221110.6059880.9647970.9675910.9300290.1846800.6229620.4129630.3630610.0366030.8681490.6728280.0874720.8869660.7824650.3173040.8183140.5075550.0211930.4335220.4463130.2388200.8302460.7447640.5864790.4928680.4873560.2667410.6050110.7535440.2705840.5223030.0983290.7136370.8840410.5670540.9944820.1787400.0122000.4569980.9317520.8460250.4733300.9025550.2259960.3041540.7149940.7240910.0186760.2858130.5804860.9307870.3389970.1200830.5162730.6992070.2986410.8616100.9058070.7685830.2612320.9384560.9386420.7450450.9107350.2372250.4949670.8098780.9545660.6374830.9108500.6921370.0429430.8335870.3699490.9365570.4830530.1253320.9644540.0170260.6765710.1404400.1553130.6495580.9816540.6948070.7619740.4252090.1388930.2161860.7647000.0546060.4901230.1806900.6309250.5512420.5670810.8183450.9389870.1929010.7128440.6979400.2582960.9158080.5323580.5579640.3227720.3386310.3323020.9788180.2032150.6670260.5747840.0519750.5428380.2079490.0910900.8698560.0273700.9686250.3275000.4102780.1355440.1270660.4139840.6174440.1322670.9744810.1806350.7603500.4821620.7680790.3028980.0151750.4633690.7033370.0660410.6690110.3454790.5917210.2290530.2675680.9328270.8261450.1454430.6470040.8839510.7413610.5157110.1352520.0398840.8343220.1170580.5231020.8730580.0387080.6923910.4762680.1692640.0631720.0322240.2424310.1127070.4049900.0420730.9265650.9352630.8104270.1883430.5873180.903511100.9673420.0675390.3175860.6968630.6402650.6326230.8287510.7131100.3354800.1676950.7646900.3593150.0880050.7295680.8810500.0412640.1748680.4200970.3406070.0447690.1128910.4380410.0710730.8162450.8661160.1311200.1932190.4374930.9709250.7738610.1317760.9271800.8277970.3927320.1405710.0521360.0927290.8869900.1681510.3628870.6542820.6048220.3949930.3746050.0630730.4289590.7197210.7680310.1943680.8628710.0287220.9021290.2365460.1285840.3178760.8487610.8322980.3456510.2399710.5357880.2714670.0344310.6270860.5202000.0419560.7574730.9883500.8014010.3439810.3353910.3515710.4429460.5794930.6175610.1771170.8649820.7102710.1706320.8550830.0198570.6416840.1623340.2575500.3426060.0061440.4385510.7970440.6756650.5450230.5642270.0139840.6089770.9885660.2241070.5872180.8350580.7924980.3292280.3572030.9601130.2237960.2115370.1539150.4958960.2612950.5556860.0729160.3785170.4610890.7785400.7204430.2312040.0245440.2573650.4101160.0083990.4715490.8524220.9231800.2314360.9909550.0059980.3352510.7892580.0985120.4423320.3806690.8325980.7119620.3550010.0246360.6935130.4212120.8583490.5750740.9400620.8802560.4581450.0173100.0686550.3206080.5923020.6100520.5124280.1447560.8768090.7382350.3733200.8286860.0902400.0640030.5058970.9334270.1489620.5694790.0597490.1692780.0690280.9060220.4474100.1063850.6652600.5022730.4092060.7279930.1720900.3844610.2670010.3082210.1773030.4825580.6297170.0595530.1968870.2792080.7078210.3274290.4252940.7047680.1590770.4394040.6293300.9250580.3569880.8191330.6401430.7150520.7384230.9710000.2460490.0425820.2477970.0450170.7054620.8347070.9341360.4707930.5123600.2629800.0988970.7988460.1428030.8056660.8795260.4999200.9142520.4124130.2003740.6435710.3998650.6142310.4373110.5931040.9514400.5531200.9037350.1385050.0015440.6128340.5417030.7806310.8214940.9534100.6099560.2900820.8268080.3760170.6091770.6200220.4415000.1987720.4439540.9247670.6714340.0815230.5726590.1206620.9999640.9973800.6947120.3738800.4015110.9250990.2448590.6640130.4812210.0349440.1108950.8953690.892101150.9151610.3074020.2984200.6592520.5951380.9843690.6156220.1547160.8314690.8156970.0920420.8877900.0164390.8639300.8987710.8503670.6528690.3287550.5453790.2379350.8717850.1767340.3706360.7595850.3061840.6161390.2192910.8725240.6478650.4730030.2341900.8338220.0985160.2050270.2347310.5969740.6284680.9826510.1763170.7999770.1552640.3609920.9550750.1301580.2728470.8091180.9656570.0924220.5834240.4054260.8993240.0847830.1811360.0506650.3012790.1901840.0086050.1275230.1128650.7304140.2393750.9015700.3285140.8740430.2365300.3784550.5422910.5157940.4138020.3888670.3403310.4022350.4571100.3829910.6580900.8812140.5726730.4280400.2583780.8652690.1732780.5799530.7273770.7304020.4039960.1179270.7635950.5336610.7220350.5976320.4228660.9334860.9939710.5478390.7302350.0279840.8635910.9986310.3253100.8502610.6114920.4411130.5272050.7798210.2513500.4628920.8471870.6780240.3678620.1379830.4028090.9312970.6731630.4192300.5686670.0417110.9956340.6190040.7794660.9313390.3416190.8112990.8727100.6659880.5887870.8933520.4485840.2443840.8141730.6971490.4096050.0057150.9540140.6052530.0065460.4984930.5986350.3001470.4617570.4956000.5856590.8696380.8322270.7785630.5484330.6134520.7342700.5663690.7752100.9865460.7892060.6143360.1582850.4763860.2836490.1538120.7772200.0589630.0791230.6642380.5233450.4464070.3068300.0172850.2935270.2677940.0367260.8040400.3338000.8918870.8103530.9641010.9577140.5911660.3115030.9184210.0506500.2257430.3627060.4122560.9446210.5793830.1867600.5964850.9337560.1341380.9822840.1538760.8207280.6775360.4040890.2172870.7735850.8476960.5297000.4096000.0183080.1486600.8043350.4197780.3392180.2971460.7179860.9978070.5519020.8898960.1684680.8835640.7027760.4221090.8633150.2350430.5637510.0265600.3800510.3618350.0912440.0452540.3424520.3554140.9958380.9442050.1311440.5183550.4772450.4011060.9306140.5153360.8095820.8817720.7626680.4644210.0739200.4704990.2005720.2085670.1775400.3542410.9117530.4335210.1782960.7521620.0504710.0826690.0385830.4652790.6038290.1817890.5190300.710153200.9249800.5291320.9711860.5472530.0064380.4727770.5220880.1522090.6542340.1304440.4541490.9823610.1325140.0602790.0678720.0961460.8193420.6296070.7836310.0771350.9719980.8828340.6304330.9290730.3981270.4889260.6858030.2815970.6767000.4957320.7911420.2188340.7461960.4541110.4082620.9226430.1507210.1309830.3818900.5419870.9443700.3232590.0974420.9473870.8570350.0260370.1178940.8293760.1384740.5694710.4777750.3066860.0566070.9368350.9040040.7222350.6540780.3922100.9736750.7110080.4930480.3264410.1158530.9720610.2744280.1874500.2148950.7608540.9448890.5015510.6620840.3474040.1285700.6812960.3912830.0262040.5006000.5281270.2232680.0016900.4465630.5053260.0810190.8227400.2401950.0096900.2250420.0841900.8259650.7147670.2445560.0638370.4267540.7060420.7181540.1934340.7400480.9567300.5158940.4300450.0230370.5073260.6865620.1381750.6724230.0393110.4317770.8542760.4223280.0884490.0566950.1032730.4853160.6746570.0908950.8322120.7764640.0611630.3224180.3771400.5022650.4499650.4673620.1047140.3737510.0217720.4483380.8931150.7758810.2491610.7315450.3151380.4961300.0504260.5825200.2825940.2933360.1260540.8931810.4512730.6508710.8093050.2829630.2733820.3857370.4216080.9321650.8676330.4451740.0291890.1071980.1962590.2382360.8245100.8964860.0278870.5733010.8056430.4205120.5252670.2861430.6586460.0903000.8222650.8074140.1916170.6383030.8324650.4698270.5803530.1089030.4624190.8863520.4649830.4662150.1960050.0387290.6158620.5646310.1082310.7416330.1834820.3486410.4804810.6439260.6216260.7611930.2866510.4923850.6819100.5099700.7682110.2999360.5468810.2446450.4435970.8100140.1038670.2299850.7917640.5665410.8274170.9749340.9652240.9497030.5517870.0925360.7404310.5642970.7458580.4553900.1556630.9959530.8896910.8037490.4114760.2131570.2944400.6229310.2482170.7996810.0188820.4803510.7340150.6835680.4212830.6932030.3671980.2324410.7850510.7267050.7064570.0317420.2394390.3710580.5818790.0879890.2321290.8125160.7527400.8047770.2944430.7806190.2247860.2898490.8489820.7441660.3322530.5673340.699648250.0919350.0538020.8627960.6299700.8696530.0876910.8659040.0412480.9581740.2273680.7518620.4007490.4030750.2532870.5068380.1845600.0570840.3669270.7198370.4741750.9226200.1701220.7183820.8697980.1293100.9740560.7542160.9166770.0377030.2858490.8229080.2747340.0517240.1479430.0164930.7824170.3491220.7496780.0549530.0781980.7893410.3704380.1109620.4052160.6512990.4362880.2024750.4438900.7421480.0960150.5117210.8436160.9935440.6307560.2854730.1260220.0133560.3381560.4843200.5461910.0360390.0612240.0231610.5073890.2665910.4453060.9736090.7977760.2841260.5557860.1975880.7906010.0876200.8379250.2412630.4342620.4278620.1021170.9088140.1490110.9075680.0104540.1735340.8391390.3102550.8489860.9113440.8999010.8672290.8377620.2536430.8430080.6176280.9841770.6105400.6516980.6544650.5523270.1857300.9809760.0959370.7482630.5246180.2907600.2281910.5037390.9319570.5741300.9897450.4297730.4163560.6278770.9073680.0694230.5504030.1546060.7185610.1354070.0045460.5375160.0165930.5355150.0456920.1539790.8430100.7979290.3035940.3984930.4492940.0205350.6175540.8045550.2341720.4001280.4933140.5018810.3334880.1054200.6408080.1514690.1951770.0573910.9147450.8306700.1590040.8677070.5072980.1283010.1131180.2227980.8898370.4509220.6972100.3902900.6226240.7164480.5008590.7600810.8326040.5599440.5438530.5879720.0251540.9891020.0707740.8176150.1370360.1530200.3592420.2534620.2187640.5633830.4800620.0930470.5139070.1974180.4802700.2770200.0104840.8877810.3738980.4162170.8775830.7607710.5481120.9023410.9207010.4654410.5656470.0285580.1403310.3999980.8270980.4553910.6935830.6379800.6558830.7693190.0002270.3006950.6954710.0908870.5236480.8945950.9637060.7056880.7640290.3446080.2518500.6672090.1493050.4709170.0222920.7597110.2056570.8405900.7748540.1761640.8845590.0930640.2021880.3724050.1736560.3452340.5677380.1569520.7757400.0336620.0109590.3201230.5267270.6297270.8815140.6411390.0226880.6951900.8846520.7513940.2630780.5075740.1241910.6087260.6933130.0777860.4040810.5134870.8070660.0989660.4725320.567342300.5359840.1842630.5867830.7859110.9980690.0527300.0426790.5289340.6033790.0822530.7098160.1161380.1973020.7792850.4558790.3088500.3676760.7633080.1804470.1377430.5008610.0149030.3472940.3377370.5046310.4923790.3502960.2023900.1599440.5610170.4461760.8552990.9111810.8765650.9654290.2023110.7263760.5713180.5839270.4567220.5821110.0677480.0059510.4680120.7902280.9229490.7202410.1259310.7190920.6154940.3867180.7852140.1013440.4029380.7423970.0124340.9281830.4602230.0696250.9099310.1233040.8947820.2050600.9319890.4979290.3600040.1608710.7263760.8352750.3188790.9780650.4727110.5661440.1466840.0997440.0865170.7530140.7422890.3155060.8453140.5345470.8325700.1860340.2759530.5830580.9299510.0572950.8182970.1646230.4397060.3665210.0657790.7878090.5123880.1768390.5208310.5910090.4445390.1430080.9612640.4177700.1300250.6509930.5879050.2547380.2874330.8052790.0562080.2781920.9367110.8384070.9081740.5946170.7735010.3441000.3838670.3779410.4259640.7068980.2441710.1777810.2164650.7243900.6314870.7945350.7857190.1449770.0874880.2567570.6401170.5697080.8893430.9181420.1523850.1189850.0100540.2798390.1229220.4576360.1884010.0076110.8963380.9975530.8060040.0301680.5353230.6100010.8514240.4099580.2613970.7547910.7910760.7872900.9477820.4002080.6582160.5256360.4181430.4075350.3712690.8438940.4708260.5849000.1657180.5471580.5388190.5076300.6430810.5446840.3182540.7881910.5644250.4155790.3279310.9206480.9304690.0106920.0930820.1340890.6273370.2616920.5825430.5549020.2003410.6570800.9432070.3567680.0318010.4735270.0674580.4992540.6921440.0761180.2298300.4973680.5427910.4949350.8012830.3079590.1140200.5602810.7691090.4351870.0835340.5985940.8460640.1832560.9129690.1036520.1268240.0040740.7845890.5604780.6605200.5218220.7957460.2516440.5304820.0563040.1373330.1419880.6637680.1078400.7570350.4542550.6941280.3567270.7680180.8173280.9267440.2070380.6009570.0344780.2929900.0423010.0972680.3009170.0602670.5831780.7244170.7507680.6980990.1133590.2869590.2621450.0662280.0021770.2693440.0338110.467862350.5408270.2047750.2287980.6533310.0196220.2994160.4804160.5212740.9589980.7606800.8034260.3295610.3767790.6870570.7072530.1108460.2677530.0305330.4009940.0061220.6688720.8688990.3758230.2811100.1013510.8057160.4842740.8766750.1522220.2197160.7332710.0655210.8155110.8597730.0316110.0668030.4730450.2056180.2254440.4343790.2329100.8284090.8914420.8143070.9613000.6638470.0459570.8755540.9429500.9691060.7493010.9327360.0884120.8343470.7313810.9614460.1146670.2634810.1974280.1455890.2695520.0839050.1957440.9475190.9697370.0038970.1842930.9279660.6865000.8147940.9900790.0806900.5735120.8665180.2464050.5933350.9758620.1938110.2929370.4964200.6537520.6066130.7078740.3142010.4458540.3010900.4372840.0507750.9535110.1788930.0767530.9367870.8358250.9726190.8231750.0331040.5694970.1475150.5800540.0834910.4552870.8591570.3255760.3375950.9181370.6372030.1659510.8741230.0955670.5901230.6327500.3326550.1611800.6407750.3877400.8165280.2293200.6651160.5756070.0793720.0423220.8570220.1475420.1030780.1063490.2932520.5301170.8663260.8687840.3565030.0981270.4382270.9474860.0415950.3108480.7822870.7955100.8525810.5438910.5906290.1391080.0347240.1552600.7569190.3687820.2828120.2417990.8713520.3670940.8880360.9498790.8727590.3720450.6458570.4326910.7306000.6989450.4302680.4038720.6011060.6488860.1140800.7053510.3597290.4229260.3135420.5683060.0335650.9768400.9705890.2822730.6578210.7770860.9454950.6681080.4505200.8402530.8225210.9301830.7020580.8006250.9589450.3858840.7325100.1285250.2053340.8831820.6958240.7109030.3697910.5782740.0838090.5941830.1769730.4208670.2398740.1275280.8956020.9100760.6288790.1575610.7305900.9890960.7797480.9795350.8049480.4197330.4650540.7563950.8101500.1413430.0811620.3575510.9687920.6917280.0226320.2128220.7262470.6732180.0383960.3586870.7511410.8656720.9542170.8795650.8659620.7120570.6637710.3847950.1793040.7445320.7670240.1565470.0023020.5216880.7585710.4411690.8885580.5293150.8849920.4526770.6839130.0612000.7405370.6725970.0103960.6732220.7899250.8307750.994382400.5670550.8615620.0911710.1689130.3306070.9547290.1036980.4972330.9890880.6155340.5569420.2374310.4683760.4688480.5631280.4116600.1775370.1523290.7496350.4888560.7292770.4249680.7256260.5880080.1370710.5647470.2944750.6339950.6432350.5525020.3900210.2671220.8021660.8996360.1015880.4537800.3940230.6716430.5537940.8429090.0059650.6459080.1148570.7563750.2280410.2185380.4113400.0684950.4687520.3544380.0827020.1358290.9127070.8719280.7836640.7148360.6703390.6341910.3906740.7666540.2217100.7067570.3045540.7837220.6059980.8717480.0859380.5456520.9155450.6126610.5593320.3289050.8326040.2451670.2880220.6026080.3893000.4123110.5328530.8759270.7643140.8517180.8399690.5470910.5447420.0088150.6197030.9123700.2125960.3221510.2616460.8933620.8224510.2616510.2068840.5263700.0174290.4173860.0890230.9872800.9494890.7521570.6402640.2083780.1678660.1437200.4528460.0044710.3147810.6104550.9938930.5215800.1026770.0523930.3285840.5597620.8377540.0561140.8949200.8958000.4522580.9049280.1531900.7364610.4747040.9741070.5256820.8581110.8188300.8385570.1883830.9248690.7063190.0587880.8836310.3377290.9958010.4620740.8109190.7034230.9606800.7149310.4952140.9747450.7269470.4968950.3306210.3692280.0768640.7676580.9272810.4226650.5208930.0089540.4303270.1530620.4813890.5022240.4911420.7930160.0495010.7163410.5512660.3444680.9414140.7533130.8012080.6270310.5482850.7176080.5288460.5193110.2389710.7295450.9960750.6718740.5713390.3570990.0642730.7078200.2347930.7852740.3599550.0713220.7852050.3885020.3567670.5160930.8325680.3016450.5413660.3230270.1248230.1693840.0805940.4630170.8586330.1043550.8529880.5971230.9155840.1777160.9821030.6543840.1420180.0867050.4045650.4265880.8277470.6505770.0188830.9046820.5304500.0799200.6246700.4659730.3169800.2766350.9482450.7167800.2582650.3489110.4707680.0381670.2990570.3717660.6216700.0269730.9195480.2388660.1374100.9374220.7562190.9528880.8596590.8637230.4054970.6965080.1234940.9826200.2934090.0563640.9345410.6487800.3455820.5433100.8774910.8705950.9765890.981365450.4358960.0843000.3771240.9452980.5208450.7856900.8615670.4293750.6854400.2647640.1950040.8205170.5202840.3934950.0410820.1209450.6974980.3263770.3058870.8746240.8647120.7347660.2771360.3575380.2773510.6409940.1218150.3721800.4505320.3905610.8156840.9736440.9206140.0989800.1184540.9804590.1444180.9032130.7459150.3484590.0093440.6612470.7761380.9266180.1094160.0698860.8878430.7059020.2158220.7225140.9790470.0602940.7149180.1789700.8620100.6292780.3150530.2339320.6829520.6343710.5939900.6532780.1591690.8892910.4298080.9236760.4592040.6295890.1218090.2306980.0204910.0829250.1620640.3472800.3835000.7166140.4807500.8727870.5080410.9830350.4262150.5220110.9467440.5148180.3752330.5571680.4552690.9445960.7470600.5927560.9345950.8579460.6244520.7671870.7984260.7964310.0905900.0256600.3540530.2828020.0557170.0678240.1016800.6166960.2020650.8798320.9970080.7837190.7251940.2872130.7171010.6507330.1348640.0648110.3051910.6940900.5887570.7173070.8739500.8053250.0988740.3069140.3087380.6401910.3340830.2152300.0184010.8629860.1112050.2520690.9924700.8278760.2450560.0535510.2132060.6424790.7661730.7510220.0559330.6186490.3463200.1818440.4190660.2787520.0492160.8337840.8138030.3469550.7517570.0191380.7184950.1409490.6555430.4352200.7680170.2094110.3377960.5065790.2912000.6716360.0253660.3238170.0928970.1842270.8293700.0761550.5215680.9840660.4242390.6358260.4355680.5528290.7848890.1625030.5828400.5704190.1550160.2488840.1980530.2867890.5777200.5757230.7721010.4098070.6669050.8683160.3295130.0535480.7940440.6433820.4460250.0134210.3848980.0517980.5305310.2095150.2737660.2119400.3267140.0000430.2668030.9501260.4178660.5449100.6108010.0502810.1216250.5062970.5974270.2741210.0291520.8806730.9116680.0904840.5993090.6881650.0576130.0846100.3333170.5905750.9286700.1054240.3893760.7546460.7898280.0101460.5595520.4810310.3036890.9907860.6153700.8357260.4597650.6324200.8442620.6710210.1468770.1802280.9110610.6446610.9124710.5534640.7680970.0438430.3278120.9216820.5819010.7211120.6171710.759219

Explicit Locators

For the ultimate flexibility in positioning tick locations and labels, you can use the toyplot.locator.Explicit locator. With it, you can specify an explicit set of labels, and a set of \([0, N)\) integer locations will be created to match. This is particularly useful if you are working with categorical data:

fruits = ["Apples", "Oranges", "Kiwi", "Miracle Fruit", "Durian"]
counts = [452, 347, 67, 21, 5]

canvas, axes, mark = toyplot.bars(counts, width=400, height=300)
axes.x.ticks.locator = toyplot.locator.Explicit(labels=fruits)
ApplesOrangesKiwiMiracle FruitDurian0100200300400

Note that in the above example the implicit \([0, N)\) tick locations match the implicit \([0, N)\) X coordinates that are generated for each bar when you don’t supply any X coordinates of your own. This is by design!

You can also use Explicit locators with a list of tick locations, and a set of tick labels will be generated using a format string. For example:

x = numpy.linspace(0, 2 * numpy.pi)
y = numpy.sin(x)
locations=[0, numpy.pi/2, numpy.pi, 3*numpy.pi/2, 2*numpy.pi]

canvas, axes, mark = toyplot.plot(x, y, width=500, height=300)
axes.x.ticks.locator = toyplot.locator.Explicit(locations=locations, format="{:.2f}")
0.001.573.144.716.28-1.0-0.50.00.51.0

Finally, you can supply both locations and labels to an Explicit locator:

labels = ["0", u"\u03c0 / 2", u"\u03c0", u"3\u03c0 / 2", u"2\u03c0"]

canvas, axes, mark = toyplot.plot(x, y, width=500, height=300)
axes.x.ticks.locator = toyplot.locator.Explicit(locations=locations, labels=labels)
0π / 2π3π / 22π-1.0-0.50.00.51.0

Timestamp Locators

Toyplot includes the toyplot.locator.Timestamp locator which can be used to provide human-consumable date-time labels when your data’s domain is timestamps (seconds since the Unix epoch, i.e. midnight, January 1st, 1970, UTC). As an example, let’s load some real-world data containing date-time information:

import toyplot.data
data = toyplot.data.commute()
data[:6]
DatetimeNameValueUnits
2014-05-01T14:08:53.587607ZStatus Since DTC Cleared0011110100110
2014-05-01T14:08:53.656972ZFuel System Status0000
2014-05-01T14:08:53.726403ZCalculated Load Value0.0%
2014-05-01T14:08:53.734393ZCoolant Temperature13C
2014-05-01T14:08:53.804349ZShort Term Fuel Trim0.0%
2014-05-01T14:08:53.873862ZLong Term Fuel Trim-3.125%

Our first step will be to convert the string datetimes from the file into true numeric timestamps. Note that for this example we’re using Arrow, a library that improves upon the builtin datetime functionality in Python. Note that Arrow is used in the timestamp locator implementation, so it must already be installed for the following examples to work:

import arrow
timestamps = numpy.array([arrow.get(datetime).timestamp for datetime in data["Datetime"]])

Now, we can plot the data using the timestamps as our independent variable:

observations = numpy.logical_and(data["Name"] == "Vehicle Speed", data["Value"] != "NODATA")
x = timestamps[observations]
y = data["Value"][observations]

canvas, axes, mark = toyplot.plot(
    x, y, label="Vehicle Speed", xlabel="Time", ylabel="km/h",
    width=600, height=300)
1398953000139895400013989550001398956000Time04080120km/hVehicle Speed

As you would expect, the timestamps make very unfriendly tick labels. Let’s use the timestamp locator instead:

canvas, axes, mark = toyplot.plot(
    x, y, label="Vehicle Speed", xlabel="Time", ylabel="km/h",
    width=600, height=300)
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Timestamp()
5/1 14:105/1 14:155/1 14:205/1 14:255/1 14:305/1 14:355/1 14:405/1 14:455/1 14:50Time04080120km/hVehicle Speed

By default, the timestamp locator chooses a “good” time interval based on the data domain - for this data, it chose to create ticks at five minute intervals. In addition, the locator also chooses a default format based on the interval - in this case, month/day hour:minute. This is a significant improvement over raw timestamps, but before we continue, we need to address timezone issues.

As alluded to above, in Toyplot all timestamps must always be UTC timestamps, without exception … that is to say that the numeric values to be displayed by the timestamp locator must be the number of seconds since Midnight, January 1st, 1970, UTC time. Our current example data already contained UTC datetimes (note the “Z” timezone in the data file), so no special conversion was necessary. If for some reason you’re working with datetimes that aren’t UTC, you’ll need to take their timezone into consideration when converting them to timestamps for display by Toyplot … and as an aside: you need to run, not walk to anyone collecting data using local timestamps, and make them stop!

Since all Toyplot timestamps are UTC, the times displayed by the timestamp locator are also UTC by default. If you prefer to display times using a specific timezone, you can specify it when creating the locator.

An Important Note on Timezone Names

The arrow library (and thus Toyplot) relies on the underlying operating system for its timezone information. The following examples use “US/Mountain” to identify a timezone, and should work on most posix-like systems including Linux and OSX. Unfortunately, Windows operating systems use a different naming scheme; if you are using Windows, you will need to substitute a different name, such as “US Mountain Standard Time”.

canvas, axes, mark = toyplot.plot(
    x, y, label="Vehicle Speed", xlabel="Time (US/Mountain)", ylabel="km/h",
    width=600, height=300)
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Timestamp(timezone="US/Mountain")
5/1 08:105/1 08:155/1 08:205/1 08:255/1 08:305/1 08:355/1 08:405/1 08:455/1 08:50Time (US/Mountain)04080120km/hVehicle Speed

Note that the hour in this data changed from 14:00 to 8:00, which makes more sense, since this data came from a morning commute. You could also specify a timezone of “utc” (the default) to explicitly document in the code that no timezone conversion is taking place. Finally, you may use “local” to automatically display the data using whichever timezone is local to the host running the code … but be careful with this option, since it means that the the content of a figure could change based on where your laptop was when you generated it!

With timezones out of the way, let’s focus on the labels. The current set is a little crowded, so let’s look at different ways to clean things up. First, we can use the count attribute to request that the locator choose an interval that produces a specific number of ticks:

canvas, axes, mark = toyplot.plot(
    x, y, label="Vehicle Speed", xlabel="Time (US/Mountain)", ylabel="km/h",
    width=600, height=300)
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Timestamp(timezone="US/Mountain", count=5)
5/1 08:105/1 08:205/1 08:305/1 08:405/1 08:50Time (US/Mountain)04080120km/hVehicle Speed

Note that in most cases the locator won’t produce the exact number of ticks requested (we got lucky in this case), it will choose an interval that produces the closest match.

Alternatively, we might choose to accept the default tick count and alter the tick format, to save space:

canvas, axes, mark = toyplot.plot(
    x, y, label="Vehicle Speed", xlabel="Time (US/Mountain)", ylabel="km/h",
    width=600, height=300)
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Timestamp(
    timezone="US/Mountain", format="{0:HH}:{0:mm}")
08:1008:1508:2008:2508:3008:3508:4008:4508:50Time (US/Mountain)04080120km/hVehicle Speed

The individual tick values are passed to the format function as arrow.arrow.Arrow objects, so you can use any of the arrow attributes and formatting tokens in the format string, as we’ve done here.

Or, we might force a specific interval if it had special meaning for our domain, such as the number of seven-minute workouts we could have completed during our commute:

canvas, axes, mark = toyplot.plot(
    x, y, label="Vehicle Speed", xlabel="Time (US/Mountain)", ylabel="km/h",
    width=600, height=300)
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Timestamp(
    timezone="US/Mountain", interval=(7, "minutes"))
5/1 08:145/1 08:215/1 08:285/1 08:355/1 08:425/1 08:49Time (US/Mountain)04080120km/hVehicle Speed

Toyplot supports common intervals in both singular and plural forms from seconds to millennia.

Finally, we might go in the opposite direction and show more detail in the timestamps. This is often a case where you’ll want to adjust the orientation of the labels so they don’t overlap (note in the following example that we had to make the canvas larger and position the axes manually on the canvas to make room for the angled labels - and we manually placed the x axis label to avoid overlap):

canvas = toyplot.Canvas(width=600, height=350)
axes = canvas.cartesian(bounds=(80, -80, 50, -120), label="Vehicle Speed", ylabel="km/h")
axes.plot(x, y)
axes.x.ticks.show = True
axes.x.ticks.locator = toyplot.locator.Timestamp(
    timezone="US/Mountain", format="{0:MMMM} {0:d}, {0:YYYY} {0:h}:{0:mm} {0:a}")
axes.x.ticks.labels.angle = 30
canvas.text(300, 320, "Time (US/Mountain)", style={"font-weight":"bold"});
May 4, 2014 8:10 amMay 4, 2014 8:15 amMay 4, 2014 8:20 amMay 4, 2014 8:25 amMay 4, 2014 8:30 amMay 4, 2014 8:35 amMay 4, 2014 8:40 amMay 4, 2014 8:45 amMay 4, 2014 8:50 am04080120km/hVehicle SpeedTime (US/Mountain)
_images/toyplot.png

Units

There are several places in Toyplot where you will need to specify quantities with real-world units, including canvas dimensions, font sizes, and target dimensions for document-oriented backends such as toyplot.pdf. For example, when creating a canvas, whether explicitly or implicitly through the Convenience API, you could specify its width and height in inches:

import numpy
x = numpy.linspace(0, 1)
y = x ** 2

import toyplot
toyplot.plot(x, y, width="3in", height="2in");
0.00.51.00.00.51.0

You can also specify the quantity and units separately:

toyplot.plot(x, y, width=(3, "in"), height=(2, "in"));
0.00.51.00.00.51.0

If you rendered either plot using the PDF backend, the resulting document size would be 3 inches × 2 inches.

If you don’t specify any units, the canvas assumes a default unit of CSS pixels:

toyplot.plot(x, y, width=600, height=400);
0.00.51.00.00.51.0

Note: You’re probably used to treating pixels as dimensionless; however CSS Pixels are always 1/96th of an inch. Thus, the above example would produce a PDF document that is 6.25 inches × 4.16 inches.

If you rendered the same canvas using the PNG or MP4 backends, it would produce 600 × 400 pixel images / movies. Put another way, the backends that produce raster images always assume 96 DPI, unless overridden by the caller.

Allowed Units

The units and abbreviations currently understood by Toyplot are as follows:

  • centimeters - “cm”, “centimeter”, “centimeters”
  • decimeters - “dm”, “decimeter”, “decimeters”
  • inches - “in”, “inch”, “inches”
  • meters - “m”, “meter”, “meters”
  • millimeters - “mm”, “millimeter”, “millimeters”
  • picas (1/6th of an inch) - “pc”, “pica”, “picas”
  • pixels (1/96th of an inch) - “px”, “pixel”, “pixels”
  • points (1/72nd of an inch) - “pt”, “point”, “points”

Functions that accept quantities with units as parameters will always accept them in either of two forms:

  • A string that combines the value and unit abbreviations: “5in”, “12px”, “25.4mm”.
  • A 2-tuple containing a number and string unit abbreviation: (5, “in”), (12, “px”), (25.4, “mm”).

In addition, some functions will also accept a single numeric value, with a documented default unit of measure (such as the canvas width and height discussed above).

Further, some functions may accept quantities with “%” as the units. In this case, the quantity will be relative to some other documented value.

Style Units

Toyplot style parameters always explicitly follow the CSS standard. As such, they support a subset of unit abbreviations including “cm”, “in”, “mm”, “pc”, “px”, and “pt”. Although CSS provides additional units for relative dimensioning, they assume that the caller understands their relationship to the underlying Document Object Model (DOM). Because Toyplot does not expose the DOM to callers and may change it at any time, these units are not supported.

_images/toyplot.png

Toyplot Case Studies

The following case studies provide more realistic, in-depth examples of how you might use Toyplot as part of a larger workflow:

_images/toyplot.png

Visualizing Community Detection in Graphs

The following explores how Toyplot’s graph visualization could be used to support development of a hypothetical new community detection algorithm:

Graph Data

First, we will load some sample graph data provided by Toyplot in three parts. The first part is an \(E \times 2\) matrix containing the source and target vertices for each of \(E\) graph edges:

import toyplot.data

edges, truth, assigned = toyplot.data.communities()
edges

array([[ 1,  2],
       [ 1,  3],
       [ 1,  4],
       [ 2,  3],
       [ 2,  4],
       [ 3,  4],
       [ 5,  6],
       [ 5,  7],
       [ 5,  8],
       [ 6,  7],
       [ 6,  8],
       [ 7,  8],
       [ 9, 10],
       [ 9, 11],
       [ 9, 12],
       [10, 11],
       [10, 12],
       [11, 12],
       [ 4,  5],
       [ 8,  9]])

Conveniently, Toyplot can display this matrix directly as a graph using a force-directed layout, and inducing the vertex labels from the edge data:

toyplot.graph(edges);
123456789101112

Ground Truth Communities

The second part of the data we loaded is a set of ground truth community assignments in the form of a \(V \times 2\) matrix containing the vertex ID and community ID for each of \(V\) vertices (note that in this case the assignments are already sorted in ID order, if they hadn’t been, we’d need to sort them explicitly):

truth

array([[ 1,  1],
       [ 2,  1],
       [ 3,  1],
       [ 4,  1],
       [ 5,  2],
       [ 6,  2],
       [ 7,  2],
       [ 8,  2],
       [ 9,  3],
       [10,  3],
       [11,  3],
       [12,  3]])

We want to color each graph vertex by its community ID, so we create an appropriate categorical colormap:

colormap = toyplot.color.brewer.map("Set2")
colormap

Now we can rerender the graph, overriding the default edge color, vertex size, vertex label style, and vertex color:

ecolor = "lightgray"
vlstyle = {"fill":"white"}
vcolor = truth[:,1]
toyplot.graph(edges, ecolor=ecolor, vsize=20, vlstyle=vlstyle, vcolor=(vcolor, colormap));
123456789101112

Assigned Communities

Next, we render the graph again using the third part of the loaded data: a different set of community ID values, generated using a hypothetical community detection algorithm that we are working on:

assigned

array([[ 1,  4],
       [ 2,  1],
       [ 3,  1],
       [ 4,  1],
       [ 5,  2],
       [ 6,  2],
       [ 7,  2],
       [ 8,  2],
       [ 9,  2],
       [10,  2],
       [11,  2],
       [12,  2]])

vcolor = assigned[:,1]
toyplot.graph(edges, ecolor=ecolor, vsize=20, vlstyle=vlstyle, vcolor=(vcolor, colormap));
123456789101112

We want to compare the ground truth communities with the communities assigned by our algorithm, but there are two challenges:

  • Flipping back-and-forth between the two visualizations and trying to understand what changed is extremely difficult.
  • Even if the algorithm we’re testing arrives at identical community memberships across the graph, it is unlikely that it would happen to assign the same ID for each community … so even in the best case, the vertex colors won’t match the ground truth.

What we need is a way to highlight the differences between the two sets of communities, so we only have to look at a single visualization. The following is suggested by Jon Berry at Sandia National Laboratories:

Highlighting Edge Types

We will render the graph using the vertex colors assigned by the algorithm, but with the edges colored using a set of rules that highlight the differences between the ground truth and assigned communities:

  • Edges that are intra-community in both ground truth and assigned communities remain light gray.
  • Edges that are inter-community in both ground truth and assigned communities remain light gray.
  • Edges that are intra-community in the ground truth but inter-community for the assigned communities are displayed red (i.e. the assignment split up a ground truth community).
  • Edges that are inter-community in the ground truth but intra-community for the assigned communities are displayed green (i.e. the assignment merged two ground-truth communities).
truth_map = dict(truth.tolist())
assigned_map = dict(assigned.tolist())

truth_source = [truth_map[vertex] for vertex in edges[:,0]]
truth_target = [truth_map[vertex] for vertex in edges[:,1]]

assigned_source = [assigned_map[vertex] for vertex in edges[:,0]]
assigned_target = [assigned_map[vertex] for vertex in edges[:,1]]

import numpy

# Default all edges to light gray.
ecolor = numpy.repeat("lightgray", len(edges))

selection = numpy.equal(truth_source, truth_target) & numpy.not_equal(assigned_source, assigned_target)
ecolor[selection] = "red"

selection = numpy.not_equal(truth_source, truth_target) & numpy.equal(assigned_source, assigned_target)
ecolor[selection] = "green"

canvas, axes, mark = toyplot.graph(edges, ecolor=ecolor, vsize=20, vlstyle=vlstyle, vcolor=(vcolor, colormap));
123456789101112

Now, we have a single visualization that emphasizes the differences between the two sets of community assignments, and we can clearly see the behavior of the tested algorithm: the green edge connecting vertices 8 and 9 indicate that two ground truth communities were merged together into one, while the red edges adjacent to vertex 1 show that it was “split” from its neighbors into its own community.

Now that that’s taken care of, we can create a publication-quality PDF version of the plot for incorporation into a paper:

import toyplot.pdf
toyplot.pdf.render(canvas, "communities.pdf")
_images/toyplot.png

Generating Neural Network Diagrams

The following explores how Toyplot’s graph visualization can be used to generate high-quality diagrams of neural networks.

Network Data

First, we will define the edges (weights) in our network, by explicitly listing the source and target for each edge:

import numpy
import toyplot

numpy.random.seed(1234)

edges = numpy.array([
    ["x0", "a0"],
    ["x0", "a1"],
    ["x0", "a2"],
    ["x0", "a3"],
    ["x1", "a0"],
    ["x1", "a1"],
    ["x1", "a2"],
    ["x1", "a3"],
    ["x2", "a0"],
    ["x2", "a1"],
    ["x2", "a2"],
    ["x2", "a3"],
    ["a0", "y0"],
    ["a0", "y1"],
    ["a1", "y0"],
    ["a1", "y1"],
    ["a2", "y0"],
    ["a2", "y1"],
    ["a3", "y0"],
    ["a3", "y1"],
])

Network Layout

As a straw-man, we can quickly render a graph using just the edge data:

canvas, axes, mark = toyplot.graph(edges)
a0a1a2a3x0x1x2y0y1

Clearly, this needs work - Toyplot’s default force-directed layout algorithm obscures the fact that our neural network is organized in layers. What we want is to put all of the x nodes in the first (input) layer, all of the a nodes in a second (hidden) layer, and all of the y nodes in the last (output) layer. Since Toyplot doesn’t have a graph layout algorithm that can do that for us, we’ll have to compute the vertex coordinates ourselves:

vertex_ids = numpy.unique(edges)

layer_map = {"x": 0, "a": -1, "y": -2}
offset_map = {"x": 0.5, "a": 0, "y": 1}
vcoordinates = []
for vertex_id in vertex_ids:
    layer = vertex_id[0]
    column = int(vertex_id[1:])
    x = column + offset_map[layer]
    y = layer_map[layer]
    vcoordinates.append((x, y))
vcoordinates = numpy.array(vcoordinates)

Now, we can see what the graph looks like with our explicitly defined coordinates:

canvas, axes, mark = toyplot.graph(edges, vcoordinates=vcoordinates)
a0a1a2a3x0x1x2y0y1

Vertex and Edge Styles

With the graph layout looking better, we can begin to work on the appearance of the vertices and edges:

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    tmarker=">",
    vcolor="white",
    vcoordinates=vcoordinates,
    vmarker="o",
    vsize=50,
    vstyle={"stroke":"black"},
    width=500,
    height=500,
)

# So we can control the aspect ratio of the figure using the canvas width & height
axes.aspect=None

# Prevent large vertex markers from falling outside the canvas
axes.padding=50
a0a1a2a3x0x1x2y0y1

In many cases, we might not want to see the vertex labels:

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    tmarker=">",
    vcolor="white",
    vcoordinates=vcoordinates,
    vlshow=False,
    vmarker="o",
    vsize=50,
    vstyle={"stroke":"black"},
    width=500,
    height=500,
)
axes.aspect=None
axes.padding=50

Or we might want to substitute our own, explicit vertex labels, to illustrate the values of individual activation units during network evaluation:

vertex_values = numpy.random.uniform(size=len(vertex_ids))
vertex_labels = ["%.2f" % value for value in vertex_values]

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    tmarker=">",
    vcolor="white",
    vcoordinates=vcoordinates,
    vlabel=vertex_labels,
    vmarker="o",
    vsize=50,
    vstyle={"stroke":"black"},
    width=500,
    height=500,
)
axes.aspect=None
axes.padding=50
0.190.620.440.790.780.270.280.800.96

Edge Weights

We might also want to display the network edge weights. Edge middle markers are a good choice to do this:

edge_weights = numpy.random.uniform(size=len(edges))
mstyle = {"fill": "white"}
lstyle = {"font-size": "12px"}
mmarkers = [toyplot.marker.create(shape="s", label="%.1f" % weight, size=30, mstyle=mstyle, lstyle=lstyle) for weight in edge_weights]

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    mmarker=mmarkers,
    tmarker=">",
    vcolor="white",
    vcoordinates=vcoordinates,
    vlabel=vertex_labels,
    vmarker="o",
    vsize=50,
    vstyle={"stroke":"black"},
    width=500,
    height=500,
)
axes.aspect=None
axes.padding=50
0.90.40.50.70.70.40.60.50.00.80.90.40.60.10.40.90.70.40.80.30.190.620.440.790.780.270.280.800.96

Note that the middle markers are aligned with the edges, making the weight values difficult to read. To fix this, we can set an explicit orientation for the middle markers:

mmarkers = [toyplot.marker.create(angle=0, shape="s", label="%.1f" % weight, size=30, mstyle=mstyle, lstyle=lstyle) for weight in edge_weights]

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    mmarker=mmarkers,
    tmarker=">",
    vcolor="white",
    vcoordinates=vcoordinates,
    vlabel=vertex_labels,
    vmarker="o",
    vsize=50,
    vstyle={"stroke":"black"},
    width=500,
    height=500,
)
axes.aspect=None
axes.padding=50
0.90.40.50.70.70.40.60.50.00.80.90.40.60.10.40.90.70.40.80.30.190.620.440.790.780.270.280.800.96

Now however, many of the middle markers overlap, making it appear as if there are fewer weights than edges. One way to address this is to randomly reposition the markers so that they rarely overlap:

mposition = numpy.random.uniform(0.1, 0.8, len(edges))

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    mmarker=mmarkers,
    mposition=mposition,
    tmarker=">",
    vcolor="white",
    vcoordinates=vcoordinates,
    vlabel=vertex_labels,
    vmarker="o",
    vsize=50,
    vstyle={"stroke":"black"},
    width=500,
    height=500,
)
axes.aspect=None
axes.padding=50
0.90.40.50.70.70.40.60.50.00.80.90.40.60.10.40.90.70.40.80.30.190.620.440.790.780.270.280.800.96

Note that the mposition argument is a value between zero and one that positions each middle marker anywhere along its edge from beginning to end, respectively.

Layer-Only Diagrams

Once a network reaches a certain level of complexity, it is typical to only diagram the layers in the network, instead of all the activation units. Here, we define per-layer data for a simple layer-only diagram:

layers = [
    "<b>conv1</b><br/>3&#215;3 convolutional",
    "<b>pool1</b><br/>max pooling",
    "<b>fc_1</b><br/>4096 dense",
    "<b>fc_2</b><br/>1000 dense softmax",
]

vertex_ids = numpy.arange(len(layers))

edges = numpy.column_stack((
    vertex_ids[:-1],
    vertex_ids[1:],
))

vcoordinates = numpy.column_stack((
    numpy.zeros_like(layers, dtype="float"),
    numpy.arange(0, -len(layers), -1),
    ))

In this case, it’s useful to use Toyplot’s special rectangular markers for the graph nodes:

canvas, axes, mark = toyplot.graph(
    edges,
    ecolor="black",
    tmarker=">",
    vcoordinates=vcoordinates,
    vlabel=layers,
    vmarker=toyplot.marker.create("r3x1", lstyle={"font-size":"12px"}, size=50),
    vstyle={"stroke":"black", "fill":"white"},
    width=200,
    height=400,
)
axes.padding = 50
conv13×3 convolutionalpool1max poolingfc_14096 densefc_21000 dense softmax
_images/toyplot.png

Projects Using Toyplot

The following projects are using Toyplot, either for final rendering or as a rendering back-end for domain-specific visualization:

Toytree

Toytree - http://toytree.readthedocs.io - is a tree manipulation and plotting library that aims to be rich in features but simple in design, by layering functionality atop Toyplot.

_images/toyplot.png

Contributing

Getting Started

If you haven’t already, you’ll want to get familiar with the Toyplot repository at http://github.com/sandialabs/toyplot … there, you’ll find the Toyplot sources, issue tracker, and wiki.

Next, you’ll need to install Toyplot’s Dependencies. Then, you’ll be ready to get Toyplot’s source code and use setuptools to install it. To do this, you’ll almost certainly want to use “develop mode”. Develop mode is a a feature provided by setuptools that links the Toyplot source code into the install directory instead of copying it … that way you can edit the source code in your git sandbox, and you don’t have to re-install it to test your changes:

$ git clone https://github.com/sandialabs/toyplot.git
$ cd toyplot
$ python setup.py develop

Versioning

Toyplot version numbers follow the Semantic Versioning standard.

Coding Style

The Toyplot source code follows the PEP-8 Style Guide for Python Code.

Running Regression Tests

To run the Toyplot test suite, simply run regression.py from the top-level source directory:

$ cd toyplot
$ python regression.py

The tests will run, providing feedback on successes / failures.

Writing Regression Tests

Note

Toyplot has been gradually transitioning from nose to behave for implementing regression tests. New tests should be added to the features directory using behave. The following outlines how the old tests were written, and will remain as a reference until they are all replaced.

Existing tests are located in tests/tests.py.

Many of the tests function by comparing the SVG representation of a toyplot.canvas.Canvas against a reference stored in tests/reference. These tests all end with a call to assert_canvas_matches(canvas, “test-name”), which compares the canvas to the file tests/reference/test-name.svg. The first time to you run a new test that uses assert_canvas_matches(), it will generate and store the new reference file, then fail, prompting you to examine the reference file to ensure that it’s correct. The next time you run the test, it will function normally, comparing the canvas against the reference file.

If you make changes that cause an existing test to fail, the failed SVG will be written to tests/failed/test-name.svg, so you can compare it against the corresponding reference SVG in tests/reference/test-name.svg.

Test Coverage

When you run the test suite with regression.py, it also automatically generates code coverage statistics. To see the coverage results, open .cover/index.html in a web browser.

Building the Documentation

To build the documentation, run:

$ cd toyplot
$ python docs/setup.py

Note that significant subsets of the documentation are written using Jupyter notebooks, so the docs/setup.py script requires Jupyter to convert the notebooks into restructured text files for inclusion with the rest of the documentation.

Once the documentation is built, you can view it by opening docs/_build/html/index.html in a web browser.

_images/toyplot.png

Release Notes

Toyplot 0.18.0 - December 24th, 2018

  • This will be the final release of Toyplot with Python 2 support!
  • Added unit and currency formatting classes, courtesy of @ben-cunningham and @dahuget.
  • Reduced code duplication in the toyplot.format module.
  • Canvas borders are supported in PDF output.
  • Improved output previewing toyplot.data.Table in Jupyter notebooks.
  • Added ellipse visualizations.
  • Added hyperlink support for bar visualizations.
  • Redesigned toyplot.mark.Rect as toyplot.mark.Range, and added range visualization on numberlines.
  • Converted all remaining regression tests from nose to behave.
  • toyplot.canvas.Canvas.matrix formats cell titles properly.
  • Redesigned regression tests to use the DOM for comparisons.
  • Documentation notebooks are included in regression testing.
  • Documentation notebooks are included in coverage testing.
  • toyplot.reportlab backend ignores hyperlinks instead of failing.

Toyplot 0.17.0 - April 1st, 2018

  • Moved sample datasets into the toyplot.data module.
  • toyplot.mp4.render() generates H.264 output.
  • Restored toyplot.canvas.AnimationFrame.set_datum_text(), which was broken by the debut of rich text.
  • Use the Python warnings module for deprecation warnings.
  • Disabled pylint testing on Travis-CI, it was too much of a moving target.
  • Simplified the animation API.
  • Switched to Python 3 as the primary build and test environment.
  • Removed obsolete dependencies from the Travis build.
  • Disabled PNG downscaling for ghostscript versions < 9.14.
  • Table cell data can be rotated.
  • Moved image manipulation into a new toyplot.bitmap module.
  • Added a bitdepth option to toyplot.bitmap.to_png().
  • Allow default canvas width and height to be set in toyplot.config.
  • Fixed a false-positive comparing XML documents.
  • Explicit colormap domains aren’t required for toyplot.canvas.matrix().

Toyplot 0.16.0 - October 26th, 2017

  • The -toyplot-anchor-shift property didn’t affect text layout extents correctly - thanks to Deren Eaton.
  • Corrected a broken link in the documentation - thanks to Github user @kannes.
  • Removed the dependency on colormath, which is currently broken by an API change in networkx.
  • Replaced toyplot.compatibility with six, since the latter is already a transitive dependency.
  • Replaced toyplot.color.near_black with toyplot.color.black
  • A hyperlink can be set for an entire canvas.
  • A hyperlink can be set for a set of Cartesian axes.
  • Per-datum hyperlinks can be set for scatterplots.
  • Moved documentation- and test-specific code out of the main library.
  • Set a reasonable stroke width when drawing text layout boxes for troubleshooting.
  • Clarified in the documentation how tick locators can affect the visible domain.
  • Corrected copy-n-paste errors in many docstrings.
  • Fixed many broken documentation crosslinks.
  • Supplied many missing docstrings.
  • Removed the WebM rendering backend, which has been broken and unused for a long time.

Toyplot 0.15.1 - July 27, 2017

  • Markers can be embedded in any text, including tick marks, legends, labels, and table contents.
  • Hyperlinks can be embedded in any text using the <a href=”…”> tag.
  • Legends are implemented using table coordinates, so legends can be customized using any table feature.
  • Started a new documentation section for case-studies, with graph community and neural network examples.
  • Started a new section in the documentation for projects using Toyplot.
  • Callers can define their own custom marks, and modify rendering for existing marks, using the new rendering API.
  • Defined a new API for embedding Javascript in HTML markup, for use with custom marks.
  • Graph visualizations can export vertex and edge data as CSV tables.
  • Added support for head, middle, and tail markers on graph edges.
  • Added an offset property for Cartesian axis labels.
  • Toyplot colors are allowed as style property values.
  • Per-series and per-datum colors can be specified using Python sequences as well as numpy arrays.
  • Error messages specify which CSS properties are allowed.
  • Deprecated the gutter parameter in favor of margin, which can specify separate left / right / top / bottom margins, if desired.
  • Added toyplot.html.tostring() to simplify generating HTML.
  • Added a style option to toyplot.html.render() and toyplot.html.tostring().
  • Added a palette argument to override the default series palette when creating axes.
  • Text markup didn’t include units for font-size, causing incorrect results on Firefox.

Toyplot 0.14.0 - April 17, 2017

  • Completely new text layout that explicitly positions all text.
  • Experimental support for hyperlinks in table cells.
  • Return a scalar instead of an array when accessing toyplot.data.Table using a single column name and row index.
  • Correct a bug that caused text baselines to be computed incorrectly in PDF output.
  • Add pylint to the regression test suite.
  • Allow font-family to be used in inline rich text styles.
  • Created an API to retrieve font metrics.
  • Disable obnoxious colormath logging by default.
  • Mention XML escaping for rich text in the user guide.
  • The “<” and “>” markers were rendered reversed.
  • Eliminate warnings using a Pandas series as the baseline for a bar plot.
  • Make it easier to disable graph vertex labels.
  • Allow stroke-linecap for CSS line styles.
  • Improve rasterized PNG output quality.
  • Warn when using older versions of ghostscript that produce lower-quality PNG output.
  • Suppress the “No handlers could be found for logger toyplot” warning.
  • Rewrote the logic for detecting Ghostscript.

Toyplot 0.13.0 - July 22, 2016

  • Allow fill marks to be used as annotation.
  • Explicitly disable data export from annotation marks.
  • Add an experimental <axis>.domain.show parameter to control whether the domain is displayed using axis spines.
  • toyplot.data.read_csv(convert=True) will try to parse integer as well as floating-point types.
  • Completely rewrote the table coordinates implementation.
  • Table coordinates support advanced, numpy-style indexing for all rows, columns, cells, gridlines, and gaps.
  • Added API to delete table coordinate rows and columns.
  • Added API to insert table coordinate rows and columns.
  • By default, all table cells are vertically and horizontally centered with a default font.
  • Matrix visualizations no longer bold row and column indices by default.
  • End-users can export CSV data from table coordinates and matrix visualizations.
  • Added table-cell bar plots and line plots that use the data already contained in the table.

Toyplot 0.12.0 - May 27, 2016

  • Pandas data frame indices (including hierarchical indices) can optionally be included when converting to toyplot.data.Table.
  • Fixed a Python 3 portability issue.
  • Table coordinates didn’t format NaN values properly when using a custom formatting string.
  • The arrow module is only imported when needed.
  • New documentation on grouping table rows.
  • Documented platform-specific timezone naming issues.
  • Improved documentation of the color factory objects in toyplot.color.
  • Use consistent naming for numberline coordinates.
  • Made it easier to iterate over toyplot.data.Table rows.
  • Interactive mouse coordinates work correctly with numberlines and shared axes, and are only displayed by click / touch events.
  • Position ticks relative to axes with a location property, and deprecate the tick labels location property.
  • Fixed a problem rendering bars with a log scale and nonzero domain minimum.
  • Removed the API to change text during animation.
  • Significant cleanup and organization of HTML backend code and generated markup.
  • Renamed the toyplot.axes module to toyplot.coordinates for consistency, clarity.
  • Added toyplot.canvas.Canvas.cartesian() and deprecated toyplot.canvas.Canvas.axes().
  • Added toyplot.locator.Uniform and deprecated toyplot.locator.Basic.
  • Added documentation links to external libraries, where practical.
  • Added text-shadow to the list of valid CSS text attributes.
  • Updated dependencies to require numpy >= 1.8.0, and eliminated code that inadvertently depended on numpy >= 1.9.
  • Experimental support for displaying PIL and scikit-image images.
  • Added a style property to toyplot.canvas.Canvas.
  • Deprecated implicit conversion from palettes to colormaps for matrix visualization.
  • Provide better error messages if a caller passes anything but a canvas to a rendering backend.
  • Add support for multi-series marks in legends.
  • Updated links to point to our new documentation domain, http://toyplot.readthedocs.io.
  • Axis labels support the same location and offset parameterization as axis ticks / tick labels.

Toyplot 0.11.0 - February 18, 2016

  • Added more complex indexing / slicing options to toyplot.data.Table.
  • Deprecated toyplot.data.Table.rows() and toyplot.data.Table.columns().
  • Removed support for custom markers.
  • -toyplot-anchor-shift didn’t work correctly with rotated text.
  • Documented text alignment behavior for rotated text.
  • Added location parameter for axis labels.
  • Improved text alignment defaults for rotated and unrotated axis labels.
  • Don’t alter the axis domain if tick labels aren’t visible.
  • Change the default linear color map to a diverging blue-red palette.
  • Pandas data frames with duplicate column names can be converted to toyplot.data.Table.
  • Allow callers to suppress NaNs in table visualization cells.
  • Render color arrays as swatches in Jupyter notebooks.
  • Added toyplot.color.brewer.palette(), toyplot.color.brewer.map(), and toyplot.color.diverging.map().
  • Deprecated toyplot.color.brewer() and toyplot.color.diverging().
  • toyplot.color.LinearMap color stops can be explicitly positioned.
  • Added toyplot.color.linear.map() with “Blackbody”, “ExtendedBlackbody”, “Kindlmann” and “ExtendedKindlmann” color maps.
  • Deprecated implicit conversions from color palettes to color maps during color mapping.
  • Split color-related documentation into separate “Color” and “Color Mapping” sections of the user guide.
  • Improved debugging output when a regression test fails.
  • Many code coverage improvements.

Toyplot 0.10.0 - January 12, 2016

  • Added rich text support, using a limited subset of HTML markup.
  • Added a tick locator for displaying timestamp data with properly formatted times.
  • Created a new, pure-Python PDF backend using ReportLab.
  • Created a new PNG backend that renders by rasterizing PDFs with Ghostscript.
  • Removed deprecated PDF and PNG backends.
  • Added numberline axes, for displaying one-dimensional data.
  • Refactored the scatterplot mark to support data with any number of dimensions.
  • Added one-dimensional scatterplot support to numberlines.
  • Completely redesigned the color scale implementation to use numberlines.
  • Added API for easily adding color scales to axes and matrix visualizations.
  • Provided both size and area parameters to specify marker sizes.
  • Moved log scales to a dedicated section of the user guide.
  • Optimized graph layout when every vertex already has a position.
  • Removed the GraphViz graph layout strategy.
  • Use consistent naming for matrix visualization parameters.
  • toyplot.data.read_csv() can optionally convert string values to numeric values.
  • Replaced toyplot.color.lighten() with toyplot.color.spread(), which is more flexible.
  • Display toyplot color values as swatches in Jupyter notebooks.
  • Expanded the color documentation in the user guide.
  • Reduced regression test boilerplate code.
  • Test coverage improvements.

Toyplot 0.9.0 - November 22, 2015

  • Documented installation for Anaconda and FreeBSD.
  • Experimental support for graph visualization, with flexible layout algorithms, shared layouts and node “pinning”.
  • Allow cartesian axes to fill the available range while maintaining their aspect ratio.
  • Axis ticks can extend above or below the axis spine.
  • Positioning an axis spine positions its ticks and tick labels as well.
  • Added support for shared axes / multiple axes, to display multiple overlapping domains in a single plot.
  • Format specifiers are available for the Extended and Heckbert tick locators, courtesy of Johann du Toit.
  • Began using pylint as a regular code quality check.
  • Pandas data frames are automatically converted when creating data tables / table axes.
  • Created a new default PDF backend using the ReportLab library.
  • Switched to toyplot.qt.png as the default PNG backend.
  • Provide better feedback when using the toyplot.pdf and toyplot.png meta backends.

Toyplot 0.8.0 - September 7, 2015

  • Removed deprecated colormap and palette parameters from the API.
  • Allow simplified color mapping specifications.
  • Improved test coverage.
  • Fix a problem embedding embedding axes in tables using more than one merged cell.
  • Add table cell width / height support for real-world units.
  • Hide masked values in table axes.
  • Reorganize the installation documentation.
  • Add support for rotated text in table cells.
  • Add top/bottom/left/right label support for matrix visualizations.
  • Add new toyplot.locator.Null do-nothing tick locator.
  • Add matrix visualization support for right / bottom ticks.
  • Add custom locator support for matrix visualizations.
  • Make matrix visualization color parameters consistent with the rest of the API.
  • Add missing reference documentation for toyplot.projection module.
  • Cleanup the toyplot.color.broadcast(…) API and implementation.
  • Make the API for specifying color mapping consistent across all visualization types.
  • Allow per-datum titles on line plots and scatterplots.
  • Expand the color section in the user guide to cover color mapping.
  • Add a new section on null data to the user guide.
  • Eliminate nuisance warnings from numpy.
  • Automatically validate source notebooks as part of the documentation build.

Toyplot 0.7.0 - August 12, 2015

  • Added a user guide section on embedding plots.
  • Added a user guide example of datetime objects as tick labels.
  • Make the Toyplot sourcecode fully PEP-8 conforming - thanks to Chris Morgan.
  • Worked around problems with numpy.broadcast_arrays() in numpy 1.8.
  • Removed LaTeX table formatting functionality that was replaced by table axes.
  • Added a new backend to display figures in a standalone Qt window.
  • Switched to the Python logger module for warnings / errors.
  • Updated the public API for specifying scalar color palettes / maps, and deprecated separate color palette / map API parameters.
  • Changed the way we encode opacities, for compatibility with Inkscape and Adobe Illustrator.
  • Removed the obsolete toyplot.selenium backend.
  • Treat hlines() and vlines() as annotation (so they don’t affect the data domain), unless the caller specifies otherwise.
  • Created new Qt backends to generate PDF and PNG figures.
  • Figures can be resized consistently across all browsers, particularly Firefox and IE.
  • Reorganized the backend documentation, and explicitly documented the distinction between backends and displays.
  • Fixed a case where canvas resizing didn’t handle explicit units correctly.
  • Added a new section on interaction to the user guide.
  • Allow figure creators to override the default filename when users export data from an interactive figure.
  • Significant changes to our travis-ci.org test environment.
  • toyplot.data.Table.matrix() didn’t work in Python 3.
  • Removed toyplot.data.Table.to_csv(), we want to discourage people from using Toyplot for data manipulation.
  • Many objects didn’t render properly in Jupyter notebooks with Python 3.
  • Added parameters to disable the row and column labels in matrix visualizations.

Toyplot 0.6.0 - July 13, 2015

  • Unicode text wasn’t handled correctly by text marks.
  • Added an experimental matrix visualization using table axes.
  • Added a “title” property for table cells.
  • Fix inconsistencies in our use of alignment-baseline and text-anchor CSS properties.
  • Added a new section to the user guide on the convenience API.
  • Allow real-world units for canvas layouts, and tweak the parameter order for corner layouts.
  • Expanded user guide documentation on canvas layouts.
  • Added table axes regions for all four sides and corners, plus a property to access every cell in a region.
  • Added automatic conversion from numpy NpzFile to toyplot.data.Table.
  • Added experimental support for graph visualization.
  • Allow toyplot.data.Table initialization from a sequence of 2-tuples.
  • Cairo backends were ignoring -toyplot-anchor-shift.
  • Cairo backends didn’t handle all supported alignment-baseline values.
  • Added matrix and table visualizations to the convenience API.
  • Added accessors for shape, row count, and column count for table axes and regions.
  • Added toyplot.locator.Integer, and a step parameter to control labelling for matrix visualizations.
  • Always return a unicode string from toyplot.canvas.Canvas._repr_html_(), for compatibility with Jupyter / IPython notebooks running Python 3 kernels.
  • Assign a sensible default filename for CSV downloads, for browsers that support it.
  • Added a contributed Conda build recipe.
  • Allow toyplot.data.Table to be initialized from a 2D numpy array.
  • Rename the toyplot.axes.Table “title” parameter to “label” for consistency with the other axes.
  • Added a new “Labels and Legends” section to the user guide.
  • Added a new “Tick Locators” section to the user guide.
  • Added experimental toyplot.data.contiguous() function to identify contiguous ranges in an array.
  • Fix a problem with interactive Y coordinates when using a log scale that straddled the origin.

Toyplot 0.5.0 - May 26, 2015

  • Switched to https://travis-ci.org/sandialabs/toyplot for continuous integration testing.
  • Switched to https://coveralls.io/r/sandialabs/toyplot to track test coverage.
  • Added a custom CSS style -toyplot-anchor-shift for controlling horizontal text offsets.
  • Added new documentation on color, text alignment, units, data tables, and table axes to the user guide.
  • Callers can increase the number of table rows and columns when creating table axes from a data table.
  • Overhauled Toyplot’s handling of real-world units, allowing arbitrary units throughout the API, and made it explicit that the default canvas units are CSS pixels.
  • Added axis visibility options to the convenience API.
  • toyplot.data.Table can be converted to a numpy matrix.
  • Positive angles yield counterclockwise rotation throughout the API, for consistency with trigonometry.
  • Rendered text automatically expands a plot’s domain to avoid clipping.
  • Fixed a longstanding problem displaying mouse coordinates outside the data domain for a plot.
  • Moved interaction-specific markup from the SVG backend to the HTML backend.
  • When exporting data from a figure, only the caller-supplied data is exported.
  • The API makes an explicit distinction between text used for “annotation” and text used for data.
  • Many small fixes.

Toyplot 0.4.0 - January 27, 2015

  • Began continuous integration testing.
  • Switched from ost.io to https://gitter.im/sandialabs/toyplot for support requests.
  • Made the HTML backend the primary renderer.
  • Improved logarithmic tick formatting and customization.
  • Increased consistency between the fill() and plot() APIs.
  • Simplified the way colors are inherited for line plots and scatter plots.
  • Added basic functionality for reading and writing CSV files.
    • Note: for pedagical purposes only - Toyplot is not a data manipulation tool!
  • Ongoing improvements to the table axes API:
    • Added support for table titles.
    • Added support for hiding table headers.
    • Table headers can have multiple rows.
    • Ensure that visible cells are rendered in a deterministic order.
    • Create a default grid line between table header and body.
    • Added support for user-configurable gaps between cells.

Toyplot 0.3.0 - November 5, 2014

  • Switched to toyplot.data.Table for all internal data storage.
  • Reorganized the codebase into smaller, more focused modules.
  • Added a new backend to produce WebM video.
  • Data tables can be rendered to LaTeX.
  • New table axes for rendering tables as data graphics.

Toyplot 0.2.0 - September 2, 2014

  • Introduced support for Python 3.
  • Removed pure black from the default styling.
  • Allow regression tests to run without optional dependencies.

Toyplot 0.1.0 - August 25, 2014

a Initial Release

_images/toyplot.png

Python API

toyplot module

Provides the top-level Convenience API, which allows you to create many plots using a single compact statement.

exception toyplot.DeprecationWarning[source]

Bases: Warning

Used with warnings.warn() to mark deprecated API.

toyplot.bars(a, b=None, c=None, along='x', baseline='stacked', color=None, filename=None, height=None, hyperlink=None, label=None, margin=50, opacity=1.0, padding=10, show=True, style=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale='linear', xshow=True, ylabel=None, ymax=None, ymin=None, yscale='linear', yshow=True)[source]

Convenience function for creating a bar plot in a single call.

See toyplot.coordinates.Cartesian.bars(), toyplot.canvas.Canvas.cartesian(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.fill(a, b=None, c=None, along='x', baseline=None, color=None, filename=None, height=None, label=None, margin=50, opacity=1.0, padding=10, show=True, style=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale='linear', xshow=True, ylabel=None, ymax=None, ymin=None, yscale='linear', yshow=True)[source]

Convenience function for creating a fill plot in a single call.

See toyplot.coordinates.Cartesian.fill(), toyplot.canvas.Canvas.cartesian(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.graph(a, b=None, c=None, along='x', ecolor=None, eopacity=1.0, estyle=None, ewidth=1.0, height=None, hmarker=None, layout=None, margin=50, mmarker=None, mposition=0.5, olayout=None, padding=20, tmarker=None, varea=None, vcolor=None, vcoordinates=None, vlabel=None, vlshow=True, vlstyle=None, vmarker='o', vopacity=1.0, vsize=None, vstyle=None, vtitle=None, width=None)[source]

Convenience function for creating a graph plot in a single call.

See toyplot.coordinates.Cartesian.graph(), toyplot.canvas.Canvas.cartesian(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.image(data, height=None, margin=0, width=None)[source]

Convenience function for displaying an image in a single call.

See toyplot.canvas.Canvas.image(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.matrix(data, blabel=None, blocator=None, bshow=None, colorshow=False, filename=None, height=None, label=None, llabel=None, llocator=None, lshow=None, margin=50, rlabel=None, rlocator=None, rshow=None, step=1, tlabel=None, tlocator=None, tshow=None, width=None)[source]

Convenience function to create a matrix visualization in a single call.

See toyplot.canvas.Canvas.matrix(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.plot(a, b=None, along='x', area=None, aspect=None, color=None, filename=None, height=None, label=None, margin=50, marker=None, mfill=None, mlstyle=None, mopacity=1.0, mstyle=None, mtitle=None, opacity=1.0, padding=10, show=True, size=None, stroke_width=2.0, style=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale='linear', xshow=True, ylabel=None, ymax=None, ymin=None, yscale='linear', yshow=True)[source]

Convenience function for creating a line plot in a single call.

See toyplot.coordinates.Cartesian.plot(), toyplot.canvas.Canvas.cartesian(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.scatterplot(a, b=None, along='x', area=None, aspect=None, color=None, filename=None, height=None, hyperlink=None, label=None, margin=50, marker='o', mlstyle=None, mstyle=None, opacity=1.0, padding=10, show=True, size=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale='linear', xshow=True, ylabel=None, ymax=None, ymin=None, yscale='linear', yshow=True)[source]

Convenience function for creating a scatter plot in a single call.

See toyplot.coordinates.Cartesian.scatterplot(), toyplot.canvas.Canvas.cartesian(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:
toyplot.table(data=None, brows=None, columns=None, filename=None, height=None, label=None, lcolumns=None, margin=50, rcolumns=None, rows=None, trows=None, width=None)[source]

Convenience function to create a table visualization in a single call.

See toyplot.canvas.Canvas.table(), and toyplot.canvas.Canvas for parameter descriptions.

Returns:

toyplot.bitmap module

Bitmap management and manipulation.

toyplot.bitmap.to_png(data, stream, bitdepth=None)[source]

Convert an in-memory bitmap to PNG format.

Parameters:
  • data (numpy.ndarray, required) – Source array containing bitmap data to be converted. Valid array shapes are \(M \times N \times 1\) (greyscale data), \(M \times N \times 2\) (greyscale plus alpha channel), \(M \times N \times 3\) (RGB data), or \(M \times N \times 4\) (RGB + alpha). Floating point values are scaled and converted to unsigned 8 bit integers.
  • stream (file-like object, required) – Target file to receive PNG data.
  • bitdepth (integer, optional) – Override the default output bit depth. Allowed color / bitdepth combinations are: greyscale (1/2/4/8/16), greyscale + alpha (8/16), RGB (8/16), and RGB + alpha (8/16).
toyplot.bitmap.to_png_data_uri(data)[source]

Convert an in-memory bitmap to PNG format, encoded as a data: URI.

Parameters:data (numpy.ndarray, required) – Source array containing bitmap data to be converted. Valid array shapes are \(M \times N \times 1\) (greyscale data), \(M \times N \times 2\) (greyscale plus alpha channel), \(M \times N \times 3\) (RGB data), or \(M \times N \times 4\) (RGB + alpha). Floating point values are scaled and converted to unsigned 8 bit integers.
Returns:uri – A data: URI containing the base64 encoded bitmap.
Return type:str

toyplot.broadcast module

Functions for broadcasting values into 1D or 2D arrays.

The functions in this module are used by Toyplot to handle the conversion from constant, per-series, and per-datum values into their canonical 1D and 2D array representations.

toyplot.broadcast.pyobject(value, shape)[source]

Return a 1D or 2D array of objects with the given shape.

Parameters:shape ((tuple)) – Shape of the desired output array. A 1-tuple will produce a 1D output vector containing \(N\) per-series values. A 2-tuple will produce an \(M \times N\) output matrix of per-datum values grouped into \(N\) series.
Returns:array
Return type:numpy.ndarray
toyplot.broadcast.scalar(value, shape)[source]

Return a 1D or 2D array of floats with the given shape.

Parameters:shape ((tuple)) – Shape of the desired output array. A 1-tuple will produce a 1D output vector containing \(N\) per-series values. A 2-tuple will produce an \(M \times N\) output matrix of per-datum values grouped into \(N\) series.
Returns:array
Return type:numpy.ndarray

toyplot.browser module

Functionality for displaying a Toyplot canvas in a web browser.

toyplot.browser.show(canvases, title='Toyplot Figure')[source]

Display one or more canvases in a web browser.

Uses Toyplot’s preferred HTML+SVG+Javascript backend to display one-or-more interactive canvases in a web browser window.

Because the canvases are displayed in a separate web browser process, this function returns immediately.

Parameters:

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.

begin

Beginning of the current frame in seconds.

count

Total number of frames in the current animation.

end

End of the current frame in seconds.

length

Duration of the current frame in seconds.

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

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, 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”, <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, 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.
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.

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)[source]

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)[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”, <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
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, 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
width

Width of the canvas in CSS pixels.

toyplot.color module

Functionality for managing colors, palettes, and color maps.

class toyplot.color.BrewerFactory[source]

Bases: object

Creates Toyplot color palettes and maps based on the Color Brewer 2.0 palettes.

category(name)[source]

Return the category for the given palette.

counts(name)[source]

Return a list of available palette sizes.

map(name, count=None, reverse=False, center=None, domain_min=None, domain_max=None)[source]

Return a color map that uses the given Color Brewer 2.0 palette.

Returns:colormap
Return type:toyplot.color.LinearMap or toyplot.color.CategoricalMap, depending on the palette category.
maps(category=None)[source]

Return a (name, colormap) tuple for every Color Brewer 2.0 palette.

The type of the returned colormaps will be chosen based on the category of each palette.

Parameters:category (str, optional) – If specified, only return palettes from the given category.
Returns:palettes
Return type:sequence of (str, toyplot.color.Map) tuples.
names(category=None)[source]

Return a list of available palette names.

palette(name, count=None, reverse=False)[source]

Construct a toyplot.color.Palette instance from a ColorBrewer 2.0 palette.

Note that some of the sequential palettes have been renamed / reversed so that low-luma colors are always mapped to low values and high-luma colors are always mapped to high values.

Parameters:
  • name (str) – The name of the ColorBrewer 2.0 palette.
  • count (integer, optional) – The number of values in the palette. If unspecified, the named palette with the largest number of values is returned.
  • reverse (boolean, optional) – If True, the values in palette will be stored in reverse order.
Returns:

palette
Return type:

toyplot.color.Palette
palettes(category=None)[source]

Return a (name, palette) tuple for every Color Brewer 2.0 palette.

Parameters:category (str, optional) – If specified, only return palettes from the given category.
Returns:palettes
Return type:sequence of (str, toyplot.color.Palette) tuples.
class toyplot.color.CategoricalMap(palette=None)[source]

Bases: toyplot.color.Map

Maps 1D categorical values (nonnegative integers) to colors.

Parameters:palette (an instance of toyplot.color.Palette) – Defines the set of colors used by the map.

Notes

Categorical maps are displayed as a collection of color swatches when viewed in a Jupyter notebook.

color(index, domain_min=None, domain_max=None)[source]

Return one color from the map.

Parameters:index (nonnegative integer) – Specifies the index of the color to retrieve. Note that the palette repeats infinitely, so any nonnegative integer value will return a color from the palette.
Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
colors(values, domain_min=None, domain_max=None)[source]

Convert a sequence of categorical (nonnegative integer) values to colors.

Each value is mapped to a color in the underlying palette. Note that the palette repeats infinitely, so any nonnegative integer value will return a color from the palette.

Parameters:values (array-like collection of nonnegative integers)
Returns:colors
Return type:numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype and the same shape as values.
css(index, domain_min=None, domain_max=None)[source]

Return the CSS representation of one color from the map.

Parameters:index (nonnegative integer) – Specifies the index of the color to retrieve. Note that the palette repeats infinitely, so any nonnegative integer value will return a color from the palette.
Returns:css
Return type:str containing a CSS color.
class toyplot.color.DivergingFactory[source]

Bases: object

Creates high-quality diverging color maps by name.

map(name, domain_min=None, domain_max=None)[source]

Construct a named toyplot.color.DivergingMap instance.

Parameters:name (str) – The name of the map. Use toyplot.color.DivergingFactory.names() to retrieve a list of available names.
Returns:map
Return type:toyplot.color.DivergingMap
maps()[source]

Return a (name, colormap) tuple for every map in the collection.

Returns:palettes
Return type:sequence of (str, toyplot.color.DivergingMap) tuples.
names()[source]

Return a list of available map names.

class toyplot.color.DivergingMap(low=None, high=None, domain_min=None, domain_max=None)[source]

Bases: toyplot.color.Map

Maps 1D values to colors using a perceptually-uniform diverging color map.

Based on “Diverging Color Maps for Scientific Visualization”, Kenneth Moreland, http://www.sandia.gov/~kmorel/documents/ColorMaps

Values within the domain specified at construction time are mapped to the colors in the underlying palette. Values outside the domain are clamped to the minimum / maximum domain values. If unspecified, the domain will be computed on-the-fly every time toyplot.color.DivergingMap.colors() is called.

Parameters:
  • low (Toyplot color, optional) – Defines the color used to represent low values.
  • high (Toyplot color, optional) – Defines the color used to represent high values.
  • domain_min (scalar, optional)
  • domain_max (scalar, optional)

Notes

Diverging maps generate a color preview when viewed in a Jupyter notebook.

color(value, domain_min=None, domain_max=None)[source]

Convert one value to a color.

Parameters:value (scalar value)
Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
colors(values, domain_min=None, domain_max=None)[source]

Convert an array-like collection of values to colors.

Parameters:values (array-like collection of scalar values)
Returns:colors
Return type:numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype and the same shape as values.
css(value, domain_min=None, domain_max=None)[source]

Convert one value to a CSS representation of its color.

Parameters:value (scalar value)
Returns:css
Return type:str containing a CSS color.
class toyplot.color.LinearFactory[source]

Bases: object

Creates high-quality linear color maps by name.

map(name, domain_min=None, domain_max=None)[source]

Construct a named toyplot.color.LinearMap instance.

Parameters:name (str) – The name of the map. Use toyplot.color.LinearFactory.names() to retrieve a list of available names.
Returns:map
Return type:toyplot.color.LinearMap
maps()[source]

Return a (name, colormap) tuple for every map in the collection.

Returns:palettes
Return type:sequence of (str, toyplot.color.DivergingMap) tuples.
names()[source]

Return a list of available map names.

class toyplot.color.LinearMap(palette=None, stops=None, center=None, domain_min=None, domain_max=None)[source]

Bases: toyplot.color.Map

Maps 1D values to colors.

Values within the domain specified at construction time are mapped to the colors in the underlying palette. Values outside the domain are clamped to the minimum / maximum domain values. If unspecified, the domain will be computed on-the-fly each time toyplot.color.LinearMap.colors() is called.

Parameters:
  • palette (toyplot.color.Palette) – Specify the set of colors used by the map.
  • stops (sequence of scalars, one per palette color, optional) – Specify a “stop” in the range [0, 1] for each palette color. By default the stops are evenly spaced.
  • center (scalar, optional) – If specified, map [domain_min, center] to the first half of the color palette, and [center, domain_max] to the second half of the palette. This is useful for diverging palettes when there is a domain-specific critical value that should fall in the middle of the color range, such as zero or a mean or median.
  • domain_min (scalar, optional)
  • domain_max (scalar, optional)

Notes

Linear maps are displayed as a color preview of their domain when viewed in a Jupyter notebook.

color(value, domain_min=None, domain_max=None)[source]

Convert one value to a color.

Parameters:value (scalar value)
Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
colors(values, domain_min=None, domain_max=None)[source]

Convert an array-like collection of values to colors.

Parameters:values (array-like collection of scalar values)
Returns:colors
Return type:numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype and the same shape as values.
css(value, domain_min=None, domain_max=None)[source]

Convert one value to a CSS representation of its color.

Parameters:value (scalar value)
Returns:css
Return type:str containing a CSS color.
class toyplot.color.Map(domain_min, domain_max)[source]

Bases: object

Abstract interface for objects that map scalar values to colors.

class DomainHelper(domain_min, domain_max)[source]

Bases: object

Interface to get / set the domain for a toyplot.color.Map.

max

Maximum domain value.

min

Minimum domain value.

domain

Accessor for the map’s domain.

Returns:domain – Provides access to the minimum and maximum domain values for the map.
Return type:toyplot.color.Map.DomainHelper
class toyplot.color.Palette(colors=None, reverse=False)[source]

Bases: object

Storage for an ordered collection of colors.

Parameters:
  • colors (sequence of color values, optional) – Specifies the list of color values to store in the palette. Each color may be a CSS color string, a Toyplot color, a sequence of three RGB values, or a sequence of four RGBA values. If colors is unspecified, the palette will be initialized with a default collection of colors.
  • reverse (boolean, optional) – If True, the values in colors will be stored in reverse order.

Notes

You can iterate over the colors in a Palette using normal Python iteration.

Palettes are displayed as a collection of color swatches when viewed in a Jupyter notebook.

color(index)[source]

Return one color from the palette.

Parameters:index (integer) – Specifies the index of the color to retrieve.
Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
css(index)[source]

Return the CSS representation of one color from the palette.

Parameters:index (integer) – Specifies the index of the color to retrieve.
Returns:css
Return type:str containing a CSS color.
toyplot.color.black = '#292724'

Default color used throughout Toyplot figures.

toyplot.color.brewer = <toyplot.color.BrewerFactory object>

Instance of toyplot.color.BrewerFactory

Use this to create Toyplot color palettes and maps based on the Color Brewer 2.0 palettes.

toyplot.color.broadcast(colors, shape, default=None)[source]

Return a 1D or 2D array of colors with the given shape.

Parameters:shape (tuple) – Shape of the desired output array. A 1-tuple will produce a 1D output array containing \(N\) per-series colors. A 2-tuple will produce an \(M \times N\) output matrix of per-datum colors grouped into \(N\) series.
Returns:colors
Return type:One- or two-dimensional numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype.
toyplot.color.css(value)[source]

Construct a Toyplot color from a CSS string.

Parameters:value (str)
Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
toyplot.color.diverging = <toyplot.color.DivergingFactory object>

Instance of toyplot.color.DivergingFactory

Use this to create Toyplot diverging color maps by name.

toyplot.color.dtype = {'formats': ['float64', 'float64', 'float64', 'float64'], 'names': ['r', 'g', 'b', 'a']}

Data type for storing RGBA color information in numpy.ndarray instances.

toyplot.color.lab(l, a, b)[source]

Construct a Toyplot color from CIE Lab values.

toyplot.color.linear = <toyplot.color.LinearFactory object>

Instance of toyplot.color.LinearFactory

Use this to create Toyplot linear color maps by name.

toyplot.color.near_black = '#292724'

Deprecated, use toyplot.color.black instead.

toyplot.color.rgb(r, g, b)[source]

Construct a Toyplot color from RGB values.

Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
toyplot.color.rgba(r, g, b, a)[source]

Construct a Toyplot color from RGBA values.

Returns:color
Return type:numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.
toyplot.color.spread(color, count=5, lightness=0.9, reverse=False)[source]

Create a palette by progressively altering an initial color.

toyplot.color.to_css(color)[source]

Convert a Toyplot color to a CSS string.

Parameters:color (numpy.ndarray) – Array of RGBA values with dtype = toyplot.color.dtype, which is converted to a CSS rgba() color.
Returns:css
Return type:str containing a CSS color value.
toyplot.color.to_lab(color)[source]

Convert a Toyplot color to a CIE Lab color.

toyplot.color.to_xyz(color)[source]

Convert a Toyplot color to a CIE XYZ color using observer = 2 deg and illuminant = D65.

toyplot.color.xyz(x, y, z)[source]

Construct a Toyplot color from CIE XYZ values, using observer = 2 deg and illuminant = D65.

toyplot.config module

Provides global configuration for Toyplot figures.

You can write to the attributes in toyplot.config if you wish to change the default behaviors for multiple figures.

toyplot.config.autoformat = 'html'

Default value for the toyplot.canvas.Canvas autoformat feature.

toyplot.config.autorender = True

Default value for the toyplot.canvas.Canvas autorender feature.

toyplot.config.height = None

Default value for the toyplot.canvas.Canvas height.

toyplot.config.width = None

Default value for the toyplot.canvas.Canvas width.

toyplot.coordinates module

Classes and functions for working with coordinate systems.

class toyplot.coordinates.Axis(label=None, domain_min=None, domain_max=None, scale='linear', show=True, tick_angle=0, tick_locator=None)[source]

Bases: object

One dimensional axis that can be used to create coordinate systems.

class DomainHelper(domain_min, domain_max)[source]

Bases: object

Controls domain related behavior for this axis.

max

Specify an explicit domain maximum for this axis. By default the implicit domain maximum is computed from visible data.

min

Specify an explicit domain minimum for this axis. By default the implicit domain minimum is computed from visible data.

show

Control whether the domain should be made visible using the axis spine.

class InteractiveCoordinatesHelper[source]

Bases: object

Controls the appearance and behavior of interactive coordinates.

label

toyplot.coordinates.Axis.InteractiveCoordinatesLabelHelper instance.

location

Controls the position of interactive coordinates relative to the axis.

Allowed values are “above” (force coordinates to appear above the axis), “below” (the opposite), or None (the default - display interactive coordinates opposite tick labels).

show

Set False to disable showing interactive coordinates for this axis.

tick

toyplot.coordinates.Axis.InteractiveCoordinatesTickHelper instance.

class InteractiveCoordinatesLabelHelper[source]

Bases: object

Controls the appearance and behavior of interactive coordinate labels.

show

Warning

attribute ‘toyplot.coordinates.Axis.InteractiveCoordinatesLabelHelper.show’ undocumented

style

Dictionary of CSS property-value pairs.

Use the style property to control the text appearance. The following CSS properties are allowed:

  • alignment-baseline
  • baseline-shift
  • fill
  • fill-opacity
  • font-size
  • font-weight
  • opacity
  • stroke
  • stroke-opacity
  • stroke-width
  • text-anchor
  • -toyplot-anchor-shift

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

class InteractiveCoordinatesTickHelper[source]

Bases: object

Controls the appearance and behavior of interactive coordinate ticks.

show

Warning

attribute ‘toyplot.coordinates.Axis.InteractiveCoordinatesTickHelper.show’ undocumented

style

Dictionary of CSS property-value pairs.

Use the style property to control the appearance of the line. The following CSS properties are allowed:

  • opacity
  • stroke
  • stroke-dasharray
  • stroke-opacity
  • stroke-width

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

class InteractiveHelper[source]

Bases: object

Controls interactive behavior for this axis.

coordinates

toyplot.coordinates.Axis.InteractiveCoordinatesHelper instance.

class LabelHelper(text, style)[source]

Bases: object

Controls the appearance and behavior of an axis label.

location

Warning

attribute ‘toyplot.coordinates.Axis.LabelHelper.location’ undocumented

offset

Specifies the position relative to the axis. Increasing values of offset move the position further away from the axis, whether the location is “above” or “below”.

Getter:Returns the offset in CSS pixels.
Setter:Sets the offset using a number, string, or (number, string) tuple. Assumes CSS pixels if units aren’t provided. See Units for details.
style

Dictionary of CSS property-value pairs.

Use the style property to control the text appearance. The following CSS properties are allowed:

  • alignment-baseline
  • baseline-shift
  • fill
  • fill-opacity
  • font-size
  • font-weight
  • opacity
  • stroke
  • stroke-opacity
  • stroke-width
  • text-anchor
  • -toyplot-anchor-shift

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

text

The text to be displayed, or None.

class PerTickHelper(allowed)[source]

Bases: object

Controls the appearanace and behavior of individual axis ticks.

class TickProxy(tick, allowed)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Axis.PerTickHelper.TickProxy’ undocumented

style

Warning

attribute ‘toyplot.coordinates.Axis.PerTickHelper.TickProxy.style’ undocumented

styles(values)[source]

Warning

method ‘toyplot.coordinates.Axis.PerTickHelper.styles’ undocumented

class SpineHelper[source]

Bases: object

Controls the appearance and behavior of an axis spine.

position

Warning

attribute ‘toyplot.coordinates.Axis.SpineHelper.position’ undocumented

show

Warning

attribute ‘toyplot.coordinates.Axis.SpineHelper.show’ undocumented

style

Dictionary of CSS property-value pairs.

Use the style property to control the appearance of the line. The following CSS properties are allowed:

  • opacity
  • stroke
  • stroke-dasharray
  • stroke-opacity
  • stroke-width

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

class TickLabelsHelper(angle)[source]

Bases: object

Controls the appearance and behavior of axis tick labels.

angle

Warning

attribute ‘toyplot.coordinates.Axis.TickLabelsHelper.angle’ undocumented

label

Warning

attribute ‘toyplot.coordinates.Axis.TickLabelsHelper.label’ undocumented

offset

Specifies the position relative to the axis. Increasing values of offset move the position further away from the axis, whether the location is “above” or “below”.

Getter:Returns the offset in CSS pixels.
Setter:Sets the offset using a number, string, or (number, string) tuple. Assumes CSS pixels if units aren’t provided. See Units for details.
show

Warning

attribute ‘toyplot.coordinates.Axis.TickLabelsHelper.show’ undocumented

style

Dictionary of CSS property-value pairs.

Use the style property to control the text appearance. The following CSS properties are allowed:

  • alignment-baseline
  • baseline-shift
  • fill
  • fill-opacity
  • font-size
  • font-weight
  • opacity
  • stroke
  • stroke-opacity
  • stroke-width
  • text-anchor
  • -toyplot-anchor-shift

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

class TicksHelper(locator, angle)[source]

Bases: object

Controls the appearance and behavior of axis ticks.

far

Specifies the distance from the axis, in the opposite direction as location.

labels

Warning

attribute ‘toyplot.coordinates.Axis.TicksHelper.labels’ undocumented

location

Controls the position of ticks (and labels) relative to the axis.

Allowed values are “above” (force labels to appear above the axis), “below” (the opposite), or None (use default, context-sensitive behavior).

locator

Warning

attribute ‘toyplot.coordinates.Axis.TicksHelper.locator’ undocumented

near

Specifies the distance from the axis, in the same direction as location.

show

Warning

attribute ‘toyplot.coordinates.Axis.TicksHelper.show’ undocumented

style

Dictionary of CSS property-value pairs.

Use the style property to control the appearance of the line. The following CSS properties are allowed:

  • opacity
  • stroke
  • stroke-dasharray
  • stroke-opacity
  • stroke-width

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

tick

Warning

attribute ‘toyplot.coordinates.Axis.TicksHelper.tick’ undocumented

domain

toyplot.coordinates.Axis.DomainHelper instance.

interactive

toyplot.coordinates.Axis.InteractiveHelper instance.

label

toyplot.coordinates.Axis.LabelHelper instance.

scale

Warning

attribute ‘toyplot.coordinates.Axis.scale’ undocumented

show

Warning

attribute ‘toyplot.coordinates.Axis.show’ undocumented

spine

toyplot.coordinates.Axis.SpineHelper instance.

ticks

toyplot.coordinates.Axis.TicksHelper instance.

class toyplot.coordinates.Cartesian(aspect, hyperlink, label, padding, palette, parent, show, xaxis, xlabel, xmax, xmax_range, xmin, xmin_range, xscale, xshow, xticklocator, yaxis, ylabel, ymax, ymax_range, ymin, ymin_range, yscale, yshow, yticklocator)[source]

Bases: object

Standard two-dimensional Cartesian coordinate system.

Do not create Cartesian instances directly. Use factory methods such as toyplot.canvas.Canvas.cartesian() instead.

class LabelHelper(text, style)[source]

Bases: object

Controls the appearance and behavior of a Cartesian coordinate system label.

offset

Specifies the position relative to the axis. Increasing values of offset move the position further away from the axis, whether the location is “above” or “below”.

Getter:Returns the offset in CSS pixels.
Setter:Sets the offset using a number, string, or (number, string) tuple. Assumes CSS pixels if units aren’t provided. See Units for details.
style

Dictionary of CSS property-value pairs.

Use the style property to control the text appearance. The following CSS properties are allowed:

  • alignment-baseline
  • baseline-shift
  • fill
  • fill-opacity
  • font-size
  • font-weight
  • opacity
  • stroke
  • stroke-opacity
  • stroke-width
  • text-anchor
  • -toyplot-anchor-shift

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

text

The text to be displayed, or None.

add_mark(mark)[source]

Add a mark to the axes.

This is only of use when creating your own custom Toyplot marks. It is not intended for end-users.

Example

To add your own custom mark to a set of axes:

mark = axes.add(MyCustomMark())
Parameters:mark (toyplot.mark.Mark, required)
Returns:mark
Return type:toyplot.mark.Mark
aspect

Control the mapping from domains to ranges.

By default, each axis maps its domain to its range separately, which is what is usually expected from a plot. Sometimes, both axes have the same domain. In this case, it is desirable that both axes are mapped to a consistent range to avoid “squashing” or “stretching” the data. To do so, set aspect to “fit-range”.

bars(a, b=None, c=None, along='x', baseline='stacked', color=None, filename=None, hyperlink=None, opacity=1.0, style=None, title=None)[source]

Add stacked bars to the axes.

This command generates one-or-more series of stacked bars. For convenience, you can call it with many different types of input. To generate a single series of \(M\) bars, pass an optional vector of \(M\) bar positions plus a vector of \(M\) bar magnitudes:

>>> axes.bars(magnitudes)
>>> axes.bars(centers, magnitudes)
>>> axes.bars(minpos, maxpos, magnitudes)

To generate \(N\) stacked series of \(M\) bars, pass an optional vector of \(M\) bar positions plus an \(M \times N\) matrix of bar magnitudes:

>>> axes.bars(magnitudes)
>>> axes.bars(centers, magnitudes)
>>> axes.bars(minpos, maxpos, magnitudes)

As a convenience for working with numpy.histogram(), you may pass a 2-tuple containing \(M\) counts and \(M+1\) bin edges:

>>> axes.bars((counts, edges))

Alternatively, you can generate \(N-1\) stacked series of \(M\) bars by passing an optional vector of \(M\) bar positions plus an \(M \times N\) matrix of bar boundaries:

>>> axes.bars(boundaries, baseline=None)
>>> axes.bars(centers, boundaries, baseline=None)
>>> axes.bars(minpos, maxpos, boundaries, baseline=None)
Parameters:
  • a, b, c (array-like series data.)
  • along (string, “x” or “y”, optional) – Specify “x” (the default) for vertical bars, or “y” for horizontal bars.
  • baseline (array-like, “stacked”, “symmetrical”, “wiggle”, or None)
  • color (array-like set of colors, optional) – Specify a single color for all bars, one color per series, or one color per bar. Color values can be explicit toyplot colors, or scalar values to be mapped to colors using the colormap or palette parameter.
  • opacity (array-like set of opacities, optional) – Specify a single opacity for all bars, one opacity per series, or one opacity per bar.
  • title (array-like set of strings, optional) – Specify a single title, one title per series, or one title per bar.
  • hyperlink (array-like set of strings, optional) – Specify a single hyperlink, one hyperlink per series, or one hyperlink per bar.
  • style (dict, optional) – Collection of CSS styles to be applied globally.
Returns:

bars
Return type:

toyplot.mark.BarBoundaries or toyplot.mark.BarMagnitudes
color_scale(colormap, label=None, tick_locator=None, width=10, padding=10)[source]

Add a color scale to the axes.

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

axes
Return type:

toyplot.coordinates.Numberline
ellipse(x, y, rx, ry, angle=None, color=None, opacity=1.0, title=None, style=None, filename=None)[source]

Add ellipses to the axes.

This command creates a single series of one-or-more ellipses. To create one ellipse, pass scalar values for the center and x and y radiuses:

>>> axes.ellipse(xcenter, ycenter, xradius, yradius)

You may also specify an optional angle, measured in degrees, that will be used to rotate the ellipse counter-clockwise around its center:

>>> axes.ellipse(xcenter, ycenter, xradius, yradius, angle)

To create \(M\) ellipses, pass size-\(M\) vectors for each of the parameters:

>>> axes.ellipse(xcenters, ycenters, xradiuses, yradiuses)
>>> axes.ellipse(xcenters, ycenters, xradiuses, yradiuses, angles)
Parameters:
  • x, y (array-like series of center coordinates.)
  • rx, ry (array-like series of x and y radiuses.)
  • angle (array-like series of rotation angles, optional.)
  • color (array-like series of colors, optional.) – Specify a single color for all ellipses, or one color per ellipse. Color values can be explicit Toyplot colors, scalar values to be mapped to colors with a default colormap, or a (scalar, colormap) tuple containing scalar values to be mapped to colors with the given colormap.
  • opacity (array-like set of opacities, optional.) – Specify a single opacity for all ellipses, or one opacity per ellipse.
  • title (array like set of strings, optional.) – Specify a single title for all ellipses, or one title per ellipse.
  • style (dict, optional) – Collection of CSS styles to be applied to every ellipse.
  • filename (string, optional) – Specify a default filename to be used if the end-viewer decides to export the plot data.
Returns:

mark
Return type:

toyplot.mark.Ellipse containing the mark data.
fill(a, b=None, c=None, along='x', baseline=None, color=None, opacity=1.0, title=None, style=None, annotation=False, filename=None)[source]

Fill multiple regions separated by curves.

Parameters:
  • a, b, c (array-like sets of coordinates) – If a, b, and c are provided, they specify the X coordinates, bottom coordinates, and top coordinates of the region respectively. If only a and b are provided, they specify the X coordinates and top coordinates, with the bottom coordinates lying on the X axis. If only a is provided, it specifies the top coordinates, with the bottom coordinates lying on the X axis and the X coordinates ranging from [0, N).
  • 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.FillBoundaries for a list of useful styles.
  • annotation (boolean, optional) – Set to True if this mark should be considered an annotation.
Returns:

mark
Return type:

toyplot.mark.FillBoundaries or toyplot.mark.FillMagnitudes
graph(a, b=None, c=None, olayout=None, layout=None, along='x', ecolor=None, efilename=None, eopacity=1.0, estyle=None, ewidth=1.0, hmarker=None, mmarker=None, mposition=0.5, tmarker=None, varea=None, vcolor=None, vcoordinates=None, vfilename=None, vlabel=None, vlshow=True, vlstyle=None, vmarker='o', vopacity=1.0, vsize=None, vstyle=None, vtitle=None)[source]

Add a graph plot to the axes.

Returns:plot
Return type:toyplot.mark.Graph
hlines(y, color=None, opacity=1.0, title=None, style=None, annotation=True)[source]

Add horizontal line(s) to the axes.

Horizontal lines are convenient because they’re guaranteed to fill the axes from left to right regardless of the axes size.

Parameters:
  • y (array-like set of Y coordinates) – One horizontal line will be drawn through each Y coordinate provided.
  • 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.AxisLines for a list of useful styles.
  • annotation (boolean, optional) – Set to True if this mark should be considered an annotation.
Returns:

hlines
Return type:

toyplot.mark.AxisLines

Specify a URI that will be hyperlinked from the axes range.

padding

Control the default distance between axis spines and data.

By default, axis spines are offset slightly from the data, to avoid visual clutter and overlap. Use padding to change this offset. The default units are CSS pixels, but you may specify the padding using any Units you like.

plot(a, b=None, along='x', color=None, stroke_width=2.0, opacity=1.0, title=None, marker=None, area=None, size=None, mfill=None, mopacity=1.0, mtitle=None, style=None, mstyle=None, mlstyle=None, filename=None)[source]

Add bivariate line plots to the axes.

Parameters:
  • a, b (array-like sets of coordinates) – If a and b are provided, they specify the first and second coordinates respectively of each point in the plot. If only a is provided, it provides second coordinates, and the first coordinates will range from [0, N).
  • along (string, optional) – Controls the mapping from coordinates to axes. When set to “x” (the default), first and second coordinates map to the X and Y axes. When set to “y”, the coordinates are reversed.
  • color (array-like, optional) – Overrides the default per-series colors provided by the axis palette. Specify one color, or one-color-per-series. Colors may be CSS colors, toyplot colors, or scalar values that will be mapped to colors using colormap or palette.
  • stroke_width (array-like, optional) – Overrides the default stroke width of the plots. Specify one width in drawing units, or one-width-per-series.
  • stroke_opacity (array-like, optional) – Overrides the default opacity of the plots. Specify one opacity, or one-opacity-per-series.
  • marker (array-like, optional) – Allows markers to be rendered for each plot datum. Specify one marker, one-marker-per-series, or one-marker-per-datum. Markers can use the string marker type as a shortcut, or a full marker specification.
  • size (array-like, optional) – Controls marker sizes. Specify one size, one-size-per-series, or one-size-per-datum.
  • fill (array-like, optional) – Override the fill color for markers, which defaults to the per-series color specified by color. Specify one color, one-color-per-series, or one-color-per-datum. Colors may be CSS colors, toyplot colors, or scalar values that will be mapped to colors using fill_colormap or fill_palette.
  • opacity (array-like, optional) – Overrides the default opacity of the markers. Specify one opacity, one-opacity-per-series, or one-opacity-per-datum.
  • title (array-like, optional) – Human-readable title for the data series. The SVG / HTML backends render the title using tooltips. Specify one title or one-title-per-series.
  • style (dict, optional) – Collection of CSS styles applied to all plots.
  • mstyle (dict, optional) – Collection of CSS styles applied to all markers.
  • mlstyle (dict, optional) – Collection of CSS styles applied to all marker labels.
Returns:

mark
Return type:

toyplot.mark.Plot
project(axis, values)[source]

Project a set of domain values to coordinate system range values.

Note that this API is intended for advanced users creating their own custom marks, end-users should never need to use it.

Parameters:
  • axis (“x” or “y”, required) – The axis to be projected
  • values (array-like, required) – The values to be projected
Returns:

projected – The projected values.
Return type:

numpy.ndarray
rectangle(a, b, c, d, along='x', color=None, filename=None, opacity=1.0, style=None, title=None)[source]

Warning

method ‘toyplot.coordinates.Cartesian.rectangle’ undocumented

rects(a, b, c, d, along='x', color=None, filename=None, opacity=1.0, style=None, title=None)[source]

Deprecated, use toyplot.coordinates.Cartesian.rectangle() instead.

scatterplot(a, b=None, along='x', area=None, color=None, filename=None, hyperlink=None, marker='o', mlstyle=None, mstyle=None, opacity=1.0, size=None, title=None)[source]

Add a bivariate plot to the axes.

Parameters:
  • a, b (array-like sets of coordinates) – If a and b are provided, they specify the X coordinates and Y coordinates of each point in the plot. If only a is provided, it specifies the Y coordinates, and the X coordinates will range from [0, N).
  • 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 across all datums.
Returns:

plot
Return type:

toyplot.mark.Plot
share(axis='x', hyperlink=None, palette=None, xlabel=None, xmax=None, xmin=None, xscale='linear', xticklocator=None, ylabel=None, ymax=None, ymin=None, yscale='linear', yticklocator=None)[source]

Create a Cartesian coordinate system with a shared axis.

Parameters:
  • axis (string, optional) – The axis that will be shared. Allowed values are “x” and “y”.
  • 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).
  • 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”, <base>) tuple, optional) – Specifies the mapping from data to canvas coordinates along an axis.
Returns:

axes
Return type:

toyplot.coordinates.Cartesian
show

Control axis visibility.

Use the show property to hide all visible parts of the axes: labels, spines, ticks, tick labels, etc. Note that this does not affect visibility of the axes contents, just the axes themselves.

text(a, b, text, angle=0, color=None, opacity=1.0, title=None, style=None, filename=None, annotation=True)[source]

Add text to the axes.

Parameters:
  • a, b (float) – Coordinates of the text anchor.
  • 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.
  • annotation (boolean, optional) – Set to True if this mark should be considered an annotation.
Returns:

text
Return type:

toyplot.mark.Text
vlines(x, color=None, opacity=1.0, title=None, style=None, annotation=True)[source]

Add vertical line(s) to the axes.

Vertical lines are convenient because they’re guaranteed to fill the axes from top to bottom regardless of the axes size.

Parameters:
  • x (array-like set of X coordinates) – One vertical line will be drawn through each X coordinate provided.
  • 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.AxisLines for a list of useful styles.
  • annotation (boolean, optional) – Set to True if this mark should be considered an annotation.
Returns:

mark
Return type:

toyplot.mark.AxisLines
xmax_range

Warning

attribute ‘toyplot.coordinates.Cartesian.xmax_range’ undocumented

xmin_range

Warning

attribute ‘toyplot.coordinates.Cartesian.xmin_range’ undocumented

ymax_range

Warning

attribute ‘toyplot.coordinates.Cartesian.ymax_range’ undocumented

ymin_range

Warning

attribute ‘toyplot.coordinates.Cartesian.ymin_range’ undocumented

class toyplot.coordinates.Numberline(x1, y1, x2, y2, padding, palette, spacing, min, max, show, label, ticklocator, scale, parent)[source]

Bases: object

Standard one-dimensional coordinate system / numberline.

Do not create Numberline instances directly. Use factory methods such as toyplot.canvas.Canvas.numberline() instead.

add_mark(mark)[source]

Add a mark to the axes.

This is only of use when creating your own custom Toyplot marks. It is not intended for end-users.

Example

To add your own custom mark to a set of axes:

mark = axes.add(MyCustomMark())
Parameters:mark (toyplot.mark.Mark, required)
Returns:mark
Return type:toyplot.mark.Mark
axis

toyplot.coordinates.Axis instance that provides the numberline coordinate system.

colormap(colormap, offset=None, width=10, style=None)[source]

Warning

method ‘toyplot.coordinates.Numberline.colormap’ undocumented

padding

Control the default distance between the axis spine and data.

By default, the axis spine is offset slightly from the data, to avoid visual clutter and overlap. Use padding to change this offset. The default units are CSS pixels, but you may specify the padding using any Units you like.

range(start, end, color=None, filename=None, offset=None, opacity=1.0, style=None, title=None, width=10)[source]

Warning

method ‘toyplot.coordinates.Numberline.range’ undocumented

scatterplot(coordinates, area=None, color=None, filename=None, hyperlink=None, marker='o', mlstyle=None, mstyle=None, offset=None, opacity=1.0, size=None, title=None)[source]

Add a univariate plot to the axes.

Parameters:
  • coordinate (array-like one-dimensional coordinates)
  • 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 across all datums.
Returns:

plot
Return type:

toyplot.mark.Plot
show

Control axis visibility.

Use the show property to hide all visible parts of the axis: label, spine, ticks, tick labels, etc. Note that this does not affect visibility of the numberline contents, just the axis.

spacing

Control the default distance between data added to the numberline.

The default units are CSS pixels, but you may specify the spacing using any Units you like.

class toyplot.coordinates.Table(xmin_range, xmax_range, ymin_range, ymax_range, rows, columns, trows, brows, lcolumns, rcolumns, label, parent, annotation, filename)[source]

Bases: object

Row and column-based table coordinate system.

Do not create Table instances directly. Use factory methods such as toyplot.canvas.Canvas.table() instead.

class CellBarMark(table, axes, baseline, color, filename, opacity, padding, series, style, title, width)[source]

Bases: toyplot.coordinates.CellMark

Warning

class ‘toyplot.coordinates.Table.CellBarMark’ undocumented

class CellMark(table, axes, series)[source]

Bases: object

Abstract interface for objects that embed other Toyplot visualizations in table cells.

class CellPlotMark(table, axes, area, color, filename, marker, mfill, mlstyle, mopacity, mstyle, mtitle, opacity, series, size, stroke_width, style, title)[source]

Bases: toyplot.coordinates.CellMark

Warning

class ‘toyplot.coordinates.Table.CellPlotMark’ undocumented

class CellReference(table, selection)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.CellReference’ undocumented

align

Warning

attribute ‘toyplot.coordinates.Table.CellReference.align’ undocumented

angle

Warning

attribute ‘toyplot.coordinates.Table.CellReference.angle’ undocumented

cartesian(aspect=None, hyperlink=None, cell_padding=3, label=None, padding=3, palette=None, show=True, xlabel=None, xmax=None, xmin=None, xscale='linear', xshow=False, xticklocator=None, ylabel=None, ymax=None, ymin=None, yscale='linear', yshow=False, yticklocator=None)[source]

Warning

method ‘toyplot.coordinates.Table.CellReference.cartesian’ undocumented

data

Warning

attribute ‘toyplot.coordinates.Table.CellReference.data’ undocumented

format

Warning

attribute ‘toyplot.coordinates.Table.CellReference.format’ undocumented

height

Warning

attribute ‘toyplot.coordinates.Table.CellReference.height’ undocumented

Warning

attribute ‘toyplot.coordinates.Table.CellReference.hyperlink’ undocumented

lstyle

Warning

attribute ‘toyplot.coordinates.Table.CellReference.lstyle’ undocumented

merge()[source]

Warning

method ‘toyplot.coordinates.Table.CellReference.merge’ undocumented

show

Warning

attribute ‘toyplot.coordinates.Table.CellReference.show’ undocumented

style

Warning

attribute ‘toyplot.coordinates.Table.CellReference.style’ undocumented

title

Warning

attribute ‘toyplot.coordinates.Table.CellReference.title’ undocumented

width

Warning

attribute ‘toyplot.coordinates.Table.CellReference.width’ undocumented

class ColumnCellReference(table, selection)[source]

Bases: toyplot.coordinates.CellReference

Warning

class ‘toyplot.coordinates.Table.ColumnCellReference’ undocumented

delete()[source]

Warning

method ‘toyplot.coordinates.Table.ColumnCellReference.delete’ undocumented

class DistanceArrayReference(array)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.DistanceArrayReference’ undocumented

class EmbeddedCartesian(table, *args, **kwargs)[source]

Bases: toyplot.coordinates.Cartesian

Warning

class ‘toyplot.coordinates.Table.EmbeddedCartesian’ undocumented

cell_bars(baseline='stacked', color=None, filename=None, opacity=1.0, padding=0, series='columns', style=None, title=None, width=0.5)[source]

Warning

method ‘toyplot.coordinates.Table.EmbeddedCartesian.cell_bars’ undocumented

cell_plot(area=None, color=None, filename=None, marker=None, mfill=None, mlstyle=None, mopacity=1.0, mstyle=None, mtitle=None, opacity=1.0, series='columns', size=None, stroke_width=2.0, style=None, title=None)[source]

Warning

method ‘toyplot.coordinates.Table.EmbeddedCartesian.cell_plot’ undocumented

class GapReference(row_gaps, column_gaps)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.GapReference’ undocumented

columns

Warning

attribute ‘toyplot.coordinates.Table.GapReference.columns’ undocumented

rows

Warning

attribute ‘toyplot.coordinates.Table.GapReference.rows’ undocumented

class GridReference(table, hlines, vlines)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.GridReference’ undocumented

hlines

Warning

attribute ‘toyplot.coordinates.Table.GridReference.hlines’ undocumented

separation

Warning

attribute ‘toyplot.coordinates.Table.GridReference.separation’ undocumented

style

Warning

attribute ‘toyplot.coordinates.Table.GridReference.style’ undocumented

vlines

Warning

attribute ‘toyplot.coordinates.Table.GridReference.vlines’ undocumented

class Label(text, style)[source]

Bases: object

Controls the appearance and behavior of the table label.

style

Dictionary of CSS property-value pairs.

Use the style property to control the text appearance. The following CSS properties are allowed:

  • alignment-baseline
  • baseline-shift
  • fill
  • fill-opacity
  • font-size
  • font-weight
  • opacity
  • stroke
  • stroke-opacity
  • stroke-width
  • text-anchor
  • -toyplot-anchor-shift

Note that when assigning to the style property, the properties you supply are merged with the existing properties.

text

The text to be displayed, or None.

class Region(table, row_begin, row_end, column_begin, column_end)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.Region’ undocumented

class CellAccessor(region)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.Region.CellAccessor’ undocumented

class ColumnAccessor(region)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.Region.ColumnAccessor’ undocumented

insert(before=None, after=None)[source]

Warning

method ‘toyplot.coordinates.Table.Region.ColumnAccessor.insert’ undocumented

class RowAccessor(region)[source]

Bases: object

Warning

class ‘toyplot.coordinates.Table.Region.RowAccessor’ undocumented

insert(before=None, after=None)[source]

Warning

method ‘toyplot.coordinates.Table.Region.RowAccessor.insert’ undocumented

cell

Warning

attribute ‘toyplot.coordinates.Table.Region.cell’ undocumented

cells

Warning

attribute ‘toyplot.coordinates.Table.Region.cells’ undocumented

column

Warning

attribute ‘toyplot.coordinates.Table.Region.column’ undocumented

gaps

Warning

attribute ‘toyplot.coordinates.Table.Region.gaps’ undocumented

grid

Warning

attribute ‘toyplot.coordinates.Table.Region.grid’ undocumented

row

Warning

attribute ‘toyplot.coordinates.Table.Region.row’ undocumented

shape

Warning

attribute ‘toyplot.coordinates.Table.Region.shape’ undocumented

class RowCellReference(table, selection)[source]

Bases: toyplot.coordinates.CellReference

Warning

class ‘toyplot.coordinates.Table.RowCellReference’ undocumented

delete()[source]

Warning

method ‘toyplot.coordinates.Table.RowCellReference.delete’ undocumented

annotation

Warning

attribute ‘toyplot.coordinates.Table.annotation’ undocumented

body

Warning

attribute ‘toyplot.coordinates.Table.body’ undocumented

bottom

Warning

attribute ‘toyplot.coordinates.Table.bottom’ undocumented

cells

Warning

attribute ‘toyplot.coordinates.Table.cells’ undocumented

label

Warning

attribute ‘toyplot.coordinates.Table.label’ undocumented

left

Warning

attribute ‘toyplot.coordinates.Table.left’ undocumented

right

Warning

attribute ‘toyplot.coordinates.Table.right’ undocumented

shape

Warning

attribute ‘toyplot.coordinates.Table.shape’ undocumented

top

Warning

attribute ‘toyplot.coordinates.Table.top’ undocumented

toyplot.data module

Classes and functions for working with raw data.

class toyplot.data.Table(data=None, index=False)[source]

Bases: object

Encapsulates an ordered, heterogeneous collection of labelled data series.

Parameters:
  • data ((data series, optional)) – You may initialize a toyplot.data.Table with any of the following:
    • None (the default) - creates an empty table (a table without any columns).
    • toyplot.data.Table - creates a copy of the given table.
    • collections.OrderedDict - creates a column for each key-value pair in the input, in the same order. Each value must be implicitly convertable to a numpy masked array, and every value must contain the same number of items.
    • object returned when loading a .npz file with numpy.load() - creates a column for each key-value pair in the given file, in the same order. Each array in the input file must contain the same number of items.
    • dict / collections.abc.Mapping - creates a column for each key-value pair in the input, sorted by key in lexicographical order. Each value must be implicitly convertable to a numpy masked array, and every value must contain the same number of items.
    • list / collections.abc.Sequence - creates a column for each key-value tuple in the input sequence, in the same order. Each value must be implicitly convertable to a numpy masked array, and every value must contain the same number of items.
    • numpy.ndarray - creates a column for each column in a numpy matrix (2D array). The order of the columns is maintained, and each column is assigned a unique name.
    • pandas.DataFrame - creates a column for each column in a Pandas data frame. The order of the columns is maintained.
  • index (bool or string, optional) – Controls whether to convert a Pandas data frame index to columns in the resulting table. Use index=False (the default) to leave the data frame index out of the table. Use index=True to include the index in the table, using default column names (hierarchical indices will be stored in the table using multiple columns). Use index=”format string” to include the index and control how the index column names are generated. The given format string can use positional {} / {0} or keyword {index} arguments to incorporate a zero-based index id into the column names.
items()[source]

Return column names and columns, in column order.

Returns:items – Sequence of (name, column) tuples.
Return type:list
keys()[source]

Return the table column names, in column order.

Returns:keys
Return type:sequence of str column names.
matrix()[source]

Convert the table to a matrix (2D numpy array).

The data type of the returned array is chosen based on the types of the columns within the table. Tables containing a homogeneous set of column types will return an array of the the same type. If the table contains one or more string columns, the results will be an array of strings.

Returns:matrix – The returned array will have two dimensions.
Return type:numpy.ma.MaskedArray
metadata(column)[source]

Return metadata for one of the table’s columns.

Parameters:column (string.) – The name of an existing column.
Returns:metadata
Return type:dict containing key-value pairs.
shape

The table shape (number of rows and columns).

Returns:shape – (number of rows, number of columns) tuple.
Return type:tuple
values()[source]

Return the table columns, in column order.

Returns:values
Return type:sequence of numpy.ndarray columns.
toyplot.data.cars()[source]

Return sample automobile model data.

Returns:table – Table containing descriptions of multiple makes and models of automobile.
Return type:toyplot.data.Table
toyplot.data.communities()[source]

Return sample community detection data.

Returns:
  • edges (numpy.ndarray) – An \(E \times 2\) matrix containing source and target vertex ids for \(E\) edges.
  • truth (numpy.ndarray) – A \(V \times 2\) matrix containing a vertex id and ground-truth community id for \(V\) vertices.
  • assigned (numpy.ndarray) – A \(V \times 2\) matrix containing a vertex id and alternate community id for \(V\) vertices.
toyplot.data.commute()[source]

Return sample OBD-II commuting data.

Returns:table – Table containing a stream of OBD-II data collected from an automobile during a morning commute.
Return type:toyplot.data.Table
toyplot.data.contiguous(a)[source]

Split an array into a collection of contiguous ranges.

toyplot.data.deliveries()[source]

Return sample delivery data.

Returns:table – Table containing a stream of OBD-II data collected from an automobile during a morning commute.
Return type:toyplot.data.Table
toyplot.data.minimax(items)[source]

Compute the minimum and maximum of an arbitrary collection of scalar- or array-like items.

The items parameter must be an iterable containing any combination of None, scalars, numpy arrays, or numpy masked arrays. None, NaN, masked values, and empty arrays are all handled correctly. Returns (None, None) if the inputs don’t contain any usable values.

Returns:
  • min (minimum value of the input arrays, or None.)
  • max (maximum value of the input arrays, or None.)
toyplot.data.read_csv(fobj, convert=False)[source]

Load a CSV (delimited text) file.

Parameters:
  • fobj (file-like object or string, required) – The file to read. Use a string filepath, an open file, or a file-like object.
  • convert (boolean, optional) – By default, the columns in a table will contain strings. If True, convert column types to integers and floats where possible.
Returns:

table
Return type:

toyplot.data.Table

Notes

read_csv() is a simple tool for use in demos and tutorials. For more full-featured delimited text parsing, you should consider the csv module included in the Python standard library, or functionality provided by numpy or Pandas.

toyplot.data.temperatures()[source]

Return sample temperature data.

Returns:table – Table containing temperature data collected by NOAA.
Return type:toyplot.data.Table

toyplot.font module

Font management and font metrics.

class toyplot.font.Font[source]

Bases: object

Abstract interface for objects that return information about a specific combination of typeface and size.

ascent

Font ascent (maximum height above the baseline).

Returns:ascent – ascent of the font in CSS pixels.
Return type:number
descent

Font descent (maximum height below the baseline).

Returns:descent – descent of the font in CSS pixels.
Return type:number
width(string)[source]

Return the width of a string if rendered using the font.

Parameters:string (str, required) – The text to be measured.
Returns:width – Width of the string in CSS pixels, if rendered using the given font and font size.
Return type:number
class toyplot.font.Library[source]

Bases: object

Abstract interface for objects that manage a collection of fonts.

font(style)[source]

Lookup a font using CSS style information and return a corresponding Font object.

Parameters:style (dict containing CSS style information)
Returns:font
Return type:instance of toyplot.font.Font
class toyplot.font.ReportlabFont(family, size)[source]

Bases: toyplot.font.Font

Use Reportlab to access the metrics for a font.

Parameters:
  • font_family (str) – PDF font family to use for measurement.
  • font_size (number) – Font size for the measurement. Defaults to CSS pixel units, and supports all toyplot Units.
ascent

Font ascent (maximum height above the baseline).

Returns:ascent – ascent of the font in CSS pixels.
Return type:number
descent

Font descent (maximum height below the baseline).

Returns:descent – descent of the font in CSS pixels.
Return type:number
width(string)[source]

Return the width of a string if rendered using the font.

Parameters:string (str, required) – The text to be measured.
Returns:width – Width of the string in CSS pixels, if rendered using the given font and font size.
Return type:number
class toyplot.font.ReportlabLibrary[source]

Bases: toyplot.font.Library

Use Reportlab to provide information about standard PDF fonts.

font(style)[source]

Lookup a font using CSS style information and return a corresponding Font object.

Parameters:style (dict containing CSS style information)
Returns:font
Return type:instance of toyplot.font.ReportlabFont

toyplot.format module

Strategy objects for formatting text.

class toyplot.format.BasicFormatter(nanshow=True)[source]

Bases: toyplot.format.Formatter

Convert data to its default string representation.

format(value)[source]

Return a text representation of the given value.

Parameters:value (value to be formatted)
Returns:
  • prefix (string) – Formatted data to be displayed before the separator.
  • separator (string) – Separator between formatted data, or empty string.
  • suffix (string) – Formatted data to be displayed after the separator, or empty string.
class toyplot.format.CurrencyFormatter(format='{:, .2f}', nanshow=True, curr='cad', sep=', ', dp='.')[source]

Bases: toyplot.format.BasicFormatter

Formats currency value with corresponding codes places: required number of places after the decimal point curr: optional currency symbol before the sign (may be blank) sep: optional grouping separator (comma, period, space, or blank) dp: decimal point indicator (comma or period)

only specify as blank when places is zero
format(value)[source]

Return a text representation of the given currency value.

Parameters:value (value to be formatted)
Returns:
  • codes (string) – Formatted currency code to be displayed before the prefix, or empty string.
  • prefix (string) – Formatted data to be displayed before the separator.
  • dp (string) – Separator between formatted data, or empty string.
  • suffix (string) – Formatted data to be displayed after the separator, or empty string.
class toyplot.format.DefaultFormatter[source]

Bases: toyplot.format.BasicFormatter

Deprecated, use toyplot.format.BasicFormatter instead.

class toyplot.format.FloatFormatter(format='{:.6g}', nanshow=True)[source]

Bases: toyplot.format.BasicFormatter

Formats floating-point values with aligned decimal points.

Parameters:
  • format (format string, optional) – Uses standard Python Format String Syntax.
  • nanshow (bool, optional) – Set to False to hide NaN values.
format(value)[source]

Return a text representation of the given value.

Parameters:value (value to be formatted)
Returns:
  • prefix (string) – Formatted data to be displayed before the separator.
  • separator (string) – Separator between formatted data, or empty string.
  • suffix (string) – Formatted data to be displayed after the separator, or empty string.
class toyplot.format.Formatter[source]

Bases: object

Abstract interface for formatters - objects that compute text representations from data.

format(value)[source]

Return a text representation of the given value.

Parameters:value (value to be formatted)
Returns:
  • prefix (string) – Formatted data to be displayed before the separator.
  • separator (string) – Separator between formatted data, or empty string.
  • suffix (string) – Formatted data to be displayed after the separator, or empty string.
class toyplot.format.NullFormatter[source]

Bases: toyplot.format.Formatter

Do-nothing formatter that returns empty strings.

format(value)[source]

Return a text representation of the given value.

Parameters:value (value to be formatted)
Returns:
  • prefix (string) – Formatted data to be displayed before the separator.
  • separator (string) – Separator between formatted data, or empty string.
  • suffix (string) – Formatted data to be displayed after the separator, or empty string.
class toyplot.format.UnitFormatter(format='{:.6g}', nanshow=True, units='pt')[source]

Bases: toyplot.format.BasicFormatter

Formats values with corresponding units

Parameters:
  • format (format string, optional) – Uses standard Python Format String Syntax.
  • nanshow (bool, optional) – Set to False to hide NaN values.
format(value)[source]

Return a text representation of the given value.

Parameters:
  • value (value to be formatted)
  • units (units to be formatted)
Returns:

  • prefix (string) – Formatted data to be displayed before the separator.
  • separator (string) – Separator between formatted data, or empty string.
  • suffix (string) – Formatted data to be displayed after the separator, or empty string.
  • units (string) – Formatted units to be displayed after the suffix, or empty string.

toyplot.html module

Functions to render the canonical HTML representation of a Toyplot figure.

class toyplot.html.RenderContext(root)[source]

Bases: object

Stores context data during rendering.

This is only of use for Toyplot developers and library developers who are implementing rendering code. It is not intended for end-users.

already_rendered(o)[source]

Track whether an object has already been rendered.

Used to prevent objects that can be shared, such as toyplot.coordinates.Axis, from generating duplicate markup in the output HTML.

Parameters:o (any Python object, required)
Returns:rendered – If the given object hasn’t already been rendered, records it as rendered and returns False. Subsequent calls with the given object will always return True.
Return type:bool

Examples

The following checks to see if mark has already been rendered:

if not context.already_rendered(mark):
    # Render the mark
animation

Warning

attribute ‘toyplot.html.RenderContext.animation’ undocumented

copy(parent)[source]

Copy the current toyplot.html.RenderContext.

Creates a copy of the current render context that can be used to render children of the currently-rendered object.

Parameters:parent (any Python object, required.)
Returns:context – The parent attribute will be set to the supplied parent object.
Return type:toyplot.html.RenderContext
define(name, dependencies=None, factory=None, value=None)[source]

Define a Javascript module that can be embedded in the output markup.

The module will only be embedded in the output if it is listed as a dependency of another module, or code specified using require().

You must specify either factory or value.

Parameters:
  • name (string, required) – Module name. Any string is valid, but alphanumerics separated with slashes are recommended. Multiple calls to define with the same name argument will be silently ignored.
  • dependencies (sequence of strings, optional) – Names of modules that are dependencies of this module.
  • factory (string, optional) – Javascript code that will construct the module, which must be a function that takes the modules listed in dependencies, in-order, as arguments, and returns the initialized module.
  • value (Python object, optional) – Arbitrary value for this module, which must be compatible with json.dumps().
get_id(o)[source]

Return a globally unique identifier for an object.

The generated identifier is cached, so multiple lookups on the same object will return consistent results.

Parameters:o (any Python object, required.)
Returns:id – Globally unique identifier that can be used in HTML markup as an identifier that can be targeted from Javascript code.
Return type:str
parent

Current DOM node. Typical rendering code will append HTML content to this node.

require(dependencies=None, arguments=None, code=None)[source]

Embed Javascript code and its dependencies into the output markup.

The given code will be unconditionally embedded in the output markup, along with any modules listed as dependencies (plus their dependencies, and-so-on).

Parameters:
  • dependencies (sequence of strings, optional) – Names of modules that are required by this code.
  • arguments (sequence of Python objects, optional) – Additional arguments to be passed to the Javascript code, which must be compatible with json.dumps().
  • code (string, required) – Javascript code to be embedded, which must be a function that accepts the modules listed in requirements in-order, followed by the values listed in arguments in-order, as arguments.
root

Top-level DOM node.

toyplot.html.apply_changes(html, changes)[source]

Warning

function ‘toyplot.html.apply_changes’ undocumented

toyplot.html.dispatch(*types, **kwargs)

Decorator for registering custom rendering code.

This is only of use when creating your own custom Toyplot marks. It is not intended for end-users.

Example

To register your own rendering function:

@toyplot.html.dispatch(toyplot.coordinates.Cartesian, MyCustomMark, toyplot.html.RenderContext)
def _render(axes, mark, context):
    # Rendering implementation here
toyplot.html.render(canvas, fobj=None, animation=False, style=None)[source]

Convert a canvas to its HTML DOM representation.

Generates HTML markup with an embedded SVG representation of the canvas, plus JavaScript code for interactivity. If the canvas contains animation, the markup will include an HTML user interface to control playback.

Parameters:
  • canvas (toyplot.canvas.Canvas) – The canvas to be rendered.
  • fobj (file-like object or string, optional) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the HTML tree will be returned to the caller instead.
  • animation (boolean, optional) – If True, return a representation of the changes to be made to the HTML tree for animation.
  • style (dict, optional) – Dictionary of CSS styles that will be applied to the top-level output <div>.
Returns:

  • html (xml.etree.ElementTree.Element or None) – HTML representation of canvas, as a DOM tree, or None if the caller specifies the fobj parameter.
  • changes (JSON-compatible data structure, or None) – JSON-compatible representation of the animated changes to canvas.

Notes

The output HTML is the “canonical” representation of a Toyplot canvas - the other toyplot backends operate by converting the output from toyplot.html.render() to the desired end target.

Note that the output HTML is a fragment wrapped in a <div>, suitable for embedding in a larger document. It is the caller’s responsibility to supply the <html>, <body> etc. if the result is intended as a standalone HTML document.

toyplot.html.tostring(canvas, style=None)[source]

Convert a canvas to its HTML string representation.

Generates HTML markup with an embedded SVG representation of the canvas, plus JavaScript code for interactivity. If the canvas contains animation, the markup will include an HTML user interface to control playback.

Parameters:
  • canvas (toyplot.canvas.Canvas) – The canvas to be rendered.
  • style (dict, optional) – Dictionary of CSS styles that will be applied to the top-level output <div>.
Returns:

html – HTML representation of canvas as a string.
Return type:

str

Notes

The output HTML is a fragment wrapped in a <div>, suitable for embedding in a larger document. It is the caller’s responsibility to supply the <html>, <body> etc. if the result is intended as a standalone HTML document.

toyplot.layout module

Provides layout algorithms.

class toyplot.layout.Buchheim(edges=None, basis=None)[source]

Bases: toyplot.layout.GraphLayout

Compute a tree layout using the 2002 algorithm of Buchheim, Junger, and Leipert.

Note: this layout currently ignores preexisting vertex coordinates.

graph(vcoordinates, edges)[source]

Compute vertex and edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.
  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve (requires two sets of coordinates).
    • C - draw a cubic Bezier curve (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.CurvedEdges(curvature=0.15)[source]

Bases: toyplot.layout.EdgeLayout

Creates curved edges between graph vertices.

Parameters:curvature (number) – Controls the curvature of each edge’s arc, as a percentage of the distance between the edge’s vertices. Use negative values to curve edges in the opposite direction.
edges(vcoordinates, edges)[source]

Return edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) matrix) – Contains the coordinates for every graph vertex, in vertex order.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment from the current coordinates (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve from the current coordinates (requires two sets of coordinates).
    • C - draw a cubic Bezier curve from the current coordinates (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.Eades(edges=None, c1=2, c2=1, c3=1, c4=0.1, M=100, seed=1234)[source]

Bases: toyplot.layout.GraphLayout

Compute a force directed graph layout using the 1984 algorithm of Eades.

Parameters:
  • edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.
  • c1, c2, c3, c4 (numbers, optional) – Constants defined in Eades’ original paper.
  • M (integer, optional) – Number of iterations to run the spring simulation.
  • seed (integer, optional) – Random seed used to initialize vertex coordinates.
graph(vcoordinates, edges)[source]

Compute vertex and edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.
  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve (requires two sets of coordinates).
    • C - draw a cubic Bezier curve (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.EdgeLayout[source]

Bases: object

Abstract interface for algorithms that compute graph edge coordinates.

edges(vcoordinates, edges)[source]

Return edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) matrix) – Contains the coordinates for every graph vertex, in vertex order.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment from the current coordinates (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve from the current coordinates (requires two sets of coordinates).
    • C - draw a cubic Bezier curve from the current coordinates (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.FruchtermanReingold(edges=None, area=1, temperature=0.1, M=50, seed=1234)[source]

Bases: toyplot.layout.GraphLayout

Compute a force directed graph layout using the 1991 algorithm of Fruchterman and Reingold.

Parameters:
  • edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.
  • area, temperature (numbers, optional) – Constants defined in the original paper.
  • M (integer, optional) – Number of iterations to run the spring simulation.
  • seed (integer, optional) – Random seed used to initialize vertex coordinates.
graph(vcoordinates, edges)[source]

Compute vertex and edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.
  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve (requires two sets of coordinates).
    • C - draw a cubic Bezier curve (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.Graph(vids, vcoordinates, edges, eshapes, ecoordinates)[source]

Bases: object

Stores graph layout information.

Typically used when sharing a layout among more than one graph.

ecoordinates

Return a matrix of edge coordinates. The number of coordinates is determined by the contents of the eshapes vector.

ecount

Return the number of edges \(E\) in the graph.

edges

Return the graph edges as a \(E \times 2\) matrix of source, target indices.

eshapes

Return a vector of \(E\) string edge shapes.

vcoordinates

Return graph vertex coordinates as a \(V \times 2\) matrix.

vcount

Return the number of vertices \(V\) in the graph.

vids

Return \(V\) graph vertex identifiers.

class toyplot.layout.GraphLayout[source]

Bases: object

Abstract interface for algorithms that compute coordinates for graph vertices and edges.

graph(vcoordinates, edges)[source]

Compute vertex and edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.
  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve (requires two sets of coordinates).
    • C - draw a cubic Bezier curve (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.IgnoreVertices(edges=None)[source]

Bases: toyplot.layout.GraphLayout

Do-nothing graph layout for use when all vertices are already specified.

Parameters:edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.
graph(vcoordinates, edges)[source]

Compute vertex and edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.
  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve (requires two sets of coordinates).
    • C - draw a cubic Bezier curve (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.Random(edges=None, seed=1234)[source]

Bases: toyplot.layout.GraphLayout

Compute a random graph layout.

Parameters:
  • edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.
  • seed (integer, optional) – Random seed used to generate vertex coordinates.
graph(vcoordinates, edges)[source]

Compute vertex and edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.
  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve (requires two sets of coordinates).
    • C - draw a cubic Bezier curve (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
class toyplot.layout.StraightEdges[source]

Bases: toyplot.layout.EdgeLayout

Creates straight edges between graph vertices.

edges(vcoordinates, edges)[source]

Return edge coordinates for a graph.

Parameters:
  • vcoordinates (\(V \times 2\) matrix) – Contains the coordinates for every graph vertex, in vertex order.
  • edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.
Returns:

  • eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:
    • M - change the current coordinates without drawing (requires one set of coordinates).
    • L - draw a straight line segment from the current coordinates (requires one set of coordinates).
    • Q - draw a quadratic Bezier curve from the current coordinates (requires two sets of coordinates).
    • C - draw a cubic Bezier curve from the current coordinates (requires three sets of coordinates).
  • ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.
toyplot.layout.graph(a, b=None, c=None, olayout=None, layout=None, vcoordinates=None)[source]

Compute a graph layout.

toyplot.layout.region(xmin, xmax, ymin, ymax, bounds=None, rect=None, corner=None, grid=None, margin=None)[source]

Specify a rectangular target region relative to a parent region.

Parameters:
  • xmin (number, required) – Minimum X boundary of the parent region, specified in CSS pixel units.
  • xmax (number, required) – Maximum X boundary of the parent region, specified in CSS pixel units.
  • ymin (number, required) – Minimum Y boundary of the parent region, specified in CSS pixel units.
  • ymax (number, required) – Maximum Y boundary of the parent region, specified in CSS pixel units.
  • margin (number, string, (number, string) tuple, or tuple containing between one and four numbers, strings, or (number, string) tuples, optional) – Padding around the target region, specified in real-world units. Defaults to CSS pixel units. See Units for details. Follows the same behavior as the CSS margin property.
Returns:

xmin, xmax, ymin, ymax – The boundaries of the target region, specified in CSS pixel units.
Return type:

number

toyplot.locator module

Strategy objects that compute the position and format of axis ticks and labels.

class toyplot.locator.Explicit(locations=None, labels=None, titles=None, format='{:g}')[source]

Bases: toyplot.locator.TickLocator

Explicitly specify a collection of tick locations and labels for an axis.

You must specify the set of locations, the set of labels, or both. If you only specify locations, the labels will be generated using a formatting string. If you only specify labels, the locations will default to integers in the range \([0, n)\). The latter behavior is especially useful for categorical axes.

Parameters:
  • locations (sequence numbers, optional) – Axis locations where ticks should be displayed.
  • labels (sequence of strings, optional) – Labels for each tick location.
  • titles (sequence of strings, optional) – Titles for each tick location. Typically, backends render titles as tooltips.
  • format (string, optional) – Format string used to generate labels from tick locations.
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Extended(count=5, steps=None, weights=None, only_inside=False, format='{0:.{digits}f}')[source]

Bases: toyplot.locator.TickLocator

Generate ticks using “An Extension of Wilkinson’s Algorithm for Positioning Tick Labels on Axes” by Talbot, Lin, and Hanrahan.

Parameters:
  • count (number, optional) – Desired number of ticks. Note that the algorithm may produce fewer ticks than requested.
  • steps (sequence of numbers, optional) – Prioritized list of “nice” values to use for generating ticks.
  • only_inside (boolean) – If set to True, only ticks inside the axis domain will be generated.
  • format (string, optional) – Format string used to generate labels from tick locations.
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Heckbert(count=5, format='{0:.{digits}f}')[source]

Bases: toyplot.locator.TickLocator

Generate ticks using the “Nice numbers for graph labels” algorithm by Paul Heckbert.

Note that this locator can produce ticks outside the minimum / maximum axis domain.

Parameters:
  • count (number of ticks to generate)
  • format (string, optional) – Format string used to generate labels from tick locations.
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Integer(step=1)[source]

Bases: toyplot.locator.TickLocator

Generate evenly-spaced integer ticks

Parameters:step (integer, optional) – Number of integer values to skip between labels.
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Log(base=10, format='{base}<sup> {exponent}</sup>')[source]

Bases: toyplot.locator.TickLocator

Generate ticks that are evenly spaced on a logarithmic scale

Parameters:
  • base (number, optional) – Logarithm base.
  • format (string, optional) – Python format string, see Format String Syntax for the syntax. The format string will be called with a single positional argument containing the locator value, and two keyword arguments base and exponent. If omitted, the locator will generate high-quality labels using superscript notation.

Examples

Generate locator labels using fixed decimal point notation and two significant digits:

>>> locator = toyplot.locator.Log(format="{:.2g}")

Generate locator labels using scientific notation and three significant digits:

>>> locator = toyplot.locator.Log(format="{:.3e}")

Generate locator labels using mixed scientific and decimal notation and four significant digits:

>>> locator = toyplot.locator.Log(format="{:.4g}")

Generate locator labels using “carat” notation:

>>> locator = toyplot.locator.Log(format="{base}^{exponent}")
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Null[source]

Bases: toyplot.locator.TickLocator

Do-nothing tick locator that generates no ticks.

Use toyplot.locator.Null when you want to display an axis, but omit any ticks.

ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.TickLocator[source]

Bases: object

Base class for tick locators - objects that compute the position and format of axis tick labels.

ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Timestamp(count=None, interval=None, timezone='utc', format=None)[source]

Bases: toyplot.locator.TickLocator

Generate ticks when the domain is UTC timestamps relative to the Unix epoch.

Callers may explicitly specify the desired time interval as a string:

>>> toyplot.locator.Timestamp(interval="hours")

or as a tuple containing a quantity of units:

>>> toyplot.locator.Timestamp(interval=(3, "days"))

Instead of specifying an interval, the caller may supply the desired number of ticks, and the interval that produces the closest number of ticks will be used (note that the number of ticks produced may not match exactly):

>>> toyplot.locator.Timestamp(count=4)

If the count is not specified, it defaults to 7.

Parameters:
  • count (number, optional) – Specifies the desired number of ticks.
  • interval (string or (integer, string) tuple, optional) – Specifies the desired tick interval in anthropomorphic time units. Allowed units are “millenium”, “millenia”, “century”, “centuries”, “decade”, “decades”, “year”, “years”, “quarter”, “quarters”, “month”, “months”, “week”, “weeks”, “day”, “days”, “hour”, “hours”, “minute”, “minutes”, “second”, and “seconds”.
  • timezone (string, optional) – Specifies a local timezone to be used for label generation. Defaults to “utc”. Supports any timezone code allowed by arrow.arrow.Arrow.
  • format (string, optional) – Format string used to generate labels from tick locations. The formatted value will be a arrow.arrow.Arrow object, so any of the attributes and formatting provided by https://arrow.readthedocs.org may be used in the format. For example, to display the full day of the week, month, day of the month without zero padding, and year, you could use:
  • >>> toyplot.locator.Timestamp(format=”{0 (dddd}, {0:MMMM} {0:D}, {0:YYYY}”))
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
class toyplot.locator.Uniform(count=5, format='{:g}')[source]

Bases: toyplot.locator.TickLocator

Generate \(N\) evenly spaced ticks that include the minimum and maximum values of a domain.

Parameters:
  • count (number, optional) – Number of ticks to generate.
  • format (string, optional) – Format string used to generate labels from tick locations.
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters:domain_min, domain_max (number)
Returns:
  • locations (sequence of numbers) – Axis locations where ticks should be displayed.
  • labels (sequence of strings) – Labels for each tick location.
  • titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.

toyplot.mark module

Provides data objects (marks) that are displayed on a canvas.

class toyplot.mark.AxisLines(coordinate_axes, table, coordinates, stroke, opacity, title, style, annotation)[source]

Bases: toyplot.mark.Mark

Render multiple lines parallel to an axis.

Do not create AxisLines instances directly. Use factory methods such as toyplot.coordinates.Cartesian.hlines() and toyplot.coordinates.Cartesian.vlines() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
class toyplot.mark.BarBoundaries(coordinate_axes, table, left, right, boundaries, fill, opacity, title, hyperlink, style, filename)[source]

Bases: toyplot.mark.Mark

Render multiple stacked bars defined by bar boundaries.

Do not create BarBoundaries instances directly. Use factory methods such as toyplot.bars() or toyplot.coordinates.Cartesian.bars() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.BarMagnitudes(coordinate_axes, table, left, right, baseline, magnitudes, fill, opacity, title, hyperlink, style, filename)[source]

Bases: toyplot.mark.Mark

Render multiple stacked bars defined by bar magnitudes.

Do not create BarMagnitudes instances directly. Use factory methods such as toyplot.bars() or toyplot.coordinates.Cartesian.bars() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.Ellipse(coordinate_axes, table, x, y, rx, ry, angle, fill, opacity, title, style, filename)[source]

Bases: toyplot.mark.Mark

Plot ellipses.

Do not create Ellipse instances directly. Use factory methods such as toyplot.coordinates.Cartesian.ellipse() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
class toyplot.mark.FillBoundaries(coordinate_axes, table, position, boundaries, fill, opacity, title, style, annotation, filename)[source]

Bases: toyplot.mark.Mark

Render multiple stacked fill regions defined by boundaries.

Do not create FillBoundaries instances directly. Use factory methods such as toyplot.fill() or toyplot.coordinates.Cartesian.fill() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.FillMagnitudes(coordinate_axes, table, position, baseline, magnitudes, fill, opacity, title, style, annotation, filename)[source]

Bases: toyplot.mark.Mark

Render multiple stacked fill regions defined by magnitudes.

Do not create FillMagnitudes instances directly. Use factory methods such as toyplot.fill() or toyplot.coordinates.Cartesian.fill() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.Graph(coordinate_axes, ecolor, ecoordinates, efilename, eopacity, eshape, esource, estyle, etable, etarget, ewidth, hmarker, mmarker, mposition, tmarker, vcolor, vcoordinates, vfilename, vid, vlabel, vlshow, vlstyle, vmarker, vopacity, vsize, vstyle, vtable, vtitle)[source]

Bases: toyplot.mark.Mark

Plot a graph (collection of vertices and edges).

Do not create Graph instances directly. Use factory methods such as toyplot.coordinates.Cartesian.graph() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
ecoordinates

Warning

attribute ‘toyplot.mark.Graph.ecoordinates’ undocumented

ecount

Return the number of edges in the graph.

edges

Return the graph edges as a \(E \times 2\) matrix of source, target indices.

eshapes

Warning

attribute ‘toyplot.mark.Graph.eshapes’ undocumented

esources

Warning

attribute ‘toyplot.mark.Graph.esources’ undocumented

etargets

Warning

attribute ‘toyplot.mark.Graph.etargets’ undocumented

vcoordinates

Return the graph vertex coordinates.

vcount

Return the number of vertices in the graph.

vids

Returns the graph vertex identifiers.

class toyplot.mark.Image(xmin_range, xmax_range, ymin_range, ymax_range, data)[source]

Bases: toyplot.mark.Mark

Plot a bitmap image.

Do not create Image instances directly. Use factory methods such as toyplot.image() and toyplot.canvas.Canvas.image() instead.

class toyplot.mark.Mark(annotation=False)[source]

Bases: object

Abstract interface for Toyplot marks.

Marks are data objects that are added to a coordinate system for display on a canvas. Marks carry no explicit visual representation of their own - it is up to the coordinate system and rendering backend to determine how to render the data.

For example, a scatterplot mark is rendered using points by a cartesian coordinate system, but could be rendered using lines by a hypothetical parallel coordinate system.

annotation

Warning

attribute ‘toyplot.mark.Mark.annotation’ undocumented

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
extents(axes)[source]

Return range extents for the mark using the given axes.

Parameters:axes (sequence of strings, required) – Specifies the order in which domain coordinates must be returned.
Returns:
  • coordinates (tuple containing arrays of coordinates, in the order specified by the axes parameter.)
  • extents ((left, right, top, bottom) tuple of arrays containing the extents of each datum in range-space, relative to the domain coordinates.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.Plot(coordinate_axes, table, coordinates, series, stroke, stroke_width, stroke_opacity, stroke_title, marker, msize, mfill, mstroke, mopacity, mtitle, style, mstyle, mlstyle, filename)[source]

Bases: toyplot.mark.Mark

Plot multiple bivariate data series using lines and/or markers.

Do not create Plot instances directly. Use factory methods such as toyplot.plot(), toyplot.scatterplot(), toyplot.coordinates.Cartesian.plot() and toyplot.coordinates.Cartesian.scatterplot() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.Point(coordinate_axes, coordinates, filename, marker, mfill, mhyperlink, mlstyle, mopacity, msize, mstroke, mstyle, mtitle, table)[source]

Bases: toyplot.mark.Mark

Represent one or more data series as points in an arbitrary-dimension space.

Do not create Point instances directly. Use factory methods such as toyplot.scatterplot() and toyplot.coordinates.Cartesian.scatterplot() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
markers

Return an ordered set of markers used by this mark, if any.

Returns:markers
Return type:list of toyplot.marker.Marker objects.
class toyplot.mark.Range(coordinate_axes, coordinates, filename, fill, opacity, style, table, title)[source]

Bases: toyplot.mark.Mark

Represents axis-aligned ranges (min/max pairs) in arbitrary-dimensional space.

Do not create Range instances directly. Use factory methods such as toyplot.coordinates.Cartesian.rects() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
class toyplot.mark.Text(coordinate_axes, table, coordinates, text, angle, fill, opacity, title, style, annotation, filename)[source]

Bases: toyplot.mark.Mark

Render text.

Do not create Text instances directly. Use factory methods such as toyplot.canvas.Canvas.text() or toyplot.coordinates.Cartesian.text() instead.

domain(axis)[source]

Return minimum and maximum domain values for the mark along the given axis.

Parameters:axis (string, required) – Name of an axis along which to return domain values.
Returns:
  • minimum (minimum domain value along the given axis, or None.)
  • maximum (maximum domain value along the given axis, or None.)
extents(axes)[source]

Return range extents for the mark using the given axes.

Parameters:axes (sequence of strings, required) – Specifies the order in which domain coordinates must be returned.
Returns:
  • coordinates (tuple containing arrays of coordinates, in the order specified by the axes parameter.)
  • extents ((left, right, top, bottom) tuple of arrays containing the extents of each datum in range-space, relative to the domain coordinates.)

toyplot.marker module

Functionality for managing markers (shapes used to highlight datums in plots and text).

class toyplot.marker.Marker(shape, mstyle, size, angle, label, lstyle)[source]

Bases: object

Represents the complete specification of a marker’s appearance.

angle

Warning

attribute ‘toyplot.marker.Marker.angle’ undocumented

intersect(p)[source]

Compute the intersection between this marker’s border and a line segment.

Parameters:p (numpy.ndarray with shape (2), required) – Relative coordinates of a line segment originating at the center of this marker.
Returns:dp – Relative coordinates of the intersection with this marker’s border.
Return type:numpy.ndarray with shape (2)
label

Warning

attribute ‘toyplot.marker.Marker.label’ undocumented

lstyle

Warning

attribute ‘toyplot.marker.Marker.lstyle’ undocumented

mstyle

Warning

attribute ‘toyplot.marker.Marker.mstyle’ undocumented

shape

Warning

attribute ‘toyplot.marker.Marker.shape’ undocumented

size

Warning

attribute ‘toyplot.marker.Marker.size’ undocumented

to_html()[source]

Convert a marker specification to HTML markup that can be embedded in rich text.

toyplot.marker.convert(value)[source]

Construct an instance of toyplot.marker.Marker from alternative representations.

toyplot.marker.create(shape=None, mstyle=None, size=None, angle=None, label=None, lstyle=None)[source]

Factory function for creating instances of toyplot.marker.Marker.

toyplot.marker.from_html(html)[source]

Convert a parsed xml.etree.ElementTree representation of a marker to a toyplot.marker.Marker object.

toyplot.mp4 module

toyplot.pdf module

Functions to render PDF documents.

toyplot.pdf.render(canvas, fobj=None, width=None, height=None, scale=None)[source]

Render the PDF representation of a canvas.

Because the canvas dimensions are specified explicitly at creation time, they map directly to real-world units in the output PDF image. Use one of width, height, or scale to override this behavior.

Parameters:
  • canvas (toyplot.canvas.Canvas) – Canvas to be rendered.
  • fobj (file-like object, string, or None) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the PDF data will be returned to the caller instead.
  • width (number, string, or (number, string) tuple, optional) – Specify the width of the output image with optional units. If the units aren’t specified, defaults to points. See Units for details on unit conversion in Toyplot.
  • height (number or (number, string) tuple, optional) – Specify the height of the output image with optional units. If the units aren’t specified, defaults to points. See Units for details on unit conversion in Toyplot.
  • scale (number, optional) – Scales the output canvas by the given ratio.
Returns:

pdf – PDF representation of canvas, or None if the caller specifies the fobj parameter.
Return type:

PDF data, or None

Examples

>>> toyplot.pdf.render(canvas, "figure-1.pdf", width=(4, "inches"))

Notes

The output PDF is currently rendered using toyplot.reportlab.pdf.render().

toyplot.png module

Functions to render PNG images.

toyplot.png.render(canvas, fobj=None, width=None, height=None, scale=None)[source]

Render the PNG bitmap representation of a canvas.

By default, canvas dimensions in CSS pixels are mapped directly to pixels in the output PNG image. Use one of width, height, or scale to override this behavior.

Parameters:
  • canvas (toyplot.canvas.Canvas) – Canvas to be rendered.
  • fobj (file-like object or string, optional) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the PNG data will be returned to the caller instead.
  • width (number, optional) – Specify the width of the output image in pixels.
  • height (number, optional) – Specify the height of the output image in pixels.
  • scale (number, optional) – Ratio of output image pixels to canvas pixels.
Returns:

png – Returns None if the caller specifies the fobj parameter, returns the PNG image data otherwise.
Return type:

bytes containing PNG image data, or None

Notes

The output PNG is rendered using toyplot.reportlab.png.render(). This is subject to change.

toyplot.png.render_frames(canvas, width=None, height=None, scale=None)[source]

Render a canvas as a sequence of PNG images.

By default, canvas dimensions in CSS pixels are mapped directly to pixels in the output PNG images. Use one of width, height, or scale to override this behavior.

Parameters:
  • canvas (toyplot.canvas.Canvas) – Canvas to be rendered.
  • width (number, optional) – Specify the width of the output image in pixels.
  • height (number, optional) – Specify the height of the output image in pixels.
  • scale (number, optional) – Ratio of output image pixels to canvas pixels.
Returns:

frames – The caller must iterate over the returned frames and is responsible for all subsequent processing, including disk I/O, video compression, etc.
Return type:

Sequence of bytes objects containing PNG image data.

Notes

The output PNG images are rendered using toyplot.reportlab.png.render_frames(). This is subject to change.

Examples

>>> for frame, png in enumerate(toyplot.png.render_frames(canvas)):
...   open("frame-%s.png" % frame, "wb").write(png)

toyplot.projection module

Classes and functions for projecting coordinates between spaces.

class toyplot.projection.Piecewise(segments)[source]

Bases: toyplot.projection.Projection

Projects between domain and range data using a piecewise collection of linear and log segments.

Parameters:
  • segments (sequence of toyplot.projection.Piecewise.Segment objects, required) – Callers must supply one-to-many segments, each of which defines a mapping between bounded, non-overlapping regions of the domain and range spaces.
  • .. automethod:: __call__
class Segment(scale, domain_bounds_min, domain_min, domain_max, domain_bounds_max, range_bounds_min, range_min, range_max, range_bounds_max)[source]

Bases: object

Defines a mapping between bounded regions of domain-space and range-space.

Parameters:
  • scale (“linear” or (“log”, base) tuple, required)
  • domain_bounds_min, domain_bounds_max (number, required) – These values define the bounds of this segment in domain space, and may include positive or negative infinity.
  • domain_min, domain_max (number, required) – These values are mapped to range_min and range_max, respectively.
  • range_min, range_max (number, required) – These values are mapped to domain_min and domain_max, respectively.
  • range_bounds_min, range_bounds_max (number, required) – These values define the bounds of this segment in range space, and may include positive or negative infinity.
inverse(range_values)[source]

Map range values to domain values.

Parameters:range_values (numpy.ndarray or compatible.) – The range values to convert.
Returns:domain_values – The range values projected into domain values.
Return type:numpy.ndarray

Examples

>>> projection = toyplot.projection.linear(0, 1, -1, 1)
>>> projection.inverse(-0.5)
0.25
class toyplot.projection.Projection[source]

Bases: object

Abstract interface for objects that can map between one-dimensional domain and range spaces.

__call__(domain_values)[source]

Map domain values to range values.

Parameters:domain_values (numpy.ndarray or compatible.) – The domain values to convert.
Returns:range_values – The domain values projected into range values.
Return type:numpy.ndarray

Examples

>>> projection = toyplot.projection.linear(0, 1, -1, 1)
>>> projection(0.75)
0.5
inverse(range_values)[source]

Map range values to domain values.

Parameters:range_values (numpy.ndarray or compatible.) – The range values to convert.
Returns:domain_values – The range values projected into domain values.
Return type:numpy.ndarray

Examples

>>> projection = toyplot.projection.linear(0, 1, -1, 1)
>>> projection.inverse(-0.5)
0.25
toyplot.projection.linear(domain_min, domain_max, range_min, range_max)[source]

Return an instance of toyplot.projection.Piecewise that performs a linear projection.

Parameters:
  • domain_min, domain_max (number) – Defines a closed interval of domain values that will be mapped to the range.
  • range_min, range_max (number) – Defines a closed interval of range values that will be mapped to the domain.
Returns:

projection
Return type:

toyplot.projection.Piecewise
toyplot.projection.log(base, domain_min, domain_max, range_min, range_max, linear_domain_min=-1, linear_domain_max=1)[source]

Return an instance of toyplot.projection.Piecewise that performs a log projection.

The returned projection will work correctly with both positive, negative, and zero domain values. To support mapping zero, the projection will switch from log projection to a linear projection within a user-defined region around the origin.

Parameters:
  • base (number) – Logarithmic base used to map from domain values to range values.
  • domain_min, domain_max (number) – Defines a closed interval of domain values that will be mapped to the range.
  • range_min, range_max (number) – Defines a closed interval of range values that will be mapped to the domain.
  • linear_domain_min, linear_domain_max (number, optional) – Defines an interval of domain values around the origin that will be mapped linearly.
Returns:

projection
Return type:

toyplot.projection.Piecewise

toyplot.reportlab.pdf module

Functions to render PDF documents using ReportLab.

toyplot.reportlab.pdf.render(canvas, fobj=None, width=None, height=None, scale=None)[source]

Render the PDF representation of a canvas using ReportLab.

Because the canvas dimensions are specified explicitly at creation time, they map directly to real-world units in the output PDF image. Use one of width, height, or scale to override this behavior.

Parameters:
  • canvas (toyplot.canvas.Canvas) – Canvas to be rendered.
  • fobj (file-like object or string) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the PDF data will be returned to the caller instead.
  • width (number, string, or (number, string) tuple, optional) – Specify the width of the output image with optional units. If the units aren’t specified, defaults to points. See Units for details on unit conversion in Toyplot.
  • height (number or (number, string) tuple, optional) – Specify the height of the output image with optional units. If the units aren’t specified, defaults to points. See Units for details on unit conversion in Toyplot.
  • scale (number, optional) – Scales the output canvas by the given ratio.
Returns:

pdf – PDF representation of canvas, or None if the caller specifies the fobj parameter.
Return type:

PDF data, or None

Examples

>>> toyplot.reportlab.pdf.render(canvas, "figure-1.pdf", width=(4, "inches"))

toyplot.reportlab.png module

Functions to render PNG images using Ghostscript.

toyplot.reportlab.png.render(canvas, fobj=None, width=None, height=None, scale=None)[source]

Render the PNG bitmap representation of a canvas using ReportLab and Ghostscript.

By default, canvas dimensions in CSS pixels are mapped directly to pixels in the output PNG image. Use one of width, height, or scale to override this behavior.

Parameters:
  • canvas (toyplot.canvas.Canvas) – Canvas to be rendered.
  • fobj (file-like object or string, optional) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the PNG data will be returned to the caller instead.
  • width (number, optional) – Specify the width of the output image in pixels.
  • height (number, optional) – Specify the height of the output image in pixels.
  • scale (number, optional) – Ratio of output image pixels to canvas pixels.
Returns:

png – Returns None if the caller specifies the fobj parameter, returns the PNG image data otherwise.
Return type:

bytes containing PNG image data, or None
toyplot.reportlab.png.render_frames(canvas, width=None, height=None, scale=None)[source]

Render a canvas as a sequence of PNG images using ReportLab and Ghostscript.

By default, canvas dimensions in CSS pixels are mapped directly to pixels in the output PNG images. Use one of width, height, or scale to override this behavior.

Parameters:
  • canvas (toyplot.canvas.Canvas) – Canvas to be rendered.
  • width (number, optional) – Specify the width of the output image in pixels.
  • height (number, optional) – Specify the height of the output image in pixels.
  • scale (number, optional) – Ratio of output image pixels to canvas pixels.
Returns:

frames – The caller must iterate over the returned frames and is responsible for all subsequent processing, including disk I/O, video compression, etc.
Return type:

Sequence of bytes objects containing PNG image data.

Examples

>>> for frame, png in enumerate(toyplot.reportlab.png.render_frames(canvas)):
...   open("frame-%s.png" % frame, "wb").write(png)

toyplot.reportlab module

Support functions for rendering using ReportLab.

toyplot.reportlab.render(svg, canvas)[source]

Render the SVG representation of a toyplot canvas to a ReportLab canvas.

Parameters:
  • svg (xml.etree.ElementTree.Element) – SVG representation of a toyplot.canvas.Canvas returned by toyplot.svg.render().
  • canvas (reportlab.pdfgen.canvas.Canvas) – ReportLab canvas that will be used to render the plot.

toyplot.require module

Functions used by the Toyplot implementation to validate inputs. These are not intended for end-users.

toyplot.require.filename(value)[source]

Raise an exception if a value isn’t a valid string filename, or None.

Raise an exception if a value isn’t a valid string hyperlink, or None.

toyplot.require.instance(value, types)[source]

Raise an exception if a value isn’t one of the given type(s).

toyplot.require.integer_vector(value, length=None, min_length=None, modulus=None)[source]

Raise an exception if a value isn’t convertable to a 1D array of integers.

toyplot.require.optional_string(value)[source]

Raise an exception if a value isn’t a string, or None.

toyplot.require.scalar(value)[source]

Raise an exception if a value isn’t a number.

toyplot.require.scalar_array(value)[source]

Raise an exception if a value isn’t convertable to an array of numbers.

toyplot.require.scalar_matrix(value, rows=None, columns=None)[source]

Raise an exception if a value isn’t convertable to a 2D array of numbers.

toyplot.require.scalar_vector(value, length=None, min_length=None, modulus=None)[source]

Raise an exception if a value isn’t convertable to a 1D array of numbers.

toyplot.require.string_vector(value, length=None, min_length=None, modulus=None)[source]

Raise an exception if a value isn’t convertable to a 1D array of numbers.

toyplot.require.table_keys(table, keys, length=None, min_length=None, modulus=None)[source]

Raise an exception if any of the given keys fails to match the column keys in the given table.

toyplot.require.value_in(value, choices)[source]

Raise an exception if a value doesn’t match one of the given choices.

toyplot.require.vector(value, length=None, min_length=None, modulus=None)[source]

Raise an exception if a value isn’t convertable to a 1D array.

toyplot.style module

Functionality for working with CSS style information.

class toyplot.style.allowed[source]

Bases: object

Defines groups of allowable CSS property names.

fill = {'stroke', 'stroke-width', 'opacity', 'fill-opacity', 'stroke-opacity', 'fill', 'stroke-dasharray'}

Allowable CSS property names for filling areas.

line = {'stroke', 'stroke-width', 'stroke-linecap', 'opacity', 'stroke-opacity', 'stroke-dasharray'}

Allowable CSS property names for stroking lines.

marker = {'stroke-width', 'opacity', 'fill-opacity', 'stroke-opacity', 'fill', 'stroke'}

Allowable CSS property names for Markers.

text = {'-toyplot-anchor-shift', 'line-height', '-toyplot-text-layout-line-visibility', 'font-family', '-toyplot-text-layout-visibility', 'baseline-shift', 'stroke-width', 'text-anchor', 'text-shadow', 'alignment-baseline', '-toyplot-text-layout-box-visibility', 'opacity', 'fill-opacity', 'font-size', 'stroke-opacity', 'fill', 'stroke', 'font-weight', '-toyplot-vertical-align'}

Allowable CSS property names for text.

toyplot.style.combine(*styles)[source]

Combine multiple style specifications into one.

Parameters:styles (sequence of dict instances) – A collection of dicts containing CSS-compatible name-value pairs.
Returns:styles
Return type:dict containing CSS-compatible name-value pairs.
toyplot.style.parse(css)[source]

Parse a CSS style into a dict.

toyplot.style.require(css, allowed)[source]

Validate that an object is usable as CSS style information.

Parameters:
  • css (dict or None) – The style dictionary to be validated. An exception will be raised if it is not a valid style dictionary or None.
  • allowed (sequence of strings) – The set of allowed style properties. An exception will be raised if css contains any keys that aren’t in this sequence.
Returns:

style – The validated style dictionary.
Return type:

dict
toyplot.style.to_css(*styles)[source]

Convert one-or-more dicts containing CSS properties into a single CSS string.

toyplot.svg module

Generates SVG images.

toyplot.svg.apply_changes(svg, changes)[source]

Modify the SVG DOM representation of a canvas with the given changes.

toyplot.svg.render(canvas, fobj=None, animation=False)[source]

Render the SVG representation of a canvas.

Parameters:
  • canvas (toyplot.canvas.Canvas) – The canvas to be rendered.
  • fobj (file-like object or string, optional) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the SVG tree will be returned to the caller instead.
  • animation (boolean, optional) – If True, return a representation of the changes to be made to the SVG tree for animation.
Returns:

  • svg (xml.etree.ElementTree.Element or None) – SVG representation of canvas, as a DOM tree, or None if the caller specifies the fobj parameter.
  • changes (JSON-compatible data structure, or None) – JSON-compatible representation of the animated changes to canvas.

toyplot.text module

Functions for manipulating text.

class toyplot.text.Layout(style)[source]

Bases: object

Top-level container for one-or-more lines of text.

class toyplot.text.LineBox(style)[source]

Bases: object

Container for one line of text.

class toyplot.text.MarkerBox(marker, style)[source]

Bases: object

Container for a Toyplot marker specification.

Bases: object

Marks the end of a hyperlink.

Bases: object

Marks the beginning of a hyperlink.

class toyplot.text.TextBox(text, style)[source]

Bases: object

Container for a block of text that shares a single style.

toyplot.text.dump(box, stream=None, level=0, indent=' ', recursive=True)[source]

Writes formatted text layout information to a stream.

Parameters:
toyplot.text.extents(text, angle, style)[source]

Compute canvas coordinate extents for a text string, based on the given angle and style.

toyplot.text.layout(text, style, fonts)[source]

Convert text with markup into a layout that is ready to be rendered.

Parameters:
  • text (string, required) – Text with markup to be converted.
  • style (dict, required) – Collection of CSS properties to be used as defaults for the text layout.
  • fonts (toyplot.font.Library, required) – Font library that will supply font information for the text layout.
Returns:

layout – The text layout contains a hierarchy of styled, positiioned nodes that are ready to be rendered.
Return type:

toyplot.text.Layout

toyplot.transform module

Functions for manipulating transformation matrices.

toyplot.transform.rotation(angle)[source]

Return a 2D transformation matrix.

Parameters:angle (number) – Rotation angle in degrees. Positive values produce counterclockwise rotation.

toyplot.units module

Functionality for performing unit conversions.

toyplot.units.convert(value, target, default=None, reference=None)[source]

Convert quantities using real-world units.

Supported unit abbreviations include: centimeter, centimeters, cm, decimeter, decimeters, dm, in, inch, inches, m, meter, meters, mm, millimeter, millimeters, pc, pica, picas, point, points, pt, pixel, pixels, and px.

Relative quantities can be specified using %.

Parameters:
  • value (number, string or (number, string) tuple) – Value to be converted. The value may be a number (in which case the default parameter must specify the default unit of measure), a string containing a number and unit abbreviation, or a (value, units) tuple.
  • target (string) – Unit of measure to convert to.
  • default (optional string) – Default unit of measure to use when value is a plain number, or when reference has been specified.
  • reference (optional number) – When the caller specifies a relative measure using % as the unit abbreviation, the returned value will equal value * 0.01 * reference. Note that the reference must be specified in target units.
Returns:
Return type:

Returns value converted to the target units, as a floating point number.
_images/toyplot.png

Javascript API

Note that the Javascript API described here is for developers adding new functionality to Toyplot … casual Toyplot users will never need to work with this code.

toyplot/canvas/id module

The toyplot/canvas/id module is a string containing the globally-unique HTML DOM id for the SVG element containing a Toyplot figure. You can use this id to reference the SVG element and make changes. For example:

context.require(dependencies=["toyplot/canvas/id"], code="""function(canvas_id)
{
    var canvas = document.querySelector("#" + canvas_id);
    /* Make changes to the figure using canvas. */
}""")

toyplot/canvas module

The toyplot/canvas module is a reference to the SVG element that contains the figure. For example:

context.require(dependencies=["toyplot/canvas"], code="""function(canvas)
{
    /* Make changes to the figure using canvas. */
}""")

toyplot/io module

The toyplot/io module contains functionality for exporting data from the viewer’s browser.

toyplot/io.save_file(mime_type, charset, data, filename)

Save data from the viewer’s browser to a file. For example:

context.require(
    dependencies=["toyplot/tables", "toyplot/io"],
    code="""function(tables, io)
    {
        var data = tables.get_csv("my-graph", "vertices");
        io.save_file("text/csv", "utf-8", data, "my-graph-vertices.csv");
    }""")

Note that the behavior of individual browsers when saving files will vary - they may-or-may not prompt the user to choose an alternate filename, or offer to open the file in some other application instead.

Arguments:
  • mime_type – String MIME type of the data to be saved (e.g. “text/csv”).
  • charset – String character encoding of the data to be saved (e.g. “utf-8”).
  • data – String data to be saved.
  • filename – Suggested filename string to use for saving the data to disk.

toyplot/menus/context module

The toyplot/menus/context module provides functionality to display custom context menu entries when the user right-clicks over a figure.

toyplot/menus/context.add_item(label, show, activate)

Adds a new menu item to the context menu. Each menu item has a label, a callback to determine when item should be visible, and a callback to performe some action when the item is activated by the user. Typically, menu items are added by individual marks, and the visibility callback will show the item if the mouse pointer was over the mark when the context menu was opened. For example:

context.require(
    dependencies["toyplot/menus/context"],
    code="""function(menus)
    {
        // This item will always be visible.
        function show() { return true; }
        function activate() { console.log("Hello, World!"); }
        menus.add_item("Hello World!", show, activate);
    }""")

Note that the Toyplot context menu will not be shown if there are no visible items. When this happens the system context menu will be shown instead.

Arguments:
  • label – Human readable string label for the menu item to be added.
  • show – Javascript callback function that will be called before the context menu is opened. The function must take one argument - the DOM event that is causing the context menu to be shown (such as a contextmenu or mousedown event). The callback should return true if the menu item should be visible, or false otherwise.
  • activate – Javascript callback function that will be called if the user selects this item.

toyplot/root/id module

The toyplot/root/id module is a string containing the globally-unique HTML DOM id for a Toyplot figure. You can use this id to reference the outer DOM element that contains the figure. For example:

context.require(dependencies=["toyplot/root/id"], code="""function(root_id)
{
    var root = document.querySelector("#" + root_id);
    /* Make global changes to the figure using root. */
}""")

toyplot/root module

The toyplot/root module is a reference to the outer DOM element that contains the figure. For example:

context.require(dependencies=["toyplot/root"], code="""function(root)
{
    /* Make global changes to the figure using root. */
}""")

toyplot/tables module

The toyplot/tables module can be used to store tabular data for later retrieval.

toyplot/tables.set(owner, key, names, columns)

Store tabular information, identified by owner and key, for later retrieval. For example:

context.require(
    dependencies=["toyplot/tables"],
    arguments=[mark_id, column_names, columns],
    code="""function(tables, mark_id, column_names, columns)
    {
        tables.store(mark_id, "vertex_data", column_names, columns);
    }""")
Arguments:
  • owner – Unique string id for the object that “owns” the table.
  • key – String key used to disambiguate tables when the owner has more than one.
  • names – Array of string names for each column in the table.
  • columns – Array of value arrays for eacn column in the table.
toyplot/tables.get(owner, key)

Retrieve a table stored previously using toyplot/tables.set(). For example:

context.require(
    dependencies=["toyplot/tables"],
    arguments=[graph_id],
    code="""function(tables, graph_id)
    {
        console.log(tables.get(graph_id, "vertex_data"));
    }""")
Arguments:
  • owner – Unique string id for the object that “owns” the table.
  • key – String key used to disambiguate tables when the owner has more than one.
Returns:

object containing names and columns arrays, containing the table column names and column values, respectively.
_images/toyplot.png

Support

The Toyplot documentation:

Visit our GitHub repository for access to source code, issue tracker, and the wiki:

We also have a continuous integration server that runs the Toyplot regression test suite anytime changes are committed to GitHub:

And here are our test coverage stats, also updated automatically when modifications are committed:

For Toyplot questions, comments, or suggestions, get in touch with the team at:

Otherwise, you can contact Tim directly:

_images/toyplot.png

Credits

Included in Toyplot

Cynthia A. Brewer, “ColorBrewer: Color Advice for Maps,” http://colorbrewer2.org, accessed October, 2014.

K. Moreland, “Diverging Color Maps for Scientific Visualization,” presented at the ISVC ‘09: Proceedings of the 5th International Symposium on Advances in Visual Computing: Part II, Berlin, Heidelberg, 2009, vol. 5876, no. 9, pp. 92–103, http://www.sandia.gov/~kmorel/documents/ColorMaps.

J. Talbot, S. Lin, and P. Hanrahan, “An Extension of Wilkinson’s Algorithm for Positioning Tick Labels on Axes,” IEEE Transactions on Visualization and Computer Graphics, vol. 16, no. 6, pp. 1036–1043, Nov. 2010, http://www.justintalbot.com/research/axis-labeling.

Paul S. Heckbert, “Nice numbers for graph labels,” 1990, In Graphics gems, Andrew S. Glassner (Ed.). Academic Press Professional, Inc., San Diego, CA, USA 61-63.

Ian Storm Taylor, “Design Tip: Never Use Black,” http://ianstormtaylor.com/design-tip-never-use-black, accessed October, 2014.

L. Byron and M. Wattenberg, “Stacked Graphs – Geometry & Aesthetics,” IEEE Transactions on Visualization and Computer Graphics, vol. 14, no. 6, pp. 1245–1252, Nov. 2008, http://leebyron.com/streamgraph/stackedgraphs_byron_wattenberg.pdf.

Color conversions in the toyplot.color module were ported to run in Python from the ColorMine library, http://colormine.org:

The MIT License (MIT)

Copyright (c) 2013 ColorMine.org

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Influential Reading

Jake Vanderplas, “Matplotlib and the Future of Visualization in Python,” http://jakevdp.github.io/blog/2013/03/23/matplotlib-and-the-future-of-visualization-in-python, accessed October, 2014.

Michael Droettboom, “Matplotlib Lessons Learned,” http://mdboom.github.io/blog/2013/03/25/matplotlib-lessons-learned, accessed October, 2014.

Olga Botvinnik, “prettyplotlib: Painlessly create beautiful matplotlib plots,” http://blog.olgabotvinnik.com/prettyplotlib, accessed October 2014.

Indices and tables