# What would be the most helpful way to write code for a paper so that readers can clearly match the results to the code that generates them?

I'm writing a reproducible paper, and the paper has computational results that are generated by a Python script (a similar MATLAB script generates nearly identical results). I feel that the paper would be easier to understand for readers if they could match up the calculations in the paper with calculations in the code. The work proposes an abstract formalism, and the examples in the paper are supposed to make this formalism more concrete for readers (many of whom will be engineers); the code will probably be the most detailed record of how to perform the calculations, and making it clear could help us during the review process.

Does anyone have any suggestions on how to make the correspondence between code and computational results (figures, equations) more clear?

For instance, I was thinking that when it came to lines of code implementing various steps in the paper, I could cite equation numbers (it would be amazing if I could cross reference between the code and LaTeX, but hand-labeling them is fine), and I could write functions corresponding to the various examples and figures, such as

def example_1():
# Insert code corresponding to first example
pass

def figure_1():
# Insert code that generates Figure 1
pass


If the code were large, and I weren't trying to explain how a bunch of different mathematical methods used in engineering were actually the same, I probably wouldn't bother so much with making the code clear, but given the abstract nature of the paper and the small code base, it seems as though there could be value in this exercise.

-
You could post both code and figures on Figshare. Each would get a DOI-like identifier that you could reference wherever necessary. –  David Ketcheson Oct 12 '12 at 13:11

1. You might consider writing the entire paper in Noweb. It's a bit tedious to set up, but it's a very powerful way to mix code and LaTeX-formatted text, equations, and figures. For long programs, it tends to turn your code into more of a book than an article, but for short programs, it might work out pretty well.

2. If you don't want to go that far, it still ought to be reasonably straightforward to format the comment sections of your code listings using LaTeX. The listingspackage can help you pull this off. Here's a short example:

\documentclass{article}
\usepackage{amsmath}
\usepackage{listings}
\begin{document}
$$\label{eq:one} Ax=b$$
\begin{lstlisting}[escapechar=\%]
# Comment with a reference to Equation%~\eqref{eq:one}%
def f(a):
return a+1
\end{lstlisting}
\end{document}


With some additional manipulations, you ought to be able to get your referenced equation numbers to appear in the monospace font that it uses for listing the equation.

-
The lstlisting environment actually also allows you to specify a programming language and it nicely color codes/style codes the various elements of each language. –  Wolfgang Bangerth Oct 12 '12 at 12:14
Yeah, I'm not a huge fan of its pretty-printing, but Wolfgang is right. –  Bill Barth Oct 12 '12 at 14:08

The noweb approach mentioned by Bill has evolved quite a bit, both in it's original spirit of documenting code (rather than scientific publication) under the term literate programming and now comes in many flavors (I guess noweb was a generalization of cweb initially), of which doxygen and various language specific versions can generate documentation in TeX, HTML, and other formats.

More to your point, noweb has been developed for some time in the R community (well originally the S community, hence the name) under the title "Sweave" with the goal of providing a "reproducible research" paper, where the code is actually run when the latex file is compiled (and optionally displayed as well). Quite a number of academic papers are written in Sweave (including, I believe, all of the R-journal; but see also the journal of biostatistics and it's policy on reproducible papers).

While Sweave is still part of any base R installation, it is being replaced by knitr which is now language agnostic, making it a possible choice for your python code. Knitr supports writing in LaTeX or markdown, supporting syntax highlighting, caching, externalization of the code from the source latex and many other desirable features for this kind of work.

Python has it's own solutions that are similar, ipython notebooks, which can render to HTML, maybe LaTeX, but I know less about this.

Another project definitely worth a look is dexyit, another language-agnostic program that works very nicely with LaTeX and HTML. While it has more examples in documenting code than in writing scientific papers, working in LaTeX it should be straight forward.

Both knitr and dexyit will do exactly what you describe in the LaTeX, including pointing to external python script and reading in the code. Similar things can be accomplished in DocBook and XML, though I'm less familiar with this approach.

-