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)

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

canvas = toyplot.Canvas(width=300)
axes = canvas.cartesian()


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- 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\):

    label="Toyplot Users",
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()
DateDeliveredOn Time

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.