Ampule (Automated MatPlotLib) is a minimalistic tool designed for repeated non-interactive processing and plotting of tabular data
Prerequisites
You need a Linux distribution, python3 installed, and knowledge (or desire to learn) of Matplotlib library.
Features
Easy import, post-processing and plotting of tabular data
Data are to be stored on disk in the following DSV-like format
#:x f g
0.01 0.01 0.0001
0.02 0.02 0.0004
0.03 0.03 0.0009
0.04 0.04 0.0016
0.05 0.05 0.0025
0.06 0.06 0.0036
The import is simple
data, _ = ampule.load(dat_parser, 'dat/poly.dat')
After the import, columns are accessed as data.x
, data.f
and data.g
.
The data class is pandas.DataFrame
, so expressions like data.f + data.g/2
work too. Also you get compatibility with data processing functions from
numpy, scipy, pandas etc.
However, you don't need to know these libraties for plotting using Matplotlib, just pass the columns to the plotter
plt.plot(data.x, data.f, label = r'$f(x)$')
plt.plot(data.x, data.g, label = r'$g(x)$')
Metadata support
In addition, you can store some meta-information as follows:
#:foo=0
#:bar='bar'
Such variables must be written one per line, and strictly before the column names. The work with metadata is straightforward
data, meta = ampule.load(dat_parser, 'dat/data.dat')
print(meta.foo, meta.bar)
Other data formats
New data formats may be added in future development, but you can also
implement them yourself by replacing dat_parser
with your_parser
function,
which takes path to the file as an argument and returns tabular data
(pandas.Dataframe
or any other class you find convenient to use with
Matplotlib)
Makefile for mass (re)building of output plots
Let's say you have written a script for data plotting, and want to update the picture after receving fresh data. Or you decided to prettify your plot and have changed the script itself. It couldn't be easier
make
Ampule will automatically rebuild those and only those pictures for which the
data or plotting script have changed. For this to work, special dependency
files are stored (similar to ones producing by gcc -MT
)
Import by mask
When you have a lot of data files, you may start giving them parametric names,
like H_0.dat
, H_1.dat
, H_2.dat
...
Say no more
for path, k in search_mask('dat/hermite/H_', '.dat'):
data, _ = ampule.load(dat_parser, path)
plt.plot(data.x, data.H, label = rf'$H_{k}$')
Reproducible plots
Sometimes it is needed for the pictures do not change if they are plotted on the same data, especially if you decide to store pictures under version control system. This behavior is supported and enabled by default. If you refactor the script without changing its essence, the pictures will not change either.
Getting started
Install the package from PyPI
pip3 install ampule
Get the build files
mkdir try_ampule
cd try_ampule
ln -s ~/.local/ampule/Makefile Makefile
cp ~/.local/ampule/ampule_config.mk ampule_config.mk
Symbolic link for the Makefile is preferable, since it automatically updates the Makefile when the package is updated. However, if later you will need to embed the plotting in your own Makefile, you may want to just copy the Ampule Makefile content.
The ampule_config.mk
contains some paths that you may want to vary later.
Get the test data and test scripts
This is step is optional for experienced users, but highly recommended when first trying of Ampule.
cp -r ~/.local/ampule/figs figs
cp -r ~/.local/ampule/dat dat
make
If the last command completed without errors, then you have just successfully
installed and configured ampule! Check the figs/pdf
directory to see the
results of plotting.
Explore ampule
Read the scripts in figs/py
and understand how they work. This shouldn't be
difficult, unless this is your first time seeing a Python code. Feel free to
mess with scripts and data files to get used to Ampule. When you are ready,
create your own script and delete the test ones. You may also find the make clean
command useful, which clears the working directory from pictures and
dependency files.