15
$\begingroup$

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.

Improve this question
$\endgroup$
2
  • 1
    $\begingroup$ You could post both code and figures on Figshare. Each would get a DOI-like identifier that you could reference wherever necessary. $\endgroup$
    – David Ketcheson
    Oct 12, 2012 at 13:11
  • $\begingroup$ Software requires continuous maintenance. Papers are published and at that date they are set in stone. The goal is admirable, but it will never work. (I'd be glad to be proved wrong: Anyone who finds a paper over 5 years old whose associated software still works can call me out. For myself, I've never found any code associated with a paper that actually works, other than the "framework description papers", like the FFTW whitepaper.) $\endgroup$
    – user14717
    Apr 10, 2019 at 13:50

4 Answers 4

Reset to default
7
$\begingroup$

  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}
\begin{equation}
  \label{eq:one}
  Ax=b
\end{equation}
\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.

Improve this answer
$\endgroup$
2
  • 1
    $\begingroup$ 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. $\endgroup$
    – Wolfgang Bangerth
    Oct 12, 2012 at 12:14
  • $\begingroup$ Yeah, I'm not a huge fan of its pretty-printing, but Wolfgang is right. $\endgroup$
    – Bill Barth
    Oct 12, 2012 at 14:08
5
$\begingroup$

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.

Improve this answer
$\endgroup$
3
$\begingroup$

The LaTeX package minted provides very extensive syntax highlighting (based on Pygments) and allows cross-referencing in both directions. You can escape to LaTeX from within the code part (the minted part) and you can refer in your main text to lines of code. On top of that, it provides a listings environment so that you can generate a "list of listings" (like a list of tables) and allows referencing entire listings. See LaTeX MWE and its output with LuaLaTeX below (don't judge the code :-) ).

Another option would be to use PythonTeX from the same author/maintainer which allows running the calculations while compiling the LaTeX source, hence paper and code results are always generated together and hence are always coherent. See the PythonTeX gallery here. 

\documentclass[a4paper,notitlepage,11pt]{article}

\usepackage{amsmath}
\usepackage{cases}
\usepackage{minted}

\begin{document}

The mathematical definition of the Fibonacci
series is given in~Equations~(\ref{eq:fibdef:init1}--\ref{eq:fibdef:rule})
It can be implemented using either a recursive or iterative algorithm
in Python.

\begin{numcases}{f(n)=}
  \label{eq:fibdef}
    0               & n = 0 \label{eq:fibdef:init1}\\
    1               & n = 1 \label{eq:fibdef:init2}\\
    f(n-1) + f(n-2) & \text{otherwise} \label{eq:fibdef:rule}
\end{numcases}

The algorithms below are an implementation of both variants.
Listing~\ref{alg:fib_recursive} shows the recursive variant (see
line~\ref{alg:fibo_rec:line_rec} in listing~\ref{alg:fib_recursive}) while
listing~\ref{alg:fib_iterative} shows the iterative variant. Both can be
optimized, of course.

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_rec(N):
    if N == 0:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init1})]|
    elif N == 1:
        result = 1 |[Comment: See case (\ref{eq:fibdef:init2})]|
    else:
        result = fibo_rec(N-1) + fibo_rec(N-2) |\label{alg:fibo_rec:line_rec}[Comment: See case (\ref{eq:fibdef:rule})]|

    return result
  \end{minted}
\caption{Fibonacci recursive}
\label{alg:fib_recursive}
\end{listing}

\begin{listing}[ht]
  \begin{minted}[linenos, escapeinside=||]{python}
def fibo_iter(N):
    if N == 0:
        fib_N = 1
    elif N == 1:
        fib_N = 1
    else:
        fib_Nmin2 = 1
        fib_Nmin1 = 1
        for i in range(2,N+1):
            fib_N = fib_Nmin2 + fib_Nmin1
            fib_Nmin2 = fib_Nmin1
            fib_Nmin1 = fib_N
    return fib_N
  \end{minted}
\caption{Fibonacci iterative}
\label{alg:fib_iterative}
\end{listing}

\end{document}

enter image description here

Improve this answer
$\endgroup$
0
$\begingroup$

Use the Literate Programming Functionality of org-mode.

Most org-mode users tend to focus exclusively on the either the built-in project/time management functionality or the ability to export documents into multiple popular file formats, e.g. PDF, from easy to maintain text files.

However, the best feature of org-mode is ability to create literate programs in over 30 languages with more languages added every month by the open source community.

Below are trivial code examples using Ruby and Python:

 #+NAME: trivial-code-ex1
 #+BEGIN_SRC ruby 
   "hello world!"
 #+END_SRC

 #+RESULTS: trivial-code-ex1
 : hello world!
 
 
 #+NAME: func-of-x-and-y
 #+BEGIN_SRC python :var x=1 :var y=2 :session
   x + y
 #+END_SRC

 #+RESULTS: func-of-x-and-y
 : 3

Pros

  • Support for over 30 programming languages, including R, Python, Ruby, Perl, C, C++, Java, Clojure, Javascript, Common Lisp, Shell, SQL, ...

  • The ability to:

    • Capture SRC block results as output and/or value.
    • Format SRC block results as code, lists, table, latex, html
    • Use both external & internal data for variables of SRC blocks.
    • Use the output of named SRC blocks into SRC blocks as variables.
    • Use noweb syntax inside SRC blocks.

      Pro Tip: You can use noweb syntax to:

      • insert code from a named SRC block, e.g. func-of-x-and-y, inside another SRC block.

        #+BEGIN_SRC python :session :noweb yes 
  x=2
  y=3
  "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f({0},{1}) equals\n\n {2}".format(x,y,<<func-of-x-and-y>>)
#+END_SRC

#+RESULTS:
: f(x,y) is
: 
:  x + y 
: 
: so f(2,3) equals
: 
:  5

      • insert the results of a named SRC block, e.g. func-of-x-and-y inside another SRC block

        #+BEGIN_SRC python :session :noweb yes 
  "f(x,y) is\n\n <<func-of-x-and-y>> \n\nso f(3,4) equals\n\n <<func-of-x-and-y(x=3,y=4)>>"
#+END_SRC

#+RESULTS:
: f(x,y) is
: 
:  x + y 
: 
: so f(3,4) equals
: 
:  7

      • Place named SRC blocks anywhere in an org-mode file for readability and use :tangle header or export code into external source files.

  • Open source project - both free as in beer and free as in freedom.

  • Text file format works great with version control software like git.

  • Ooodles of other features which I won't go into because this answer is getting long.

Cons

  • Need to have gnu emacs installed and configured to use org-mode.

    Note: Most of you stopped reading this answer after you read gnu emacs. For the brave souls that are left, you can use your favorite text editor and just call emacs to process your org-mode files from the command-line.

  • Need to install and configure all of the programming software you need.

  • Need to install and configure LaTeX utilities if you want to make PDFs.

  • org-mode is not as well know as ipython notebooks or Sweave so you probably won't see as many job postings even though Literate Programming functionality was added in 2008.

  • Learning org-mode markup syntax

  • Potentially learning how to use gnu emacs or spacemacs if want to get most out of the other cool tools that work with org-mode.

Full disclosure: I am the primary maintainer of the org-mode package for the Atom editor.

The code in this answer was validated using:
emacs version: GNU Emacs 25.2.1
org-mode version: 9.1.2

Improve this answer
$\endgroup$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.