| Name | matspy JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | Sparse matrix spy plot and sparkline renderer that works with Jupyter. |
| upload_time | 2023-10-26 03:06:25 |
| maintainer | |
| docs_url | None |
| author | Adam Lugowski |
| requires_python | >=3.7 |
| license | |
| keywords |
matrix
sparse
spy
plot
graph
numpy
scipy
graphblas
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/alugowski/matspy/actions/workflows/tests.yml)
[](https://codecov.io/gh/alugowski/matspy)
[](https://pypi.org/project/matspy/)
[](https://anaconda.org/conda-forge/matspy)
# MatSpy
Sparse matrix spy plot and sparkline renderer.
```python
from matspy import spy
spy(A)
```
<img src="https://raw.githubusercontent.com/alugowski/matspy/main/doc/images/spy.png" width="400" alt="Spy Plot"/>
Supports:
* **SciPy** - sparse matrices and arrays like `csr_matrix` and `coo_array` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb)
* **NumPy** - `ndarray` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-numpy.ipynb)
* **[Python-graphblas](https://github.com/python-graphblas/python-graphblas)** - `gb.Matrix` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-python-graphblas.ipynb)
* **[PyData/Sparse](https://sparse.pydata.org/)** - `COO`, `DOK`, `GCXS` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-pydata-sparse.ipynb)
Features:
* Simple `spy()` method plots non-zero structure of a matrix, similar to MatLAB's spy.
* Sparklines: `to_sparkline()` creates small self-contained spy plots for inline HTML visuals.
* FAST and handles very large matrices.
See a [Jupyter notebook demo](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb).
```shell
pip install matspy
```
```shell
conda install matspy
```
## 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. Multiple sparklines can be automatically to-scale with each other using the `retscale` and `scale` arguments.
* `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.
## Examples
See the [demo notebook](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb) for more.
#### Save spy plot as a PNG image
```python
fig, ax = matspy.spy_to_mpl(A)
fig.savefig("spy.png", bbox_inches='tight')
```
## 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.
* `precision`: For numpy arrays, only plot values with magnitude greater than `precision`. Like [matplotlib.pyplot.spy()](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.spy.html)'s `precision`.
### Overriding defaults
`matspy.params` contains the default values for all arguments.
For example, to default to binary shading, no title, and no indices:
```python
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()` creates small spy plots that work anywhere HTML is displayed.
# 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.
<img src="https://raw.githubusercontent.com/alugowski/matspy/main/doc/images/triple_product.png" height="125" width="400" alt="triple product"/>
Note: the spy plots in this image were created with `to_sparkline()`. Code in the [demo notebook](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb).
# 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](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-anti-aliasing.ipynb) 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](matspy/adapters) for details.
You may use `matspy.register_driver` to register a `Driver` for your own matrix class.
Raw data
{
"_id": null,
"home_page": "",
"name": "matspy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "matrix,sparse,spy,plot,graph,numpy,scipy,graphblas",
"author": "Adam Lugowski",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/7e/d7/36edf302c496ae21f6ad0244d28ac4840ede8919ae50ffc12d063caec707/matspy-1.0.0.tar.gz",
"platform": null,
"description": "[](https://github.com/alugowski/matspy/actions/workflows/tests.yml)\n[](https://codecov.io/gh/alugowski/matspy)\n[](https://pypi.org/project/matspy/)\n[](https://anaconda.org/conda-forge/matspy)\n\n# MatSpy\n\nSparse matrix spy plot and sparkline renderer.\n\n```python\nfrom matspy import spy\n\nspy(A)\n```\n\n<img src=\"https://raw.githubusercontent.com/alugowski/matspy/main/doc/images/spy.png\" width=\"400\" alt=\"Spy Plot\"/>\n\nSupports:\n* **SciPy** - sparse matrices and arrays like `csr_matrix` and `coo_array` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb)\n* **NumPy** - `ndarray` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-numpy.ipynb)\n* **[Python-graphblas](https://github.com/python-graphblas/python-graphblas)** - `gb.Matrix` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-python-graphblas.ipynb)\n* **[PyData/Sparse](https://sparse.pydata.org/)** - `COO`, `DOK`, `GCXS` [(https://nbviewer.org/github/alugowski/matspy/blob/main/demo)](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-pydata-sparse.ipynb)\n\nFeatures:\n* Simple `spy()` method plots non-zero structure of a matrix, similar to MatLAB's spy.\n* Sparklines: `to_sparkline()` creates small self-contained spy plots for inline HTML visuals.\n* FAST and handles very large matrices.\n\nSee a [Jupyter notebook demo](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb).\n\n```shell\npip install matspy\n```\n```shell\nconda install matspy\n ```\n\n## Methods\n* `spy(A)`: Plot the sparsity pattern (location of nonzero values) of sparse matrix `A`.\n* `to_sparkline(A)`: Return a small spy plot as a self-contained HTML string. Multiple sparklines can be automatically to-scale with each other using the `retscale` and `scale` arguments.\n* `spy_to_mpl(A)`: Same as `spy()` but returns the matplotlib Figure without showing it.\n* `to_spy_heatmap(A)`: Return the raw 2D array for spy plots. \n\n## Examples\n\nSee the [demo notebook](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb) for more.\n\n#### Save spy plot as a PNG image\n\n```python\nfig, ax = matspy.spy_to_mpl(A)\nfig.savefig(\"spy.png\", bbox_inches='tight')\n```\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.\n* `indices`: Whether to show matrix indices.\n* `figsize`, `sparkline_size`: size of the plot, in inches\n* `shading`: `binary`, `relative`, `absolute`.\n* `buckets`: spy plot pixels (longest side).\n* `dpi`: determine `buckets` relative to figure size.\n* `precision`: For numpy arrays, only plot values with magnitude greater than `precision`. Like [matplotlib.pyplot.spy()](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.spy.html)'s `precision`.\n\n### Overriding defaults\n`matspy.params` contains the default values for all arguments.\n\nFor example, to default to binary shading, no title, and no indices:\n\n```python\nmatspy.params.shading = 'binary'\nmatspy.params.title = False\nmatspy.params.indices = False\n```\n\n## Jupyter\n\n`spy()` simply shows a matplotlib figure and works well within Jupyter.\n\n`to_sparkline()` creates small spy plots that work anywhere HTML is displayed.\n\n# Fast\nAll operations work with very large matrices.\nA spy plot of tens of millions of elements takes less than half a second.\n\nLarge matrices are downscaled using two native matrix multiplies. The final dense 2D image is small.\n\n<img src=\"https://raw.githubusercontent.com/alugowski/matspy/main/doc/images/triple_product.png\" height=\"125\" width=\"400\" alt=\"triple product\"/>\n\nNote: the spy plots in this image were created with `to_sparkline()`. Code in the [demo notebook](https://nbviewer.org/github/alugowski/matspy/blob/main/demo.ipynb).\n\n# Spy Plot Anti-Aliasing\nOne application of spy plots is to quickly see if a matrix has a noticeable structure.\nAliasing artifacts can give the false impression of structure where none exists,\nsuch as moir\u00e9 or even a false grid pattern.\n\nMatSpy employs some simple methods to help eliminate these effects in most cases.\n\n\n\nSee the [Anti-Aliasing demo](https://nbviewer.org/github/alugowski/matspy/blob/main/demo-anti-aliasing.ipynb) for more.\n\n# How to support more packages\n\nEach package that MatSpy supports implements two classes:\n\n* `Driver`: Declares what types are supported and supplies an adapter.\n * `get_supported_type_prefixes`: This declares what types are supported, as strings to avoid unnecessary imports.\n * `adapt_spy(A)`: Returns a `MatrixSpyAdapter` for a matrix that this driver supports.\n* `MatrixSpyAdapter`. A common interface for extracting spy data.\n * `describe()`: Describes the adapted matrix. This description serves as the plot title.\n * `get_shape()`: Returns the adapted matrix's shape.\n * `get_spy()`: Returns spy plot data as a dense 2D numpy array.\n\nSee [matspy/adapters](matspy/adapters) for details.\n\nYou may use `matspy.register_driver` to register a `Driver` for your own matrix class.\n",
"bugtrack_url": null,
"license": "",
"summary": "Sparse matrix spy plot and sparkline renderer that works with Jupyter.",
"version": "1.0.0",
"project_urls": {
"homepage": "https://github.com/alugowski/matspy",
"repository": "https://github.com/alugowski/matspy"
},
"split_keywords": [
"matrix",
"sparse",
"spy",
"plot",
"graph",
"numpy",
"scipy",
"graphblas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8efc4108012589c50b767988eee40cea60159c71eefe733eb891d830fa820aa",
"md5": "dd4bb337b60f209ce5828a5422282cfb",
"sha256": "455696693a3eb9bd774aadb2fa3a0dc8125c2fa86ff57a7760bdc0618895451b"
},
"downloads": -1,
"filename": "matspy-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd4bb337b60f209ce5828a5422282cfb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16629,
"upload_time": "2023-10-26T03:06:24",
"upload_time_iso_8601": "2023-10-26T03:06:24.338908Z",
"url": "https://files.pythonhosted.org/packages/d8/ef/c4108012589c50b767988eee40cea60159c71eefe733eb891d830fa820aa/matspy-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7ed736edf302c496ae21f6ad0244d28ac4840ede8919ae50ffc12d063caec707",
"md5": "fd9d2ea3867f7b1cb81256524d13f0fc",
"sha256": "4c9abda5c57c4e35fca9aa6d436995c0ecfdc001b28a45f746f408e9acf6b9e8"
},
"downloads": -1,
"filename": "matspy-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fd9d2ea3867f7b1cb81256524d13f0fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16152,
"upload_time": "2023-10-26T03:06:25",
"upload_time_iso_8601": "2023-10-26T03:06:25.777037Z",
"url": "https://files.pythonhosted.org/packages/7e/d7/36edf302c496ae21f6ad0244d28ac4840ede8919ae50ffc12d063caec707/matspy-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-26 03:06:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alugowski",
"github_project": "matspy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matspy"
}
