Style guides for scientific papers

This page summarizes the style guides used in the hadron structure paper arXiv:1001.3620. Since this paper combines several contributions by authors with distinct computational strategies and visual tastes, we needed to establish a common ground for how the figures are supposed to look like and how to express physical constants and observables in a unified manner.

To this end, I have written three style guides which put forward reasonable rules for how the results were presented. You can feel free to use them in your own papers if you so wish.

Note, that the paper is consistently written in LaTeX, thus all comments on symbols below explicitly refer to the standard software.

The issue of uniform graphs has come up a few times in some small-group and large-group conference calls. Therefore, I have suggested to employ a wide-spread graphics program uniformly in our upcoming paper. The one discussed on this page is already used by the majority of collaborators and thus a logical choice.

The standard program for 2D plots in the final version of the paper is Grace with the default font size altered. This software is available for all relevant platforms and easy to learn and use. The data files are human readable and can also be accessed and edited by scripts (e.g. via Python or Perl).

Grace is open source software and thus should outlive the production process of our paper. (I hope … with regards to the production process, I mean.) In addition, this page contains a standard template and a tutorial on how to draw error bars.

Standard template

I submit the following template for 2D graphs: Kappa-v template for Grace. The template produces the following graph:

Kappa-v template for Grace
The template for Grace with a sample graph of the isovector anomalous magnetic moment.

The plot contains experimental data, lattice data, and error bands. The color scheme is close to the default and is both easily readable and supports quick comprehension.

The following rules apply:

Any graph should tell a clear message. If we don't know the message, the graph is not included. The goal is to eliminate any superfluous information and distraction.
The central value fit is shown by a solid black line. In case of additional data points in the figure, the colors of the error bands correspond to the data points. If the data point symbol is varied, the line remains black and the line style varies, instead. The latter variant is discouraged unless absolutely necessary since it reduces clarity.
The default error band denoting statistical error is gray. Adding multiple error bands might clutter the graph too much. If necessary, this should only be done with different colors of the lattice data (see below) and the color should correspond to the lattice data fitted.
The default systematic error band is cyan. Again, adding multiple systematic error bands might clutter the graph too much. It is discouraged to use multiple systematic error bands in one graph.
Experimental data is red, multiple data in active colors. If necessary with error band. Suggested default is the star symbol.
Lattice data is blue, solid disks as symbols. Multiple data sets should vary style according to meaning:
- Colors should always be soft (blue, green, etc.)
- Different quantities (e.g. ΔΣ, J_q and L_q) in the same graph should alter the colors and the symbols.
- Similar quantities (e.g. ff data at different m_pi) should alter the colors only, not the symbols.
- Changing both symbols and colors for the purpose of adding information to a graph is discouraged unless it doesn't affect readability (which is unlikely IMHO).
Quantities with physical units should always contain the unit in legends and axis labels. Default style is “Quantity / Unit”.
Legends do not contain spurious information. If present, they can be placed anywhere on the canvas to minimize overlap with the figure. Default is upper right.
Multi-layers (in the example from front to back: data, central value fit line, gray shaded error band for statistical error, cyan error band for systematic error) should be 5% shorter than the next-upper layer.
Axis placement relative to the graph mass:
- Plots should leave 10% space on the x-axis at the left- and right side of a graph.
- Plots should leave 20%-30% space on the massive parts of the plot on the y-axis to the top- and bottom side of a graph.
- Unless it violates the previous rules, an axis origin should be included.
Any rule can be broken if it enhances the message the graph is supposed to tell.

Creating error bands in Grace

Since several people have asked about this, I describe how to draw error bands using Grace.

Starting data

Prior to reading them in the error bands have been computed (this form is quite common and human-readable):

<x_val_1> <y_val_1>-<y_err_1> <y_val_1>+<y_err_1> <x_val_2> <y_val_1>-<y_err_1> <y_val_1>+<y_err_1> … <x_val_n> <y_val_n>-<y_err_n> <y_val_n>+<y_err_n>

Next, they need to be brought into the form:

<x_val_1> <y_val_1>-<y_err_1> <x_val_2> <y_val_2>-<y_err_2> … <x_val_n> <y_val_n>-<y_err_n> <x_val_n> <y_val_n>+<y_err_n> … <x_val_2> <y_val_2>+<y_err_2> <x_val_1> <y_val_1>+<y_err_1>

Unless the data has already been generated in the proper form it can easily be converted with the following Python program:

 #!/usr/bin/env python -ttt
 import sys

 # Read input file
 myh = open(sys.argv[1], 'r')
 cont = myh.readlines()
 myh.close()

 # Column offset?
 if len(sys.argv)>2:
     offset = int(sys.argv[2])
 else:
     offset = 0

 # Compute result
 for i in range(len(cont)):
     j = cont[i].split()
     print '%s %s' % (j[0], j[1+offset])

 for i in range(len(cont)-1, -1, -1):
     j = cont[i].split()
     print '%s %s' % (j[0], j[2+offset])

The important point is that the data forms a “contour” on the canvas that can be interpreted as a closed polygon. Therefore, the reversed ordering of the second half of the data (x_n back to x_1) is crucial. Also note, that the data is now a simple x y data set, no longer a data set of points with error bars x y dy.

Getting data into Grace

If we have prepared the input as a text file, we import it in the usual way via Grace's Data→Import→ASCII… dialog. We select the data, load a “Single set” and choose set type: “XY” (as discussed above).
Importing data ASCII data import dialog
In the Plot→Set Appearance dialog, we select the data, right click on it and choose “Send to back”. This way, it won't block other information.

Showing the error bands

Next, we go to the “Line” tab and select the “Fill properties”. We pick the Type “As polygon” and choose a solid pattern and color (in the example it is “cyan”). The rest can be left unchanged. Additionally, we should also set same color in the “Line properties” part on the first tab (“Main”). Otherwise, the error band will have a band around it plotted in a different color.
Filling the error band Setting the same line color

That's all

That's basically all there is to it. We can still play around with settings (to send systematic error bands to the back behind statistical ones etc.). But there is little need to tinker with the other settings since in most cases the default options are fine and/or already set in the sample graph linked above.

Enjoy!

Equations and observables

Overview

This style guide standardizes notations for equations, observables and symbols and finally some miscellaneous items. Notations follow the former paper on GPDs, arXiv:0705.4295, unless otherwise explicitly stated.

General

Labels follow the convention used by RefTeX. Prefixes for equations are eq:, sections sec: etc.
References follow Phys.Rev. standard where applicable.
Bibliography is handled by BibTeX. Symbol names follow Spires database if possible. Note: The BibTeX-symbols generated by the database are not guaranteed to be unique! This means that conflicts may need to be worked out manually – I have had one such case recently!
Every section writer provides her own BibTeX file.
Conflicts during merge are handled by me (Wolfram Schroers).
Names should be canonized and employ properly escaped special characters (where known). This is not the default in the entries automatically generated by Spires. It certainly would be asking too much to read and translate any possible code in all possible formats, so we need to do some manual work here.
Figure and table captions contain a brief description of content. Interpretation and details are explained in the main text.

Equations

Equations are referenced by \eqref{eq:X}.
Section writers can assume all form factors, GPDs, PDs (i.e., all relevant observables) etc. are already defined in the introduction. Appropriate labels will be announced later. Placeholders can be used until then.

Symbols

Quantities in lattice units are written as $(aX)$, where X is the entity in question.
Entities in physical units are written as $X$ Unit, e.g. $500$ MeV.
- Ranges in physical units are surrounded by braces, e.g. $(300-700)$ MeV.
Default unit for particle masses is MeV.
Default unit for virtual momentum transfer is GeV².
Plots of virtual momentum transfer plot Q² / GeV² with the origin in the lower left corner.
Notation and meaning of kinematic variables is specified by arXiv:0705.4295, Figure 1, Section II. Addition: In the form factors section we introduce Q²=-t.