# mpl_ascii
A matplotlib backend that produces plots using only ASCII characters. It is available for python 3.7+.
## Quick start
Install `mpl_ascii` using pip
```bash
pip install mpl_ascii
```
To use mpl_ascii, add to your python program
```python
import matplotlib as mpl
mpl.use("module://mpl_ascii")
```
When you use `plt.show()` then it will print the plots as strings that consists of ASCII characters.
If you want to save a figure to a `.txt` file then just use `figure.savefig("my_figure.txt")`
See more information about using backends here: https://matplotlib.org/stable/users/explain/figure/backends.html
## Examples
### Bar chart
The following is taken from the example in `examples/bar_color.py`
```python
import matplotlib.pyplot as plt
import matplotlib as mpl
import mpl_ascii
mpl_ascii.AXES_WIDTH=100
mpl_ascii.AXES_HEIGHT=40
mpl.use("module://mpl_ascii")
import matplotlib.pyplot as plt
# Example data
fruits = ['apple', 'blueberry', 'cherry', 'orange']
counts = [10, 15, 7, 5]
colors = ['red', 'blue', 'red', 'orange'] # Colors corresponding to each fruit
fig, ax = plt.subplots()
# Plot each bar individually
for fruit, count, color in zip(fruits, counts, colors):
ax.bar(fruit, count, color=color, label=color)
# Display the legend
ax.legend(title='Fruit color')
plt.show()
```
### Scatter plot
The following is taken from the example in `examples/scatter_multi_color.py`
```python
import matplotlib.pyplot as plt
import numpy as np
import matplotlib as mpl
import mpl_ascii
mpl_ascii.AXES_WIDTH=100
mpl_ascii.AXES_HEIGHT=40
mpl.use("module://mpl_ascii")
np.random.seed(0)
x = np.random.rand(40)
y = np.random.rand(40)
colors = np.random.choice(['red', 'green', 'blue', 'yellow'], size=40)
color_labels = ['Red', 'Green', 'Blue', 'Yellow'] # Labels corresponding to colors
# Create a scatter plot
fig, ax = plt.subplots()
for color, label in zip(['red', 'green', 'blue', 'yellow'], color_labels):
# Plot each color as a separate scatter plot to enable legend tracking
idx = np.where(colors == color)
ax.scatter(x[idx], y[idx], color=color, label=label)
# Set title and labels
ax.set_title('Scatter Plot with 4 Different Colors')
ax.set_xlabel('X axis')
ax.set_ylabel('Y axis')
# Add a legend
ax.legend(title='Point Colors')
plt.show()
```
### Line plot
The following is taken from the example in `examples/double_plot.py`
```python
import matplotlib.pyplot as plt
import numpy as np
import matplotlib as mpl
import mpl_ascii
mpl_ascii.AXES_WIDTH=100
mpl_ascii.AXES_HEIGHT=40
mpl.use("module://mpl_ascii")
# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)
c = 1 + np.cos(2 * np.pi * t)
fig, ax = plt.subplots()
ax.plot(t, s)
ax.plot(t, c)
ax.set(xlabel='time (s)', ylabel='voltage (mV)',
title='About as simple as it gets, folks')
plt.show()
```
You can find more examples and their outputs in the `examples` folder.
## Global Variables
### mpl_ascii.AXES_WIDTH
Adjust the width of each axis according to the number of characters. The library first looks for the `AXES_WIDTH` as an environment variable. This can then be overwritten in the Python program by setting `mpl_ascii.AXES_WIDTH`. The final width of the image might extend a few characters beyond this, depending on the size of the ticks and axis labels. Default is `150`.
### mpl_ascii.AXES_HEIGHT
Adjust the height of each axis according to the number of characters. The library first looks for the `AXES_HEIGHT` as an environment variable. This can then be overwritten in the Python program by setting `mpl_ascii.AXES_HEIGHT`. The final height of the image might extend a few characters beyond this, depending on the size of the ticks and axis labels. Default is `40`.
### mpl_ascii.ENABLE_COLORS
Executing `plt.show()` will render the image in colored text. Default is `True`
## Use cases
### Using Version Control for Plots
Handling plots with version control can pose challenges, especially when dealing with binary files. Here are some issues you might encounter:
- Binary Files: Committing binary files like PNGs can significantly increase your repository’s size. They are also difficult to compare (diff) and can lead to complex merge conflicts.
- SVG Files: Although SVGs are more version control-friendly than binary formats, they can still cause problems:
- Large or complex graphics can result in excessively large SVG files.
- Diffs can be hard to interpret.
To mitigate these issues, ASCII plots serve as an effective alternative:
- Size: ASCII representations are much smaller in size.
- Version Control Compatibility: They are straightforward to diff and simplify resolving merge conflicts.
This package acts as a backend for Matplotlib, enabling you to continue creating plots in your usual formats (PNG, SVG) during development. When you’re ready to commit your plots to a repository, simply switch to the `mpl_ascii` backend to convert them into ASCII format.
## Feedback
Please help make this package better by:
- reporting bugs.
- making feature requests. Matplotlib is an enormous library and this supports only a part of it. Let me know if there particular charts that you would like to be converted to ASCII
- letting me know what you use this for.
If you want to tell me about any of the above just use the Issues tab for now.
Thanks for reading and I hope you will like these plots as much as I do :-)
Raw data
{
"_id": null,
"home_page": null,
"name": "mpl-ascii",
"maintainer": "Chris Cave",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "matplotlib, plotting, ASCII",
"author": "Chris Cave",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/53/83/702b073e1d31cdb3fa292195d6fa21fa21b33f735adf0f130a5c0a8654d6/mpl_ascii-0.10.0.tar.gz",
"platform": null,
"description": "# mpl_ascii\n\nA matplotlib backend that produces plots using only ASCII characters. It is available for python 3.7+.\n\n## Quick start\n\nInstall `mpl_ascii` using pip\n\n```bash\npip install mpl_ascii\n```\n\nTo use mpl_ascii, add to your python program\n\n```python\nimport matplotlib as mpl\n\nmpl.use(\"module://mpl_ascii\")\n```\n\nWhen you use `plt.show()` then it will print the plots as strings that consists of ASCII characters.\n\nIf you want to save a figure to a `.txt` file then just use `figure.savefig(\"my_figure.txt\")`\n\nSee more information about using backends here: https://matplotlib.org/stable/users/explain/figure/backends.html\n\n## Examples\n\n### Bar chart\n\nThe following is taken from the example in `examples/bar_color.py`\n\n```python\nimport matplotlib.pyplot as plt\nimport matplotlib as mpl\nimport mpl_ascii\n\nmpl_ascii.AXES_WIDTH=100\nmpl_ascii.AXES_HEIGHT=40\n\nmpl.use(\"module://mpl_ascii\")\n\nimport matplotlib.pyplot as plt\n\n# Example data\nfruits = ['apple', 'blueberry', 'cherry', 'orange']\ncounts = [10, 15, 7, 5]\ncolors = ['red', 'blue', 'red', 'orange'] # Colors corresponding to each fruit\n\nfig, ax = plt.subplots()\n\n# Plot each bar individually\nfor fruit, count, color in zip(fruits, counts, colors):\n ax.bar(fruit, count, color=color, label=color)\n\n# Display the legend\nax.legend(title='Fruit color')\n\nplt.show()\n```\n\n\n\n### Scatter plot\n\nThe following is taken from the example in `examples/scatter_multi_color.py`\n\n```python\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport matplotlib as mpl\nimport mpl_ascii\n\nmpl_ascii.AXES_WIDTH=100\nmpl_ascii.AXES_HEIGHT=40\n\n\nmpl.use(\"module://mpl_ascii\")\n\nnp.random.seed(0)\nx = np.random.rand(40)\ny = np.random.rand(40)\ncolors = np.random.choice(['red', 'green', 'blue', 'yellow'], size=40)\ncolor_labels = ['Red', 'Green', 'Blue', 'Yellow'] # Labels corresponding to colors\n\n# Create a scatter plot\nfig, ax = plt.subplots()\nfor color, label in zip(['red', 'green', 'blue', 'yellow'], color_labels):\n # Plot each color as a separate scatter plot to enable legend tracking\n idx = np.where(colors == color)\n ax.scatter(x[idx], y[idx], color=color, label=label)\n\n# Set title and labels\nax.set_title('Scatter Plot with 4 Different Colors')\nax.set_xlabel('X axis')\nax.set_ylabel('Y axis')\n\n# Add a legend\nax.legend(title='Point Colors')\nplt.show()\n```\n\n\n\n### Line plot\n\nThe following is taken from the example in `examples/double_plot.py`\n\n\n```python\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport matplotlib as mpl\nimport mpl_ascii\n\nmpl_ascii.AXES_WIDTH=100\nmpl_ascii.AXES_HEIGHT=40\n\n\nmpl.use(\"module://mpl_ascii\")\n\n\n# Data for plotting\nt = np.arange(0.0, 2.0, 0.01)\ns = 1 + np.sin(2 * np.pi * t)\nc = 1 + np.cos(2 * np.pi * t)\n\nfig, ax = plt.subplots()\nax.plot(t, s)\nax.plot(t, c)\n\nax.set(xlabel='time (s)', ylabel='voltage (mV)',\n title='About as simple as it gets, folks')\n\nplt.show()\n```\n\n\nYou can find more examples and their outputs in the `examples` folder.\n\n## Global Variables\n\n### mpl_ascii.AXES_WIDTH\n\nAdjust the width of each axis according to the number of characters. The library first looks for the `AXES_WIDTH` as an environment variable. This can then be overwritten in the Python program by setting `mpl_ascii.AXES_WIDTH`. The final width of the image might extend a few characters beyond this, depending on the size of the ticks and axis labels. Default is `150`.\n\n### mpl_ascii.AXES_HEIGHT\n\nAdjust the height of each axis according to the number of characters. The library first looks for the `AXES_HEIGHT` as an environment variable. This can then be overwritten in the Python program by setting `mpl_ascii.AXES_HEIGHT`. The final height of the image might extend a few characters beyond this, depending on the size of the ticks and axis labels. Default is `40`.\n\n### mpl_ascii.ENABLE_COLORS\n\nExecuting `plt.show()` will render the image in colored text. Default is `True`\n\n\n## Use cases\n\n### Using Version Control for Plots\n\nHandling plots with version control can pose challenges, especially when dealing with binary files. Here are some issues you might encounter:\n\n- Binary Files: Committing binary files like PNGs can significantly increase your repository\u2019s size. They are also difficult to compare (diff) and can lead to complex merge conflicts.\n\n- SVG Files: Although SVGs are more version control-friendly than binary formats, they can still cause problems:\n - Large or complex graphics can result in excessively large SVG files.\n - Diffs can be hard to interpret.\n\nTo mitigate these issues, ASCII plots serve as an effective alternative:\n\n- Size: ASCII representations are much smaller in size.\n- Version Control Compatibility: They are straightforward to diff and simplify resolving merge conflicts.\n\n\nThis package acts as a backend for Matplotlib, enabling you to continue creating plots in your usual formats (PNG, SVG) during development. When you\u2019re ready to commit your plots to a repository, simply switch to the `mpl_ascii` backend to convert them into ASCII format.\n\n## Feedback\n\nPlease help make this package better by:\n- reporting bugs.\n- making feature requests. Matplotlib is an enormous library and this supports only a part of it. Let me know if there particular charts that you would like to be converted to ASCII\n- letting me know what you use this for.\n\nIf you want to tell me about any of the above just use the Issues tab for now.\n\nThanks for reading and I hope you will like these plots as much as I do :-)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A matplotlib backend that produces plots using only ASCII characters",
"version": "0.10.0",
"project_urls": {
"Homepage": "https://github.com/chriscave/mpl_ascii"
},
"split_keywords": [
"matplotlib",
" plotting",
" ascii"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b2b83b363e49b7d3e70f2eb48dae10d0a4da0a9b46566897e1d27cbe0b5950f7",
"md5": "b5b788a307ce4a829b93cfcae0a96bec",
"sha256": "8db7d7b29e9d92424008296c3a47334f48bc90068d468e27d800d376fc3af16a"
},
"downloads": -1,
"filename": "mpl_ascii-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5b788a307ce4a829b93cfcae0a96bec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19843,
"upload_time": "2024-07-01T17:11:46",
"upload_time_iso_8601": "2024-07-01T17:11:46.936057Z",
"url": "https://files.pythonhosted.org/packages/b2/b8/3b363e49b7d3e70f2eb48dae10d0a4da0a9b46566897e1d27cbe0b5950f7/mpl_ascii-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5383702b073e1d31cdb3fa292195d6fa21fa21b33f735adf0f130a5c0a8654d6",
"md5": "8e487378b3df79c63151de24d774dbd9",
"sha256": "8e4ae770d5a612dab0e8055c7677c6c3d271da4f5127cce46a60ce3ce4a4e72c"
},
"downloads": -1,
"filename": "mpl_ascii-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "8e487378b3df79c63151de24d774dbd9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 49143,
"upload_time": "2024-07-01T17:11:48",
"upload_time_iso_8601": "2024-07-01T17:11:48.079139Z",
"url": "https://files.pythonhosted.org/packages/53/83/702b073e1d31cdb3fa292195d6fa21fa21b33f735adf0f130a5c0a8654d6/mpl_ascii-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-01 17:11:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chriscave",
"github_project": "mpl_ascii",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.3"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.7.1"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.4"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"62"
]
]
},
{
"name": "setuptools_scm",
"specs": [
[
">=",
"7.1.0"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"4.0.2"
]
]
},
{
"name": "build",
"specs": [
[
">=",
"1.1.1"
]
]
}
],
"lcname": "mpl-ascii"
}
JSON
