Awesome
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
pip install mpl_ascii
To use mpl_ascii, add to your python program
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
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
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
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 :-)