The MPLW is Matplotlib (MPL) wrapper, which can work as AsciiDoc filter. Using this filter you can generate plots from inline matplotlib scripts.
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. role=include
We just include following MPL code snippet:
link:example-sin.txt[role=include]
---------------------------------------
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.
["graphviz", "flow.png"]
---------------------------------------------------------------------
digraph G {
rankdir=LR;
node [shape=plaintext];
{ node [shape=box]; AsciiDoc; MPLW; }
{ rank=same; "PNG file"; "HTML file"; }
"source TXT file" -> AsciiDoc -> "HTML file";
AsciiDoc -> "MPL script snippet" -> MPLW -> "PNG file";
}
--------------------------------------------------------------------
Now let say we have some data from two experiments and we need to plot it:
link:example-data.txt[role=include]
It can be made with this snippet:
--------------------------------
link:example-data.txt[role=include]
-------------------------------
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 http://matplotlib.sourceforge.net/gallery.html[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.
////////////////////
[CAUTION]
Matplotlib is pre-1.0 version which means it has
httpx://matplotlib.sourceforge.net/api/api_changes.html[unstable API] and it might be not easy to install.
From this are very stringent dependencies version requirements.
Using bleeding edge and installing from source might be required.
MPLW works best with Matplotlib version 0.98 or higher. With lower versions MPLW style will be set to "none".
But you can style your plot by using Mutplotlib commands in snippet.
Matplotlib-0.98 is not compatible with python-2.6, version 0.99 is compatible with python-2.6.
See also http://matplotlib.sourceforge.net/users/installing.html[matplotlib install instruction].
.Upstream "best" versions As of 8/9/2009:
* matplotlib-0.99.1
* python-2.6.2
.Gentoo
***********************************************************
.Current best versions:
* matplotlib-0.99.1.1
* python-2.6.2
You might need to re-install `dev-python/pycxx` in order to install matplotlib.
**********************************************************
.Ubuntu-8.04
**********************************************************
.Current best versions:
* matplotlib-0.91.2 (?)
* python-2.5.2 (?)
********************************************************
.Ubuntu-9.04
**********************************************************
.Current best versions:
* matplotlib-0.98.5.2
* python-?
********************************************************
matplotlib 0.98.5.1 <=python-2.6
matploblib-0.91.1 <numpy-1.2.1
matplotlib-0.9.1 <numpy-1.1.0
numpy 1.2.1 =ptyhon-2.5
numpy 1.3 <=ptyhon-2.6
nose 0.10.4 <=python 2.6
scipy 0.7.0 =python-2.5
f2py <python-2.6
However, numpy developers hope to have a 2.6 compatible release before /
just after the new year, with scipy and matplotlib probably following soon after.
/////////////////////////////////////////////////////////////////
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.
//////////////////
* There is also plotting function 'benchmark' available, based on 'barh'. It should probably be
in MPL code, not in MPLW. I will send patch to MPL project.
See http://volnitsky.com/project/lvvlib/array[example use of benchmark]
/////////////////////
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.
.References
- [[[1]]] http://www.methods.co.nz/asciidoc/asciidoc-graphviz-sample.html[Graphviz filter for AsciiDoc]
- [[[2]]] http://matplotlib.sourceforge.net[MatPlotLib - python plotting library]
- [[[3]]] http://code.google.com/p/scitools/wiki/EasyvizDocumentation[Easyviz - Python library for scientific computing]
- [[[4]]] http://detexify.kirelabs.org/classify.html[drawing to LaTeX symbol]
- [[[5]]] httpx://ditaa.sourceforge.net[DIagrams Through Ascii Art],
- [[[6]]] httpx://blog.m3r.nl/personal/full-text-based-document-generation-using-asciidoc[Full text-based document generation using asciidoc and ditaa]
- [[[7]]] http://kaioa.com/node/45[How to Configure Apache to Serve SVG/SVGZ the Right Way]
- [[[8]]] http://igraph.sourceforge.net/[Igraph - free software for creating and manipulating undirected and directed graphs.]
- [[[9]]] http://www.w3.org/Graphics/SVG/IG/resources/svgprimer.html[An SVG Primer]
// vim:ts=8 ft=asciidoc: