tomplot

The Only Matplotlib PDE Library Of Tom

tomplot is an interface to matplotlib for quickly making neat plots for numerical models of PDEs.

It is intended for use with LFRic and some Firedrake packages, such as gusto.

Why?

tomplot is motivated by the importance of neat data visualisation. To avoid code duplication across different projects or even plotting scripts, tomplot contains a set of routines that are commonly used to make figures ready for publication or presentation. This is all provided as an interface to matplotlib, so that all these plots can be made quickly and easily, while allowing the full capability of matplotlib to be exploited.

tomplot provides:

routines to extract and process data
default formats for various types of plot, to quickly make neat plots
several specialised routines used in making publication-worthy plots

The design philosophy is that everything that is possible with matplotlib should still be possible whilst using tomplot -- it creates no new objects which need to be passed around. Instead, it is aimed at avoiding code duplication by providing routines to perform some tedious tasks involved in making neat plots.

INSTALLATION

The main dependencies are netCDF4, numpy and matplotlib. To take advantage of full features, it requires pandas, scipy and cartopy, and these are currently treated as full dependencies through the pip installation.

The recommended installation method is to use pip to install tomplot into a virtual environment (either an existing virtual environment or a new one).

Creating a virtual environment for tomplot

To create a virtual environment called tomplotvenv in your current working directory, use

python -m venv tomplotvenv

The virtual environment can then be activated through

source tomplotvenv/bin/activate

Installing with pip: editable version

To get an editable version of tomplot, first clone the git repository into the virtual environment:

git clone git@github.com:tommbendall/tomplot.git

git clone https://github.com/tommbendall/tomplot.git

Then change to the top level directory of tomplot and install, through:

cd tomplot
pip install -e .

Installing with pip: non-editable version

If you don't need an editable version of tomplot, then you can install directly with either:

pip install git+ssh://git@github.com/tommbendall/tomplot.git

pip install git+https://github.com/tommbendall/tomplot.git

Without pip

It is not recommended to use tomplot by cloning the repository and setting the pythonpath to make tomplot temporarily made available through

export PYTHONPATH=<path_to_tomplot>/tomplot

It is much better to use pip instead.

Testing

You can test an editable installation by running

make test

from the top level directory of tomplot.

The plots generated through the unit-tests can be seen by running

make show-test

Development

When new features are added, they should have a unit-test created in the tests directory. These tests should ideally make a figure. Existing tests generally do this using the conftest.py.

Accepted figures are saved in tests/figures.

When testing a new feature, temporary figures can be generated by the

make save-test

command, which saves these figures in tests/tmp_figures. These figures can then be compared with the accepted figures in tests/figures.

Once the feature is complete, the accepted figures can be updated with

make overwrite-test

All changes must be lint tested through

make lint

Examples

Some basic LFRic and Gusto examples can be found in the examples directory.

tommbendall / tomplot