The MPLW is Matplotlib (MPL) wrapper, which can work as AsciiDoc filter. Using this filter you can generate plots from inline matplotlib scripts.

Introduction

Matplotlib (MPL) is python charting library, with function similar to Gnuplot and interface modelled on Matlab API. AsciiDoc is converter from ascii text files (with human readable markup) to html and other doc formats.

Let say we need include sin(x) plot below into asciidoc document.

figure(figsize=(4,2))           # PNG size, inches
X = arange(0, 6, 0.1)           # 0, 0.1, 0.2 ... 6.0
Y = sin(X)                      # vector op
plot(X,Y)

We just include following MPL code snippet:

["mpl", "example-sin.png"]
-------------------------------------------
figure(figsize=(4,2))           # PNG size, inches
X = arange(0, 6, 0.1)           # 0, 0.1, 0.2 ... 6.0
Y = sin(X)                      # vector op
plot(X,Y)
-------------------------------------------

On first line in square brackets there are two parameters. First - "mpl" is name of asciidoc filter. Second is file name of your choice to store generated chart

Asciidoc will send inline python code between "----" lines to stdin of mplw.py, and generate HTML file with <img …> tag for MPLW produced PNG file.

flow.png

Now let say we have some data from two experiments and we need to plot it:

figure(figsize=(5,2.5))
title('Two Charts')
xlabel('Some text')
plot(c[0],c[1])         # x, y1
plot(c[0],c[2])         # x, y2
                        # columns below:  x, y1, y2
___________________________________________
1.0e0,    2.0e0,    1.0e0
2.0e0,    4.0e0,    1.2e0
3.0e0,    4.5e0,    1.6e0
4.0e0,    5.0e0,    3.3e0
5.0e0,    5.2e0,    4.4e0

It can be made with this snippet:

["mpl", "example-data.png"]
---------------------------
figure(figsize=(5,2.5))
title('Two Charts')
xlabel('Some text')
plot(c[0],c[1])         # x, y1
plot(c[0],c[2])         # x, y2
                        # columns below:  x, y1, y2
___________________________________________
1.0e0,    2.0e0,    1.0e0
2.0e0,    4.0e0,    1.2e0
3.0e0,    4.5e0,    1.6e0
4.0e0,    5.0e0,    3.3e0
5.0e0,    5.2e0,    4.4e0

--------------------------

Text after "__" is plot data in table form. The c[][] is matrix where c[0] is vector holding 1st column from above table, c[1] is second column and so on. You can store plot data in in external file if needed, see matplotlib manual.

To see what MatPlotLib is capable of go to matplotlib gallery.

Install

Replace emerge with your distro package manager:

emerge -u matplotlib git
git clone git://github.com/lvv/mplw.git
cd mplw.git
make install          # this will create 2 files: /usr/share/asciidoc/filters/mpl/{mpl.conf,mplw.py}

Your disros might have different location for storing asciidoc’s filters. Default is /usr/share/asciidoc/filters. If this is not the case, you need to modify ASCIIDOC_FILTERS variable in Makefile.

How MPLW API differ from MPL

MPL API was somewhat simplified for use as AsciiDoc filter.

  • Python inline code evaluated in environment with following modules imported without namespace:

from matplotlib.pyplot import *
from numpy import *
  • If there is inline plot data, MPLW fills in c matrix. If entry looks like number it is converted to float.

  • If style is other then "none", then it is applied.

  • After MPL inline code evaluated, mplw.py writes chart PNG file. You must not call MPL’s show() function.

Currently there is "asciidoc" — only and default style recognized by MPLW. When style is a "asciidoc", mplw will:

  • adjust figure borders sizes to accommodate tick text and x/ylabel text. MPL does not do it automatically, it only have correct frame size if image have default size.

  • enable grid.

  • set figure frame background to light grey and darker grey for frame border. Note: there is bug in MPL, borders drawn not on all sides.

About

MPLW is based on GNU licensed graphviz2png.py by Gouichi Iisaka. MPLW is currently in alpha state.

Todo

  • Make normal chart font to match page font/font-size. Needs some JavaScript magic to do this. Don’t know how to do this.

  • For inline-data add optional column header line, which can be used for plot legend.

  • When mplw.py used not as asciidoc filter, but as stand alone utility generating PNGs from text files:

    • if title not set take file name as title

    • if multiple input files specified: make one overlay-ed chart

  • PNG size should be specified in filter parameters and passed to MPLW. I don’t know how to do this

  • PNG should be centered by default or at least filter should accept param align=center. I don’t know how to do this.

  • SVG? (MPL can generate SVG)

  • Code cleanup and make tabs size consistent in mplw.py source.