matspy 0.6

Sparse matrix spy plot, HTML, and LaTeX rendering with Jupyter integration.

MatSpy

Sparse matrix spy plot and sparkline renderer.

Supports:

• scipy.sparse sparse matrices and arrays like csr_matrix and coo_array.
• python-graphblas sparse matrix gb.Matrix. See demo.

See a Jupyter notebook demo.

For HTML/LaTeX see MatRepr.

Quick Start

pip install matspy

from matspy import spy

spy(A)

Methods

• spy(A): Plot the sparsity pattern (location of nonzero values) of sparse matrix A.
• to_sparkline(A): Return a small spy plot as a self-contained HTML string.
• spy_to_mpl(A): Same as spy() but returns the matplotlib Figure without showing it.
• to_spy_heatmap(A): Return the raw 2D array for spy plots.

Arguments

All methods take the same arguments. Apart from the matrix itself:

• title: string label. If True, then a matrix description is auto generated.
• indices: Whether to show matrix indices.
• figsize, sparkline_size: size of the plot, in inches
• shading: binary, relative, absolute.
• buckets: spy plot pixels (longest side).
• dpi: determine buckets relative to figure size.

Overriding defaults

matspy.params contains the default values for all arguments.

For example, to default to binary shading, no title, and no indices:

matspy.params.shading = 'binary'
matspy.params.title = False
matspy.params.indices = False

Jupyter

spy() simply shows a matplotlib figure and works well within Jupyter.

to_sparkline() can create small matrix visualizations that work anywhere HTML is displayed. Multiple sparklines can be automatically to-scale with each other using the retscale and scale arguments.

Fast

All operations work with very large matrices. A spy plot of tens of millions of elements takes less than half a second.

Large matrices are downscaled using two native matrix multiplies. The final dense 2D image is small.

Spy Plot Anti-Aliasing

One application of spy plots is to quickly see if a matrix has a noticeable structure. Aliasing artifacts can give the false impression of structure where none exists, such as moiré or even a false grid pattern.

MatSpy employs some simple methods to help eliminate these effects in most cases.

See the Anti-Aliasing demo for more.

How to support more packages

Each package that MatSpy supports implements two classes:

• Driver: Declares what types are supported and supplies an adapter.
  • get_supported_type_prefixes: This declares what types are supported, as strings to avoid unnecessary imports.
  • adapt_spy(A): Returns a MatrixSpyAdapter for a matrix that this driver supports.
• MatrixSpyAdapter. A common interface for extracting spy data.
  • describe(): Describes the adapted matrix. This description serves as the plot title.
  • get_shape(): Returns the adapted matrix's shape.
  • get_spy(): Returns spy plot data as a dense 2D numpy array.

See matspy/adapters for details.

You may use matspy.register_driver to register a Driver for your own matrix class.