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