Scientific figures

The main aim here is to document a work flow for producing publication quality figures. This work flow has been developed over a number of years and unifies my own ideas with those from Ray Goldstein in Cambridge. It uses purely open source tools and the focus is on Linux, though the tools so far as I know are also available for Windows. There are two variants - the first uses grace with inkscape, and the second uses grace with psfrag. My current preference is for the first of these but there are advantages and disadvantages for both.

For a data set I will use the pendulum-timed free fall data from Giovanni Riccioli's Almagestum Novum, published in 1651. For more background see Christopher M Graney's article in Physics Today (September 2012), and my Letter in Physics Today (March 2013) and the accompanying article arXiv:1303:5554. The table below shows the extracted data which can be cut-&-paste into your favourite application (no, no, no... not excel, please!). The figure below plots this data showing the free fall distance as a function of the square of the free fall time. For the present purposes the question is : how did we make the figure ?

Table (left): Riccioli's data extracted for subsequent processing. The first column (t / T) is the free fall time measured in pendulum half periods. The second column (z) is the free fall distance measured in Roman Feet. The data is taken from the table on page 387 of the Almagestum.

Figure (right): free fall distance (in Roman feet) as a function of the square of the free fall time measured in pendulum half-periods, with a best fit line (dashed black line) annotated with the calculated pendulum length L, and the expected behaviour from Riccioli's reported pendulum length (solid blue line). See arXiv:1303:5554 for more details.

Making the Figure - the grace / inkscape route

Tools needed :

• grace plotting package (formerly known as xmgrace, xmgr, or ACE/gr),

• TeX / LaTeX installation such as TeXLive,

• inkscape vector graphics drawing package,

• textext plugin for inkscape,

• epstool (optional - may be needed to fix problems with eps files).

• grace import plugin for inkscape (optional).

Apart from the textext plugin, all these tools are probably available as installation packages for your favourite linux distribution. The grace plotting package is widely used for publication quality graphs, but also includes fairly sophisticated data exploration tools such as non-linear curve fitting. Inkscape is a vector graphics drawing package designed with stability and ease-of-use in mind. It works with svg (scaleable vector graphics) as the native format, but is also a pretty good pdf and eps editor. One advantage of inkscape (compared to many other packages) is that the graphics zoom perfectly, including text.

Basic work flow :

• prepare plot in grace, without any labels, annotation, or decorations,

• [save as a grace data file (agr file) to preserve metadata at this stage,]

• EITHER print to encapsulated postscript (eps) and import into inkscape (see below for a comment about occasional bounding box problems),

• OR (better!) directly import the agr file into inkscape using grace import plugin,

• add LaTeX labels and annotation using textext plugin, and other decorations like arrows,

• [save as inkscape svg to preserve metadata at this stage,]

• export bitmap to get, eg, png files for web pages, presentations, and posters, etc,

• save as pdf for inclusion in documents using pdflatex for processing,

• save as pdf then convert to eps (using pdf2ps or similar) for documents using latex / dvipdf for processing.

Grace tricks :

• plot appearance - set page background to no fill,

• increase width of plot frame, tick marks, and lines to '2' (for fine data lines I sometimes use width 1.5),

• for symbols I typically use a size typically around '50', line style width '2', and solid white fill (by making sure the data set is brought to the front the net effect is that the circle symbols has the appearance of lying on top of the other lines),

• error bars are likewise line width '2' and width around '50',

• for tick labels I use size around '150' (my personal preference is to have relatively few tick marks and even fewer tick labels).

To force a best fit line through the origin, here's a trick I learnt a long time ago. Duplicate the data twice. For the second copy, do a data transformation 'evaluate expression' and set x = -x, followed by y = -y, so that the data is reflected through the origin. Then join the data sets, and do a standard linear regression on the joint data. The regression line will pass through the origin since the joint data now has this reflection symmetry. This extra data set can be 'hidden' so it doesn't show up in the plot, but is still preserved as metadata in the grace data (agr) file.

Here is the baseline grace plot exported to eps, prior to import into inkscape :

Inkscape tricks :

• use textext plugin for all labels and annotation, unless just simply adding '(a)' etc labels

• use textext scale factor to resize text systematically,

• use a textext preamble file like the one below then you can use \color{} to colour the annotation,

• use extension Modify Path -> Color Markers to Stroke, to recolor the arrows at the ends of coloured lines,

• add a slightly larger white rectangle as background to force white borders, or force the plot size scaling.

An example textext preamble file ~/.config/inkscape/extensions/usepackagecolor.tex

\usepackage{color}

\definecolor{brown}{RGB}{188,143,143}

\definecolor{grey}{RGB}{220,220,220}

\definecolor{violet}{RGB}{148,0,211}

\definecolor{orange}{RGB}{255,165,0}

\definecolor{indigo}{RGB}{114,33,188}

\definecolor{maroon}{RGB}{103,7,72}

\definecolor{turquoise}{RGB}{64,224,208}

\definecolor{green4}{RGB}{0,139,0}

This defines colours to match the standard Grace colour names. In the same way you can add \usepackage{amsmath} and \usepackage{amssymb} to gain access to the AMS LaTeX and symbol packages.

Note that you can customise colours in Grace by editing the .agr file (which is simply a text file). For example changing

@map color 7 to (220, 220, 220), "grey"

to

@map color 7 to (153, 153, 153), "grey"

produces a darker grey colour.

There are occasionally problems importing eps files generated by grace (missing annotation etc). A fix for this that may work is to run the file through epstool, thus

% epstool --copy --bbox fig.eps fig_newbb.eps

which fixes up the bounding box. Then try importing the processed eps file. The grace import plugin for inkscape does this step automatically.

I've also noticed some occasional problems exporting eps files from inkscape. To get around this, export as pdf and then convert to eps separately using one of the many available tools like pdf2ps. Converting pdf to png can also be done, eg with the ImageMagick convert tool (use -density <dpi> option to set the resolution otherwise the default is 72 dpi).

Inkscape can also be called at the command line to convert the svg to pdf, with

inkscape fig.svg --export-area-drawing --export-pdf=fig.pdf

In a Makefile this can be automated by

%.pdf : %.svg

inkscape $< --export-area-drawing --export-pdf=$@

Making the Figure - the grace / psfrag route

Tools needed :

• grace plotting package (formerly known as xmgrace, xmgr, or ACE/gr),

• TeX / LaTeX installation such as TeXLive,

• psfrag package,

• epstool (optional).

Again these are typically available as installation packages, apart from epstool probably. The work flow starts with grace as above, but then uses the LaTeX psfrag package to substitute text placeholders with LaTeX typeset fragments, thus creating the final image file. The epstool tool is handy for clipping resulting eps files to the bounding box, for inclusion in downstream documents.

Basic work flow :

• prepare plot in grace, but include decorations like arrows, and text placeholders for labels including axis labels,

• [save as a grace data file (agr file) to preserve metadata at this stage,]

• print to encapsulated postscript (eps) file,

• make a LaTeX file which imports the eps graphic and uses psfrag to substitute for the text placeholders,

• process the LaTeX file to get a final eps or pdf for inclusion in documents.

Grace tricks (in addition to those already described) :

• arrow line thickness can be set to '2', etc,

• use specified perpendicular offsets for axes labels, 'xaxis' and 'yaxis', to get them in the right place.

For example here is the baseline grace plot, exported as eps for processing with LaTeX and psfrag.

Psfrag tricks :

• make a dedicated LaTeX file for each figure,

• use class options 10pt, 11pt, 12pt for overall type size,

• make judicious use of \large, \small, \color, and \rotatebox,

• use psfrag options [][] to adjust placement,

• use \thispagestyle{empty} to avoid having any other page markup,

• use includegraphics with size option to set final size.

For example, the following LaTeX file was used with the above eps file (called riccioli_psfrag_b.eps) :

\documentclass[10pt]{article}

\usepackage{psfrag,graphicx,color}

\begin{document}

\thispagestyle{empty}

\begin{figure}

\centering

\psfrag{xaxis}[][]{\large $(t/T)^2$}

\psfrag{yaxis}[][]{\rotatebox{90}{\large $z$}}

\psfrag{aaa}[][]{$L=1.002(5)\,{}''\,\mathrm{Rm}$}

\psfrag{bbb}[][]{\color{blue}$L=1.15\,{}''\,\mathrm{Rm}$}

\includegraphics[width=3.0in]{riccioli_psfrag_b.eps}

\end{figure}

\end{document}

Given this file (called riccioli_psfrag.tex) and the original grace file (called riccioli_psfrag.agr), the following sequence of commands (entered at the command line) will make the final figure :

% gracebat -hdevice EPS -printfile riccioli_psfrag_b.eps riccioli_psfrag.agr

% latex riccioli_psfrag

% dvips -E -o riccioli_psfrag.ps riccioli_psfrag

% epstool --copy --bbox riccioli_psfrag.ps riccioli_psfrag.eps

In here, the first command generates the intermediate eps file, using grace in batch mode. Then we process the LaTeX file with latex and dvips to make a postscript file which is finally clipped back to the bounding box using epstool. The final figure is shown below, compared to the inkscape route.

The sequence of commands can be incorporated in a Makefile, as for example in the following :

riccioli_psfrag.eps : riccioli_psfrag_b.eps

%_b.eps : %.agr

gracebat -hdevice EPS -printfile $@ $<

%.eps : %.tex

latex $(@:.eps=)

dvips -E -o $(@:.eps=.ps) $(@:.eps=)

epstool --copy --bbox $(@:.eps=.ps) $@

Then it is only necessary to issue a 'make' command to rebuild the final figure. Some remarks here are :

• this works here only as long as riccioli_psfrag.eps is the first target in the Makefile,

• the Makefile can be extended to cover all the figures and indeed all the documents in a project, with suitably written targets,

• multi-part figures can be made with multiple includegraphics commands in the LaTeX file, and multiple dependencies in the Makefile,

• part labels, (a), (b), etc, in multi-part figures can be generated by adding suitable makebox commands in the LaTeX file,

• if you are feeling really sophisticated, on-the-fly substitution (with, eg, sed -i commands in the Makefile) can be used to unify notation between figure LaTeX files and a master document.

Whilst it is possible to use psfrag commands directly in longer documents, in my experience many manuscript submission will only take basic LaTeX files, hence I now use separate LaTeX files for all the figures, as in the above work flow. Then the final documents only rely on graphics include commands.

Inkscape or psfrag ?

If your priority is graphic design (annotation placement, etc) inkscape is hard to beat. If you want programmatic control, psfrag is probably best, where it is judiciously supported by Makefiles and supporting commands. But the final results are practically interchangeable :

The final figure : inkscape on the left, and psfrag on the right.

Other packages

Just about anything that generates postscript can be used to inject eps files at the intermediate processing stage in either route :

• the R platform can produce excellent graphics and has many support packages (I have used it to generate scatter plots where the data points are additionally coloured by value, which is not available in grace),

• gnuplot - this is an excellent command line alternative to grace when it comes to quickly eyeballing data,

• octave, MATLAB ($$$), Mathematica ($$$), NumPy, etc - whilst these all produce good graphics my personal finding is that it is better to export the numerical results and replot in grace, with the above workflow in mind.

I haven't decided on a good 3d plot package in all this, but generally I find 3d plots are not very helpful unless one can interact with them.