MatRepr

Make every matrix beautiful.

MatRepr formats matrices and tensors to HTML, string, and LaTeX, with Jupyter integration. See Jupyter notebook for examples.

Brief examples:

from matrepr import mdisplay, mprint

mprint(A) or to_str(A):

<1000×1000, 212345 'float64' elements, coo>       0       1       2       3       4       5        6       7   ┌                                                                      ┐ 0 │                                 0.3876                           ... │ 1 │ 0.5801  0.5085          0.8927                           0.629   ... │ 2 │                                                                  ... │ 3 │                 0.7142                                           ... │ 4 │                                         0.8631                   ... │ 5 │ 0.7863  0.1298  0.9918   0.71                            0.3444  ... │ 6 │                 0.9481                          0.9609           ... │ 7 │                                                 0.09361  0.1679  ... │ 8 │                                 0.4023                           ... │   │   :       :       :       :       :       :        :       :     ... │   └                                                                      ┘

mdisplay(A) or to_html(A):

Supports:

• SciPy - sparse matrices and arrays like csrmatrix and cooarray
• NumPy - ndarray (demo)
• PyTorch - dense and sparse torch.Tensor (demo)
• TensorFlow - tf.Tensor and tf.SparseTensor (demo)
• Python-graphblas - gb.Matrix and gb.Vector (demo)
• PyData/Sparse - COO, DOK, GCXS (demo)
• list, tuple, including multi-dimensional and ragged

Features:

• Jupyter extension to format matrices in cell outputs.
• Configurable float precision or format string.
• Toggle row and column indices or set your own labels.
• Nested sub-matrices of any supported type, including mixing packages.
• Toggle matrix description or set your own title.
• String output can optionally autodetect terminal width.
• Methods to directly display a matrix (mprint, mdisplay for Jupyter)
• Methods to convert to string (tohtml, tolatex, to_str).
• Configurable per method call or set defaults with matrepr.params.
• A repr monkey patch to format matrices in the Python shell.
• Fast.

Install:

pip install matrepr

or

conda install matrepr

More Examples

HTML

mdisplay(A), to_html(A) or simply A with Jupyter extension %load_ext matrepr

LaTeX

mdisplay(A, 'latex'), to_latex(A) or simply A with Jupyter extension %load_ext matrepr.latex

Jupyter Extension

MatRepr's Jupyter extension registers with Jupyter's formatter to format supported matrices with MatRepr. Simply:

%load_ext matrepr

Or if you prefer LaTeX:

%load_ext matrepr.latex

Example:

Methods

• to_str(A): Format A as a text string.
• to_html(A): Format A as a plain or notebook-styled HTML table. Returns a string.
• to_latex(A): Format A as a LaTeX matrix. Returns a string.
• mprint(A): print A as a string to stdout.
• mdisplay(A): Displays the output of tohtml, tolatex, or to_str in Jupyter.

Note: For Spy plots see MatSpy.

Arguments

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

• title: string label. If True, then a matrix description is auto generated that contains matrix shape, number and type of nonzeros, etc.
• indices: Whether to show matrix indices.
• maxrows, maxrows: size of table. Matrices larger than this are truncated with ellipses.
• precision: floating-point precision
• numafterdots: How many rows/columns to show from the end of the matrix if the entire matrix does not fit.
• fill_value: Value to fill empty cells.

Overriding defaults

matrepr.params contains the default values for all arguments.

For example, to always disable the title, disable indices, and only show the top-left part of the matrix:

matrepr.params.title = False
matrepr.params.indices = False
matrepr.params.numafterdots = 0

Interactive Python: Monkey Patching repr

The interactive Python REPL does not have a nice way to register a formatter.

We can monkey patch a repl method into supported matrix classes for a similar effect.

This is implemented in the matrepr.patch module. Simply import the patch you want:

• import matrepr.patch.scipy
• import matrepr.patch.graphblas
• import matrepr.patch.sparse

Example:

>>> a = scipy.sparse.random(4, 4, density=0.5)
>>> a
<4x4 sparse matrix of type '<class 'numpy.float64'>'
	with 8 stored elements in COOrdinate format>
>>> import matrepr.patch.scipy
>>> a
<4×4, 8 'float64' elements, coo>
      0       1        2        3
  ┌                                  ┐
0 │ 0.6536          0.008388  0.6564 │
1 │                                  │
2 │         0.2987   0.8098          │
3 │ 0.1064  0.9613   0.7477          │
  └                                  ┘

Edge Cases

MatRepr gracefully handles: * multiple elements with the same coordinates (i.e. duplicates) * nested matrices * complex values * string values (including multiline) * LaTeX scientific notation as $\times 10^{power}$

See demo-edgecases notebook for more.

How does it work?

Each package that MatRepr supports implements two classes:

• Driver: Declares what types are supported and supplies an adapter.

* getsupportedtypes: This declares what types are supported, as strings to avoid unnecessary imports. * adapt(A): Returns a MatrixAdapter for a matrix that this driver supports.

• Implement any of these MatrixAdapter classes:

* MatrixAdapterRow: for structs able to efficiently read a selected row. * MatrixAdapterCol: for structs able to efficiently read a selected column. * MatrixAdapterCoo: for structs able to extract a portion of the matrix as tuples.

See matrepr.adapters module for details.

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