Simplify production of publication-quality figures based on matplotlib.
matplotlib is a powerful package for plotting in python. It allows
detailed control over every possible aspect of a plot. However, a lot
of the provided functionality is cumbersome to use and impossible to
remember. For specific use cases, however, a lot of this can be hidden
in dedicated functions. The
plottools package does this for
scientific publications by adding a number of functions to
matplotlib and Figure classes.
The second design goal of the
plottools package is separation of
content and design. We know this from LaTeX documents. A good LaTeX
document contains only the text and the logical structure. The actual
layout (fonts, format of the sections, etc.) can then be entirely
controlled by the header without touching the text. Equivalently,
python scripts generating various figures should only provide the
data and necessary annotation like axes labels. The design should be
controllable by a single central function or module that is used by
all the scripts generating the figures. matplotlib's rcParams are
a big step in this direction but do not completely reach this
plottools package expands on this, by providing additional
rcParams, and by introducing the concept of plot
The following modules are provided by the
See API documentation of the modules for more infos.
Enhanced matplotlib functionality
Most modules patch the matplotlib and Axes classes to provide new functionality or some specialized interface:
align: align axes labels.
aspect: adapting plots to aspect ratio of axes.
circuits: electrical circuits.
common: reduce common axis labels.
figure: size and file names of a figure.
insets: insets made easy. More...
labels: annotate axis with label and unit.
legend: enhance legend text.
neurons: draw sketches of neurons.
scalebars: labeled scale bars. More...
significance: indicating statsitical significance.
spines: modify the appearance of spines. More...
subplots: enhanced subplots with margins. More...
tag: tag axes with a label.
text: enhance textual annotations.
ticks: setting tick locations and formats. More...
The patching is done by each module's
function. This function is called automatically upon importing the
module. While some modules simply add a few new member functions
others modify existing functions
uninstall_<module>() function is provided to undo the patching.
You usually do not need to care about the install/uninstall functions. Simply import the module of interest and you are all set.
Colors and styles
These two modules do not patch matplotlib, but provide functions aiding the separation of content and design:
These modules are used internally by other modules of the plottools package:
latex: translate LaTeX texts.
rcsetup: additional validators for
version: version of plottools and other packages.
Importing plottools modules
Each module can be imported separately. No other functionality of the
plottools is then installed or executed. The only exception are the
modules that import all the other modules. For example, if you are
only interested in the functions the
provides, then you can do
import matplotlib.pyplot as plt import plottools.ticks # installs set_xticks_delta() (and other functions) on matplotlib Axes class fig, ax = plt.subplots() ax.set_xticks_delta(1.0)
For importing all
plottools modules, simply import the module
plottools: import all plottool modules and install their functions in matplotlib.
import plottools.plottools as pt
This also imports all the functions of the modules such they can be used
directly in the
pt namespace. For example:
light_blue = pt.lighter(pt.color_palettes['muted']['blue'], 0.4)
A special module is
which also imports and installs all other modules via the
module. This module provides a few functions
that set some default rcParams and add a number of plotting styles
to a namespace.
These functions can be used like this:
from plottools.params import paper_style class s: pass # namespace for plotting styles paper_style(s) # install all plottool functions in matplotlib and populate s with plotting styles fig, ax = plt.subplots(cmsize=(12, 8)) # new subplots() argument `cmsize` ax.plot(x, y, **s.lsB1) # plotting style ax.set_xticks_delta(0.5) # new function for setting spacing of tick marks fig.savefig() # use name of script as name for figure file
Usually you will not import the
module, but rahter copy one of its functions and adapt them to your
Most modules have a
<module>_params() function for setting rc
parameters to default values. In many cases these functions are just
an alternative way to set matplotlib's rcParams. Many
modules define additional rcParams, that also can be set by these
The following modules just provide such a function as an alternative interface for setting matplotlib's rcParams:
<module>_params() have many arguments that by default
are set to
None. Only the arguments that you provide and differ from
None are actually set, the other ones stay untouched. For example:
from plottools.text import text_params # set the default font size and family: text_params(font_size=12.0, font_family='sans-serif') # turn on LaTex mode: text_params(latex=True)
This is equivalent to
import matplotlib as mpl mpl.rcParams['font.size'] = 12 mpl.rcParams['font.family'] = 'sans-serif' mpl.rcParams['text.usetex'] = True
For a demonstration of the functionality of all modules run
For demos of the individual modules in
run, for example,
python -m plottools.spines
- A quick introduction to matplotlib: Getting started with matplotlib.
- A general guidline for preparing figures for your next manuscript or presentation: Figure guidelines.
- From spaghetti code to a structured code generating a figure: Coding a figure.
- A suggestion for structuring code that generates plot figures: How to structure your code.
plottools are still in a conceptual phase, interfaces might
change without notice and tests on various python and matplotlib
versions are not done yet. So getting an error is not unlikely.
Providing a pull request that fixes the error or provides new functionality is, of course, most appreciated.
You can also open an issue, describing the error. Before doing so, check whether you get the error when you run the demo of the respective module. E.g.
python -m plottools.figures
Mention the outcome in the issue.
In any case, run
python -m plottools.version
and paste the output (python, numpy, pandas, matplotlib and
plottools versions) into the issue.
The full documentation is provided on github.io.