Matrix Plots

class sage.plot.matrix_plot.MatrixPlot(xy_data_array, xrange, yrange, options)

Bases: sage.plot.primitive.GraphicPrimitive

Primitive class for the matrix plot graphics type. See matrix_plot? for help actually doing matrix plots.


  • xy_data_array - list of lists giving matrix values corresponding to the grid
  • xrange - tuple of 2 floats indicating range for horizontal direction (number of columns in the matrix)
  • yrange - tuple of 2 floats indicating range for vertical direction (number of rows in the matrix)
  • options - dict of valid plot options to pass to constructor


Note this should normally be used indirectly via matrix_plot():

sage: from sage.plot.matrix_plot import MatrixPlot
sage: M = MatrixPlot([[1,3],[2,4]],(1,2),(2,3),options={'cmap':'winter'})
sage: M
MatrixPlot defined by a 2 x 2 data grid
sage: M.yrange
(2, 3)
sage: M.xy_data_array
[[1, 3], [2, 4]]
sage: M.options()
{'cmap': 'winter'}

Extra options will get passed on to show(), as long as they are valid:

sage: matrix_plot([[1, 0], [0, 1]], fontsize=10)
sage: matrix_plot([[1, 0], [0, 1]]).show(fontsize=10) # These are equivalent


We test creating a matrix plot:

sage: matrix_plot([[mod(i,5)^j for i in range(5)] for j in range(1,6)])

Returns a dictionary with the bounding box data.


sage: m = matrix_plot(matrix([[1,3,5,1],[2,4,5,6],[1,3,5,7]]))[0]
sage: list(sorted(m.get_minmax_data().items()))
[('xmax', 3.5), ('xmin', -0.5), ('ymax', -0.5), ('ymin', 2.5)]
sage.plot.matrix_plot.matrix_plot(*args, **kwds)

A plot of a given matrix or 2D array.

If the matrix is dense, each matrix element is given a different color value depending on its relative size compared to the other elements in the matrix. If the matrix is sparse, colors only indicate whether an element is nonzero or zero, so the plot represents the sparsity pattern of the matrix.

The tick marks drawn on the frame axes denote the row numbers (vertical ticks) and the column numbers (horizontal ticks) of the matrix.


  • mat - a 2D matrix or array

The following input must all be passed in as named parameters, if default not used:

  • cmap - a colormap (default: ‘gray’), the name of a predefined colormap, a list of colors, or an instance of a matplotlib Colormap. Type: import; for available colormap names.
  • norm - If None (default), the value range is scaled to the interval [0,1]. If ‘value’, then the actual value is used with no scaling. A matplotlib.colors.Normalize instance may also passed.
  • vmin - The minimum value (values below this are set to this value)
  • vmax - The maximum value (values above this are set to this value)
  • origin - If ‘upper’ (default), the first row of the matrix is on the top of the graph. If ‘lower’, the first row is on the bottom of the graph.


A matrix over \ZZ colored with different grey levels:

sage: matrix_plot(matrix([[1,3,5,1],[2,4,5,6],[1,3,5,7]]))

Here we make a random matrix over \RR and use cmap='hsv' to color the matrix elements different RGB colors:

sage: matrix_plot(random_matrix(RDF, 50), cmap='hsv')

By default, entries are scaled to the interval [0,1] before determining colors from the color map. That means the two plots below are the same:

sage: P = matrix_plot(matrix(2,[1,1,3,3]))
sage: Q = matrix_plot(matrix(2,[2,2,3,3]))
sage: P; Q

However, we can specify which values scale to 0 or 1 with the vmin and vmax parameters (values outside the range are clipped). The two plots below are now distinguished:

sage: P = matrix_plot(matrix(2,[1,1,3,3]), vmin=0, vmax=3)
sage: Q = matrix_plot(matrix(2,[2,2,3,3]), vmin=0, vmax=3)
sage: P; Q

We can also specify a norm function of ‘value’, which means that there is no scaling performed:

sage: matrix_plot(random_matrix(ZZ,10)*.05, norm='value')

Generally matrices are plotted with the (0,0) entry in the upper left. However, sometimes if we are plotting an image, we’d like the (0,0) entry to be in the lower left. We can do that with the origin argument:

sage: matrix_plot(identity_matrix(100), origin='lower')

Another random plot, but over \GF{389}:

sage: m = random_matrix(GF(389), 10)
sage: matrix_plot(m, cmap='Oranges')

It also works if you lift it to the polynomial ring:

sage: matrix_plot(m.change_ring(GF(389)['x']), cmap='Oranges')

Here we plot a random sparse matrix:

sage: sparse = matrix(dict([((randint(0, 10), randint(0, 10)), 1) for i in xrange(100)]))
sage: matrix_plot(sparse)
sage: A=random_matrix(ZZ,100000,density=.00001,sparse=True)
sage: matrix_plot(A,marker=',')

As with dense matrices, sparse matrix entries are automatically converted to floating point numbers before plotting. Thus the following works:

sage: b=random_matrix(GF(2),200,sparse=True,density=0.01)
sage: matrix_plot(b)

While this returns an error:

sage: b=random_matrix(CDF,200,sparse=True,density=0.01)
sage: matrix_plot(b)
Traceback (most recent call last):
ValueError: can not convert entries to floating point numbers

To plot the absolute value of a complex matrix, use the apply_map method:

sage: b=random_matrix(CDF,200,sparse=True,density=0.01)
sage: matrix_plot(b.apply_map(abs))

Plotting lists of lists also works:

sage: matrix_plot([[1,3,5,1],[2,4,5,6],[1,3,5,7]])

As does plotting of NumPy arrays:

sage: import numpy
sage: matrix_plot(numpy.random.rand(10, 10))


sage: P.<t> = RR[]
sage: matrix_plot(random_matrix(P, 3, 3))
Traceback (most recent call last):
TypeError: cannot coerce nonconstant polynomial to float
sage: matrix_plot([1,2,3])
Traceback (most recent call last):
TypeError: mat must be a Matrix or a two dimensional array
sage: matrix_plot([[sin(x), cos(x)], [1, 0]])
Traceback (most recent call last):
ValueError: can not convert entries to floating point numbers

Previous topic

Step function plots

Next topic

Plotting fields

This Page