{"author":"Adam Lugowski","author_email":null,"bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","Intended Audience :: Science/Research","License :: OSI Approved :: BSD License","Programming Language :: Python :: 3 :: Only","Topic :: Scientific/Engineering","Topic :: Software Development :: Libraries"],"description":"[![tests](https://github.com/alugowski/matrepr/actions/workflows/tests.yml/badge.svg)](https://github.com/alugowski/matrepr/actions/workflows/tests.yml)\n[![codecov](https://codecov.io/gh/alugowski/matrepr/graph/badge.svg?token=e9QEAd57gz)](https://codecov.io/gh/alugowski/matrepr)\n[![PyPI version](https://badge.fury.io/py/matrepr.svg)](https://pypi.org/project/matrepr/)\n[![Conda Version](https://img.shields.io/conda/vn/conda-forge/matrepr.svg)](https://anaconda.org/conda-forge/matrepr)\n\n# MatRepr\n\nMake every matrix beautiful.\n\nMatRepr formats matrices and tensors to HTML, string, and LaTeX, with Jupyter integration.\nSee [Jupyter notebook for examples.](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo.ipynb)\n\nBrief examples:\n\n```python\nfrom matrepr import mdisplay, mprint\n```\n\n`mprint(A)` or `to_str(A)`:\n```\n<1000×1000, 212345 'float64' elements, coo>\n 0 1 2 3 4 5 6 7\n ┌ ┐\n0 │ 0.3876 ... │\n1 │ 0.5801 0.5085 0.8927 0.629 ... │\n2 │ ... │\n3 │ 0.7142 ... │\n4 │ 0.8631 ... │\n5 │ 0.7863 0.1298 0.9918 0.71 0.3444 ... │\n6 │ 0.9481 0.9609 ... │\n7 │ 0.09361 0.1679 ... │\n8 │ 0.4023 ... │\n │ : : : : : : : : ... │\n └ ┘\n```\n\n`mdisplay(A)` or `to_html(A)`:\n\n $\"HTML$
\n\nSupports:\n* **SciPy** - sparse matrices and arrays like `csr_matrix` and `coo_array`\n* **NumPy** - `ndarray` [(demo)](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo-numpy.ipynb)\n* **[PyTorch](https://pytorch.org/docs/stable/sparse.html)** - dense and sparse `torch.Tensor` [(demo)](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo-pytorch.ipynb)\n* **[TensorFlow](https://www.tensorflow.org/guide/sparse_tensor)** - `tf.Tensor` and `tf.SparseTensor` [(demo)](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo-tensorflow.ipynb)\n* **[Python-graphblas](https://github.com/python-graphblas/python-graphblas)** - `gb.Matrix` and `gb.Vector` [(demo)](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo-python-graphblas.ipynb)\n* **[PyData/Sparse](https://sparse.pydata.org/)** - `COO`, `DOK`, `GCXS` [(demo)](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo-pydata-sparse.ipynb)\n* `list`, `tuple`, including multi-dimensional and ragged\n\nFeatures:\n* Jupyter extension to format matrices in cell outputs.\n* Configurable float precision or format string.\n* Toggle row and column indices or set your own labels.\n* Nested sub-matrices of any supported type, including mixing packages.\n* Toggle matrix description or set your own title.\n* String output can optionally autodetect terminal width.\n* Methods to directly display a matrix (`mprint`, `mdisplay` for Jupyter)\n* Methods to convert to string (`to_html`, `to_latex`, `to_str`).\n* Configurable per method call or set defaults with `matrepr.params`.\n* A `__repr__` monkey patch to format matrices in the Python shell.\n* Fast.\n\nInstall:\n```shell\npip install matrepr\n```\n\nor\n\n```shell\nconda install matrepr\n```\n\n## More Examples\n\n### HTML\n\n $\"HTML$
\n $\"4D$
\n $\"Adjacency$
\n\n`mdisplay(A)`, `to_html(A)` \nor simply `A` with Jupyter extension `%load_ext matrepr`\n\n\n### LaTeX\n $\"LaTeX$
\n $\"LaTeX$ \n\n`mdisplay(A, 'latex')`, `to_latex(A)` \nor simply `A` with Jupyter extension `%load_ext matrepr.latex`\n\n## Jupyter Extension\n\nMatRepr's Jupyter extension registers with [Jupyter's formatter](https://ipython.readthedocs.io/en/stable/config/integrating.html)\nto format supported matrices with MatRepr. Simply:\n\n```jupyter\n%load_ext matrepr\n```\n\nOr if you prefer LaTeX:\n```jupyter\n%load_ext matrepr.latex\n```\n\nExample:\n\n $\"Jupyter$ \n\n\n## Methods\n* `to_str(A)`: Format `A` as a text string.\n* `to_html(A)`: Format `A` as a plain or notebook-styled HTML table. Returns a string.\n* `to_latex(A)`: Format `A` as a LaTeX matrix. Returns a string.\n* `mprint(A)`: print `A` as a string to stdout.\n* `mdisplay(A)`: Displays the output of `to_html`, `to_latex`, or `to_str` in Jupyter.\n\n**Note:** For Spy plots see [MatSpy](https://github.com/alugowski/matspy).\n\n### Arguments\n\nAll methods take the same arguments. Apart from the matrix itself:\n\n* `title`: string label. If `True`, then a matrix description is auto generated that contains matrix shape, number and type of nonzeros, etc.\n* `indices`: Whether to show matrix indices.\n* `max_rows`, `max_rows`: size of table. Matrices larger than this are truncated with ellipses.\n* `precision`: floating-point precision\n* `num_after_dots`: How many rows/columns to show from the end of the matrix if the entire matrix does not fit.\n* `fill_value`: Value to fill empty cells.\n\n#### Overriding defaults\n`matrepr.params` contains the default values for all arguments.\n\nFor example, to always disable the title, disable indices, and only show the top-left part of the matrix:\n\n```python\nmatrepr.params.title = False\nmatrepr.params.indices = False\nmatrepr.params.num_after_dots = 0\n```\n\n## Interactive Python: Monkey Patching `__repr__`\n\nThe interactive Python REPL does not have a nice way to register a formatter.\n\nWe can monkey patch a `__repl__` method into supported matrix classes for a similar effect.\n\nThis is implemented in the [matrepr.patch](matrepr/patch) module. Simply import the patch you want:\n\n* `import matrepr.patch.scipy`\n* `import matrepr.patch.graphblas`\n* `import matrepr.patch.sparse`\n\nExample:\n\n```\n>>> a = scipy.sparse.random(4, 4, density=0.5)\n>>> a\n<4x4 sparse matrix of type ''\n\twith 8 stored elements in COOrdinate format>\n>>> import matrepr.patch.scipy\n>>> a\n<4×4, 8 'float64' elements, coo>\n 0 1 2 3\n ┌ ┐\n0 │ 0.6536 0.008388 0.6564 │\n1 │ │\n2 │ 0.2987 0.8098 │\n3 │ 0.1064 0.9613 0.7477 │\n └ ┘\n```\n\n## Edge Cases\n\nMatRepr gracefully handles:\n * multiple elements with the same coordinates (i.e. duplicates)\n * nested matrices\n * complex values\n * string values (including multiline)\n * LaTeX scientific notation as $`\\times 10^{power}`$\n\nSee [demo-edgecases notebook](https://nbviewer.org/github/alugowski/matrepr/blob/main/doc/demo-edgecases.ipynb) for more.\n\n## How does it work?\n\nEach package that MatRepr supports implements two classes:\n\n* `Driver`: Declares what types are supported and supplies an adapter.\n * `get_supported_types`: This declares what types are supported, as strings to avoid unnecessary imports.\n * `adapt(A)`: Returns a `MatrixAdapter` for a matrix that this driver supports.\n* Implement any of these `MatrixAdapter` classes:\n * `MatrixAdapterRow`: for structs able to efficiently read a selected row.\n * `MatrixAdapterCol`: for structs able to efficiently read a selected column.\n * `MatrixAdapterCoo`: for structs able to extract a portion of the matrix as tuples.\n\nSee [matrepr.adapters](matrepr/adapters) module for details.\n\nYou may use `matspy.register_driver` to register a Driver for your own matrix class.\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"matrix, tensor, sparse, html, latex, representation, table, numpy, scipy, pydata, graphblas, torch, pytorch, tensorflow","license":null,"license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"matrepr","package_url":"https://pypi.org/project/matrepr/","platform":null,"project_url":"https://pypi.org/project/matrepr/","project_urls":{"homepage":"https://github.com/alugowski/matrepr","repository":"https://github.com/alugowski/matrepr"},"provides_extra":["supported","test"],"release_url":"https://pypi.org/project/matrepr/1.0.1/","requires_dist":["tabulate","scipy; extra == \"supported\"","numpy; extra == \"supported\"","python-graphblas; extra == \"supported\"","sparse; extra == \"supported\"","torch>=2.0.0; extra == \"supported\"","tensorflow; extra == \"supported\"","pytest; extra == \"test\"","html5lib; extra == \"test\"","scipy; extra == \"test\""],"requires_python":">=3.7","summary":"Format matrices and tensors to HTML, string, and LaTeX, with Jupyter integration.","version":"1.0.1","yanked":false,"yanked_reason":null}

Dependency	Optional
tabulate	false
html5lib	true
numpy	true
pytest	true
python-graphblas	true
scipy	true
sparse	true
tensorflow	true
torch	true

Package search

matrepr

project_urls

Dependencies

All package metadata

Releases