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

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

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

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

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

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

toyplot.matrix((big_matrix, colormap), tshow=False, lshow=False, label="A matrix");

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

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

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

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"

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