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

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]);


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]);


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]);


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.scatterplot(events.T[0])
numberline.scatterplot(events.T[1])
numberline.scatterplot(events.T[2], offset=40)
numberline.scatterplot(events.T[3], offset=50);


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},
);


In addition to scatterplots, 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})


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)


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)


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)


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


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.colormap(colormap1)
numberline.colormap(colormap2)
numberline.scatterplot([0], marker="d", color="black");


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={"border":"1px solid lightgray"})

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));


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, style={"border":"1px solid lightgray"})

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);