matrepr 1.0.0

Format matrices and tensors to HTML, string, and LaTeX, with Jupyter integration.

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 csr_matrix and coo_array
• 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 (to_html, to_latex, 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 to_html, to_latex, 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.
• max_rows, max_rows: size of table. Matrices larger than this are truncated with ellipses.
• precision: floating-point precision
• num_after_dots: 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.num_after_dots = 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.
  • get_supported_types: 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.