Fork me on GitHub

welcome to the strawlab styleguide

Warning

This is a work in progress. Some parts are unfinished and undocumented. As always, when in doubt, use the source.

plotting

The basic idea behind our plots is that we want them to convey the most information in the simplest, most intuitive way possible. Edward Tufte’s works are great inspiration here.

There is no completely automated way to make such plots, but the strawlab_mpl package contains various utilities that make this easier when using matplotlib.

Example 1 - category scatter plot

Let’s take a look at an example. We’ll use a relatively simple category scatter plot showing the distribution of samples from three categories. A simple plot done with matplotlib would look like the plot on the left. On the right is an example with much better style.

_images/bad_good.png

Example 2 - timeseries data

Our second example is timeseries data. The top plot shows three individual trials (in grey) and the mean (in red). The bottom plot shows the mean (red line) in a shaded region denoting the standard deviation. These are both good ways to convey the mean response while still showing some of the underlying variation.

_images/panel_timeseries.png

multi-panel figures

Most figures in most papers often have many panels. Regenerating a single panel within a multi-panel figure can be cumbersome if it means every minor change need the entire figure to be remade manually. For this reason, I suggest automating the construction of such multi-panel figures so they can be re-built whenever a constituent panel changes. The svg_stack library serves this purpose when used with .svg figure files. It strives to make the output compatible with further editing by Inkscape.

Consequently, the workflow in our lab consists of:

  1. rendering intermediate panels to the .svg format
  2. compose these panels into a figure using svg_stack
  3. (if necessary) manual editing of the final figure with Inkscape
  4. export from Inkscape into the required target format (.png or .pdf, typically)

rendering to svg with matplotlib

I have two main tips to make nice SVG files with matplotlib.

First is to adjust font settings so that the fonts are rendered as SVG strings (rather than converting the text into paths). I also prefer the fonts Arial and Times New Roman to the matplotlib defaults. This can be done with:

import strawlab_mpl.defaults as smd
smd.setup_defaults()

Under the hood, the important parts of the above are:

rcParams = matplotlib.rcParams
rcParams['svg.fonttype'] = 'none' # No text as paths. Assume font installed.

rcParams['font.serif'] = ['Times New Roman']
rcParams['font.sans-serif'] = ['Arial']
rcParams['font.family'] = 'sans-serif'

The second tip for nice svg files is to let matplotlib convert any elements with many data into a raster plot. This dramatically decreases file size and rendering work. Doing this is very simple – include a “rasterized=True” kwarg when calling your relevant matmplotlib command:

ax.plot( giant_array_of_x_values,
         giant_array_of_y_values,
         rasterized=True)

compose these panels into a figure using svg_stack

svg_stack is meant for composing multiple elements into a bigger page. The instructions included with svg_stack are recommended to get you started.

export from Inkscape into the desired format

Inkscape can be scripted to export files at the command line. For example, this will render a .png file of <INPUT_FILENAME>:

inkscape -f <INPUT_FILENAME> --export-dpi=90  --export-background=white --export-png=OUTPUT_FILENAME

bringing it all together with make

I automate the whole show with the venerable make command. For an example of usage, see the example Makefile which will automatically update a final figure when run, but it will only rebuild the necessary parts based on while files were changed.