.. _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 the data. To facilitate this, Toyplot provides :meth:toyplot.canvas.Canvas.matrix and :func:toyplot.matrix functions. To demonstrate, let's begin with a visualization of a matrix containing values from a normal distribution centered at 1.0:
In [1]:
import numpy
numpy.random.seed(1234)
matrix = numpy.random.normal(loc=1.0, size=(20, 20))
In [2]:
import toyplot
toyplot.matrix(matrix, label="A matrix");
By default, the matrix is rendered using the Color Brewer diverging "BlueRed" :ref:palette<color>, 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 as a popup and compare them to the minimum and maximum values in the data:
In [3]:
print matrix.min(), matrix.max()
However, let's say that we want 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 :class:toyplot.color.LinearMap, specifying explicit minimum and maximum domain values and using it in the call to create the matrix visualization:
In [4]:
colormap = toyplot.color.LinearMap(toyplot.color.brewer("BlueRed"), domain_min=-4, domain_max=4)
toyplot.matrix(matrix, label="A matrix", colormap=colormap);
As your matrix sizes grow, you may need to thin-out the row and column indices to avoid overlap:
In [5]:
big_matrix = numpy.random.normal(loc=1, size=(50, 50))
toyplot.matrix(big_matrix, step=5, label="A matrix", colormap=colormap);
Or, you may wish to leave off the indices altogether:
In [6]:
toyplot.matrix(big_matrix, xshow=False, yshow=False, label="A matrix", colormap=colormap);
Note that the matrix visualization in Toyplot is actually just a factory function that creates and populates a set of :ref:table-axes, so you can use the full :class:toyplot.axes.Table API to configure it however you like. For example, you could highlight the maximum value in the matrix using a contrasting color:
In [7]:
i, j = numpy.unravel_index(numpy.argmax(matrix), matrix.shape)
canvas, table = toyplot.matrix(matrix, label="A matrix", colormap=colormap)
table.body.cell(i, j).bstyle = {"fill":"yellow"}
Or you could use the table API to overwrite or replace the default labels:
In [8]:
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, 0).style = {"fill":"red"}
table.top.cell(0, 25).style = {"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 :ref:canvas-layout mechanisms as usual:
In [9]:
canvas = toyplot.Canvas(width=600, height=400)
table = canvas.matrix(matrix, label="Matrix", bounds=(50, -250, 50, -50), step=5)
axes = canvas.axes(bounds=(-200, -50, 50, -50), label="Distribution", xlabel="Count", ylabel="Value")
axes.bars(numpy.histogram(matrix, 20), along="y")
Out[9]: