# matplotalt
matplotalt is a Python library for generating and displaying matplotlib figure alt text in computational notebooks.
This is an ongoing project, so let us know if you have any feedback or feature requests!
## Installation
The latest release can be installed from PyPI:
``` pip install matplotalt ```
## Examples
Documentation is available at [matplotalt's read-the-docs page](https://matplotalt.readthedocs.io), including [examples](https://matplotalt.readthedocs.io/en/latest/notebooks/examples.html), [API reference](https://matplotalt.readthedocs.io/en/latest/api.html), and other useful information.
matplotalt's ``generate_alt_text`` function will automatically generate alt text for the most recent matplotlib figure. The desc_level parameter controls how detailed the figure description is from 1 (least detail) to 3 (most) based on [Lundgard and Satyanarayan, 2021](https://arxiv.org/pdf/2110.04406).
```
from matplotalt import generate_alt_text, surface_alt_text, show_with_alt
def sunshine_bars():
sunshine_hours = [69, 108, 178, 207, 253, 268, 312, 281, 221, 142, 72, 52]
months = ["Jan", "Feb", "Mar", "Apr", "May", "June", "July", "Aug", "Sep", "Oct", "Nov", "Dec"]
plt.title("Monthly Sunshine in Seattle")
plt.barh(list(range(12)), sunshine_hours)
plt.xlabel("Average hours of sunlight")
plt.ylabel("Month")
plt.yticks(ticks=list(range(0, 12)), labels=months)
sunshine_bars()
sunshine_alt = generate_alt_text(desc_level=3)
```
Use the ``surface_alt_text`` function to make alt texts visable to screen readers in the notebook environment:
```
surface_alt_text(sunshine_alt, methods=["html", "img_file"])
```
Currently supported methods to display alt text are:
* "html": displays the last figure in html with an alt property containing the given text.
* "markdown": display text in markdown in the current cell output.
* "new_cell": create a new (code) cell after this one containing the markdown magic followed by the given text.
* "txt_file": writes the given text to a text file.
* "img_file": saves the last matplotlib figure with the given text in its alt property.
``show_with_alt`` combines ``generate_alt_text`` and ``surface_alt_text`` functions and is designed to replace calls to ``matplotlib.pyplot.show()``.
```
sunshine_bars()
show_with_alt(desc_level=3, methods=["html", "table"])
```
There are also "API" versions of each function (``show_with_api_alt``, ``generate_api_alt_text``) which generate alt text using a LLM through OpenAI and Azure APIs.
matplotalt provides the ``alttextify`` command to automatically add alt text to each matplotlib figure in a IPython notebook. For example,
```
alttextify ./examples/examples_no_alt.ipynb examples_with_alt -s html
```
will add alt text to each figure in the examples_no_alt.ipynb notebook through the HTML alt property without changing any of the code cells. ``alttextify`` can also be used to generate alt texts with LLMs:
```
alttextify ./examples/examples_no_alt.ipynb examples_with_llm_alt -k <your API key> -m gpt-4-vision-preview -us
```
## Motivation
Visualizations on the web generated by code often lack alt text. Across 100000 Jupyter notebooks, [Potluri et al., 2023](https://dl.acm.org/doi/pdf/10.1145/3597638.3608417), found that 99.81% of programmatically generated images did not have associated alt text. Of these, the vast majority were created with matplotlib or seaborn, neither of which contain methods for easily generating or displaying image descriptions. This is a critical barrier to perceiving computational notebooks for blind and visually impaired (BVI) users. The goal of this package is to provide an alternative that allows users to automatically generate screen reader visable alt text for matplotlib figures in computational notebooks.
Raw data
{
"_id": null,
"home_page": null,
"name": "matplotalt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Kai Nylund <knylund@cs.washington.com>",
"keywords": "IPython, Jupyter, LLMs, alt text, matplotlib, seaborn",
"author": null,
"author_email": "Kai Nylund <knylund@cs.washington.com>, Venkatesh Potluri <vpotluri@cs.washington.edu>",
"download_url": "https://files.pythonhosted.org/packages/f3/3a/e3356783ac9bc12e0d1a0698b2cb2fdbd4934fe420e2797b551e821f84b4/matplotalt-0.0.4.tar.gz",
"platform": null,
"description": "# matplotalt\n\nmatplotalt is a Python library for generating and displaying matplotlib figure alt text in computational notebooks.\n\nThis is an ongoing project, so let us know if you have any feedback or feature requests!\n\n## Installation\n\nThe latest release can be installed from PyPI:\n\n``` pip install matplotalt ```\n\n## Examples\n\nDocumentation is available at [matplotalt's read-the-docs page](https://matplotalt.readthedocs.io), including [examples](https://matplotalt.readthedocs.io/en/latest/notebooks/examples.html), [API reference](https://matplotalt.readthedocs.io/en/latest/api.html), and other useful information.\n\nmatplotalt's ``generate_alt_text`` function will automatically generate alt text for the most recent matplotlib figure. The desc_level parameter controls how detailed the figure description is from 1 (least detail) to 3 (most) based on [Lundgard and Satyanarayan, 2021](https://arxiv.org/pdf/2110.04406).\n\n```\nfrom matplotalt import generate_alt_text, surface_alt_text, show_with_alt\n\ndef sunshine_bars():\n sunshine_hours = [69, 108, 178, 207, 253, 268, 312, 281, 221, 142, 72, 52]\n months = [\"Jan\", \"Feb\", \"Mar\", \"Apr\", \"May\", \"June\", \"July\", \"Aug\", \"Sep\", \"Oct\", \"Nov\", \"Dec\"]\n plt.title(\"Monthly Sunshine in Seattle\")\n plt.barh(list(range(12)), sunshine_hours)\n plt.xlabel(\"Average hours of sunlight\")\n plt.ylabel(\"Month\")\n plt.yticks(ticks=list(range(0, 12)), labels=months)\n\nsunshine_bars()\nsunshine_alt = generate_alt_text(desc_level=3)\n```\n\nUse the ``surface_alt_text`` function to make alt texts visable to screen readers in the notebook environment:\n\n```\nsurface_alt_text(sunshine_alt, methods=[\"html\", \"img_file\"])\n```\n\nCurrently supported methods to display alt text are:\n\n* \"html\": displays the last figure in html with an alt property containing the given text.\n* \"markdown\": display text in markdown in the current cell output.\n* \"new_cell\": create a new (code) cell after this one containing the markdown magic followed by the given text.\n* \"txt_file\": writes the given text to a text file.\n* \"img_file\": saves the last matplotlib figure with the given text in its alt property.\n\n``show_with_alt`` combines ``generate_alt_text`` and ``surface_alt_text`` functions and is designed to replace calls to ``matplotlib.pyplot.show()``.\n\n```\nsunshine_bars()\nshow_with_alt(desc_level=3, methods=[\"html\", \"table\"])\n```\n\nThere are also \"API\" versions of each function (``show_with_api_alt``, ``generate_api_alt_text``) which generate alt text using a LLM through OpenAI and Azure APIs.\n\nmatplotalt provides the ``alttextify`` command to automatically add alt text to each matplotlib figure in a IPython notebook. For example,\n\n```\nalttextify ./examples/examples_no_alt.ipynb examples_with_alt -s html\n```\n\nwill add alt text to each figure in the examples_no_alt.ipynb notebook through the HTML alt property without changing any of the code cells. ``alttextify`` can also be used to generate alt texts with LLMs:\n\n```\nalttextify ./examples/examples_no_alt.ipynb examples_with_llm_alt -k <your API key> -m gpt-4-vision-preview -us\n```\n\n## Motivation\n\nVisualizations on the web generated by code often lack alt text. Across 100000 Jupyter notebooks, [Potluri et al., 2023](https://dl.acm.org/doi/pdf/10.1145/3597638.3608417), found that 99.81% of programmatically generated images did not have associated alt text. Of these, the vast majority were created with matplotlib or seaborn, neither of which contain methods for easily generating or displaying image descriptions. This is a critical barrier to perceiving computational notebooks for blind and visually impaired (BVI) users. The goal of this package is to provide an alternative that allows users to automatically generate screen reader visable alt text for matplotlib figures in computational notebooks.\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for adding alt text to matplotlib figures in computational notebooks",
"version": "0.0.4",
"project_urls": {
"Discussions": "https://github.com/KaiNylund/matplotalt/discussions",
"Documentation": "https://matplotalt.readthedocs.io/en/latest/",
"Homepage": "https://github.com/KaiNylund/matplotalt",
"Issues": "https://github.com/KaiNylund/matplotalt/issues"
},
"split_keywords": [
"ipython",
" jupyter",
" llms",
" alt text",
" matplotlib",
" seaborn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "228622ffd74e8172394198ee2a0c7b21efd0a8ac328f59f3c59052f05b4164b4",
"md5": "75959f2fd5592c6a5f099cfefafb0146",
"sha256": "55d50814640d2b40c453e30632bc760b819ede3184a55cf75f390f7774eae519"
},
"downloads": -1,
"filename": "matplotalt-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75959f2fd5592c6a5f099cfefafb0146",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 36078,
"upload_time": "2024-12-09T19:54:15",
"upload_time_iso_8601": "2024-12-09T19:54:15.764998Z",
"url": "https://files.pythonhosted.org/packages/22/86/22ffd74e8172394198ee2a0c7b21efd0a8ac328f59f3c59052f05b4164b4/matplotalt-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f33ae3356783ac9bc12e0d1a0698b2cb2fdbd4934fe420e2797b551e821f84b4",
"md5": "21d3a49e4b8258b0933e143dbf02bd66",
"sha256": "b88da8c136e3e464e2e65a42b37de66e853fa49c2d9ccd6c72c979127d9e2b62"
},
"downloads": -1,
"filename": "matplotalt-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "21d3a49e4b8258b0933e143dbf02bd66",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20071287,
"upload_time": "2024-12-09T19:54:46",
"upload_time_iso_8601": "2024-12-09T19:54:46.351948Z",
"url": "https://files.pythonhosted.org/packages/f3/3a/e3356783ac9bc12e0d1a0698b2cb2fdbd4934fe420e2797b551e821f84b4/matplotalt-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-09 19:54:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KaiNylund",
"github_project": "matplotalt",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "ipython",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "nbconvert",
"specs": []
},
{
"name": "nbformat",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "openai",
"specs": []
},
{
"name": "Pillow",
"specs": []
},
{
"name": "pyexiv2",
"specs": []
},
{
"name": "python_dateutil",
"specs": []
},
{
"name": "scipy",
"specs": []
}
],
"lcname": "matplotalt"
}
JSON
